Instructions for running an AWS Skill

Overview

Alexa skills require a multi-step process to go from Java source to compiled code running in the AWS cloud. The steps described in this document are as follows:

1. Getting the source code
2. Building the project
3. Creating a Lambda function
4. Creating an Alexa skill
5. Testing the skill

In addition, there are a few prerequisites not described in this document:

• git client (technically optional, but you are going to need one sooner or later!)
• development environment (described elsewhere)
• Amazon Web Services and Amazon Developer accounts
• aws-cli on the command line or the AWS Toolkit for Eclipse are recommended but optional

Where multiple methods of accomplishing the same task exist, choose only one:

On the command line (Gradle)

If you do it on the command line using gradle...

On the command line (Maven)

... don't do it again with maven...

In Eclipse

... and don't do it again in Eclipse.

These instructions use https://github.com/jneong/CS370_Echo_Demo as the example code, but the steps should be similar for most Alexa skills written in Java.

Getting the Source Code

On the command line

Navigate to the directory where you want the project. Clone the repo, then move into the Template_Skill directory within the project:

git clone https://github.com/jneong/CS370_Echo_Demo
cd CS370_Echo_Demo/Template_Skill

In Eclipse

1. Go to https://github.com/jneong/CS370_Echo_Demo. Click the green Clone or Download button and then click Download ZIP.

Building the Project

On the command line (Gradle)

Run Gradle for the fatJar task to build the project and package it with all the dependencies into a JAR:

gradle fatJar

When the command completes, the JAR will be located at ./build/libs/Template_Skill-fat-1.0.jar.

On the command line (Maven)

Run Maven to build the project and package it with all the dependencies into a JAR:

mvn assembly:assembly -DdescriptorId=jar-with-dependencies package

When the command completes, the JAR will be located at ./target/Template_Skill-1.0-jar-with-dependencies.jar.

Note: This command is specified in Template_Skill/README. Packaging the JAR without including dependencies will cause the skill to fail when run in the AWS cloud.

In Eclipse

1. Copy the Template_skill folder to the workspace folder that Eclipse creates to hold projects (usually found at C:\Users\Your_Name\workspace).

2. Open Eclipse and click File > Import

3. In the window that appears, choose Maven and then Existing Maven Projects. In the next window, set the directory to the "Template Skill" folder that was downloaded from Github, or whichever folder has the pom.xml file. Then click finish.

4. In the Navigator window on the left side of eclipse, right click the Template_skill folder. Go to "Run As" then "4 Maven Build..."

5. In the Goals text box, type in "package shade:shade" without the quotes. Then press Run.

6. The .jar file will be in Template_skill/target/ folder. This is what you upload to AWS. If there are two versions of the .jar file and one says "original" in the name, use the other one. The "original" file will also be much smaller in file size.

Creating a Lambda Function

On the command line

TODO

In Eclipse

TODO

In the browser

Navigate to the Lambda page of the AWS console for the North Virginia region (Alexa is only available in the us-east-1 region at this time) here and create a new Lambda function. If this is your first Lambda function, press the blue "Get Started Now" button.

1. Select blueprint

• There are no blueprints for Alexa skills in Java, so skip the blueprint step.

2. Configure triggers

• Click the empty box outline and select the "Alexa Skills Kit" trigger.

3. Configure function

• Name the function something clever, like "knock_knock", and optionally give it a description.
• Select the "Java 8" runtime.
• For the code entry type, choose "Upload a .ZIP or JAR file" and click the "Upload" button to browse to your copy of the project and select the Template_Skill/target/Template_Skill-1.0-jar-with-dependencies.jar file.
• The handler for this skill is defined in src/main/java/com/neong/voice/handler/TemplateSpeechletRequestStreamHandler.java. As described in the comment within that file, the signature of the handler is com.neong.voice.handler.TemplateSpeechletRequestStreamHandler.
• If you have created a role for Lambda execution already, select that role. Otherwise, to create a role:
  1. Select the option to "Create a custom role"
  2. In the new page that pops up, confirm the IAM Role is "Create a new IAM role"
  3. Press "Allow" at the bottom right of the screen to create the role
  4. You will be returned to the Lambda wizard where the Role will have changed to "existing" and the Existing role will be the name of the role you created.
• The knock knock joke skill has minimal resource requirements, 128MB should be plenty.
• The default timeout is acceptable, but it could be lower. Keep in mind that setting the timeout too low could cause your function to fail if it does not complete execution within the timeout period.
• Selecting a VPC is optional. The default "No VPC" is fine.

4. Review

• Confirm the fields, then click "Create function" to create the Lambda function.

When the function is finished processing, make note of the ARN in the top right of the function's page. It looks like arn:aws:lambda:us-east-1:${your_id}:function:knock_knock.

Creating an Alexa Skill

Navigate to the Alexa Skills Kit page of the Amazon Developer console and click the yellow "Add a New Skill" button at the top right of the page.

1. Skill Information

• Leave the Skill Type set to the "Custom Interaction Model" option.
• Name the skill something presentable, for example "Knock Knock".
• Choose a name for users to speak when using your skill, like "the joker".
• We do not need to play audio.

2. Interaction Model

• An intent schema is supplied for the example in Template_Skill/src/main/java/speechAssets/IntentSchema.json.
• Sample utterances are listed in Template_Skill/src/main/java/speechAssets/SampleUtterances.txt. Remove the comment line.
• Select the "Lambda ARN" endpoint and paste the ARN noted from the previous step into this field.
• Leave Account Linking set to "no".

Testing the Skill

For the utterance, enter:

tell me a joke

and press "Ask Knock Knock" to see the result.