Action

An action may be performed by the user when submitting a step. Actions can submit to an endpoint, progress the flow, or exit the flow.

An action typically defines its URL and HTTP method to submit step data, and can optionally indicate that, on success, the flow must end.

An endpoint can respond to a submitting action with an error status code and the standard error response format in order to display errors to the user.

If an action does not specify the exit property as true, it is expected that the action will submit the step payload. For example, the following action is a non-exiting action.

action {
    url = "/submitForm"
    method = HttpMethod.POST
}

If an action specifies exit as true, it is expected that this action should terminate the flow. For exiting actions, the url property is optional.

If the url property is not specified, when the action is taken the flow will be terminated and the value of the result property will be used as the result of the flow.

Given the following action:

action {
    exit = true
    result = encodeToJsonElement(mapOf(
        "someKey" to "someValue"
    ))
}

When this action is taken, the flow will be completed and the result of the flow will be:

{
  "someKey": "someValue"
}

If the url property is specified, the step payload will be submitted. On a successful response, the result property of the action (if provided) will be merged with the response to the submission, and that combined result will be used as the result of the flow, which will terminate. In case of any conflicts in the merge, the value of the result property of the action takes precedence.

However, it is not recommended to use this approach. Instead, a non-exiting action should be used to submit the step payload, and the flow should be terminated by the server by returning an X-DF-Response-Type: exit header in the response. See "Actions Which Sometimes Exit" for more information.

In some cases, the provider of the step will not know if a submitting action will exit. For example, depending on the data entered by the user, the flow may be complete, or we may need to ask them some follow-up questions. In these cases the exit property shouldn’t be specified. Instead, the response to the submission should include an X-DF-Response-Type: exit header. When the client receives this header in the response, it will continue in the same way as it would for a submitting exiting action. See Flow Response.

This tree summarises the possible paths an action can lead to:

• If exit is true:
  • If url is null:
    • Exit flow with value of result
  • If url is non-null: (not recommended)
    • Submit to url
    • Merge value of result into response body
    • Exit flow with the merged result
• If exit is false, or not provided:
  • Submit to url
  • If response has header X-DF-Response-Type: "exit":
    • Merge value of result into response body
    • Exit flow with the merged result
  • If response does not have header X-DF-Response-Type: "exit":
    • The response is handles as normal