This is a continuation of my series on a proof of concept to allow Alexa to interact with D365 Field Service
Objectives
- The Business scenario (Part 1)
- Create an Alexa Skill (Part 1)
- Connect the Skill to D365 (This part)
- Use Field Service to book an appointment (Part 3)
- Return the information to Alexa (This part)
In this post I will be linking Alexa to D365 and returning some information back to the end user.
Receiving information from Alexa
Alexa interacts with the outside world with a HTTPS request. Once Alexa has determined that it understands the user and they have asked for something of your skill, it posts to the web service you have configured.
That API Guy had a great post where he links his Alexa to his O365 email account and has Alexa read out his new email. This article steps through linking Alexa and Flow, and it showed me how simple that part of the integration is. Microsoft has done the hard work by certifying it’s connections, you just need to create one.
Flow provides several methods of subscribing to HTTP events, but the one we are interested in is at the bottom
The URL is generated for you, and is the bit you need to post into Alexa Skill configuration once we have created the Flow. In the JSON schema, we just want a stub for now. The schema is defined by Alexa and how you configure the skill. It is best to get the connection up and running and use the initial call to substitute the schema later.
Every Flow needs at least one action to be able to save, so to aid testing and understand the JSON sent by Alexa, the first step is to send an email to myself with the content of the call.
Saving the flow and go back to the trigger
A specific trigger URL for our Flow is now generated.
Back in Alexa
In Alexa, on the left in the Skill is Endpoints. Alexa allows different endpoints to the skill depending on the Alexa region as well as a fall back. As this is a POC, using the default is appropriate.
The important part of this is the drop down below the URL copied from Flow, this needs to be the second option “My development endpoint is a sub-domain of a domain that has a wild card certificate from a certificate authority”. Basically, Microsoft has certified all their Flow endpoints with wild card certificates, allowing Amazon to trust that it is genuine.
One saved, Build your skill again. I found every time I touched any configuration or indeed anything in Alexa, I needed to rebuild.
Testing
Ready to test. Alexa allows you to test your connection via the Test tab within your skill.
You have to select Development from the drop down. You can also use this interface to check Production skills.
A word of warning, everytime you build, to test that new build, I found I had to re-select Development in this window by toggling between “Off” and “Development”.
Back in Flow, test your flow by confirming that you will conduct the action.
In the Test panel in Alexa, enter a phrase with your Invocation and Utterance in Alexa entry and if Alexa understands it is for your invocation, your flow should be triggered! Alexa will complain, as our simple flow hasn’t returned anything to it. We’ll worry about that later.
In our simple Flow, I used email as the action, as can be seen below.
This is the raw JSON output of the Alexa skill and this is used to tell Flow what to expect. This way it will provide the rest of the Flow with properties that are more appropriate.
Back in the Flow trigger, select Use sample payload to generate schema, which presents the text entry, where you paste in the email body.
Flow does the hard work now and presents you with a schema for what Alexa is sending your Flow
Authenticating the user
Taking triggers from Alexa, hence a user is all well and good, but they expect a rapid response. Alexa Skills are public domain once you publish it, anyone can enable your skill, hence a little work needs to be done to understand who is calling our skill and whether Big Energy Co supports them.
Which User is it?
The request from Alexa does include a unique reference of the user, but normally businesses like Big Energy Co work on email addresses, which you can get from Alexa, but the user has to give you permission. This can be pre-approved when the end user installs the skill or you can ask for approval.
Alexa needs to be told that your skill would like this permission. This allows Alexa to request this permission for you when your skill is enabled by the user
On the left hand menu, there is a Permissions link, where our skill asks for the email address
To ask Alexa for an users email address is a seperate web call with properties from original message sent from Alexa in the trigger.
Alexa provides each session an access token so that Flow can ask for more information from Alexa in the context of the users session, location, names, email etc. As this is a globally distributed system, the api End point can vary depending on where the user started their session. The URI at the end asks for the email address of the user of the session.
Alexa may refuse to return the email address, because the end user has not given permission for our skill to share this information. If the call to get the email was a success, it means that Alexa has returned the value and the Flow can continue
Without the permission, the call fails and so the Flow captures this. Remember to set a run after for this step to ensure it still runs on failure. Otherwise the flow will fail not so gracefully.
Alexa provides standard permission request functionality, the Flow responds to the original call with this detail in a JSON formatted string, with the permissions the Skill wants listed. Finally, for this failure, let the Flow terminate successfully. The Flow can’t continue without the information.
Does Big Energy Co support the user?
It is not enough that the user has asked us for help, they need to be known to Big Energy, as a contact. Querying D365 for this data is the next step
Using the D365 connector, query the contact entity for the email address that Alexa has given us.
A conditional flow checks to see if the return from the Retrieve Contact step has a single record using an expression below
length(body(‘Retrieve_Contact’)?[‘value’])
Responding to the user, quickly
Like any Alexa Skill, the user expects an immediate response. Flow in itself is quick, but when it comes to updating or creating records, it can take seconds. The timeout for your response to Alexa is 10 seconds, which isn’t a lot when you want to look up several things to create the appropriate work order.
To get around this, respond to the user once you know you have all the information you need to create the appropriate records in D365. Here, the Flow responds if the contact is in our database. In production, you could do some more checks or just assume that if the contact is known, the logic could create an opportunity to sell them a contract if nothing else. Equally, terminate gracefully after responding that Big Energy Co doesnt know the customer, prompting them to ring the service desk.
In the switch statement, a response to the user is built up. Specific, personalised responses using the data you have retrieved is essential to give the customer an understanding that you have received the request and will respond.
The responses are short and to the point but personalised to the customer and what they asked for with some expressions to add more information if they told Alexa.
This snippet adds after “request for a Service” what the user asked for a service on, relying on the JSON formatted values.
if(equals(triggerBody()?[‘request’]?[‘intent’]?[‘slots’]?[‘device’]?[‘value’], ‘’), ‘’, concat(’ for your ‘,triggerBody()?[‘request’]?[‘intent’]?[‘slots’]?[‘device’]?[‘value’]))
This snippet adds to the end a sentence including the date that the user asked for.
if(equals(triggerBody()?[‘request’]?[‘intent’]?[‘slots’]?[‘date’]?[‘value’],’’),’’,concat( ‘We will endeavour to send an engineer on ‘,triggerBody()?[‘request’]?[‘intent’]?[‘slots’]?[‘date’]?[‘value’]))
Finally, for the Alexa response part, the Flow returns a response to the user. This combines the body with a little standard text. This is what Alexa will say. You can also add a response to the screen for those devices able to do that.
The final part of this flow goes on and creates the work order. I seperated out the flows using a sub flow, which is discussed in the next part of the blog.