Integrating DynamoDB with OutSystems

Simple tutorial on connecting DynamoDB to OutSystems.

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

DynamoDB Data TypeAttributeAccepted Values
BinaryBBinary Data
BooleanBooltrue or false
ListLArray[]
Map / SetMMap{}
NumberNany number
StringSany 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.

Adding AWS Credentials

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

AttributeDescription
RegionAWS Region the action will use
AccessKeyIdAccount Access Key ID
SecretAccessKeyAccount Secret Access Key

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.

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

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:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes
KeyKeys to find the recordString, Format: DynamoDB JSON StringYes

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.

OutputDescriptionData Type
ItemDynamoDB 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.

Data must contain a DynamoDB JSON-formatted string.

The following items are needed by the server action:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes
ItemDynamoDB JSON RecordString, Format: DynamoDB JSON StringYes

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:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes
KeyConditionExpressionKey values for items to be retrievedStringYes
ExpressionAttributeNamesOne or more substitution tokens for attribute names in an expressionString, Format: DynamoDB JSON StringYes, if variables are used in KeyConditionExpression
ExpressionAttributeValuesOne or more values that can be substituted in an expressionString, Format: DynamoDB JSON StringYes, if ExpressionAttributeNames has value
ProjectionExpressionString that identifies one or more attributes to retrieve from the table.StringNo
FilterExpressionString that contains conditions that DynamoDB applies after the Query operation.StringNo
SelectString that contains the attributes to be returned in the result.StringNo

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

OutputDescriptionData Type
ItemsDynamoDB 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.

The following items are needed by the server action:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes

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:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes
ItemDynamoDB JSON RecordString, Format: DynamoDB JSON StringYes

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:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes

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:

FieldDescriptionData TypeIs Required
AWSCredentialsCredentials of the AWS AccountDynamoDB\AWSCredentialsYes
TableNameName of the DynamoDB TableStringYes

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.