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.

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.

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

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:

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>"" } }"

Transforming Data

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:

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

    { "DynamoDB_Binary": { "B" : "<value>" }}
   

2. DynamoDB_Boolean

    { "DynamoDB_Boolean": { "BOOL" : "<value>" }}
   

3. DynamoDB_Number

    { "DynamoDB_Boolean": { "N" : "<value>" }}
   

4. 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.

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.

Adding AWS Credentials

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

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.

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.

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.

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.

Using the values

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.

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.

The following items are needed by the server action:

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.

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.

Data must contain a DynamoDB JSON-formatted string.

The following items are needed by the server action:

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.

The following items are needed by the server action:

To know more about the attributes, you may read the Query API article on the AWS Documentation website.

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.

The following items are needed by the server action:

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.

The following items are needed by the server action:

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

The following items are needed by the server action:

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

The following items are needed by the server action:

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.