Hey everyone!
Using the awesome power of our ServiceNow platform combined with Amazon Echo skill kit APIs, I've created an Amazon Echo integration using ServiceNow.
If you were at Knowledge 16 you may have already seen this once before. This is a new and improved version building on the capabilities of K16.
If you're interested in Integrating ServiceNow with Amazon Echo, here is how to do it!
1. Create an Amazon Developer Account
This is a required step for integrating ServiceNow with Amazon Echo. The first thing that is needed is a Developer account on Amazon. These are free and easy to set up.
2. Create an Alexa Skill
Navigate to your Alexa Skill Kit and define an Alexa skill for your ServiceNow integration. Below are the minimum required fields when setting up your Alexa Skill to integrate with your instance. Follow the bolded headers below that align with tabs on your Alexa Skill.
Skill Information:
Give your skill a name, and an invocation name (the words that wakes up your skill)
Interaction Model:
This defines the words and Phrases that trigger interactions within your ServiceNow instance. For now, we can mostly leave this blank. Follow the screenshot below to set up a starter Interaction model.
Configuration:
Make sure these fields are set as they are in the screenshot. For the endpoint, make sure you set the endpoint to be https://YOURINSTANCENAME.service-now.com/api/x_snc_amazon_echo/alexa
SSL Certificate:
Test:
Make sure the skill is enabled.
The Publishing Information and Privacy tabs can be left blank.
3. Load the App
Now that the Alexa skill has been created, the app needs to be loaded onto your instance. There are a few ways to get the app.
GitHub (Preferred😞 This will ensure you have the latest and greatest version and is the preferred method to get the app. GitHub - JonCraneNOW/SN_Echo_Integration: ServiceNow integration for Amazon Echo.
Update set - Attached: Load this update set into your instance, preview and commit. The app will come with the update set.
When the app is loaded into your instance, you will see this Application Menu available:
4. Design your interaction model
The interaction model within Alexa and ServiceNow consists of Intents and Utterances.
Utterances: These are spoken words to 'listen' for in your applicaiton. When an Utterance is heard, an Intent is executed against the endpoint.
Intents: These contain the spoken data mapped to a phrase and are sent to the endpoint.
To design your intents within ServiceNow, navigate to All Intents, and click New. The below example reads off a list of outages when asked.
Intent API Reference:
Current - Fields available on the intent record.
Content - Data that was heard and passed back to the intent. For example, if you ask a user to describe the cause of their issue when creating an incident with Alexa, the spoken dialog would be sent as Content.
Attributes - Data and various flags to send along with a user session. For example, if a user wants to interact with a Request record (Hear the request, approve it, escalate it) you may wish to pass the request number as an attribute.
ER - EchoResponse object. This object contains methods used for building a response to send back to Amazon Alexa skills.
IntentUtils - This script can be modified to add your own Utility functions, such as string manipulation, frequently-used queries, etc.
Here's a sample Intent script to use. This will read off a welcome message when asked to "Open ServiceNow".
---
(function(current, content, attributes, ER, IntentUtils){
ER.setOutputSpeech(current.output_speech_format, "Welcome to the ServiceNow Alexa app. What can I help you with? For a list of commands, say 'Help'.", "");
ER.setEnd(current.intent_ends_session);
result = ER.response; //Required
})(current, content, attributes, new EchoResponseBuilder(), new IntentUtils());
---
Other fields to set:
Intent Keyword: LaunchRequest
Output Speech Format: PlainText
Submit your Intent.
In the Related List for Phrases, add a few phrases that you would like your Alexa skill to map to this intent. Include as many phrases as you need. Keep in mind that people could ask to "Hear a list of outages" in several different ways, so you must account for these when setting up your skills.
The Phrase is what a user would ask Alexa to hear the output of the intent. Active determines whether this phrase is used. Primary is used for the portal that comes with the app. If no Phrase is set as primary, the portal displays the intent name.
The above step is not required for a "LaunchRequest" intent
5. Build the schema
After you have defined all of your intents, and their phrases, you are ready to add them to your Alexa skill and test them.
Navigate back to your list of intents. You will notice two buttons in the list for Generating Intent Schema dn Utterances. Clicking on each will give you a list of Intents (JSON-formatted) and Utterances you can use. These can simply be pasted into your Alexa Skill Interaction Model.
Go back to your Amazon Developer account, find your Alexa skill, and paste the Intent Schema and then the Utterances into your Interaction model. Save your Amazon skill.
For reference, here is what a sample Intent and Utterance Schema COULD look like:
| Intents | Utterances |
|---|---|
{ "intents": [ { "intent": "CreateIncidentIntro" }, { "intent": "ServiceInterruptions" }, { "intent": "CriticalVulnerabilities" }, { "intent": "CriticalSecurityIncidents" }, { "intent": "SecurityThreatStatus" }, { "intent": "SecurityIncidents" }, { "intent": "PortfolioStatus" }, { "slots": [ { "name": "Description", "type": "AMAZON.LITERAL" } ], "intent": "CreateIncident" }, { "slots": [ { "name": "Name", "type": "AMAZON.LITERAL" } ], "intent": "CreateIncidentGetName" }, { "intent": "CheckStatus" }, { "slots": [ { "name": "Number", "type": "AMAZON.NUMBER" } ], "intent": "CheckStatusInc" }, { "intent": "WhatsHappening" }, { "intent": "WhatsHappeningOutages" }, { "intent": "WhatsHappeningIncidents" }, { "intent": "WhatsHappeningChanges" }, { "intent": "MyRequests" }, { "intent": "ThisWeeksChanges" }, { "intent": "MyApprovals" }, { "intent": "Help" }, { "intent": "AMAZON.StopIntent" }, { "intent": "AMAZON.HelpIntent" } ] } | CreateIncidentIntro Create an incident CreateIncidentIntro Create incident ServiceInterruptions What are the service interruptions ServiceInterruptions Are there service interruptions ServiceInterruptions Are there any service interruptions CriticalVulnerabilities Hear Vulnerable Items CriticalVulnerabilities Hear the Vulnerable Items CriticalVulnerabilities Hear Vulnerabilities CriticalSecurityIncidents Critical security incidents CriticalSecurityIncidents Hear the critical security incidents CriticalSecurityIncidents Hear Critical Security Incidents SecurityThreatStatus Hear the security threats SecurityThreatStatus Hear Security Threats SecurityThreatStatus Are there security threats SecurityThreatStatus Are there any security threats SecurityIncidents Hear Security Incidents SecurityIncidents Security Incidents SecurityIncidents Hear the Security Incidents PortfolioStatus IT Operations Portfolio Status PortfolioStatus Status of the IT Operations portfolio PortfolioStatus Hear the status of the IT Operations Portfolio PortfolioStatus Whats the status of the IT Operations Portfolio CreateIncident my problem is {Generic issue description|Description} CreateIncident my issue is {Genericissuedescription|Description} CreateIncidentGetName my name is {John Smith|Name} CheckStatus Check incident status CheckStatus Check the status of an incident CheckStatus Check an incident status CheckStatus Incident status CheckStatusInc I. N. C. {Number} WhatsHappening Whats Happening WhatsHappening Whats Happening Today WhatsHappening Whats going on Today WhatsHappeningOutages Hear Outages WhatsHappeningOutages Hear the Outages WhatsHappeningIncidents Hear Incidents WhatsHappeningIncidents Hear the Incidents WhatsHappeningChanges Hear Changes WhatsHappeningChanges Hear the Changes MyRequests My requests ThisWeeksChanges This weeks changes ThisWeeksChanges Changes this week Help help AMAZON.StopIntent nevermind AMAZON.StopIntent Nevermind AMAZON.StopIntent never mind AMAZON.StopIntent cancel AMAZON.StopIntent stop |
6. Try it out!
Ask Alexa to "Open ServiceNow". You should hear a friendly message!
If you get an error, make sure you have an Utterance that maps to an Intent in your Alexa Skill. Then, make sure you have an Intent defined in ServiceNow with Phrases for that intent. Finally, make sure your script is free of errors.
Other important stuff!
Script Includes:
| Includes | Purpose |
|---|---|
| EchoConversation | Used for showing a Conversation in the Echo Service Portal. Primarily for demo purposes. |
| EchoLog | Logs data in the Log table. Logs are tied to a session. Each Session has an inbound and outbound log activity. |
| EchoPortalUtils | Portal stuff. Add your own portal functions here if you would like to extend that capability. |
| EchoRequest | Called from the Scripted REST API. This is the primary Class that handles requests, processes intent records and returns a response. |
| EchoResponseBuilder | The Method for building Echo responses. The following functions can be used to construct a response: setAttributes(obj) setOutputSpeech(type String, text String, ssml String) setCard(type String, title String, content Obj, text String, imageObj Obj) setReprompt(type String, text String, ssml String) setEnd(endSession String) getResponse() |
| EchoSkillDataGenerator | Used for generating Intent and Utterance schemas from the Intent list |
| IntentUtil | A Utility class for performing various functions such as string manipulation, date/time manipulation, or anything else. Add custom functions here. |
Documentation:
In the event that you hit a roadblock with your skill, consult the thorough Amazon documentation here!
Alexa Skills Kit Custom Interaction Model Reference - Amazon Apps & Services Developer Portal
Speech Synthesis Markup Language (SSML) Reference - Amazon Apps & Services Developer Portal
Define the Interaction Model in JSON and Text - Amazon Apps & Services Developer Portal
** IMPORTANT NOTE **
If you import the attached update set and see problems when you preview, you can SKIP them. This is because some of the functionality I used for the Knowledge 17 demo references data in tables that may not be enabled in your instance! These preview problems can be ignored.
Enjoy!!
