Integrating DynamoDB with OutSystems
Simple tutorial on connecting DynamoDB to OutSystems.
Command Palette
Search for a command to run...
Comments
Join the discussionNo comments yet. Be the first to comment.
Search for a command to run...
Simple tutorial on connecting DynamoDB to OutSystems.
No comments yet. Be the first to comment.
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 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.
You need the following before using the Dynamo Connector:
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>
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.
To check if the package was imported, go to the Logic tab and find AmazonDynamoDB.
When using the packages, the values of Keys and Item should be a DynamoDB JSON String.
A normal DynamoDB JSON is like the following:
However, when entering the value in the input box in OutSystems, we should format the DynamoDB JSON as a string.
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>"" } }"
Before you can update items from an OutSystems object, you must transform the object to a DynamoDB JSON string.
The Dynamo Connector includes four Data Type helpers:
DynamoDB_Binary = for Binary Objects
DynamoDB_Boolean = for Boolean Objects (True or False)
DynamoDB_Number = for Numbers (negative, positive, or zero, including decimals)
DynamoDB_String = for Text/String
These helpers transform the attribute into a structure with an additional attribute.
DynamoDB_Binary
{ "DynamoDB_Binary": { "B" : "<value>" }}
DynamoDB_Boolean
{ "DynamoDB_Boolean": { "BOOL" : "<value>" }}
DynamoDB_Number
{ "DynamoDB_Boolean": { "N" : "<value>" }}
DynamoDB_String
{ "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.
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.
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 |
I recommend adding the credentials as Site Properties and then applying the values through Service Center.
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.
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.
Publish the application then open Service Center.
Log in to your Service Center then go the Factory tab. Search for your application then click its name.
Select the application module where you added the Dynamo Connector.
Click on the Site Properties tab then apply values to the Site Properties you added.
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). I will also strive to keep the table updated with the latest information.
| Region Name | Region Code | Region |
| US East (Ohio) | 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 |
Go back to the Service Studio. Reference the site property you created to the server action.
Optionally, you may create a server action that outputs the AWSCredentials. You may use the AWSCredentials structure included in the Amazon Dynamo DB package.
Make sure that the Function attribute is set to Yes to use this method.
One way to perform actions in OutSystems is through Server Actions. These actions can be used in Reactive Web, Traditional Web, and Mobile applications.
You can retrieve the values of a specific item in a DynamoDB Table using its Partition Key with the DynamoDB\Item_Get server action.
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.
You may insert or update (aka Upsert) data using the DynamoDB\Item_Put server action.
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.
To search or query the DynamoDB table using conditions, we will need to use the DynamoDB\Query server action.
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 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.
You may retrieve all records (max 1MB size limit) of the table using the Scan server action.
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.
You can delete a record by passing the record's primary key and sort key.
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.
You can create a table using the DynamoDb\Table_Create server action
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.
You can delete a table and its items using the DynamoDb\Table_Delete server action
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 or leave a comment on this post.