1.
Building Boston Rail
AN ALEXA SKILL
February 2017
Prepared by Charlie Christina
charlesjchristina@gmail.com
617-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
2

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”
3

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
4
Design
Develop
Test
Prepare for
Operations
Certify

5.
Result
Boston 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”
5

6.
Action Detail
STEP BY STEP PROCESS FOR CREATING BOSTON RAIL
6

7.
Service Account Type URL Purpose
AWS Account AWS Management Console
https://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 Portal
https://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
7
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 Architecture
The Basics
8
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)
9
Console Task Type Task
Skill Development 1. Define the Minimum Viable Product and Solution Architecture to Support the MVP
Skill Development 2. Create Lambda execution role
Skill Development 3. Build the Lambda endpoint(at least a shell of one)
Skill Configuration 4. Add a New Skill on Alexa Developer Portal and get app id (Requires Alexa developers account)
Skill Configuration 5. Link the Skill to the Lambda Service Endpoint (Lambda ARN)
Skill Configuration 6. Define Interaction Model (Intent Schema, Custom Slots and Sample Utterances)
Skill Development 7. Iteratively Build and Test the Lambda Function (Unit test with Lambda test utility)
Skill Configuration 8. Testing
a) Unit Test with Alexa Service Simulator
b) Integration Test with Echo
Skill Configuration 9. Prepare for Publication & Certification
Skill Development 10.Prepare for Operations
Skill Configuration 11.Submit for Certification
Skill Dev/Config 12.Continuous Integration/Continuous Deployment

10.
Step 1. MVP & Architecture
What 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
10

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”
11

12.
Boston Rail Solution Architecture
12
Voice 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
13
Logs: AWS CloudWatch
Metrics & Dashboard: AWS CloudWatch
Alarms: AWS Cloudwatch Alarms
Notifications: AWS SNS

14.
CI/CD Toolkit
14
Development
Eclipse
Python
Source Control
Tortoise
Git
BitBucket
Testing
Lambda Test
Skill Simulator
Echo
Deployment
CloudFormation
Alexa Skill Toolkit

15.
Steps 2-5. Create Endpoint and Skill (and Link Them)
Create Skill
4. 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 Endpoint
2. Create Lambda Execution Role
IAM->Roles->Create New Role
3. Create Lambda Function Stub
Lambda->Functions->Create a Lambda Function->Blank Function
15

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.
16
IAM > Policies > AWSLambdaBasicExecutionRole

17.
Step 6. Define Interaction Model
17
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"
}
]
}
18

19.
Step 7: Develop Service Endpoint (Lambda Function)
19
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
}
}
20
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"
}
}
21
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
22
Integration Testing
Prior to certification, a skill can be accessed
via the echo device that is linked to the
developer account associated with the skill.
Debugging
CloudWatch->Log Groups->Streams for /aws/lambda/{Lambda Function}

23.
Step 9: Prepare for Publication & Certification
23
Task 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
24

25.
Boston Rail Dashboard
25

26.
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.
26
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)

27.
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

28.
Challenges (and solutions)
28
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
Detailed Log Analytics
• AWS Elastic Map Reduce
Automated regression testing
• TBD