Amazon S3 DynamoDB Connector

Amazon S3 DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance with seamless scalability. The adapter stores data in Amazon S3 DynamoDB Storage allowing to use the X4 BPMS for persisting data in cloud environments.

Properties

Operation

Defines the operation executed by the adapter

Possible values:

CreateTable: Creates a table with table name and primary key
Required parameters: tableName, partitionKey, partitionType. For sortable keys also sortKey, sortType. For AutoScaling also scalingMinCapacity, scalingMaxCapacity, scalingTargetValue, scalingInCooldown, scalingOutCooldown, scalableType, arnRole
UpdateTable: Updates an existing table modifing the Read/Write Capacity Units.
Required parameters: tableName, partitionKey, readCapacityUnits, writeCapacityUnits
ListTable: Lists all tables.
EnableAutoScaling: Enables AutoScaling for an existing table according to scalableType (Read/Write).
Required parameters: tableName. scalingMinCapacity, scalingMaxCapacity, scalingTargetValue, scalingInCooldown. scalingOutCooldown, scalableType, arnRole
DisableAutoScaling: Disables AutoScaling for an existing table according to scalableType (Read/Write).
Required parameters: tableName, scalableType
PutItem: Receives an XML input with the structure of the item to be put.
Required parameters: tableName
BatchPutMultipleItems: Inserts multiple items in a single call.
Required parameters: tableName

Required parameters

An input XML file containing the elements is required for this operation.
UpdateItem: Updates the specific item.
Required parameters: keyID,secretKey,region,tableName,partitionKey,partitionKeyValue
GetItem: Gets the specific item.
Required parameters: tableName, partitionKey, partitionType, partitionKeyValue (must match with the item to get). For sortable keys sortKey, sortType, sortKeyValue are also required.
BatchGetMultipleItems: Gets multiple items depending on the values of partitionKey specified in an XML file. All items are retrieved with all item attributes.
Required parameters: tableName, partitionKey, partitionType, partitionKeyValue (must match with the item to get). For sortable keys sortKey, sortType, sortKeyValue are also required.

An input XML file containing the elements is required for this operation.
Delete: Deletes item or table according to the configured parameters.

If tableName and the primary key elements are specified, the Delete operation deletes the specific item. If only tableName is specified, the Delete operation deletes the table.
BatchDeleteMultipleItems: Deletes multiple items in a single call.
Required parameters: tableName

An input XML file containing the elements is required for this operation.
Query: Retrieves a subset of items inside a table. Conditions are specified for the various attributes. For more information on the input file, please see the input section.
Erforderliche Parameter: tableName, partitionKey

partitionKey is mandatory and the comparator between partitionKey and sortKey is always "AND".
Possible operators: =, >, <, >=, <=, !=, BETWEEN, begins_with

Parameters

`Adapter`	Main adapter class (do not change!) Possible values: de.softproject.integration.adapter.amazondynamodb.AmazonDynamoDBAdapter: Main class (default)
`keyID`	Access key ID used to sign programmatic requests to AWS The credentials are passed by parameters to the adapter. There are different ways to configure them, see How to get credentials keys. Possible values: Any string containing the access key Id, e.g. `AKIAIOSFODNN7EXAMPLE`
`secretKey`	Secret access key used to sign programmatic requests to AWS The credentials are passed by parameters to the adapter. There are different ways to configure them, see How to get credentials keys. Possible values: Any string containing the secret access key e.g. `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
`region`	Domain region Possible values: Any string containing the region name, e.g. `us-east-2` Buckets created in a specific region, can not be accessed from a different region, s ee Regions and Endpoints.
`tableName`	Table name Possible values: Any string containing the table name The following naming rules apply to table names: All names must be UTF-8 encoded and are case-sensitive Table names and index names must be between 3 and 255 characters long, and may contain only the following characters: `a-z` `A-Z` `0-9` `_` (underscore) `-` (dash) `.` (dot) Attribute names must be between 1 and 255 characters long.
`partitionKey`, `partitionType` and `partitionKeyValue`	Items of the table primary key Possible values: `PartitionKey`: Name of the partition key `PartitionType`: Partition type S: the attribute is a string N: the attribute is a number B: the attribute is of the type Binary `PartitionKeyValue`: Item value. Is required for the `GetItem` and `BatchGetMultipleItems` operations.
`sortKey`, `sortType` and `sortKeyValue`	Items of the table primary key Possible values: `SortKey:` Name of the sortable key `SortType:` Sorting type S: the attribute is a string N: the attribute is a number B: the attribute is of the type Binary `SortKeyValue:` Item value; Is required for the operation `GetItem`.
`readCapacityUnits`, `writeCapacityUnits`	Read/Write Capacity Units Possible values: Integer Capacity Units
`scalableType`	Defines the scalable type for AutoScaling operation. Possible values: `ReadCapacity` `WriteCapacity`
`autoScaling`	Defines if the new table is created by using AutoScaling. In case of a check, all scaling parameters must be specified. Possible values: `true` `false`
`scalingMinCapacity`, `scalingMaxCapacity`, `scalingTargetValue`, `scalingInCooldown`, `scalingOutCooldown`	Defines scaling parameters for AutoScaling operation. Possible values: For more information, please see AutoScaling.
`arnRole`	ARN of the role authorized to handle AutoScaling operation for the resource of tables. Possible values: For more information, please see Amazon Resource Names (ARN).
`consistentRead`	DynamoDB uses eventually consistent reads unless it is specified otherwise. Read operations such as `GetItem` and `Query` provide a `ConsistentRead` parameter. If this parameter is set to `true` , DynamoDB uses strongly consistent reads during the operation.

Status values

1

The operation was executed successfully

0

Operation Delete:

the item does not exist
the table does not exist

-1 An error occurred during the operation's execution

Input

The adapter expects a specific XML structure as input. The structure depends on the operation used.

PutItem operation:

Expected structure for operation PutItem

XML

<?xml version="1.0" encoding="UTF-8" ?>
<RootElement>
	<Item>
		<Attribute name="..Name of PartionKey.." type="..Type of Partition.." value="..Value of PartitionKey.."/>
		<Attribute name="..Name of SortKey.." type="..Type of Sort.." value="..Value of SortKey.."/>
		<Attribute name="..Attribute Name.." type="..Attribute Type.." value="..Attribute Value.."/>
	</Item>
</RootElement>

In case of the operation PutItem there are no restrictions on element names. However the attributes name, value and type are required.

BatchGetMultipleItems operation:
Expected structure for operation BatchGetMultipleItems

XML
```
<?xml version="1.0" encoding="UTF-8" ?>
<PrimaryKeyValues>
	<PrimaryKey partitionKey="2" SortKey="Carlos" />
	<PrimaryKey partitionKey="5" SortKey="Luis" />
</PrimaryKeyValues>
```
Primary keys can be specified for different objects. If the object matches a table where only partitionKey is defined, only partitionKey may be specified, otherwise partitionKey and SortKey.

BatchPutMultipleItems operation:

Expected structure for operation BatchPutMultipleItems

XML

<?xml version="1.0" encoding="UTF-8" ?>
<RootElement>
	<Item>
		<Attribute name="ID" type="N" value="5" />
		<Attribute name="Name" type="S" value="Luis" />
		<Attribute name="Phone" type="N" value="0034666777888" />
		<Attribute name="Bonus" type="BOOL" value="true" />
		<Attribute name="Colours" type="LIST">
			<Attribute type="S" value="Red" />
			<Attribute type="S" value="Green" />
			<Attribute type="S" value="Blue" />
			<Attribute name="Cars" type="MAP">
				<Attribute5 name="Phone" type="N" value="637559681" />
				<Attribute6 name="Bonus" type="BOOL" value="true" />
				<Attribute7 name="Profession" type="S" value="Programmer" />
				<Attribute7 name="DocumentCode" type="B" value="qwrqfgdas1223455sdfffr" />
			</Attribute>
		</Attribute>
		<Attribute name="Cars" type="MAP">
			<Attribute5 name="Phone" type="N" value="637559681" />
			<Attribute6 name="Bonus" type="BOOL" value="true" />
			<Attribute7 name="Profession" type="S" value="Programmer" />
			<Attribute7 name="DocumentCode" type="B" value="qwrqfgdas1223455sdfffr" />
		</Attribute>
	</Item>
	<Item>
		<Attribute1 name="ID" type="N" value="5" />
		<Attribute3 name="Name" type="S" value="Luis" />
		<Attribute4 name="Surname" type="S" value="Delgado" />
		<Attribute2 name="Address" type="S" value="Pirandello" />
		<Attribute5 name="Phone" type="N" value="637559681" />
		<Attribute6 name="Bonus" type="BOOL" value="true" />
		<Attribute7 name="Profession" type="S" value="Programmer" />
		<Attribute7 name="DocumentCode" type="B" value="qwrqfgdas1223455sdfffr" />
	</Item>
</RootElement>

Several items can be specified. In the items, attributes of type Boolean (BOOL), String (S), Number (N), Map (MAP), List (LIST) and Binary (B) can be specified (see example). The output of this operation is the same XML file. This can be useful for further operations.

BatchDeleteMultipleItems operation:
Expected structure for operation BatchDeleteMultipleItems

XML
```
<?xml version="1.0" encoding="UTF-8" ?>
<RootElement>
	<Item>
		<Attribute1 name="ID" type="N" value="7" />
		<Attribute7 name="Name" type="S" value="Luis" />
	</Item>
	<Item>
		<Attribute1 name="ID" type="N" value="6" />
		<Attribute7 name="Name" type="S" value="Luis" />
	</Item>
</RootElement>
```
This input specifies the primary keys of the elements to be deleted. If the primary key consists only of partitionKey, only partionKey is needed. If the primary key consists of partitionKey and SortKey, both keys are needed to make the item to be deleted unique. The output of this operation is also the input.

UpdateItem operation:

Expected structure for operation updateItem

XML

<?xml version="1.0" encoding="UTF-8"?>
<Input>
	<Item>
		<Attribute name="ID" type="N" value="5"
			action="ADD|PUT|DELETE"></Attribute>
		<Attribute name="Name" type="S" value="Luis"
			action="ADD|PUT|DELETE"></Attribute>
		<Attribute name="Surname" type="S" value="Delgado"
			action="ADD|PUT|DELETE"></Attribute>
	</Item>
</Input>

Actions for updateItem

ADD: Mathematically adds a numerical value to an existing numerical attribute value.

PUT: Creates a new attribute or overwrites an existing attribute value.

DELETE: Deletes the attribute from the item.

Query operation:
Expected structure for operation Query

XML
```
<?xml version="1.0" encoding="UTF-8" ?>
<Query>
	<KeyCondition>ID=:param1</KeyCondition>
	<OtherFilters>Colors[3].Profession=:param3 or DocumentCode=:param2</OtherFilters>
	<QueryParameters>
		<Parameter type="N" alias=":param1" value="5" />
		<Parameter type="B" alias=":param2" value="cXdycWZnZGFzMTIyMzQ1NXNkZmZmcg==" />
		<Parameter type="S" alias=":param3" value="Programmer" />
	</QueryParameters>
</Query>
```
Parent element Query consists of three elements:
- KeyCondition: Only to specify partitionKey and if present SortKey, meeting following conditions:
  - Comparator between partitionKey and SortKey is always "AND".
  - partitionKey is mandatory and always used with "=".
  - If SortKey is used, following operators can be used: =, >, <, >=, <=, !=, BETWEEN, begins_with.
  - partitionKey and SortKey must not match with reserved words for AWS DynamoDB.
- OtherFilters: Specifies conditions for the rest of attributes that are not part of the primary key. The attributes must not match with reserved words for AWS DynamoDB .
- QueryParameters: Specifies the mapping between used parameters and their corresponding values. The type of every parameter must be specified.

Output

The adapter returns different kind of documents depending on the executed operation:

GetItem operation:

Sample output for operation GetItem

XML

<?xml version="1.0" encoding="UTF-8"
<Result>
	<Item partitionKey="ID" partitionKeyValue="2" SortKey="Name" SortKeyValue="Carlos">
		<Attribute name="Address" type="S" value="Pirandello"/>
		<Attribute name="Phone" type="N" value="637559681"/>
		<Attribute name="Bonus" type="BOOL" value="true"/>
		<Attribute name="DocumentCode" type="B" value="qwrqfgdas1223455sdfffr"/>
		<Attribute name="Surname" type="S" value="Delgado"/>
		<Attribute name="Profession" type="S" value="Programmer"/>
	</Item>
</Result>

BatchGetMultipleItems operation:

Sample output for operation BatchGetMultipleItems

XML

<?xml version="1.0" encoding="UTF-8" ?>
<Result>
	<Item partitionKey="ID" partitionKeyValue="5" SortKey="Name" SortKeyValue="Luis">
	<Attribute type="MAP" name="Cars">
			<Attribute type="N" name="Phone" value="637559681" />
			<Attribute type="BOOL" name="Bonus" value="true" />
			<Attribute type="B" name="DocumentCode" value="qwrqfgdas1223455sdfffr" />
	<Attribute type="S" name="Profession" value="Programmer" />
	</Attribute>
		<Attribute type="N" name="Phone" value="34666777888" />
	<Attribute type="LIST" name="Colours">
			<Attribute type="S" value="Red" />
			<Attribute type="S" value="Green" />
	<Attribute type="S" value="Blue" />
			<Attribute type="MAP" name="Colours">
				<Attribute type="N" name="Phone" value="637559681" />
				<Attribute type="BOOL" name="Bonus" value="true" />
				<Attribute type="B" name="DocumentCode" value="qwrqfgdas1223455sdfffr" />
				<Attribute type="S" name="Profession" value="Programmer" />
	</Attribute>
	</Attribute>
		<Attribute type="BOOL" name="Bonus" value="true" />
	</Item>
	<Item partitionKey="ID" partitionKeyValue="2" SortKey="Name" SortKeyValue="Carlos">
		<Attribute type="S" name="Address" value="Pirandello" />
		<Attribute type="N" name="Phone" value="637559681" />
		<Attribute type="BOOL" name="Bonus" value="true" />
	<Attribute type="B" name="DocumentCode" value="qwrqfgdas1223455sdfffr" />
		<Attribute type="S" name="Surname" value="Delgado" />
		<Attribute type="S" name="Profession" value="Programmer" />
	</Item>
</Result>

For each element, an Item element with fields for the primary key and the associated values is created. Within the Item element is a list of the associated attributes.

ListTables operation:
Sample output for operation ListTables

XML
```
<?xml version="1.0" encoding="UTF-8" ?>
<Result>
	<sampleItems />
</Result>
```
Parent element Result is provided that contains one element for each table declared in the account.

Query operation:

Sample output for operation Query

XML

<?xml version="1.0" encoding="UTF-8" ?>
<Result hasMorePages="false">
	<Item>
		<Attribute value="{Phone=637559681, Bonus=true, DocumentCode=[B@231dee4d, Profession=Programmer}" name="Cars" />
		<Attribute value="34666777888" name="Phone" />
		<Attribute value="[Red, Green, Blue, {Phone=637559681, Bonus=true, DocumentCode=[B@5857d888, Profession=Programmer}]" name="Colours" />
	<Attribute value="true" name="Bonus" />
	<Attribute value="5" name="ID" />
	<Attribute value="Luis" name="Name" />
	</Item>
</Result>

Parent element Result is delivered. Attribute hasMorePages specifies if the result has more pages to display or not. This is useful for large responses. For each element that matches the query conditions, an item element is created that contains all attributes.