Build a request

Add, order, and edit the operations of a request in the request workbench.

Each operation is a separate AWS call, and Dynomate does not roll back earlier writes. See No rollback.

version = "1.0"
name = "find-and-update-order"
description = "Find the most recent order for an account, mark it reviewed, and read it back."

[variables]
accountId = "account#42"
pageSize = "1"

[defaults]
profileName = "commerce-dev"

[[dynamodb.query]]
name = "Find recent order"
tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"
keyConditionExpression = "accountId = :accountId"
limit = "${cast(pageSize, 'integer')}"
scanIndexForward = false

[dynamodb.query.expressionAttributeValues]
":accountId" = "${accountId}"

[[dynamodb.update]]
name = "Mark reviewed"
dependsOn = "Find recent order"
tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"
updateExpression = "SET #status = :status"

[dynamodb.update.keyValues]
accountId = "${accountId}"
orderId = "${find_recent_order.items[0].orderId}"

[dynamodb.update.expressionAttributeNames]
"#status" = "status"

[dynamodb.update.expressionAttributeValues]
":status" = "REVIEWED"

[[dynamodb.get]]
name = "Read back"
dependsOn = "Mark reviewed"
tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"
consistentRead = true

[dynamodb.get.keyValues]
accountId = "${accountId}"
orderId = "${find_recent_order.items[0].orderId}"

$ dynomate-cli requests run ./orders/find-and-update-order.dnml
find-and-update-order: success
Find recent order: success
  result: {"count":1,"items":[{"accountId":"account#42","orderId":"order#9812","status":"PENDING","total":42}],"lastEvaluatedKey":"eyJvcmRlcklkIjp7IlMiOiJvcmRlciM5ODEyIn0sImFjY291bnRJZCI6eyJTIjoiYWNjb3VudCM0MiJ9fQ==","pages":1,"requestId":"1f999a0f-0ec9-4dba-bd58-c012239a26db","scannedCount":1}
Mark reviewed: success
  result: {"attributes":{"accountId":"account#42","orderId":"order#9812","status":"REVIEWED","total":42},"requestId":"38ea89c4-6e57-48d5-a038-66ab17034323"}
Read back: success
  result: {"found":true,"item":{"accountId":"account#42","orderId":"order#9812","status":"REVIEWED","total":42},"requestId":"d2946fe3-e6b1-4ede-a4ce-aa4cd1365319"}

Operation Rail

The Operations rail lists the operations in file order. To change the order, use the operation menu.

Add an operation

1. Select Add operation, the + next to Operations.
2. Type in Find an operation…, or look in the groups.
3. Select the operation type.

Dynomate adds the operation at the end, with the name of its type.

Row indicators

• Status dot: the status of the operation.
• Disabled: Dynomate skips the operation. You can still edit it.
• Issue count: the number of fields with a problem.

Operation Header

The header has these fields:

• Operation type: the block header in the file. See Operation blocks.
• Table ARN In DNML tableArn : the full ARN. Dynomate gets the region from it. Type ${ for suggestions. For Create table, enter the new ARN.
• AWS profile In DNML profileName : if it is empty, Dynomate uses the request default, or else default.
• Region In DNML region : for PartiQL statement, List tables, and Athena operations. It can also come from Request settings.
• Add dependency In DNML dependsOn : operations that must succeed first. See Dependencies.

Athena operations also show Catalog, Database, Table, and Workgroup. An endpoint URL In DNML endpointUrl from the file shows as a read-only endpoint · … chip.

An operation that deletes or truncates a table shows a Destructive badge and needs confirmation.

Operation Tabs

The fields are on a maximum of three tabs. Each tab shows its issue count.

• Action tab: what the operation does. The table gives its name.
• Output: what the operation returns, for example projections, pagination, and consumed capacity.
• Execution: On operation error In DNML onError , Operation timeout (ms) In DNML timeoutMs , and more for some types.

The other types have no action tab. For all fields, see the Operation reference.

Dynomate keeps your changes when you change the operation or tab. If a field is not valid, you cannot save or run the request. Dynomate shows the field that has the problem.

Query Fields

Find recent order is a Query. Its Query tab has:

• Index name In DNML indexName : a secondary index to query.
• Key condition expression In DNML keyConditionExpression : required.
• Filter expression In DNML filterExpression : removes items after DynamoDB reads them.
• Attribute name aliases In DNML expressionAttributeNames and Attribute value aliases In DNML expressionAttributeValues : see Placeholders and aliases.
• Consistent read In DNML consistentRead : Default writes no key to the file.

Its Output tab has:

• Projection expression In DNML projectionExpression , with an Edit attribute name aliases link.
• Scan index forward In DNML scanIndexForward : No puts the newest order first.
• Limit per call In DNML limit , Maximum pages In DNML maxPages , and Maximum items In DNML maxItems : how much to read.
• Start token or key In DNML exclusiveStartKey : starts from an earlier page.
• Consumed capacity In DNML returnConsumedCapacity : None, Total, or By index.

Update Item Fields

Mark reviewed is an Update item. Its Update tab has:

• Key In DNML keyValues : required. Here, orderId comes from the Query result: ${find_recent_order.items[0].orderId}.
• Expression form: Full expression or Separate clauses. Before you run, remove the form that you do not use.
• Update expression In DNML updateExpression : the full expression.
• SET clause In DNML setExpression , REMOVE clause In DNML removeExpression , ADD clause In DNML addExpression , and DELETE clause In DNML deleteExpression : the separate clauses.
• Condition expression In DNML conditionExpression : the update occurs only if it is true.
• Attribute name aliases In DNML expressionAttributeNames and Attribute value aliases In DNML expressionAttributeValues .

Its Output tab has Return values In DNML returnValues and Consumed capacity In DNML returnConsumedCapacity .

Read back is a Get item with Key In DNML keyValues and Consistent read In DNML consistentRead . Consistent read is Yes, so it reads the update.

Dependencies

An operation with a dependency runs after the dependency, and only if the dependency succeeds. Add one when an operation uses an earlier result.

1. Select the operation that uses the result.
2. In the header, select Add dependency In DNML dependsOn .
3. Select the operation that it depends on.

To remove a dependency, select × on its chip.

If a dependency fails or Dynomate skips it, Dynomate skips its dependents. See Dependencies and execution.

To refer to a result, use the result root: the operation name in lowercase, with underscores for spaces. For example, find_recent_order. See Result roots.

Placeholders and Aliases

DynamoDB expressions use #name placeholders for attribute names and :value placeholders for values. The Placeholders section maps them:

• Attribute name aliases: the attribute name for each #name, as text or an expression.
• Attribute value aliases: the value and type for each :value.

Each map has two views. A change of view does not change the request.

• Fields: one row for each placeholder. Enter a value for Missing value. You can remove not referenced rows.
• Editor: the map as text, or a reference to a variable with the map, for example ${nameAliases}.

A reference opens in Editor. To edit it as rows, select Replace reference with fields.

Values and Expressions

Text fields accept ${…} templates. Number, Yes/No, option, map, and list fields have these controls:

• Use expression: changes the field to a text field for a template. For example, Limit per call uses ${cast(pageSize, 'integer')} because environment variables are text.
• Use value or Use fields: changes back and restores the previous value.
• Reset: clears an optional field, so the default applies.

Consistent read, On operation error, and the timeouts accept only literal values. See Variables and expressions.

Operation Menu

The … menu of each rail row has these items:

• Rename In DNML name : Dynomate also changes the dependencies and result references that use the old name.
• Description and tags… In DNML description : edit the Description and Tags In DNML tags .
• Move up and Move down: change the order.
• Duplicate: adds a copy named <name> copy below the operation.
• Disable / Enable In DNML enabled : Dynomate skips a disabled operation and all operations that depend on it.
• Delete: removes the operation. To restore it, select Undo removal.

Change an Operation's Type

1. In Operation type, select the new type.
2. If Dynomate shows Change operation type?, select Change type and remove these fields.

The dialog lists the fields that the new type does not accept. To cancel, select Keep current type. If the new type has no table, Dynomate removes the table ARN.

Request Settings

Request settings, at the bottom of the rail, applies to the full request:

• Description: notes about the request.
• Variables: the Request variables map. See Request variables.
• Connection defaults: AWS profile, Region, Endpoint URL, Athena workgroup, and Athena output location. An operation can set its own.
• On error: Continue independent operations, Stop request, or Continue dependents without result.
• Request timeout (ms): the time limit for the full run.
• Acknowledge destructive operations: Dynomate writes this setting to the file, but still asks you to confirm table deletion and truncation.
• Extension data: for your own tools. Dynomate does not use it.

Dynomate saves these as top-level tables. See Top-level keys.