Working with Processes

The Workflow definition of a Process is described using a JSON markup schema we call "WorkflowML". Details of the schema are beyond the scope of this documentation; the RAP UI application provides a visual editor for manipulating WorkflowML for processes.

For this reason, creating and editing Processes tends to be best carried out in that application, and the API is more likely to be used for initiating and monitoring Process execution.

We call an instance of a Process a "Run". Process Runs are executed on the RunQueue, and their results end up on the RunResults. These are the two endpoints we use for Run execution and results.

The Run Queue

To run a Process, an instance of it needs to be added to the Run Queue by sending a POST request to the /RunQueue endpoint. The request body should contain an array of Run Request objects as follows:

[
    {
        "ProcessId": 64,
        "Trigger": "Hourly cron",
            "Parameters": {
            "input": [
                {
                    "name": "SomeInputParam",
                    "type": "string",
                    "label": "SomeInputParam:",
                    "value": "My Input Value",
                    "mandatory": false
                }
            ]
         }
    }
]

curl --request POST 'https://example.com/rap/api/v3/rap/runqueue' --header 'Authorization: Bearer YOURTOKENGOESHERE' --data '@./requestbody.json'

The response from the queue request will contain confirmations of all the queue requests you made.

{
    "status": "success",
    "data": [
        {
            "status": "Process 64 queued successfully",
            "queueItem": {
                "id": 1539,
                "runId": 1539,
                "processId": 64,
                "processName": "My Hourly Process",
                "batchId": "10de0669-3858-11ef-8517-00155d01670a",
                "previousBatchId": "10de0673-3858-11ef-8517-00155d01670a",
                "status": "Pending",
                "queuedOn": "2024-05-02T09:47:16Z",
                "execStarted": "0001-01-01T00:00:00",
                "lastUpdated": "2024-05-02T09:47:16Z",
                "timeout": "2024-05-03T09:47:16Z",
                "batchcount": 0,
                "batchtotal": 0,
                "currentStepStarted": "0001-01-01T00:00:00",
                "params": "{\"input\":[{\"name\":\"SomeInputParam\",\"type\":\"string\",\"label\":\"SomeInputParam:\",\"value\":\"My Input Value\",\"mandatory\":false}],\"output\":[],\"mappings\":{\"process\":null,\"workitems\":null},\"state\":[]}",
                "errorInfo": "",
                "executedBy": "SysAdmin",
                "triggeredBy": "Hourly cron"
            }
        }
    ]
}

Of particular interest here is the runId which can be used to identify this run both on the queue, and later when you're looking up the results. Don't worry too much at this stage about the execStarted and currentStepStarted times as the Workflow engine won't have begun execution yet.

To monitor progress of this execution, just query the /runqueue endpoint with the runId returned in the initial queue request:

 curl --request GET 'https://example.com/rap/api/v3/rap/runqueue/1539' --header 'Authorization: Bearer YOURTOKENGOESHERE'

When a Process Run reaches a "completion" state transition, it will automatically be moved from the /RunQueue to /RunResults by the Workflow Engine, so once the queued item is no longer returned by the /runqueue endpoint, just switch to the /runresults endpoint to fetch its final status:

curl --request GET 'https://example.com/rap/api/v3/rap/runresults?runId=1539' --header 'Authorization: Bearer YOURTOKENGOESHERE'

You'll note that here, you need to specify the runId filter as a query parameter, not as part of the URL segment.

The results returned include the final status of the run, and the output state parameters - in case they're needed for further processing. If there was an execution error, there may be further information in the errorInfo field, otherwise you may be able to determine what happened from the Workflow Engine log.

{
    "status": "success",
    "data": {
        "id": 2007,
        "processId": 64,
        "runId": 1539,
        "processName": "My Hourly Process",
        "status": "Success",
        "lastUpdated": "2024-05-02T09:47:23Z",
        "queuedOn": "2024-05-02T09:47:16Z",
        "execStarted": "2024-05-02T09:47:17Z",
        "execFinished": "2024-05-02T09:47:20Z",
        "params": "{\"input\":[{\"name\":\"SomeInputParam\",\"type\":\"string\",\"label\":\"SomeInputParam:\",\"value\":\"My Input Value\",\"mandatory\":false}],\"output\":[],\"mappings\":{\"process\":null,\"workitems\":null},\"state\":[]}",
        "errorInfo": "",
        "executedBy": "SysAdmin",
        "triggeredBy": "Hourly cron"
    }
}