Skip to main content

Step flags and other execution considerations

Doing a call to the API endpoint /v1/step-executions/executable-workflows you can obtain information about the step of a workflow. In this document will describe mainly what means the fields optional, automatic and ordinal among other execution considerations

The json below shows an example of one of the steps in a workflow returned by this endpoint

{
    "automatic": false,
    "facility": {
        "id": "demo-facility",
        "name": "Demo facility",
        "status": "OPERATIONAL"
    },
    "optional": false,
    "ordinal": 1,
    "stepDefinitionId": "start",
    "stepName": "start",
    "stepType": "INIT"
}

1. Execution Order​

Every step in a workflow has an ordinal field which is the order the step must be executed by the client. Once a step is executed, if the status returned by the API goes well, you will be able to execute the next step (ordinal + 1).

There is only one step of type INIT in a workflow and always have the ordinal 1. Evenly there is only one step of type FINISH in a workflow and is the last step to execute.

tip

In order to know which is the ordinal of every step of your workflow you can check the API Reference and try the endpoint /v1/step-executions/executable-workflows

There are two scenarios where the client could not follow the order pointed by the ordinal; In case the step is configured as automatic or optional. In that cases the client can (in the case of optional) or must (in the case of automatic) skip the step.

2. Automatic Steps​

Automatic steps can not be executed by the client because there is no need of input, and are already preconfigured with all the needed information.

The steps that can be automatic are:

There are some situations (except for finish case) where the step, despite being automatically configured, could be executed manually, and is when the step fails on the internal validation. This is when we receive in the response the status PRE_EXECUTION_FAILED.

3. Optional Steps​

Optional steps are steps that can be skipped. Once the step is skipped, executing the next one to it for instance, this optional step will not be able to be executed in this workflow execution.

The only two steps can not be optional are the INIT and the FINISH step

4. Validations and Failed executions​

When a step is executed it can fail for some reasons. In case the input data where malformed or incorrect (bad parameters), the API will return a validation error. You can fix the request and try again with the correct data.

There are some situations where the step instance of the step execution contains an error status in status. In that case if the error status is PRE_EXECUTION_FAILED you also can retry the step.

This second situation can happen because the following scenarios:

  • An automatic step of type INVENTORY trying to subtract more stock than the balance allows.
  • An automatic step of type TRANSFER trying to change the facility from a user that have not access to this facility.

5. Asset workflow exclusivity​

The smart contract related to Track and Trace forces to have only one asset running in one Workflow. In order to import An asset into another workflow or the same one, all the previous ones must be completed.

One workflow is considered completed when all its steps are in status completed.