DynamoDB
Objective
This guide will help you to quickly connect to Amazon DynamoDB and create various methods to pull the data. The purpose is to demonstrate how easy it is to integrate an external database to the VoiceWorx platform.
Pre-requisites
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
At least one DynamoDB table
If you do not have any DynamoDB table, you can create one quickly.
Login to AWS Management Console at https://console.aws.amazon.com/
Go to Services > Database > DynamoDB and create a table.
For more detailed information, you can refer to the AWS official documentation https://aws.amazon.com/getting-started/hands-on/create-nosql-table/
Provide the table Name as ‘Contacts’, and Primary Key as ‘Id’ and click on Create Table.
Now add the attributes for the table. For our demo purpose, we are going to add 3 attributes: Id, PhoneNumber and Name, all of type string. Provide a default value for the attribute that you have set as Partition Key and click on Create Item.
Select the created table, Click on Actions and click on Create Items. Select Items in the left navigation, Select Contacts table and click on Create Item.
You can repeat the process to add few more data. e.g.
{
"id": 2,
"Name": "Mike",
"PhoneNumber": "123-456-1234"
}
Access Key, Secret access key and AWS Region Name To be able to connect to Amazon DynamoDB from the VoiceWorx platform, one IAM user is required and user should have permissions to view/add/edit/delete DynamoDB data. It is recommended to have IAM policy named AmazonDynamoDBFullAccess be assigned to the user.
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
A VoiceWorx Account
For steps to create a VoiceWorx account, follow the steps at https://docs.voiceworx.ai/general/voiceworx-create-account
Steps
To proceed with these steps, you should have all the pre-requisites satisfied. If you are missing something, please go back and make sure you satisfy all of them.
Once done, you are ready to get started using VoiceWorx platform with Amazon DynamoDB.
Step 1 Connect to Amazon DynamoDB
Login to the VoiceWorx portal at https://portal.voiceworx.ai
To Configure DynamoDB, browse to: Integration > Connect System > Connect External System in the VoiceWorx platform and select options as shown below.
Once you click on “Connect System” button, you will be redirected to the configuration screen where you need to provide connection information as shown below.
If you do not have this information ready, please refer to the pre-requisites #3
The table below explains each of the inputs shown on this screen.
Input | Information |
Service Instance Name | You can give any value of your choice. |
Consumer Key | This is your AWS Access key ID |
Consumer Secret | This is your AWS Secret access key |
Region | AWS Region Name. Your DynamoDB table should be in this region. Example: us-east-1, us-east-2, us-west-1, us-west-2 |
Fill the required information and click on “Validate and Save Settings” button, this will validate the details and if it is correct, integration will be saved, and you will be redirected to the integrations listing page as shown below.
Step 2 Create an App for Amazon DynamoDB
To create an app, browse to Custom Apps > Manage Apps and click on Create New Custom App button as shown below.
You should see a small popup as shown below.
Input | Information |
Name | You can give any value of your choice. |
Custom Skill Type | Select Search |
Category | Default. |
Click on save, this will create an app and you should see a screen as shown below,
This shows that an app is successfully created, and you have various options like setup data sources. This is explained in next step.
Step 3 Create a Data Source
To follow this step, make sure you have completed above Step 2. If not please go back and do it.
A Data Source connects the app with the DynamoDB integration we did in Step #1. Once you have an app created, you can go o Data Sources by either clicking on “Data Source” button or by clicking on “Data Sources” tab.
Now you should see screen as shown below.
To create a data source, click on ‘Create New Data Source’ button and you should see a popup screen as shown below
Give a name of your choice and make sure you select the DynamoDB integration that you have created in Step 1 and click on Save. Now you should see a Data Source created as shown in below screenshot.
once a data source is created, you are ready to start creating various methods.
Step 4 Create Methods to fetch the data from Amazon DynamoDB
To use this step, make sure you have completed previous step. If not go back and complete it.
Methods allows you to fetch data from the DynamoDB table. To access the methods, click on the “Methods” tab which is next to the “Data Sources” tab.
As of the publication date of this document, the VoiceWorx platform supports following DynamoDB methods,
Get Tables
Get All Items
Get Item
Get Items
Put Item
Post Item
Delete Item
Depending on requirement, you will have to use an appropriate method, this document will explain each of these methods with an example.
Let’s start with a use case.
Scenario/ Use Case (Contact Finder):
You have a DynamoDB table which is used to store all the contacts in your organization. If you are using this for personal use, then consider that table contains contact details of your friends and family members.
You want to find email address of your friend Sam. For this, you can use GetItems method as explained below.
Method: GetItems
This method requires two parameters as explained below.
Parameters:
Parameter | Sample Value | Info |
TableName | Contact (Select from the drop-down list, you do not have to remember it) | DynamoDB table name. (Case Sensitive) |
QueryParameters | Example: 1 {"name":"John"} Example: 2 {"name":"Smith"} | Key Value pair in a valid json format. |
Other than these two parameters, you need to provide the following standard inputs
Parameter | Info |
Method Name | You can give any name. This name will be displayed in the methods list. |
Request Type | GetItems This is the method that you are using |
Parameters | As explained in the previous table |
Result Type | ListOfRecords (Auto Selected) It indicates that the method can return one or more records |
Record Limit | Numeric value (e.g. 10) If Method is returning larger number of records, then you can limit this result by providing this value. |
Record JsonPath | Each method returns data in json format and to pick any specific information from the json, we need to specify the Record JsonPath so Voice Worx platform will pick that data in consideration while displaying results. Example: $.[*] This selects all the records that is returned. |
Record Template | Let’s assume that the following json represents one record. { "Id": "1", "Name": "kiran", "PhoneNumber": "123-456-1234" } Now, you want to select name, then you can provide Record Template as Phone number of {{Name}} is {{ PhoneNumber}} Note: Anything written in between {{ }} is represented as a json field and it’s case-sensitive. |
Result Template | This indicates how method results should be represented. Here you go, {{Records}} Here, {{Records}} represents one or more records separated by a separator. |
Sample Response:
[
{
"id": 2,
"Name": "Mike",
"PhoneNumber": "123-456-1234"
}
]
Method: GetTables
Create new method
Parameter | Info |
Method Name | GetTables |
Request Type | GetTables This is the method that you are using |
Parameters | As explained in the previous table |
Result Type | ListOfRecords (Auto Selected) It indicates that the method can return one or more records |
Record Limit | Numeric value (e.g. 10) If Method is returning larger number of records, then you can limit this result by providing this value. |
Record JsonPath | Each method returns data in json format and to pick any specific information from the json, we need to specify the Record JsonPath so Voice Worx platform will pick that data in consideration while displaying results. Example: $.[*] This selects all the records that is returned. |
Record Template | {{TableName}} Note: Anything written in between {{ }} is represented as a json field and it’s case-sensitive. |
Result Template | Here are the tables. {{Records}} How else can I help you? Here, {{Records}} represents one or more records separated by a separator. |
Parameters: Not required
Sample Response:
[
{
"TableName": "Contacts"
}
]
Method: GetAllItems
Parameters:
Parameter | Sample Value | Info |
TableName | Contact | DynamoDB table name. |
Parameter | Info |
Method Name | GetAllItems |
Request Type | GetAllItems This is the method that you are using |
Parameters | TableName: Contacts |
Result Type | ListOfRecords (Auto Selected) It indicates that the method can return one or more records |
Record Limit | Numeric value (e.g. 10) If Method is returning larger number of records, then you can limit this result by providing this value. |
Record JsonPath | Each method returns data in json format and to pick any specific information from the json, we need to specify the Record JsonPath so Voice Worx platform will pick that data in consideration while displaying results. Example: $.[*] This selects all the records that is returned. |
Record Template | Name:{{Name}}, PhoneNumber: {{PhoneNumber}} Note: Anything written in between {{ }} is represented as a json field and it’s case-sensitive. |
Result Template | Here are the contacts available, {{Records}} How else can I help you? Here, {{Records}} represents one or more records separated by a separator. |
Sample Response:
[
{
"id": "3",
"PhoneNumber": "(785) 241-6200",
"Name": "Andy Young"
},
{
"id": "2",
"PhoneNumber": "(512) 757-6000",
"Name": "Sean"
},
{
"id": "9",
"PhoneNumber": "(512) 757-6000",
"Name": "Rose Gonzalez"
}
]
Method: GetItem
Parameters:
Parameter | Sample Value | Info |
TableName | Contact | DynamoDB table name. (Case Sensitive) |
PartitionKeyName | id | Name of the Partition Key for the provided table(Case Sensitive) |
PartitionKeyValue | 1 | Value for the Partition Key |
Sample Response:
{
"id": "1",
"PhoneNumber": "(336)222-7000",
"Name": "Jack Rogers"
}
Method: PutItem
Parameters:
Parameter | Sample Value | Info |
TableName | Contact | DynamoDB table name. (Case Sensitive) |
PartitionKeyName | id | Name of the Partition Key (Case Sensitive) |
PartitionKeyValue | 5 | Value for the Partition Key |
ItemData | {"PhoneNumber": "(503) 421-7800","Name": "Josh Davis"} | Item data in json format For example |
Sample Response:
{
"id": "5",
"PhoneNumber": "(503) 421-7800",
"Name": "Josh Davis"
}
Method: PostItem
Parameters:
Parameter | Sample Value | Info |
TableName | Contact | DynamoDB table name. (Case Sensitive) |
PartitionKeyName | id | Name of the Partition Key (Case Sensitive) |
PartitionKeyValue | 5 | Value for the Partition Key |
ItemData | {"PhoneNumber": "(503) 421-7800","Name": "Josh Davis"} | Item data in json format For example |
Sample Response:
{
"id": "5",
"PhoneNumber": "(503) 421-7800",
"Name": "Josh Davis"
}
Method: DeleteItem
Parameters:
Parameter | Sample Value | Info |
TableName | Contact | DynamoDB table name. (Case Sensitive) |
PartitionKeyName | id | Name of the Partition Key (Case Sensitive) |
PartitionKeyValue | 5 | Value for the Partition Key |
Sample Response:
{"response": "Delete Successful"}
From here, you can now proceed to create intents, slots, inputs and then finally publish to VoiceWorx supported publish channels. You can refer to this document for further assistance to build and publish App in VoiceWorx. You can test your app in Alexa developer console and the expected result shall be like this
Congratulations you’ve successfully integrated Amazon DynamoDB to VoiceWorx app.
Last updated