Domain App Using Amazon S3 as Data Source
Goal:
Our goal is to help users explore the functionality of the VoiceWorx platform without requiring integrations with any external platform. We will create an Alexa Skill named “Retail Demo”. Retail Demo is an app set aimed for retail customer and retail customer service provider. We will be using a json data source and perform data retrieval operations on them.
Steps:
The following shows the general steps/activities that will be carried out in setting up this integration. Note: It is advisable to use same email for signup across the 3 channels below. Step 1 -3 below are required.
Ensure you Login with Amazon (LWA) account is setup by your admin. If you are the account admin, you can follow this instruction to set it up.
Set up connection to the json data source on Amazon S3
Create a custom skill in VoiceWorx.
Publish the skill
Test the Alexa skill.
Prerequisite:
An active AWS Account
You should have an active AWS Account. If you do not have it, you can create an AWS account at https://portal.aws.amazon.com/billing/signup#/start
AWS Accounts Include 12 Months of Free Tier Access
A VoiceWorx Account
For steps to create a VoiceWorx account, follow the steps at https://docs.voiceworx.ai/general/voiceworx-create-account
Access Key, Secret access key and AWS Region Name To be able to connect to Amazon Lex from the VoiceWorx platform, one IAM user is required and user should have the required permissions to access Lex service.
Following is a json document which you can use to create an IAM policy and assign it to the IAM user in the AWS console.
For more information on creating IAM users and assigning policies, refer to the AWS official documentation https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/
You can also refer to the simplified VoiceWorx documentation at https://docs.voiceworx.ai/aws-iam-users
The user shall have Amazon console account, with permission for S3 data. S3 is used as a storage for the json data file, which the domain skills use as a data source. You can get guidance for S3 json data source creation here.
Set Up Connection to External Web API
To begin, login to the VoiceWorx platform https://portal.voiceworx.ai/ .
On the left navigation menu do the following:
Click: Integration
Select: Connect System
Click: Connect External Systems
In the resulting popup, choose:
Select External System: Custom
Select System Type: Amazon S3
Add the following in the Amazon S3 Instance Configuration:
Service Instance Name: This can be any name you choose. (Remember name as you will need this for step #16).
Consumer Key: If you do not have a Consumer Key or Consumer Secret follow step 12 to gain Access Keys.
Consumer secret: If you do not have a Consumer Key or Consumer Secret follow step 12 to gain Access Keys.
Region: See print screen below to locate your region if you are unsure of this information.
Click: Validate and Save Settings.
You can access your Consumer Key and Consumer Secret from your AWS management console.
If you are unsure of your region, it is also located in the AWS Management Console.
Download the key file and keep it safe for future use.
Create Custom Skill in Voiceworx.ai
To create a custom app in VoiceWorx:
Click: Custom Apps in left navigation menu.
Select: Manage Apps
Click: Create New Custom App button
Then complete the following steps:
Name: Retail Demo
Custom Skill Type: Search
Category: None
Click: Save
In the top menu select “Data Sources” tab, then select “Create New Data Source”.
Enter the following in the fields:
Name: Retail DS
Integration Configuration: Amazon S3- Select the instance created in Step 11 to create the Amazon S3 integration.
Click: Save
In the top menu select “Methods” tab, then “Create New Methods”.
Enter the following in the fields:
Method Name: GetProductInfoMethod |
Request Type: GetFileContents |
Parameters: BucketName, FileName. Bucket name and filename shall match the one that are in Amazon S3. |
Result Type: ListofRecords |
Record JsonPath: $.productCatalog[?(@.productName=="{{ProductName}}")] |
Empty Result Template: I'm sorry, I could not find your product. |
Result Template: Here is what i found for {{Input.ProductName}} :{{Records}} |
Record Template: Price : {{price}}, restock amount: {{restockAmount}}, discount : {{discount}} and tax: {{tax}}, |
After the method has been created, let us test it.
If you observe the following result in your Test Result tab, your method build is successful. You can now proceed to the next step. Otherwise, you might want to re-check your previous steps first. Since method defines the functionality of the App, this is a very crucial step.
In the top menu select “Intent” tab and “Create New Intent”.
Make sure to select the same method you created on Step 16.
Name: GetProductInfoInput
Intent Type: Search
Intent Action: Execute Method
Data Source: Retail DS
Data Source Method: GetProductInfoInput
Click: Save
In the top menu select “Slots” tab, select “Create New Slot”.
Note the Reprompt message is what Alexa will ask if it can’t fill/resolve the person slot.
Name: ProductName
Slot Order: 1
Reprompt Message: what’s the product name
Type: Text
Skill: Retail Demo
Intent: GetProductInfoInput
Click: Save
In the top menu select “Utterance” tab, then select “Create New Utterance”. Utterance are words spoken to launch specific intents.
Value: find product
Custom Skill: Retail Demo
Intent: GetProductInfoInput
Click: Save
In the top menu select “Input”, then select “Create New Input”.
Fill the following details:
Name: GetProductInfoInput
Description: (leave blank)
Custom Skill: Retail Demo
Custom Intent: GetProductInfoIntent
Data Source: Retail DS
Data Source Method: GetProductInfoMethod
Click: Save
Add parameters for the Custom Input GetProductInfoInput.
The Parameter drop down shall select the corresponding parameter described in Method section.
Publish to Alexa
To publish to Alexa, create an app publishing. Select the publishing tab and click “Add App Publishing” button.
Fill the following fields:
External Skill Name: For instructional purposes we used “Retail Demo”, but this will be the name you create the skill in Alexa. Therefore, make it unique and different from the names of your other skills in Alexa.
Skill Type: Search
Channel: Alexa
Uncheck the following: Require account linking
Auto Publish: Check Auto Publish
Skill Invocation: For instructional purposes we used “retail assistant”. This will be what users say to launch your skill in Alexa. It must be in lower case alphabets cannot contain START, BEGIN, STOP, EXIT, LAUNCH and cannot contain number or special characters.
Welcome Message: Welcome to Retail Demo. How can I help you?
Reprompt Message: Find the nearest store. How else can I help you?
Help Message: Replace with sample request
Optional: Replace all placeholder values in all “Message”
Uncheck all the settings shown in the second image below.
Click: Publish
Now, Publish to Alexa.
Select the LWA account setup by your admin and click the “Publish To Alexa” button.
On the Alexa skill page, ensure “Full Build Successful” message is shown before starting to test skill.
Go to “test” tab and change the skill test status to from “Off” to “Development”.
Invoke skill by typing the invocation name inserted in the publishing step in VoiceWorx. If the invocation is successful, your configured welcome message will be displayed in the developer console.
Congratulations! You have successfully created a domain app using S3 data.
Last updated
