# 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 iX Hello.
### 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
* **At least one DynamoDB table**
If you do not have any DynamoDB table, you can create one quickly.
1. Login to AWS Management Console at
2. Enter **DynamoDB** into the Search Field and select the DynamoDB result.
3. On the left side menu, select **Tables** and then press **Create Table**. For more detailed information, you can refer to the AWS official documentation
4. Provide the Table Name **Contacts** and Primary Key as **Id**. Click on **Create Table**.
5. Click on the table name **Contacts** in the Tables page:
6. 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. From the **Actions** dropdown in the upper right, choose **Create Item**.
7. Press the **Add new attribute** drop down in the upper right and select **String.** Title the new attribute **Name**. Repeat and add a second String attribute, **PhoneNumber**.
8. Populate the item with Id **1**, Name **John**, and PhoneNumber **123-555-1234.** When finished, press **Create Item**
10. Repeat the process to add more data. e.g.
{\
"id": 2,\
"Name": "Mike",\
"PhoneNumber": "123-555-6789"\
}
### Access Key, Secret Access Key, and AWS Region Name
To be able to connect to Amazon DynamoDB from iX Hello, one IAM user is required and that user should have permissions to view/add/edit/delete the DynamoDB data. It is recommended to have an 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
You can also refer to the simplified iX Hello documentation at [https://docs.ixHello.com/aws-iam-users](https://docs.voiceworx.ai/aws-iam-users)
### iX Hello Account
To create an iX Hello account, follow the steps [here](https://docs.ixhello.com/ixhc/general/ixhello-create-account#create-an-account-in-ixhello)
### Steps
Before proceeding with these steps, you should have all the prerequisites satisfied.
### Step 1: Connect to Amazon DynamoDB
1. Login to the iX Hello portal at [https://bots.ixHello.com](https://bots.ixhello.com)
2. To configure DynamoDB, browse to: Integration > Connect System > Connections Gallery.
3. From the Gallery, scroll down and select **DynamoDB**
4. Press **Connect**. The Configuration screen will open where you need to provide connection information as shown below.
If you do not have this information ready, please refer to the pre-requisites above
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.
|
5. After entering the information, click on **Validate and Save Settings**. If the input is correct, a Success message will appear and the integration will be saved. A listing will appear on the Integrations listing page as shown below.
### Step 2: Create an App for Amazon DynamoDB
1. To create an app, browse to Apps > Custom Apps and click on **New Custom App** button as shown below.
2. You should see a small popup as shown below.
Populate the fields as follows:
Name
You can give any value of your choice.
Custom App Type
Select Search
Category
Default.
3. Click on **Save**. This will create a new App.
### Step 3: Create a Data Source
A data source connects an app with the DynamoDB integration we did earlier.
1. Once you have created an App, go to Data Sources by opening the App, opening the Data Sources tab, and clicking **Create New Data Source**.
2. You should see a popup screen as shown below
3. Give the DataSource a name of your choice and make sure you select the DynamoDB integration created earlier. Click **Save**. You should now see the new Data Source listed.
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, make sure the correct DataSource shows in the Select DataSource window, and press **Create New Method**.
As of the publication date of this document, iX Hello supports following DynamoDB methods:
1. Get Tables
2. Get All Items
3. Get Item
4. Get Items
5. Put Item
6. Post Item
7. 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 returns a database entry based on a parameter value (Name). It requires two input parameters as explained below. Open Method Inputs:
#### Parameters:
| Parameter | Sample Value | Info |
| --------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Method Name | Get Items | Name of the metho |
| Request Type | GetItems | Pre-defined method |
| TableName |
Contact
(Select from the drop-down list, you do not have to remember it)
| Key Value pair in a *valid JSON* format. (*Case Sensitive*) |
To format the output, open the Method Output tab:
| Parameter | Info |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Result Type | Format of return values |
| 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.
|
Method Result displays options on how to present the returned values:
| Parameter | Info |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 the platform will pick that data in consideration while displaying results.
Example: $.\[\*]
This option returns all the records.
|
| Valid Result Template |
This indicates how results should be represented if proper values have been returned. For example:
Here you go, {{Records}}
where {{Records}} represents one or more records separated by a separator.
|
| Record Template |
Describes how to display a record that may have more than one parameter. For example, assume that the following JSON represents one record:
{
"Id": "1",
"Name": "John",
"PhoneNumber": "123-555-1234"
}
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 is case-sensitive. This would present as: Phone number of John is 123-555-1234
|
| Empty Result Template | This indicates what should be presented if no values are returned. |
#### Sample Response:
### Method: GetTables
This Method returns the name of the table.
| Parameter | Info |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method Name | Get Tables |
| 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 the platform will pick that data in consideration while displaying results.
Example: $.\[\*]
This option returns all the records.
|
| 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.
|
#### Sample Response:
### Method: GetAllItems
This method returns all records in the table
#### 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 the platform will pick that data in consideration while displaying results.
Example: $.\[\*]
This option returns all the records.
|
| Record Template |
Name:{{Name}}, PhoneNumber: {{PhoneNumber}}
Note:
Anything written in between {{ }} is represented as a JSON field and is 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:
### Method: GetItem
Returns a single record.
#### 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
Adds a record to the database.
#### 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 |
#### Sample Response:
{\
"id": "5",\
"PhoneNumber": "(503) 421-7800",\
"Name": "Josh Davis"\
}
### Method: PostItem
Adds a record to the database.
#### 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 |
#### Sample Response:
{\
"id": "5",\
"PhoneNumber": "(503) 421-7800",\
"Name": "Josh Davis"\
}
### Method: DeleteItem
Removes a record from the database.
#### 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 supported publish channels. You can refer to [this](https://docs.ixhello.com/ixhc/general/ix-hello-studio-mode/steps/app-creation) document for further assistance to build and publish Apps. 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 an iX Hello App.
