Skip to content
This repository was archived by the owner on Nov 9, 2022. It is now read-only.

State Machine Definition Syntax

Jump to bottom
Tyler Replogle edited this page Jan 11, 2021 · 5 revisions

State Conductor state machine definitions are defined using a subset of Amazon States Language (ASL). The syntax below is directly derived from the ASL specification, with any customizations or omissions noted.

  1. State Machine Definition
  2. mlDomain
  3. State Types
    1. Task
    2. Choice
    3. Pass
    4. Wait
    5. Succeed
    6. Fail
  4. Fallback States

Required fields are indicated in bold.
Unsupported fields are indicated with strikethrough.
Field names are case-sensitive.

State Machine Definition (Top Level Fields)

  • Comment - A human-readable description of the state machine.
  • StartAt - A string that must exactly match (is case sensitive) the name of one of the state objects.
  • mlDomain - Object which defines the MarkLogic scope(s) for which documents this state machine should process. State Conductor Custom
  • States - An object containing a comma-delimited set of states.
  • TimeoutSeconds - The maximum number of seconds an execution of the state machine can run. If it runs longer than the specified time, the execution fails with a States.Timeout Error Name.
{
  "Comment": "example state machine",
  "mlDomain": {
    "context": [
      {
        "scope": "collection",
        "value": "example"
      }
    ]
  },
  "StartAt": "state1",
  "States": {}
}

mlDomain

A State Conductor custom block used to define the set of documents to which this state machine will apply. These State Machine Definition Contexts are utilized by the State Conductor's triggers to match MarkLogic documents. If more than one context is defined they are "OR'd" together (ie: a document matching any of the contexts will be considered in-scope for this state machine). If no contexts are defined, then no document's will have this state machine automatically applied; however documents can be manually added via API calls.

  • context - an array of scoping rules to define documents this state machine should be applied to.
    • scope - the scope of the corresponding value field. One of "collection", "directory", or "query".
    • value - the value of the collection, directory, or serialized cts-query to match documents against.
{
  "context": [
    {
      "scope": "collection",
      "value": "example"
    },
    {
      "scope": "directory",
      "value": "/example/"
    },
    {
      "scope": "query",
      "value": "{\"andQuery\":{\"queries\":[{\"collectionQuery\":{\"uris\":[\"example\"]}}, {\"elementValueQuery\":{\"element\":[\"name\"], \"text\":[\"Jane Doe\"], \"options\":[\"lang=en\"]}}]}}"
    }
  ]
}

State Types

State Conductor state machines are comprised of one or more States. The following subset of ASL states are supported: Task, Choice, Pass, Succeed, and Fail.

Task State

A task state performs a unit of work by executing code identified by the state's Resource field.

  • Type - "Task"
  • Comment - Holds a human-readable description of the state
  • Next - The name of the next state that is run when the current state finishes. One of "Next" or "End" is required.
  • End - Designates this state as a terminal state (end of execution) if set to true. There can be any number of terminal states per state machine. One of "Next" or "End" is required.
  • Resource - A URI referencing a MarkLogic SJS module that idenfies the specific Action Module to execute.
  • Parameters - Used to pass information to the API actions of connected resources. The parameters can use a mix of static JSON and JsonPath.
  • Catch - An array of objects, called Catchers, that define a fallback state. This state is executed if the state encounters runtime errors and its retry policy is exhausted or isn't defined. For more information, see Fallback States.
  • InputPath - A path that selects a portion of the state's input to be passed to the state's task for processing. If omitted, it has the value of "$" which designates the entire input.
  • OutputPath - A path that selects a portion of the state's input to be passed to the state's output. If omitted, it has the value "$" which designates the entire input.
  • ResultPath - Specifies where (in the input) to place the results of executing the task that's specified in Resource. The input is then filtered as specified by the OutputPath field (if present) before being used as the state's output.
  • Retry - An array of objects, called Retriers, that define a retry policy if the state encounters runtime errors.
  • TimeoutSeconds - If the task runs longer than the specified seconds, this state fails with a States.Timeout error name. Must be a positive, non-zero integer. If not provided it uses the app servers time out. If timeout give is greater than the app servers max time out then the max time out is used.
  • HeartbeatSeconds - If more time than the specified seconds elapses between heartbeats from the task, this state fails with a States.Timeout error name. Must be a positive, non-zero integer less than the number of seconds specified in the TimeoutSeconds field. If not provided, the default value is 99999999.
{
  "Type": "Task",
  "End": true,
  "Comment": "runs an example DHF step",
  "Resource": "/state-conductor/actions/common/dhf/dhf5RunFlowStepAction.sjs",
  "Parameters": {
    "flowName": "exampleDhfFlow",
    "step": 1,
    "flowOptions": {
      "opt1": "value"
    }
  },
  "Catch": [
    {
      "ErrorEquals": ["States.ALL"],
      "Next": "FailState"
    }
  ]
}

Choice State

A choice state adds branching logic to a state machine. A choice state must have a "Choices" field whose value is a non-empty array. Each element of the array is called a choice rule - an object containing a comparison operator"Resource" field and a "Next" field, whose value must match a state name.

  • Type - "Choice"
  • Comment - Holds a human-readable description of the state
  • Default - The name of the state to transition to if none of the transitions in Choices is taken.
  • Retry - An array of objects, called Retriers, that define a retry policy if the state encounters runtime errors.
  • TimeoutSeconds - If the task runs longer than the specified seconds, this state fails with a States.Timeout error name. Must be a positive, non-zero integer. If not provided it uses the app servers time out. If timeout give is greater than the app servers max time out then the max time out is used.
  • Choices - An array of Choice Rules that determines which state the state machine transitions to next.
    • Resource - A URI referencing a MarkLogic SJS module that idenfies the specific Condition Module to execute.
    • Next - The state to transition to should this choice match.
    • Parameters - Used to pass information to the API actions of connected resources. The parameters can use a mix of static JSON and JsonPath. State Conductor custom.
  • Catch - An array of objects, called Catchers, that define a fallback state. This state is executed if the state encounters runtime errors and its retry policy is exhausted or isn't defined. For more information, see Fallback States.
{
  "Type": "Choice",
  "Comment": "example choice state",
  "Choices": [
    {
      "Resource": "/ext/state-conductor/example-state-machine/option1.sjs",
      "Comment": "checks for option1 condition",
      "Parameters": {
        "param1": "hello",
        "param1": "world"
      },
      "Next": "performOption1"
    },
    {
      "Resource": "/ext/state-conductor/example-state-machine/option1.sjs",
      "Comment": "checks for option2 condition",
      "Parameters": {
        "paramName": "test"
      },
      "Next": "performOption2"
    }
  ],
  "Default": "FallbackState",
  "Catch": [
    {
      "ErrorEquals": ["States.ALL"],
      "Next": "FailState"
    }
  ]
}

Pass State

The pass state simply works as a pass-through, performing no work. Pass states are useful when constructing and debugging state machines.

  • Type - "Pass"
  • Comment - Holds a human-readable description of the state
  • Next - The name of the next state that is run when the current state finishes. One of "Next" or "End" is required.
  • Parameters - Create a collection of key-value pairs that will be passed as input. Values can be static, or selected from the input with a path.
  • Result - Treated as the output of a virtual task to be passed to the next state, and filtered as specified by the ResultPath field (if present)
  • ResultPath - Specifies where (in the input) to place the "output" of the virtual task specified in Result. The input is further filtered as specified by the OutputPath field (if present) before being used as the state's output.
{
  "Type": "Pass",
  "Comment": "no-op",
  "Result": {
    "name": {
      "first": "john",
      "last": "doe"
    }
  },
  "Next": "do-next"
}

Wait State

(Added in version 0.4.0)

A Wait state ("Type": "Wait") delays the state machine from continuing. You can choose either an event based resuming or a time based resuming. Event base resuming waits for an event to get emitted. There is a common task that allows for emitting of an event and a function that can be called in an server side module to emit an event. Time base resuming allows for relative time, specified in seconds from when the state begins, or an absolute end time, specified as a timestamp.

The schedule task that checks for time based waiting happens once a minute. Granularity less than a minute is treated as a minute and will be resumed at the minute mark with schedule task

  • Type - "wait"
  • Comment - Holds a human-readable description of the state
  • Next - The name of the next state that is run when the current state finishes. One of "Next" or "End" is required.
  • Seconds - A time, in seconds, to wait before beginning the state specified in the Next field.
  • Timestamp - An absolute time to wait until beginning the state specified in the Next field. Timestamps must conform to the RFC3339 profile of ISO 8601, with the further restrictions that an uppercase T must separate the date and time portions, and an uppercase Z must denote that a numeric time zone offset is not present, for example, 2016-08-18T17:33:00Z.
  • SecondsPath - A time, in seconds, to wait before beginning the state specified in the Next field, specified using a path from the state's context data.
  • TimestampPath - An absolute time to wait until beginning the state specified in the Next field, specified using a path from the state's context data.
  • Event - The event to be listen to in order to resume
  • EventPath - The event to be listen to in order to resume, specified using a path from the state's context data (Added in version 0.6.0)
"wait_ten_seconds": {
  "Type": "Wait",
  "Seconds": 10,
  "Next": "NextState"
}
"wait_until" : {
  "Type": "Wait",
  "Timestamp": "2016-03-14T01:59:00Z",
  "Next": "NextState"
}
"wait_event": {
  "Type": "Wait",
  "Event": "eventName:EventID",
  "Next": "NextState"
}
"wait_event": {
  "Type": "Wait",
  "EventPath": "$.eventName",
  "Next": "NextState"
}

Succeed State

The succeed state terminates a state machine successfully. The succeed state is a useful target for choice-state branches that don't do anything except terminate the state machine.

  • Type - "Succeed"
  • Comment - Holds a human-readable description of the state
{
  "Type": "Succeed",
  "Comment": "State machine processing completed successfully"
}

Fail State

The fail state terminates the state machine and marks it as a failure.

  • Type - "Fail"
  • Comment - Holds a human-readable description of the state
  • Cause - Provides a custom failure string that can be used for operational or diagnostic purposes.
  • Error - Provides an error name that can be used for error handling (Retry/Catch), operational, or diagnostic purposes.
{
  "Type": "Fail",
  "Comment": "State machine processing terminated unsuccessfully"
}

Fallback States

TODO

Clone this wiki locally