For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10

Amazon DynamoDB connector

Use the Amazon DynamoDB connector to work with tables and items in Amazon DynamoDB from your BPMN process.

About this connector​

The Amazon DynamoDB connector is an outbound connector that connects your BPMN process with the Amazon DynamoDB service. Use it to perform create, read, update, and delete (CRUD) operations on DynamoDB tables and items from within a process.

The connector supports the following operations:

  • Table: Create table, Delete table, Describe table, and Scan table.
  • Item: Add item, Delete item, Get item, and Update item.

Prerequisites​

To use the Amazon DynamoDB connector, you need an AWS account with an access key and secret key to access DynamoDB, and the region where your DynamoDB tables are located. You can create an account and obtain the keys from the AWS Console.

Learn more about Amazon DynamoDB in the Amazon DynamoDB documentation.

note

Use secrets to store credentials and avoid exposing sensitive information from the process. See managing secrets.

Use this connector​

New to using an outbound connector? Learn how to add and use this type of connector, apply element templates, use connector secrets, handle results and errors, and more.

Configuration​

Authentication​

PropertyTypeRequiredDescriptionExample
AWS credentialConfigurationNoSelect a saved AWS credential with an optional default region, or enter the authentication details and a region in the fields below. Learn more about credentials.
AuthenticationDropdownYes, if no AWS credential is set

The AWS authentication strategy:

  • Credentials (SaaS/Self-Managed): Use this option if you have a valid pair of access and secret keys provided by your AWS account administrator.

  • Default Credentials Chain (Hybrid/Self-Managed only): Use this option if your system is configured for implicit authentication, such as role-based authentication, credentials supplied through environment variables, or files on the target host. This approach uses the Default Credential Provider Chain to resolve the required credentials.

Access keyStringYes, if Authentication is CredentialsThe access key of an IAM user with permissions to the Amazon DynamoDB service.
Secret keyStringYes, if Authentication is CredentialsThe secret key of the IAM user with the access key above.

Region​

PropertyTypeRequiredDescriptionExample
RegionStringYes, if no AWS credential is setThe AWS region where the DynamoDB table exists or is created.us-east-1
RegionStringYes, if the credential has no default regionOverrides the default region of the selected AWS credential. Shown when an AWS credential is selected.

For more information on AWS regions, see the AWS documentation.

Operations​

Select the category in the Choose category dropdown (Table or Item), and then select the operation in the Select action dropdown. The properties that apply depend on the action.

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 is saved as a string.

When you update items, an attribute of type SET is overwritten and saved as a list type. Consider these limitations to prevent unintended data structure modifications in your DynamoDB tables.

Create table​

Create a new DynamoDB table. The connector waits until the table is active before it returns.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the DynamoDB table to create.
Partition keyStringYesThe attribute name of the partition key of the table.
Partition key roleDropdownYesThe role of the partition key attribute: HASH or RANGE.
Partition key attribute data typeDropdownYesThe data type of the partition key attribute: Binary, Number, or String.
Sort keyStringNoThe attribute name of the sort key of the table, if the table has one.
Sort key roleDropdownNoThe role of the sort key attribute: HASH or RANGE.
Sort key attribute data typeDropdownNoThe data type of the sort key attribute: Binary, Number, or String.
Read capacity unitsNumberYesThe maximum number of strongly consistent reads per second that the table supports. The connector uses it when Billing mode is PROVISIONED.
Write capacity unitsNumberYesThe maximum number of writes per second that the table supports. The connector uses it when Billing mode is PROVISIONED.
Billing modeDropdownYesControls how you are charged for read and write throughput: PROVISIONED or PAY_PER_REQUEST.
Deletion protectionDropdownYesPrevents accidental table deletion: True or False. The default is False.

For details on the key schema and billing modes, see the CreateTable API reference.

Output​

The connector returns the description of the created table. It includes, among others, the following fields:

  • tableName: The name of the table.
  • tableStatus: The status of the table.
  • keySchema: The key schema of the table.
  • attributeDefinitions: The attribute definitions of the table.
  • provisionedThroughput: The provisioned throughput settings of the table.
  • billingModeSummary: The billing mode of the table.
  • deletionProtectionEnabled: Whether deletion protection is enabled.
  • tableArn and tableId: The Amazon Resource Name (ARN) and the ID of the table.

For all fields, see TableDescription in the AWS documentation.

Delete table​

Delete an existing DynamoDB table. The connector waits until the table no longer exists before it returns.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the DynamoDB table to delete.

Output​

The connector returns the following fields:

  • action: The action performed, in the format delete Table [<table name>].
  • status: The status of the operation. OK indicates that the table was deleted.

Example response:

{
"action": "delete Table [test]",
"status": "OK"
}

Describe table​

Return information about a DynamoDB table.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the DynamoDB table to describe.

Output​

The connector returns the description of the table, with the same fields as the output of Create table. For all fields, see TableDescription in the AWS documentation.

To use the status of the table in your process, use a result expression such as:

= {
tableStatus: response.tableStatus
}

Scan table​

Return the items of a table by accessing every item in it. Use a filter expression to return only the items that meet certain criteria.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the DynamoDB table to scan.
Filter expressionStringNoThe filter expression to apply to the scan results. See filter expressions in the Amazon DynamoDB Developer Guide.
Projection expressionStringNoA string that identifies the attributes to retrieve. For multiple attributes, separate the names with commas.
Expression attribute namesStringNoA FEEL expression with a map of placeholders to attribute names. Use it as an alternative to actual attribute names in the filter or projection expression. See expression attribute names.
Expression attribute valuesStringNoA FEEL expression with a map of placeholders to the substitution values used in the filter or projection expression. See expression attribute values.

To learn more about Friendly Enough Expression Language (FEEL) expressions, see what is FEEL?.

Output​

The connector returns the following fields:

  • action: The action performed. Always scanTable.
  • status: The status of the operation. OK indicates success.
  • response: The list of items returned by the scan. If the scan returns no items, this field is null.

Example response:

{
"action": "scanTable",
"status": "OK",
"response": [
{
"id": "5",
"name": "Example item"
}
]
}

To use the items in your process, use a result expression such as:

= {
items: response.response
}

Add item​

Create a new item or replace an existing item with a new item.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the DynamoDB table to add the item to.
ItemStringYesA FEEL expression with the item to add, as a JSON object of attribute names and values. You do not need to specify data types. For example: ={"Name": "Example Item", "ID": "123", "Description": "This is an example item"}.

Output​

The connector returns the following fields:

  • item: The attributes returned by DynamoDB as a plain object, or null if DynamoDB returns none.
  • putItemResult: The result of the put request, with the fields sdkResponseMetadata, sdkHttpMetadata, attributes, consumedCapacity, and itemCollectionMetrics.

Delete item​

Delete a single item in a table by primary key.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the DynamoDB table to delete the item from.
Primary key componentsStringYesA FEEL expression with the primary key of the item to delete. A simple primary key has the partition key. A composite key also has the sort key.

Output​

The connector returns the following fields:

  • item: The attributes returned by DynamoDB as a plain object, or null if DynamoDB returns none.
  • deleteItemResult: The result of the delete request, with the fields sdkResponseMetadata, sdkHttpMetadata, attributes, consumedCapacity, and itemCollectionMetrics.

Get item​

Return the attributes of the item with the given primary key.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the table that contains the requested item.
Primary key componentsStringYesA FEEL expression with the primary key of the item to retrieve. Provide all key attributes: for a simple primary key, the partition key; for a composite primary key, the partition and sort keys.

Output​

The connector returns a list with one object per attribute of the item, for example one object for each column of the table. If no item matches, the output is null.

Example response:

[
{
"id": "5"
},
{
"name": "Example item"
}
]

Update item​

Modify the attributes of an existing item, or add a new item to the table if it does not exist.

Input parameters​

PropertyTypeRequiredDescriptionExample
Table nameStringYesThe name of the table that contains the item to update.
Primary key componentsStringYesA FEEL expression with the primary key of the item to update.
Key attributesStringYesA FEEL expression with the attribute names and values to write to the item.
Attribute actionDropdownYesThe action to apply to the attributes: PUT sets the attribute value, DELETE removes the attribute.

Output​

The connector returns the following fields:

  • item: The attributes returned by DynamoDB as a plain object, or null if DynamoDB returns none.
  • updateItemResult: The result of the update request, with the fields sdkResponseMetadata, sdkHttpMetadata, attributes, consumedCapacity, and itemCollectionMetrics.

Example​

The following example updates an item in a DynamoDB table.

SectionFieldDescriptionExample value
OperationChoose categoryThe category of the operation to perform.Item
Select actionThe action to update an item in the DynamoDB table.Update item
AuthenticationAuthenticationThe 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 update.test
Primary key componentsThe primary key component(s) of the item to update.{"id": "5"}
Key attributesJSON object with the new values for the item attributes.{ "stringValue": "StringValue", "numberValue": 42, "booleanValue": true }
Attribute actionThe action to perform on the attributes. PUT adds or updates the specified attributes.PUT
Output mappingResult variableThe name of the variable that stores the response from DynamoDB.result

Best practices​

There is no guarantee that a requested item is retrieved or updated immediately. Build your BPMN diagram to periodically retry until the item is available.

note

To avoid performance issues, limit the number of retries.

To learn more about implementing retry logic in your BPMN diagram, see the Camunda BPMN examples, which include diagrams with timer and loop configurations.

Troubleshooting​

To learn about general error handling in Camunda, see BPMN errors and failing jobs.

Check your configuration​

If you have 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 if you need further assistance.

Further resources​