# Integrating DynamoDB with OutSystems

If you are using OutSystems and want to connect your Amazon DynamoDB tables, well, you're in luck. There's a package in OutSystems Forge that can help you achieve this. The package is called [Amazon DynamoDB Connector](https://www.outsystems.com/forge/component-overview/3549/amazon-dynamodb-connector) which includes all the functions you need to create, update, and delete tables and items.

To shorten the post, we'll call Amazon DynamoDB Connector to **Dynamo Connector**.

# Pre-requisites

You need the following before using the Dynamo Connector:

1. AWS Credentials
    
    * Access Key ID
        
    * Secret Access Key ID
        
    * AWS Region
        
        * To use the AWS Region, you need to re-type it like the following:
            
            ap-southeast-1 -> **APSoutheast1**  
            <uppercase><capitalized><number>
            

# Using the Forge Component

## Importing the Dependency

To use the Dynamo Connector, first, we need to import the dependency. Open your application, then go to **Manage Dependencies** (or press `CTRL+Q`). In the Manage Dependencies popup window, search for **AmazonDynamoDB**. Select the server actions you will use then hit **Apply**.

We will use all server actions as the basis for the examples in this post.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719726073817/34bb3dc9-6b9f-4ba1-a6f1-48d50db9fc09.png align="center")

To check if the package was imported, go to the **Logic** tab and find **AmazonDynamoDB**.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719726410129/261314c7-9d52-40ef-a569-8d87de55f9f4.png align="center")

# DynamoDB JSON String

When using the packages, the values of Keys and Item should be a DynamoDB JSON String.

A normal DynamoDB JSON is like the following:

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719731294414/c00cd43d-795f-4c4b-bb11-5a205c7aecee.png align="center")

However, when entering the value in the input box in OutSystems, we should format the DynamoDB JSON as a string.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719734159257/b198c4d3-ba88-41b7-a6fa-8fa7445defea.png align="center")

**Example Value with Variable:**  
`"{""game_id"": {""S"": """ + GameId + """}}"`

If GameId = 3 and data type is DynamoDB String, the generated string will be  
`"{""game_id"": {""S"": ""3""}}"`

**For entries with PartitionKey and SortKey**  
Ex.  
`"{ ""<partitionKey>"": { ""S"": ""<partitionKeyValue>"" }, ""<sortKey>"": { ""S"": ""<sortKeyValue>"" } }"`

# Transforming Data

Before you can update items from an OutSystems object, you must transform the object to a [DynamoDB JSON string](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-json.html).

The Dynamo Connector includes four Data Type helpers:

1. DynamoDB\_Binary = for Binary Objects
    
2. DynamoDB\_Boolean = for Boolean Objects (True or False)
    
3. DynamoDB\_Number = for Numbers (negative, positive, or zero, including decimals)
    
4. DynamoDB\_String = for Text/String
    

These helpers transform the attribute into a structure with an additional attribute.

1. DynamoDB\_Binary
    
    ```json
    { "DynamoDB_Binary": { "B" : "<value>" }}
    ```
    
2. DynamoDB\_Boolean
    
    ```json
    { "DynamoDB_Boolean": { "BOOL" : "<value>" }}
    ```
    
3. DynamoDB\_Number
    
    ```json
    { "DynamoDB_Boolean": { "N" : "<value>" }}
    ```
    
4. DynamoDB\_String
    
    ```json
    { "DynamoDB_Boolean": { "S" : "<value>" }}
    ```
    

If you do not want to use the helpers and/or want to add a Data Type not supported by the Dynamo Connector, you may create a structure with an attribute of the Data Type.

| DynamoDB Data Type | Attribute | Accepted Values |
| --- | --- | --- |
| Binary | B | Binary Data |
| Boolean | Bool | true or false |
| List | L | Array\[\] |
| Map / Set | M | Map{} |
| Number | N | any number |
| String | S | any text |

For the list of all accepted data types, you may view this [AWS Article](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypeDescriptors).

Document Types or Set Types, such as lists or maps, can be nested within each other. It can contain Nested Lists, Nested Maps, List of Strings, List of Binaries, Lists of Booleans, and Lists of Numbers. Just don't forget to set the data types of the List or Map to the "List" object.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1675059452346/9f980dd8-90a8-44db-b596-6a533b944f4e.png align="center")

# Adding AWS Credentials

All Dynamo connector server actions require an "AWSCredentials" record. This record contains the following items:

| Attribute | Description |
| --- | --- |
| Region | AWS Region the action will use |
| AccessKeyId | Account Access Key ID |
| SecretAccessKey | Account Secret Access Key |

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719726956393/04336717-9fc8-40e1-9737-b92deb0cd8f1.png align="center")

## Adding credentials securely

I recommend adding the credentials as Site Properties and then applying the values through Service Center.

### Adding Site Properties

To add new site properties, go to the **Data** tab and find **Site Properties**. Right click on the Site Properties folder the click **Add Site Property**.

Add the following site properties. You may name then anyway you like.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719727307675/4a4634f7-3432-4a32-9233-f34b2e2ff6aa.png align="center")

Optionally, you may also add them inside a folder to easily find them later. This won't affect the way you add the site properties to your records.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719727237460/694b019a-7f31-4ae5-ab5a-a2460f16e805.png align="center")

Publish the application then open Service Center.

### Adding values of Site Props using Service Center

Log in to your Service Center then go the **Factory** tab. Search for your application then click its name.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719727713259/70a27451-125f-4063-a63f-4e29218cd413.png align="center")

Select the application module where you added the Dynamo Connector.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719727883944/c50032e1-9e78-4082-895c-20d97e19a0e3.png align="center")

Click on the **Site Properties** tab then apply values to the Site Properties you added.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719727937147/062f83f8-492c-4a07-833f-f10ae4b780dd.png align="center")

Note: Make sure that the value for `AWSRegion` is in Pascal Case. For example, if you are using ap-southeast-1, you need to enter **APSoutheast1.**

Use the table below as a guide. Please note that AWS regions may change over time. For the most up-to-date values, visit [aws/aws-sdk-net (github.com)](https://github.com/aws/aws-sdk-net/blob/db5608cb0eb56e0cba08dea180ea53577e71636e/sdk/src/Core/RegionEndpoint/RegionEndpoint.generated.cs). I will also strive to keep the table updated with the latest information.

| [Region Name](https://github.com/aws/aws-sdk-net/blob/db5608cb0eb56e0cba08dea180ea53577e71636e/sdk/src/Services/S3/Generated/S3Enumerations.cs#L66) | [Region Code](https://github.com/aws/aws-sdk-net/blob/db5608cb0eb56e0cba08dea180ea53577e71636e/sdk/src/Services/S3/Generated/S3Enumerations.cs#L66) | [Region](https://github.com/aws/aws-sdk-net/blob/db5608cb0eb56e0cba08dea180ea53577e71636e/sdk/src/Services/S3/Generated/S3Enumerations.cs#L66) |
| --- | --- | --- |
| [US East (Ohio](https://github.com/aws/aws-sdk-net/blob/db5608cb0eb56e0cba08dea180ea53577e71636e/sdk/src/Services/S3/Generated/S3Enumerations.cs#L66)) | `us-east-2` | USEast2 |
| US East (N. Virginia) | `us-east-1` | USEast1 |
| US West (N. California) | `us-west-1` | USWest1 |
| US West (Oregon) | `us-west-2` | USWest2 |
| Africa (Cape Town) | `af-south-1` | AFSouth1 |
| Asia Pacific (Hong Kong) | `ap-east-1` | APEast1 |
| Asia Pacific (Hyderabad) | `ap-south-2` | APSouth2 |
| Asia Pacific (Jakarta) | `ap-southeast-3` | APSoutheast3 |
| Asia Pacific (Melbourne) | `ap-southeast-4` | APSoutheast4 |
| Asia Pacific (Mumbai) | `ap-south-1` | APSouth1 |
| Asia Pacific (Osaka) | `ap-northeast-3` | APNortheast3 |
| Asia Pacific (Seoul) | `ap-northeast-2` | APNortheast2 |
| Asia Pacific (Singapore) | `ap-southeast-1` | APSoutheast1 |
| Asia Pacific (Sydney) | `ap-southeast-2` | APSoutheast2 |
| Asia Pacific (Tokyo) | `ap-northeast-1` | APNortheast1 |
| Canada (Central) | `ca-central-1` | CACentral1 |
| Canada West (Calgary) | `ca-west-1` | CAWest1 |
| China (Beijing) | `cn-north-1` | CNNorth1 |
| China (Ningxia) | `cn-northwest-1` | CNNorthWest1 |
| Europe (Frankfurt) | `eu-central-1` | EUCentral1 |
| Europe (Ireland) | `eu-west-1` | EUWest1 |
| Europe (London) | `eu-west-2` | EUWest2 |
| Europe (Milan) | `eu-south-1` | EUSouth1 |
| Europe (Paris) | `eu-west-3` | EUWest3 |
| Europe (Spain) | `eu-south-2` | EUSouth2 |
| Europe (Stockholm) | `eu-north-1` | EUNorth1 |
| Europe (Zurich) | `eu-central-2` | EUCentral2 |
| Israel (Tel Aviv) | `il-central-1` | ILCentral1 |
| Middle East (Bahrain) | `me-south-1` | MESouth1 |
| Middle East (UAE) | `me-central-1` | MECentral1 |
| South America (São Paulo) | `sa-east-1` | SAEast1 |
| AWS GovCloud (US-East) | `us-gov-east-1` | USGovCloudEast1 |
| AWS GovCloud (US-West) | `us-gov-west-1` | USGovCloudWest1 |

### Using the values

Go back to the Service Studio. Reference the site property you created to the server action.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719727536366/afca6cbf-3bca-4a0b-b3fc-911b6ecfaefa.png align="center")

Optionally, you may create a server action that outputs the AWSCredentials. You may use the **AWSCredentials** structure included in the Amazon Dynamo DB package.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719730080022/ca2b2c87-a8de-4ba7-b94e-c2f3a0c10cb2.png align="center")

Make sure that the **Function** attribute is set to Yes to use this method.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719729929813/6df0f722-cbf1-45cb-b0f4-be2ef5c8e421.png align="center")

# Actions

One way to perform actions in OutSystems is through Server Actions. These actions can be used in Reactive Web, Traditional Web, and Mobile applications.

## 1\. Getting Data

You can retrieve the values of a specific item in a DynamoDB Table using its Partition Key with the **DynamoDB\\Item\_Get** server action.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680251677169/c3e871a6-6b72-4f6d-94b7-7d3f7fb291c8.png align="center")

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |
| Key | Keys to find the record | String, Format: DynamoDB JSON String | Yes |

If the operation is successful, it will return a DynamoDB JSON-formatted string entry.

To get the value returned by the server action, you may assign the value, returned as **Item\_Get.Item,** to a variable.

| Output | Description | Data Type |
| --- | --- | --- |
| Item | DynamoDB JSON-formatted string |  |

If no value is found, output is an empty object (`{}`) | Text |

`Item` should be JSON Deserialized using an object structure, else, you need to parse the value with other methods.

## 2\. Inserting/Updating Data

You may insert or update (aka Upsert) data using the **DynamoDB\\Item\_Put** server action.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680251084890/b81dcd11-957f-4e98-a57f-5acea12655ca.png align="center")

Data must contain a DynamoDB JSON-formatted string.

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |
| Item | DynamoDB JSON Record | String, Format: DynamoDB JSON String | Yes |

No response will be returned by the server action if the operation is successful. However, it will return an Exception if it encounters an error.

## 3\. Query

To search or query the DynamoDB table using conditions, we will need to use the **DynamoDB\\Query** server action.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719735058407/a9fb5315-f6ad-43e2-98a2-8fca1343556e.png align="center")

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |
| KeyConditionExpression | Key values for items to be retrieved | String | Yes |
| ExpressionAttributeNames | One or more substitution tokens for attribute names in an expression | String, Format: DynamoDB JSON String | Yes, if variables are used in KeyConditionExpression |
| ExpressionAttributeValues | One or more values that can be substituted in an expression | String, Format: DynamoDB JSON String | Yes, if ExpressionAttributeNames has value |
| ProjectionExpression | String that identifies one or more attributes to retrieve from the table. | String | No |
| FilterExpression | String that contains conditions that DynamoDB applies after the Query operation. | String | No |
| Select | String that contains the attributes to be returned in the result. | String | No |

To know more about the attributes, you may read the [Query API article](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) on the AWS Documentation website.

| Output | Description | Data Type |
| --- | --- | --- |
| Items | DynamoDB JSON-formatted string |  |

If no values found, output is empty array (`[]`) | Text |

`Items` should be JSON Deserialized using an object structure, else, you need to parse the value with other methods.

## 4\. Scanning Table

You may retrieve all records (max 1MB size limit) of the table using the Scan server action.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719735079736/810fed8e-c602-4871-9c74-e0d912f4b0d5.png align="center")

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |

No response will be returned by the server action if the operation is successful. However, it will return an Exception if it encounters an error.

## 5\. Deleting a Record

You can delete a record by passing the record's primary key and sort key.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719735318627/9812b2cb-830f-4ff6-bd6c-112b9daf511e.png align="center")

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |
| Item | DynamoDB JSON Record | String, Format: DynamoDB JSON String | Yes |

No response will be returned by the server action if the operation is successful. However, it will return an Exception if it encounters an error.

## 6\. Creating a Table

You can create a table using the DynamoDb\\Table\_Create server action

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719735500825/ad2969f4-e671-4a4a-8040-d11ce976beb2.png align="center")

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |

No response will be returned by the server action if the operation is successful. However, it will return an Exception if it encounters an error.

## 6\. Deleting a Table

You can delete a table and its items using the DynamoDb\\Table\_Delete server action

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1719735664563/97330f0f-557c-4899-8ed9-3d05fe545191.png align="center")

The following items are needed by the server action:

| Field | Description | Data Type | Is Required |
| --- | --- | --- | --- |
| AWSCredentials | Credentials of the AWS Account | DynamoDB\\AWSCredentials | Yes |
| TableName | Name of the DynamoDB Table | String | Yes |

No response will be returned by the server action if the operation is successful. However, it will return an Exception if it encounters an error.

---

Hi! This is my first blog post. If you see some errors, feel free to email me at [me@cmdinglasan.com](mailto:me@cmdinglasan.com) or leave a comment on this post.