Building Boston RailAN ALEXA SKILL

February 2017

Prepared by Charlie Christinacharlesjchristina@gmail.com617-901-7155

2

Situation

Had an echo, an AWS account and experience with Lambda

Wanted to learn how to develop skills for Alexa

Wanted a reliable and easily accessible source of information on MBTA Commuter Rail Status

Was aware that MassDOT had released an open API for real-time commuter rail updates

Decided to use this learning opportunity to create something new and useful

3

Target

Design and build an Alexa Skill Minimum Viable Product

◦ Provide route alerts◦ Provide real-time status (or Schedule) of specific trips◦ Provide real-time next inbound or outbound status for a given station◦ Provide real-time status on trains travelling from one station to another

Enhancements◦ Personalized Trip Info “My Trip”

4

Actions Register the Skill

Design the Skill

Create the Skill Architecture

Define the Interaction Model◦ Intents◦ Slots◦ Utterances

Develop the Skill

Prepare for Operations

Test

Submit for Certification

Design

Develop

Test

Prepare for Operations

Certify

5

ResultBoston Rail Alexa Skill

Route alerts

Real-time status (or Schedule) for specific trips (Trip Numbers)

Real-time next inbound or outbound status for a given station

Real-time status on trains travelling from one station to another

(Beta) Personalization “My Trip”

6

Action DetailSTEP BY STEP PROCESS FOR CREATING BOSTON RAIL

7

Service Account Type URL Purpose

AWS Account AWS Management Consolehttps://aws.amazon.com/console/

• Build and run skill logic in Lambda function

• Create execution role in IAM• Create and run DynamoDB• Setup and monitor metrics in

CloudWatch

Alexa Developer Account Alexa Developer Portalhttps://developer.amazon.com/alexa

• Create skill interaction model• Link interaction model and skill

endpoint• Test skill• Specify skill publishing info• Submit skill for certification

Prerequisites

Note: An echo device is not required to build and test an Alexa skill (though it is helpful to fully test the user experience)

8

Alexa Skill ArchitectureThe Basics

Voice IO

• Echo• Echo Tap• Echo Dot

Voice Service & Skill Interface

• Intents• Slots• Utterances

Skill Service

• Lambda• HTTPS

Endpoint

Backing Services

• DynamoDB• CloudWatch• MBTA API

9

Process Summary (AWS and Alexa Skills Steps)Skill Configuration

4. Add a New Skill on Alexa Developer Portal and get app id (Requires Alexa developers account)

5. Link the Skill to the Lambda Service Endpoint (Lambda ARN)

6. Define Interaction Model (Intent Schema, Custom Slots and Sample Utterances)

8. Testinga) Unit Test with Alexa Service Simulatorb) Integration Test with Echo

9. Prepare for Publication & Certification

11. Submit for Certification

Skill Development1. Define the Minimum Viable Product and Solution

Architecture to Support the MVP2. Create Lambda execution role3. Build the Lambda endpoint(at least a shell of one)

7. Iteratively Build and Test the Lambda Function (Unit test with Lambda test utility)

10. Prepare for Operations

12. Continuous Integration/Continuous Deployment

10

Step 1. MVP & ArchitectureWhat is the minimum viable feature set? What requests will the skill support?

Solution Capabilities

Which AWS services, programming language and SDKs will be used?

Solution Architecture

How will solution be monitored in production? What metrics will be monitored?

Solution Operations

How will updates, enhancements and fixes be managed with zero downtime in production?

CI/CD

11

Architecture - Solution Capabilities Minimum Viable Product

◦ Provide route alerts◦ Provide real-time status (or Schedule) of specific trips◦ Provide real-time next inbound or outbound status for a given station◦ Provide real-time status on trains travelling from one station to another

Enhancements◦ Personalized Trip Info “My Trip”

12

Boston Rail Solution ArchitectureVoice I/O: Amazon echo

Cloud Voice Service: Amazon Alexa

APIs/Tools: Alexa Skills Kit

Serverless Compute: AWS Lambda

Information Source: MBTA Real-time API

Personal Trip Data Store: AWS DynamoDB

AWS SDK: Boto 3 for Python

HTTP Requests: Requests library for Python

13

Boston Rail Operations Architecture

Logs: AWS CloudWatch

Metrics & Dashboard: AWS CloudWatch

Alarms: AWS Cloudwatch Alarms

Notifications: AWS SNS

14

CI/CD Toolkit

DevelopmentEclipsePython

Source ControlTortoise

GitBitBucket

TestingLambda Test

Skill SimulatorEcho

DeploymentCloudFormation

Alexa Skill Toolkit

15

Steps 2-5. Create Endpoint and Skill (and Link Them)

Create Skill4. Add a Skill (get application id)Get Started->Add a New Skill->Skill Information->Save

5. Configure Skill (link to Lambda)Configuration (Copy the arn for your Lambda function from Step 3)

Create Endpoint2. Create Lambda Execution RoleIAM->Roles->Create New Role

3. Create Lambda Function StubLambda->Functions->Create a Lambda Function->Blank Function

16

Anatomy of The Lambda Execution Role Policy

Allows Lambda function to create CloudWatch Log Group and Log Stream as well as write log events.

IAM > Policies > AWSLambdaBasicExecutionRole

17

Step 6. Define Interaction Model

Intents• Represent an action that

fulfills a user’s spoken request

• Intents always have at least one property – intent (the name of the intent)

• One can use built in intents and define custom intents

• Intents can (optionally) include an additional property called slots

Slot Types• Slots are optional

arguments that are passed to intents.

• Slots types contain lists of possible values to be sent to an intent.

• One can use built in slots and custom slot types

Utterances• Sample utterances map

phrases (that a user can speak) to intents and slots

18

Boston Rail Intent Schema Snippet Custom Intent

◦ GetStationToStationIntent◦ Custom Slot Type

◦ LIST_OF_STATIONS

Built In Intent◦ AMAZON.HelpIntent

{ "intents": [ {

"intent": "GetStationToStationIntent", "slots": [ { "name": "FromStation", "type": "LIST_OF_STATIONS" }, { "name": "ToStation", "type": "LIST_OF_STATIONS" } ] },

◦ { "intent": "AMAZON.HelpIntent" } ] }

19

Step 7: Develop Service Endpoint (Lambda Function)

Key Element Description

Lambda Handler Entry point to service endpoint. Orchestrates interaction with Alexa Service based on input from user.

App Id Check The first action the lambda handler should perform is an app id check (to verify that the request is meant for this skill). The app id was generated in Step 4.

Welcome Response A function that returns a message to the user whenever a new session is started.

Session Starter A function to take any actions required when a session starts.

Intent Manager A function to determine which function should be invoked for a given intent.

Intent Functions These functions are the heart of the skill. They define what a skill will do in response to user utterances.

Response Builder A function to build the response to be returned to the Alexa Service

Session Ender A function to take any actions required when a session ends.

In this step, we flesh out the details of the Lambda function stub created in Step 3.

20

Boston Rail Response Structure{ "version": “string", "sessionAttributes": { “string”: object, } "response": { "outputSpeech": { "type":“string", "text": “string” }, "card": { "type": “string", "title": “string”, "content": “string” }, "reprompt": { "outputSpeech": { "type":“string”, "text": “string” } }, "shouldEndSession": boolean }}

Response to request. If session remains open, response must also include a prompt to the user.

Session attributes to maintain state during a conversation with the user.

Title and response presented in the companion app.

Additional prompt to user if session remains open and user takes more than x seconds to respond.

Determines if the session will remain open. Best practice requires that the session be closed if a response is provided without a prompt for additional information.

21

Sample Boston Rail Response{ "version": "1.0", "response": { "outputSpeech": { "type": "PlainText", "text": "OK, departing from Ashland, to which station are you heading?" }, "card": { "content": "OK, departing from Ashland, to which station are you heading?", "title": "Boston Rail Train Station Status - Departure", "type": "Simple" }, "reprompt": { "outputSpeech": { "type": "PlainText", "text": "to which station are you heading?" } }, "shouldEndSession": false }, "sessionAttributes": { "FromStation": "Ashland", "intent": "GetArrivalStatusIntent" }}

Response to request – since this is a conversation, the response includes a prompt for additional information.

Custom session attributes to maintain state during a conversation with the user.

Card title and response presented in the companion app.

Additional prompt to user if session remains open and user takes more than x seconds to respond.

Session will remain open to listen for additional input from the user

22

Step 8: Testing Lambda Function Testing

Lambda-Functions->{Function}->Actions->Configure Test Event Skill Simulator Testing

Get Started->{Skill}->Development->Test

Integration TestingPrior to certification, a skill can be accessedvia the echo device that is linked to thedeveloper account associated with the skill.

DebuggingCloudWatch->Log Groups->Streams for /aws/lambda/{Lambda Function}

23

Step 9: Prepare for Publication & CertificationTask Description

Prepare Testing Instructions

Simple instructions to the certification team to guide their testing efforts.

Select countries to publish skill

Identify the countries where your skill will be published.

Write Short Skill Description

Description that displays in the Alexa skills list

Write Full Skill Description Detailed description of the skill that will appear in the Alexa app

Write example phrases Three phrases to help orient user to use of the skill. These will likely be the first phrases a user utters and will be tested by the certification team.

Define keywords Keywords to help users find your skill in the skills store.

Upload images Images that will be displayed in the skill list and skill detail in the Alexa app

Answer privacy and compliance questions

Financial transactions, personal information, targets children, export compliance

Submit for Certification Once a skill is submitted for certification, the skill cannot be modified in the developer portal.

24

CloudFormation• Create Execution Role• Create Skill Lambda Function• Create DynamoDB• Set Environment Variables• Create Stack

CloudWatch• Skill Logs• Skill Metrics• Skill Dashboard

CloudWatch Alarms• Exception Alarm• Error Alarm

SNS Topic• Delivery of Exception Alarms• Delivery of Error Alarms

Step 10: Prepare for Operations

25

After 1st CertificationInitial Dev

Step 11: Continuous Integration/Continuous Development

After a skill is certified, it will be made publicly available in all countries that you specified when publishing the skill (and cannot be edited)

Amazon/Alexa will also create a development version of the Alexa skill in the Alexa Developer Portal◦ This version of the interaction model can be modified.◦ The development version is tied to the same Alexa ID as production◦ However, it can be manually linked to a different instance of a Lambda function◦ For zero downtime deployments, the following blue/green deployment model is followed

◦ Odd numbered deployments link to “blue” Lambda instance when line.◦ Even numbered deployments link to “green” Lambda instance when live.

Boston Rail (Dev)

Lambda (Blue)

Boston Rail (Live)

Lambda (Blue)

Boston Rail (Dev)

Lambda (Green)

After 2nd Certification

Boston Rail (Live)

Lambda (Blue)

Boston Rail (Dev)

Lambda (Green)

26

Lessons Learned Decompose complex/multi-part utterances into a conversational interaction

◦ Conversational Design Pattern◦ Command Design Pattern (to provide a shortcut to a conversational interaction or interrupt a conversation in

progress)

Copyright◦ If using third party services, provide Amazon Alexa certification team with licensing agreement or proof of right to

use. Without this, certification team will fail the skill.

Include all slots for a given intent in sample utterances◦ If a slot is specified in the intent schema but not used in a sample utterance for the intent, the certification team

will fail the skill.

Ensure published sample utterances are represented in interaction model◦ Certification team will check for this and fail certification if published utterances are not included in interaction

model.

Never leave a session open without a prompt to the user◦ Certification team will fail the skill if sessions remain open without a prompt to the user.

27

Challenges

Testing new releases after first production release• Create dev/test Lambda endpoint (blue/green deployments)• Run Lambda locally

Code Coverage Testing with Lambda• Run Lambda locally

Automated regression testing• TBD