Skip to main content

Step Execution

Workflows in Track and Trace are made of steps, this steps stands for changes in an asset. With the execution of those steps we can change the properties of an asset, change the facility where they are or change the balance of an inventory.

In this section we explain how to execute a step, the authentication needed to do it and how to execute a specific step.

Run a step​

All the steps in Track and Trace are executed using the same endpoint. Depending on the type of the step we are running, some additional data have to be provided.

The execution step endpoint is: https://api.finboot.io/v1/step-executions

This endpoint is a PUT call to the API, and its request body have the following structure:

{
    "assetTrackId":"string",
    "stepDefinitionId": "string",
    "stepExecutorMetadata": "{}",
    "supplyChainId":"string",
    "workflowDefinitionId":"string" 
}
  • assetTrackId Stands for the unique identifier of the asset. Is needed in all the steps (except the first step of the workflow init)
  • stepDefinitionId stands for the identifier of the step we want to execute
  • stepExecutorMetadata stands for the additional data (depending on the type of step) the step needs to be executed
  • supplyChainId stands for the identifier of your supply chain
  • workflowDefinitionId stands for the workflow identifier you are executing the step on
tip
In order to know which are the identifiers of your supply chain, step definition, asset templates or workflow you can use the

/v1/step-executions/executable-workflows endpoint. More info in the API Reference

1. Authentication​

All the calls to Track and Trace uses a Json Web Token or JWT to authenticate (more info). To retrieve this token we have to make a call first to the Marco API and you will need the following information:

  • Client Id: This is the Marpp ID of the application accessing the resources.
  • Client Secret: This is a token generated for the service account that allows us to authenticate to the Finboot APIs. The token will look something like this structure: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa".
  • Service Account: This is the email of the service account being used to access resources.
note

If you do not have this data contact with Finboot team so that they can provide it to you.

This is a curl example to obtain the JWT (you must replace the identifiers [Client-Id], [Client-Secret] and [Marpp-Id] by yours)

curl --location 'https://api-marco.finboot.com/v1/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=[Client-Id]' \
--data-urlencode 'client_secret=[Client-Secret]' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'service_account=[Service-Account]'

As a result you will get a JWT string you must use in the consecutive calls for Track and Trace API.

{
    "access_token" : "[your-jwt-token]"
}

This token have to be included in an Authorization header as Bearer token (see the next section to get an example). The token have an expiration time of 5 minutes; you can call again to this endpoint to retrieve a new token when expires your current one.

'Content-Type: application/json'
'Authorization: Bearer [your-jwt-tokwen]'

2. Execute a Step​

To execute any step in Track and Trace API also will need another information and is the organization id. This information should be provided by the Finboot Team. The organizationId is a string that identifies uniquely your organization and is mandatory in all the calls.

This is a curl example to execute a step adding the previous generated JWT to the call

curl --location --request PUT 'https://api.finboot.io/v1/step-executions?organization-id=[your-organization-id]' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [your-jwt-tokwen]' \
--data '{
    "assetTrackId":"",
    "stepDefinitionId": "[your-step-definition-id]",
    "stepExecutorMetadata": {"asset-template-id":"[your-asset-template-id]"},
    "supplyChainId":"[your-supply-chain-id]",
    "workflowDefinitionId":"[your-workflow-definition-id]" 
}'
caution

The stepExecutorMetadata field is different for every type of step. In this case this object contains the asset template id, because is a INIT step and needs this information to run. A more detailed explanation of the types of the steps is included in this guide in the section Step types

3. The response of a step execution and its status​

The response of any step execution follows the same structure for all kinds of step, here an example:

{
    "assetTrackId": "UNIQUE-IDENTIFIER-OF-ASSET-001",
    "errorCode": null,
    "errorDetails": "",
    "id": "[id-of-the-step-instance]",
    "message": "",
    "status": "EXECUTED",
    "stepDefinitionId": "[your-step-definition-id]"
}
  • assetTrackId Stands for the unique identifier of the asset.
  • errorCode In case an error occurred running the step this will be filled with the code of the error.
  • errorDetails In case an error occurred running the step this fields gives additional information of the context of this error.
  • id Is the identifier of the step execution (or step instance id).
  • message: In case an error occurred running the step this fields gives a little description about the error itself.
  • status: This is the status of the execution, in this example is EXECUTED.
    • The main status that can be returned are:
      • COMPLETED : The step was successfully executed and also confirmed in the blockchain
      • EXECUTED: The step was successfully executed but still have to be confirmed by the blockchain
      • PRE_EXECUTION_FAILED: Some of the data sent to the step were not correct, or an internal validation failed.
      • EXECUTION_FAILED: An internal error in Track and trace
      • TX_FAILED: The blockchain transaction were failed.
tip

The execution endpoint returns the id param which is the identifier of the execution. You have another endpoint to check the status of this execution passing it this identifier: v1/step-executions/step-instances/{id}/stauts

Additionally, you can get in which step is currently executing a specific assetTrackId with this another endpoint: v1/step-executions/last-step-executed/{assetTrackId}

All those endpoints are described in the API Reference in this guide