API-Level Integration

[MisterJames]

Hello all,

I'm a contributor on another open source project used by the Red Cross (AllReady) and I'm looking for some information regarding integration with the API.

For certain regions, we are looking to either receive a post-back when a new smoke alarm is detected (preferred) or periodically poll an end point to "pick up" new requests. Any information that you might have would be greatly appreciated.

We are implementing a web hook approach on our site for implementation of such communication, so it would be trivial for us to expose a URI and give you a token to use as part of the post-back, should that work for you. Perhaps this is something that could be registered with a list of cities, states, or geo-coded info of some kind such that only requests for the designated areas are presented to our end point.

If you don't have direct support for this type of integration, we can also use services such as IFTTT or Zapier and consume events from those providers.

Contacts that I am working with:

• Red Cross: Jim McGowan
• Humanitarian Toolbox: Tony Surma

Looking forward to working with you folks!

Cheers.

[tonysurma]

to that end @cecilia-donnelly can you help me (I know I am late to the game) on exactly what accepted means? It sounds like accepted means we have it and all will be done by the other tool (allReady in this case). and then you don't allow any work via GASA right?

One thing we do know at time of request coming to our site is if it will get put in an org or not as we think you supply us with Region and @OhMcGoo can tell us which regions are using it at start and over time. So we can synchronously respond to you and say 'accepted: true' if it is for an region that is using allReady assuming that all requests for a region will be tagged as such by you and we can assume all requests for a region that is using allready will be managed by allready. Are those valid @OhMcGoo and @cecilia-donnelly ?

Thanks

cc @stevejgordon @MisterJames as we talked re this on Saturday

[mgmccarthy]

FYI @tonysurma, when we response to their API with true/false. it's async.

Either way, I think you're saying here that we respond to GASA with true if we service the region (which would be something we can hard-code for v1), and in our code, we still store the Request with the OrgId assigned?

This will work, but there is still the issue of the Request never being associated to an Event. The minute we send GASA true, they disallow any updates via their UI to that Request.

I'm assuming that all Requests will eventually be associated to Events, which, in turn, will allow them to eventually be assigned to an Itinerary, but any Requests that are never associated to an Event will remain "in limbo".

I don't know if the Event "sitting there" for awhile is something that would ever happen, or if the user of the org with the pending Requests would be going in an actively associating Requests to Events on a regular basis.

[mgmccarthy]

@cecilia-donnelly, thanks for those possible scenarios. We're discussing what we want to do on our end right now.

[tonysurma]

@mgmccarthy thanks, by sync I think I meant 'in response without waiting for any action on our side' so basically what is happening 😸

I think that will work for v1 and I am not worried about orphaned requests at this point.

Let's go with that approach and if we need to add anything further we can address after v1.

Thanks @cecilia-donnelly as well for the collaboration

[mgmccarthy]

@tonysurma / @cecilia-donnelly I can finish my code when we get our tokens working. We'll provide GASA with a token, on Request import, we'll look up the user based on the token, then look up the user's organization, and associate that Request to that org.

when this happens, we'll reply a true` back to GASA's endpoint.

if we cannot verify the incoming token on the Request, their call to our endpoint will fail as unauthorized...

thanks

[cecilia-donnelly]

Thanks for the updates @tonysurma and @mgmccarthy!

[mgmccarthy]

@cecilia-donnelly, a quick update. Looks like @OhMcGoo is going to give us a list of 5 or 6 regions we'll accept for the v1 rollout of AllReady. We're going to hard-code those region checks for now, so any of those regions will get back a reply of true, the rest will get back a reply of false.

On our end, we're still doing the additional mapping of the Request to an Organization (internal entity for us) and:

1. using the OrgId of the user associated to the token we will be providing you to as the org to associate the Request to
2. when the Request is assigned to an Itinerary, that's when we can actually start "doing something" with the Request in our system.

I''ll waiting to hear back from @tonysurma when he knows what that list of regions is.

If you have any questions, feel free to ask

Thanks, Mike

[mgmccarthy]

cc @tonysurma

@cecilia-donnelly, question on updating status back to you.

Right now, you have the following possible statuses for smoke alarm requests: new, in progress, installed, or canceled

We've already built the code that accepts a request with a status of new from GASA and sends you the update with a status of new and an acceptance of true when we can service the request.

I'm assuming you expect those same statuses sent back to you when we would update the status of a request in our system after we've agreed to service the request?

That being the case, our statuses don't align one-to-one with yours. So, here is what I think the "mapping" is going to be:

AllReady     GASA
---------    ------
Assigned  -> in progress
Completed -> installed
Canceled  -> canceled

[mgmccarthy]

cc @tonysurma

@cecilia-donnelly another question for you. In our system, it's possible for a Request to be Assigned (in progress), then changed back to Unassigned again (which is the initial state of all Requests, so Gasa status of new).

My guess is we allow this in case the installer doesn't get a chance to get to the install on the day of the install, and it's the last day of the Event... so any Requests they didn't get to go back to the drawing board.

In this case, what would we report back to GASA? My guess is: status = new, acceptance = true?

we are still tacking the request we agreed to service, but the request is no longer doing anything until it can be assigned to another Itinerary in our system.

Thanks

[cecilia-donnelly]

Hey @mgmccarthy, thanks for the updates!

I'm assuming you expect those same statuses sent back to you when we would update the status of a request in our system after we've agreed to service the request?

Yes! Those preliminary mappings seem sensible to me.

In our system, it's possible for a Request to be Assigned (in progress), then changed back to Unassigned again (which is the initial state of all Requests, so Gasa status of new).

In this case, what would we report back to GASA? My guess is: status = new, acceptance = true?

That sounds right to me. We don't have any rules saying that a request can only move from new, not back to it, so going from in progress back to new shouldn't present a problem.

[mgmccarthy]

@cecilia-donnelly, first off, I hope you had a nice holiday and a good new year..

I have a quick question for you. For the Requests you're sending us, have you already validated that the phone number on the Request is a valid mobile number or are you not validating the phone number in any way?

Thanks

[cecilia-donnelly]

Hi @mgmccarthy! Happy new year back atcha.

We validate that the phone number is 10 digits in layout.jade. I believe the validation is based on something in the jQuery Validation Engine codebase.

We don't, however, do anything to make sure that the 10 digits entered are a working mobile number.

[cecilia-donnelly]

@mgmccarthy I'm getting a 502 error when I POST to the endpoint you gave in this comment. Is it still up? Is there a different endpoint I should use?

Thanks!

[mgmccarthy]

it should still be up and and it is the endpoint you should use. I don't have access to the production server, so I won't be able to troubleshoot.

cc @tonysurma

Most likely it's a change to the controller (endpoint) and/or the command were sending to do the processing.

Let me look into it

[cecilia-donnelly]

Thanks for the quick response @mgmccarthy!

[mgmccarthy]

@cecilia-donnelly, I just ran all the latest code locally, and it works.

I'm assuming this could be related to something different in the live environment. I just sent you an email asking you to send me the json you're trying to send to our endpoint so I can run it locally.

Thanks

[cecilia-donnelly]

@mgmccarthy, I didn't get an email from you (?), but I sent you the body of the JSON I was sending to the endpoint (via Postman), and the full error I got in response.

[mgmccarthy]

@cecilia-donnelly I did get an email to you... it looks like the entire website is down for some reason right now... so I doubt this is a code/config problem with the endpoint.

[cecilia-donnelly]

@mgmccarthy thanks for the update!

(Sorry to spam this issue with server config questions, everyone.)

[tonysurma]

I am looking into it

[cecilia-donnelly]

@mgmccarthy, it sounds like allReady requires both email and phone, where the smoke alarm portal only requires that at least one of those fields be completed. We can send an "n/a" or similar for a blank field coming from our user. Does that sound right to you?

[mgmccarthy]

@cecilia-donnelly, this is correct. The reason being that AllReady will choose which communication method to use for requestors based on the specifics of a given integration.

For our v1 launch, we are only supporting communicating back to requestors via sms message for now. Communicating back to requestors via email is something we will implement post-v1.

That being said, since we don't support email yet, I'm imaging we could "relax" the validation around email in our system.

The problem here is once we've written that information into our system, and if we then want to support communicating to requestors via email, then we have a bunch of requests in our system which cannot do that.

not too sure what the answer is here. I'm thinking for now, we'll just continue returning a 400 to your call if email address is misisng and/or invalid.

@tonysurma @stevejgordon, thoughts?

[mgmccarthy]

@cecilia-donnelly, I should also mention that we most likely for v1 will be validating that the incoming phone number we get from GASA is a mobile number. If it's not a mobile number, we'll most likely return a 400 at the point of the call or communicate back to your endpoint an acceptance of false.

[mgmccarthy]

@cecilia-donnelly, looks like we're back up and running. I had messed up an entity framework migration and brought the live site down :frowning_face:

[kfogel]

Whups -- been there, yeah :-).

@mgmccarthy, just FYI @cecilia-donnelly will be afk until Tuesday, possibly Wednesday -- so if there's a delay in substantive response (as opposed to my non-substantive one here!), that's why.

[cecilia-donnelly]

@mgmccarthy thanks for the update! I sent a couple test requests and it looks good from here. :+1: More soon!

[mgmccarthy]

@cecilia-donnelly, do you by any chance have the ability to send us a country code?

[cecilia-donnelly]

@mgmccarthy do you mean a country code for the phone number? We assume all phone numbers coming in through the Smoke Alarm Portal are US numbers, so the country code would always be "1".

[mgmccarthy]

@cecilia-donnelly thanks for that clarification...

cc @stevejgordon

right now, in our system, if wee don't have a country code available, we assume "US"

[mgmccarthy]

@cecilia-donnelly, just an FYI if you try to invoke our API:

We've finally fixed the problem with user-generated tokens not being recognized on post-back to our system. What this means is two things:

1. the route/path to the API has changed
2. I need to provide you with a user and a token that you will attach to your http headers in order for your request to be properly authorized by AllReady

When the PR is merged, I'll create a user for GASA in the AllReady live environment, then generate a token for you. I'll then email you the information.

Thanks

[cecilia-donnelly]

@mgmccarthy fantastic! Thanks for the heads up. I'll keep an eye out for the token.

[cecilia-donnelly]

Hey @mgmccarthy, checking back on this. Were you able to get your PR merged? What's the new route to the API?

[mgmccarthy]

@cecilia-donnelly, I've been out of the loop for awhile with the AllReady project. The PR was merged a while ago.

When creating a user, we're going to need an email address/mobile phone number, and both will need to be verified. If there is a GASA email and a mobile phone number you would like to use, you can register with the site here: http://allready-d.azurewebsites.net/Account/Register

then verify both email/mobile number (I don't think you HAVE to verify a mobile number, it's optional)... once that's done, I can log in as a site admin and generate the token for you and email you the info.

Thanks!

[cecilia-donnelly]

@mgmccarthy thanks for the quick response! I created a "Get a Smoke Alarm" account on allReady. Let me know if you need any more from me to generate the token.

[mgmccarthy]

@cecilia-donnelly just sent you an email with your token and the path to our API

[cecilia-donnelly]

@mgmccarthy, thanks for all your help with this!

I'm now sending the following request using Postman:

POST to http://allready-d.azurewebsites.net/api/request

Body:

{ "ProviderRequestId": "MINN-17-00123",
  "ProviderData": "MINN",
  "Status": "new",
  "Name": "Cecilia Donnelly",
  "Address": "5300 S Pleasant Ave",
  "City": "Minneapolis",
  "State": "Minnesota",
  "Zip": "55404",
  "Phone": "444-555-3534",
  "Email": "" }

Headers:

Content-Type:application/json
ApiUser:__Registered_Email_Address__
ApiKey:__API_Key__

Instead of getting a 202 response with values for status and acceptance, I get a 200 response with the AllReady Login page. Presumably I'm doing something wrong -- maybe the body values it expects are different now? Any ideas? (The address and phone number are made up -- could that be a problem?)

[mgmccarthy]

@cecilia-donnelly Email is a required field. If you fill that out, does it work?

If that is the problem, that means we're not handling the failure of the request properly, b/c you're still getting a 200 and being redirected to our home page... that doesn't sound right

[mgmccarthy]

Also, is the phone number from a mobile phone?

[cecilia-donnelly]

@mgmccarthy I just tried it with email filled in (test@example.com) and a real mobile phone number, and no dice. (That phone number above is just made up.) Even with those changes, I still get a 200 and the home page. Can you see anything in your logs?

[mgmccarthy]

@cecilia-donnelly the problem is I don't have access to our production environment/and/logs.

Let me try to set everything up locally, and give it a shot. If it works locally, then there is some problem on production, and I'll have to get project owners involved to figure out what that is.

[cecilia-donnelly]

Thanks so much, @mgmccarthy! I'll take another look at it later with fresh eyes, in case it's something obvious and silly. (The fact that I'm getting some response makes me think I'm probably sending the request to the right place and so on, but still...)

[mgmccarthy]

@cecilia-donnelly I'm 95% sure it's a problem with our token-protected middleware... I'll take a look.

[mgmccarthy]

@cecilia-donnelly it looks like there was an API change to the model we're expecting from you... instead of a field named Zip we're expecting a field named PostalCode.

try that change and let me know what you get.

[cecilia-donnelly]

No luck yet @mgmccarthy. :(

(To be clear, I tried sending PostalCode instead of Zip, with all other values being the same, and still got the Login page back.)