ServiceNow/Amazon Echo Integration (Updated for K17)

Version 3

    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:

    IntentsUtterances

    {

      "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:

    IncludesPurpose
    EchoConversationUsed for showing a Conversation in the Echo Service Portal. Primarily for demo purposes.
    EchoLogLogs data in the Log table. Logs are tied to a session. Each Session has an inbound and outbound log activity.
    EchoPortalUtilsPortal 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()

    EchoSkillDataGeneratorUsed for generating Intent and Utterance schemas from the Intent list
    IntentUtilA 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!!

    Solution Consultant - ServiceNow