Skip to main content
Version: 8.5

Amazon DynamoDB Connector

The Amazon DynamoDB Connector allows you to connect your BPMN service with Amazon Web Service's DynamoDB Service. This can be useful for performing CRUD operations on Amazon DynamoDB tables from within a BPMN process.

Prerequisites

To use the Amazon DynamoDB Connector, you need to have an AWS account with an access key and secret key to access DynamoDB, as well as a region where your DynamoDB instance is located. You can create an account and obtain the access and secret keys from the AWS Console.

note

Use Camunda secrets to store credentials so you don't expose sensitive information directly from the process. Refer to managing secrets to learn more.

Create an Amazon DynamoDB Connector task

A Connector can be applied to a task or an event using the append menu. Access the append menu using any of the three methods below:

  • From the canvas: Select an element and click the Change element icon to change an existing element, or use the append feature to add a new element to the diagram.
  • From the properties panel: Navigate to the Template section and click Select.
  • From the side palette: Click the Create element icon.

change element

Once you have applied a Connector to your element, follow the configuration steps or read our guide on using Connectors to learn more.

Make your Amazon DynamoDB Connector executable

To work with Amazon DynamoDB Connector, choose the required operation type in the Operation section and complete the mandatory fields highlighted in red in the Connector properties panel.

note

All the mandatory and non-mandatory fields depending on the authentication selection you choose are covered in the upcoming sections.

Operation

Choose an operation type of either Table or Item in the Operation section:

  • Table: Perform operations on a DynamoDB table.
  • Item: Perform operations on a specific item in a DynamoDB table.

Method

Choose one of the following methods:

Table

  • Create table: Creates a new DynamoDB table.
  • Delete table: Deletes an existing DynamoDB table.
  • Describe table: Returns information about a DynamoDB table.
  • Scan table: Returns one or more items and their attributes by accessing every item in a table. You can use filter expressions to selectively scan for items that meet certain criteria.

Item

  • Add item: Creates a new item or replaces an existing item with a new item.
  • Delete item: Deletes a single item in a table by primary key.
  • Get item: Returns a set of attributes for the item with the given primary key.
  • Update item: Modifies an existing item's attributes or adds a new item to the table if it does not already exist.

Authentication

Choose an applicable authentication type from the Authentication dropdown. Learn more about authentication types in the related appendix entry.

If you select credentials to access the Amazon DynamoDB service, the Connector requires the appropriate credentials. The following authentication options are available:

  • Access key: Provide an access key of a user with permissions to the Amazon DynamoDB service.
  • Secret key: Provide the secret key of the user with the access key provided above.

The Access Key and Secret Key are required properties and must be provided to use the Connector. If these properties are not set, the Connector will not be able to authenticate with the DynamoDB Service.

For more information on authentication and security in Amazon DynamoDB, refer to the AWS documentation.

Configuration

The Region property in the Configuration section specifies the AWS region in which the DynamoDB table exists or will be created. This property is required and must be set to use the Connector.

For more information on AWS regions, refer to the AWS documentation.

Input

The Input section of the Amazon DynamoDB Connector specifies the input data for the selected operation. The input data varies depending on the operation type and method selected.

Table operations

For the Table operation type, the following input data is required:

Create table

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the DynamoDB table to be created.
Partition keystringYesThe attribute name of the partition key for the table.
Partition key roledropdownYesThe role of the partition key. Can be set to "HASH" or "RANGE".
Partition key attribute data typedropdownYesThe data type of the partition key attribute.
Sort keystringNoThe attribute name of the sort key for the table (if applicable).
Sort key roledropdownNoThe role of the sort key. Can be set to "HASH" or "RANGE".
Sort key attribute data typedropdownNoThe data type of the sort key attribute.
Read capacity unitsnumberYesThe maximum number of strongly consistent reads per second that the table can support.
Write capacity unitsnumberYesThe maximum number of writes per second that the table can support.
Billing modedropdownNoThe billing mode of the table. Can be set to "PROVISIONED" or "PAY_PER_REQUEST".
Deletion protectiondropdownNoIndicates whether to enable or disable deletion protection for the table.

Response

PropertyData typeDescription
Table descriptionObjectInformation about the created table, including the table name, attribute definitions, primary key schema, provisioned throughput settings, and more.

Delete table

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the DynamoDB table to be deleted.

Response

PropertyData typeDescription
actionstringThe action performed. In this case, it will always be "delete Table [tableName]", where tableName is the name of the deleted table.
statusstringThe status of the operation. In this case, it will always be "OK" to indicate that the table was successfully deleted.

Describe table

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the DynamoDB table to be described.

Response

PropertyData typeDescription
Table descriptionObjectInformation about the table, including the table name, attribute definitions, primary key schema, provisioned throughput settings, and more.

Scan table

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the DynamoDB table to be scanned.
Filter expressionstringNoThe filter expression to apply to the scan results. For more information, refer to the Expression Attribute Names and Values section of the Amazon DynamoDB Developer Guide.
Projection expressionstringNoA string that identifies one or more attributes to retrieve from the specified table.
Expression attribute namesmapNoA map of attribute names to their replacements in the filter expression or projection expression. For more information, refer to the Expression Attribute Names and Values section of the Amazon DynamoDB Developer Guide.
Expression attribute valuesmapNoA map of attribute values to their replacements in the filter expression or projection expression. For more information, refer to the Expression Attribute Names and Values section of the Amazon DynamoDB Developer Guide.

Response

PropertyData typeDescription
actionstringThe action performed. In this case, it will always be scanTable.
statusstringThe status of the operation. If successful, it will always be "OK". Otherwise, it will be an error message.
itemslistThe list of items returned by the scan operation, in case the operation was successful. If there are no items, this field will be null.

Item operations

note

The Amazon DynamoDB Connector does not currently support binary data types. If binary data is input during the creation or update of items, it will be saved as a string.

When updating items, if an attribute of type SET is updated, it will be overwritten and saved as a list type. Consider these limitations to prevent unintended data structure modifications in your DynamoDB tables.

Add item

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the DynamoDB table to add the item to.
ItemobjectYesThe item to add to the table is represented in JSON format. For example:
{"Name": "Example Item", "ID": "123", "Description": "This is an example item"}.
This JSON object succinctly represents the item's attributes through straightforward key-value pairs, without the need to explicitly mention data types.

Response

PropertyData typeDescription
ResultobjectYesThe item to add to the table.

Delete item

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the DynamoDB table to delete the item from.
Primary Key ComponentsobjectYesThe primary key components that identify the item to delete.

Response

PropertyData typeDescription
Deleted ItemobjectThe item that was deleted. This field will be null if the item was not found.

Get item

Request

Property NameData typeRequiredDescription
Table namestringYesThe name of the table containing the requested item.
Primary key componentsobjectYesA map of attribute names to AttributeValue objects, representing the primary key of the item to retrieve. For the primary key, you must provide all the attributes. For example, with a simple primary key, you only need to provide a value for the partition key. For a composite primary key, you must provide values for both the partition key and the sort key.

Response

PropertyData typeDescription
AttributesobjectA map of attribute names to AttributeValue objects, representing the item retrieved. If there is no matching item, the response will contain only the consumed capacity, and a null attributes field. The keys of the attributes map correspond to the column names of the table

Update item

Request

Property nameData typeRequiredDescription
Table namestringYesThe name of the table to update the item in.
Primary key componentsmapYesA map of attribute names to AttributeValue objects, representing the primary key of the item to update.
Key attributesmapYesA map of attribute names to AttributeValue objects, representing the attributes to update.
Attribute actiondropdownNoDropdown option for each attribute to be updated, allowing selection between "PUT" (add or replace) and "DELETE" (remove)

Response

PropertyData typeDescription
UpdateItemOutcomeobjectAn object representing the outcome of the UpdateItem operation. The UpdateItemOutcome object contains the updated attributes of the item, as well as other metadata about the operation, such as the consumed capacity.

Request example

SectionFieldDescriptionExample value
OperationCategoryChoose the category of the operation to be performed.Item
ActionSelect the specific action to update an item in the DynamoDB table.Update item
AuthenticationAuthentication typeThe method of AWS authentication; credentials are used here.Credentials
Access keyAn example of an AWS access key.AKIAU3GOTH...JBYX
Secret keyAn example of an AWS secret key.bZ/LPpqaw...0igikS
RegionThe AWS region where the DynamoDB table is located.us-east-1
InputTable nameThe name of the DynamoDB table to be updated.test
Primary key componentsThe primary key component(s) of the item to be updated.{"id": "5"}
Key attributesJSON object representing the new values for the item attributes.{ "stringValue": "StringValue", "numberValue": 42, "booleanValue": true }
Attribute actionThe action to be performed on the attributes. Here it's set to PUT, which means the specified attributes will be added or updated.PUT
Output mappingResult variableThe name of the variable that will store the response from DynamoDB.result
Result expressionThe FEEL expression used to map the DynamoDB response to process variables. Not provided in the screenshots.-

Response Mapping

When using the DynamoDB Connector, the response from the DynamoDB Connector will be available in a temporary local response variable. This variable can be mapped to the process by specifying the Result Variable.

For example, if you use the Update Item method in the DynamoDB Connector, the response may look like this:

{
"action": "updateItem",
"status": "OK",
"response": {
"Attributes": {
"ID": {
"N": "3"
},
"price": {
"N": "10"
}
}
}
}

In this example, the response variable contains an Attributes object with the updated values for the specified item.

The following fields are available in the response variable:

  • action: The action that was performed by the DynamoDB Connector.
  • status: The status of the response, which will be "OK" if the operation was successful.
  • response: The response from the DynamoDB service, which will contain the updated attributes of the specified item.

You can choose to unpack the content of your response into multiple process variables using the Result Expression, which is a FEEL Context Expression.

The Result Expression allows you to access specific attributes from the response and assign them to process variables that can be used in subsequent steps of your process.

= {
id: response.response.Attributes.ID.N,
price: response.response.Attributes.price.N
}

In this example, we are using the Result Expression to extract the ID and price attributes from the response variable and assign them to the id and price process variables, respectively. You can then use these variables in subsequent steps of your process.

note

The syntax for accessing attributes in the Result Expression may vary depending on the structure of your response object. You can refer to the FEEL Context Expression documentation for more information on how to use the Result Expression.

Error handling

The Amazon DynamoDB Connector may throw the following exceptions:

  • AwsDynamoDbConnectionException: Thrown if there is an error connecting to DynamoDB.
  • AwsDynamoDbExecutionException: Thrown if there is an error executing a DynamoDB operation.
  • AwsDynamoDbConfigurationException: Thrown if the Connector is not properly configured.

All of these checked exceptions are wrapped in a RuntimeException, so be prepared to handle this type of exception as well.

Troubleshooting

If you are having issues with the Amazon DynamoDB Connector, try the following:

  • Ensure your AWS credentials are correct.
  • Ensure your DynamoDB table exists and is located in the specified region.
  • Ensure your configuration properties are set correctly.
  • Check the logs for any error messages.
  • Contact (Camunda support)[https://camunda.com/services/support/] if you need further assistance.

For more information on Amazon DynamoDB, visit the official documentation.

Using DynamoDB Connector best practice

When using the DynamoDB Connector in a BPMN process, it is important to keep in mind that there is no guarantee that a requested item will be retrieved or updated immediately. In this case, it is recommended to build your BPMN diagram to periodically retry polling until the item is available.

note

To avoid performance issues, it is recommended to limit the number of retries.

To learn more about implementing retry logic in your BPMN diagram, you can refer to the Camunda BPMN examples page, which includes examples of BPMN diagrams with timer and loop configurations.

Appendix

AWS authentication types

There are two options to authenticate the Connector with AWS:

  • Choose Credentials in the Authentication dropdown if you have a valid pair of access and secret keys provided by your AWS account administrator. This option is applicable for both SaaS and Self-Managed users.
  • Choose Default Credentials Chain (Hybrid/Self-Managed only) in the Authentication dropdown if your system is configured as an implicit authentication mechanism, such as role-based authentication, credentials supplied via environment variables, or files on target host. This option is applicable only for Self-Managed or hybrid distribution. This approach uses the Default Credential Provider Chain to resolve required credentials.