Domain App using Internal Data
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 App 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.
Create Content Categories, Content using the json data sources.
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
Creating Content Categories and Contents
Contents can be text, media files (video, audio, image, pdf), json data that are either uploaded to the VoiceWorx platform or are provided public URL of the corresponding files. These can be accessed using Internal Data connection facility provided by the platform for use in skill building. Content Categories allow the grouping of contents based on their domain similarity. For this tutorial, we will be uploading json data files to VoiceWorx, create Content using them, and later, these contents will be used in skill building.
To begin, login to the VoiceWorx platform https://portal.voiceworx.ai/ .
On the left navigation menu do the following:
Click: Content
Select: Content Categories
Click: Add New Category
In the resulting popup, choose:
Enter Content Category: Retail Domain
Enter Description: Content category for retail domain,
Click: Save
Now, let’s create content. On the side menu do the following:
Click: Content
Select: Content
Click: Add New Content
The following pop up will appear. Enter details to create a content:
Content Name: Retail
Content Code: Retail
Content Category: Retail Domain
Text: Content for Retail Data Source
Select: Media
Media Type: Select JSON
Media Source: Select Upload File
Media File: For sample data, you can download Retail.json. Copy and the data sample in a notepad and save it as a json file. Name it as “Retail.json”. Click on Choose File and select “Retail.json” file from your system.
Click on Add button. This shall upload Retail.json to VoiceWorx platform. Users are required to keep record of Content Name, Content Code and Content Category, for later use in the skill building.
You can also select Media URL as the media source and provide a public URL of the media file.
For more information on creating a content using JSON File, you can refer to this document.
Creating Data Source
To access the content created in Step 2, we require to create a connection configuration. On the side menu:
Click: Integration
Select: Connect System
Click: Add New Connection
Enter the following details in the pop-up window:
Select Integration Category: Custom
Select System Type: Internal Content
System Instance Name: Internal Content DS
And click Connect System.
Create Custom App in Voiceworx.ai
To create a custom App in VoiceWorx:
Click: Custom Apps in menu.
Select: Manage Apps
Click: Create New Custom App button
Then complete the following steps:
Name: Retail Demo
Custom Skill Type: Search
Category: Retail Domain, same as the content category in Step 3.
Click: Save
In the top menu select “Data Sources” tab, then “Create New Data Source”.
Enter the following in the fields:
Name: Retail DS
Integration Configuration: Internal Content: Internal Content DS.
Click: Save
In the top menu select “Methods” tab, then “Create New Methods”.
Enter the following in the fields:
Name: GetProductInfoMethod
Request Type: GetJSONContents
ContentID: Retail. ContentID shall match the name of the content uploaded in Step 12.
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 customer service”. 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 resulting screen, ensure that a Success message shows for the publishing steps before clicking the “Go To Alexa Skill”. If success message is not shown, return to Skill Publishing to fix any issue shown in publishing result.
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 Internal data.
Last updated
