Skip to content

Toro Cloud Dev Center


Event Based Workflow REST API

Aside from programmatically managing your Event Based Workflow services via Event Based WorkflowMethods, Martini also allows you to manage your workflows via the Event Based Workflow REST API. With this API, you can:

Event Based Workflow REST API or Event Based WorkflowMethods?

If you are trying to handle Event Based Workflow service(s) from another service, TORO recommends you use Event Based WorkflowMethods instead.

Headers

By default, the Event Based Workflow REST API allows access to all Event Based Workflow services. The request privilege may be elevated by providing an Authorization header:

Header Name Data Type Description
Authorization string Bearer <The access token of a Martini user>

Endpoints

All endpoints of the Event Based Workflow REST API have paths beginning with /flux-api. Read on below for more information about the API's endpoints.

Available as a Postman collection (v2.1)

You can use Postman to try out and call the endpoints of the Event Based Workflow REST API. Simply download and import this Postman collection.

Execute a Event Based Workflow service

Method Path
POST /flux-api/{package}/execute

Request

Path parameters

Parameter name Data type Required Description
package string true The name of the Martini package where the Event Based Workflow is contained.

Body Parameters

Parameter Name Data Type Required Description
fluxName string true The name of the Event Based Workflow service to be run. If the service is located inside a directory, its name should be prepended by the name of its subdirectories separated by periods. For example, org.your.SendAlerts.
startState string false The name of the state where the Event Based Workflow execution should start.
input object false The inputs which will be fed to the target Event Based Workflow service.
tags string[] false The tags to be added to the Event Based Workflow service during execution.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
curl -X POST \
  'http://<host>:<port>/flux-api/examples/execute' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "fluxName": "flux.ProcessData",
    "input": {
      "order": {
        "productId": "productA",
        "quantity": 2
       }
    },
    "tags": [
        "invoke"
    ]
}'

Response

Content Type

  • application/json
  • application/xml

Example

1
2
3
4
{
  "message" : "Event Based Workflow flux.ProcessData is now executing",
  "contextId" : 13
}

Terminate a Event Based Workflow service

Method Path
DELETE /flux-api/terminate

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long true The context ID of the to-be-stopped but running Event Based Workflow service.

Example

1
2
3
curl -X DELETE \
  'http://localhost:8080/flux-api/terminate?contextId=32' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

1
2
3
{
  "message" : "Event Based Workflow terminated"
}

Send an event to Event Based Workflow services

Method Path
POST /flux-api/event

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long false The context ID of the running Event Based Workflow service you want to send the event to. Specify this parameter only when a single Event Based Workflow service will receive the event.

Body Parameters

Parameter Name Data Type Required Description
event string true The name of the event the waiting state should transition to.
input object false The inputs to be given to the Event Based Workflow service(s).
tags string[] false The tags to use for determining which Event Based Workflow Services the external event should be sent to.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl -X POST \
  http://localhost:8080/flux-api/event \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "event": "done",
  "input": {
    "greeting": "hello"
  },
  "tags": [
    "users"
  ]
}'

Response

Parameter Name Data Type Description
transitions object[] The Event Based Workflow services which were transitioned by the external event.
executions object[] The Event Based Workflow services which were triggered by the external event.

Content Type

  • application/json
  • application/xml

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "message": "Event done has been sent",
    "transitions": [
        {
            "contextId": 201,
            "state": "state_A"
        },
        {
            "contextId": 203,
            "state": "state_B"
        }
    ],
    "executions": [
        {
            "contextId": 205,
            "state": "state"
        }
    ]
}

Get all Event Based Workflow services' contexts

Method Path
GET /flux-api/contexts

Request

Query Parameters

Parameter Name Data Type Required Multiple Description
fluxName string false false Specify to fetch only the contexts of Event Based Workflow services whose names match the value of this parameter.
tag string false true Specify to fetch only the contexts of Event Based Workflow services whose tags match all the values of this parameter.
status string false false Specify to fetch only the contexts of Event Based Workflow services whose statuses match the value of this parameter.
currentState string false false Specify to fetch only the contexts of Event Based Workflow services whose current states match the value of this parameter.
startState string false false Specify to fetch only the contexts of Event Based Workflow services whose starting states match the value of this parameter.
limit integer false false Limits the number of contexts returned. The default value is 30.
page integer false false Used with limit to select which page of the response should be returned. Its default value is 0.

Example

1
2
3
curl -X GET \
  'http://localhost:8080/flux-api/contexts?status=WAITING_UNTIL&fluxName=flux.ProcessExternalEvent' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
[
    {
        "fluxName": "flux.ProcessExternalEvent",
        "id": 185,
        "currentState": "Process_Event_State",
        "startState": "Start_State",
        "waiting": true,
        "debugged": true,
        "nextRun": 1526967557049,
        "status": "WAITING_UNTIL",
        "input": {
            "name": "input",
            "type": "model",
            "allowExtraProperties": true,
            "gloopProperties": []
        },
        "output": {
            "name": "output",
            "type": "model",
            "allowExtraProperties": true,
            "gloopProperties": []
        },
        "tags": [],
        "stateContexts": [
            {
                "name": "Start_State",
                "input": {
                    "name": "input",
                    "type": "model",
                    "allowExtraProperties": true,
                    "gloopProperties": []
                },
                "output": {
                    "name": "output",
                    "type": "model",
                    "allowExtraProperties": true,
                    "gloopProperties": []
                },
                "transitionContexts": [
                    {}
                ]
            }
        ],
        "executionHistory": [
            {
                "fluxName": "flux.ProcessExternalEvent",
                "stateName": "Start_State",
                "stateIndex": 0
            }
        ]
    }
]

Get a Event Based Workflow service's context

Method Path
GET /flux-api/context

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long true The context ID of the running Event Based Workflow service whose context is to be fetched.

Example

1
2
3
curl -X GET \
  'http://localhost:8080/flux-api/context?contextId=209' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
    "fluxName": "flux.ProcessExternalEvent",
    "id": 209,
    "currentState": "Process_Event_State",
    "startState": "Start_State",
    "waiting": true,
    "debugged": true,
    "nextRun": 1526974884257,
    "status": "WAITING_UNTIL",
    "input": {
        "name": "input",
        "type": "model",
        "allowExtraProperties": true,
        "gloopProperties": []
    },
    "output": {
        "name": "output",
        "type": "model",
        "allowExtraProperties": true,
        "gloopProperties": []
    },
    "tags": [],
    "stateContexts": [
        {
            "name": "Start_State",
            "input": {
                "name": "input",
                "type": "model",
                "allowExtraProperties": true,
                "gloopProperties": []
            },
            "output": {
                "name": "output",
                "type": "model",
                "allowExtraProperties": true,
                "gloopProperties": []
            },
            "transitionContexts": [
                {}
            ]
        }
    ],
    "executionHistory": [
        {
            "fluxName": "flux.ProcessExternalEvent",
            "stateName": "Start_State",
            "stateIndex": 0
        }
    ]
}

Get a Event Based Workflow state's context

Method Path
GET /flux-api/context/state

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long true The context ID of the running Event Based Workflow service that owns the state whose context is to be fetched.
stateName string true The name of the state whose context is to be fetched.

Example

1
2
3
curl -X GET \
  'http://localhost:8080/flux-api/context/state?contextId=217&stateName=Start_State' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "name": "Start_State",
    "input": {
        "name": "input",
        "type": "model",
        "allowExtraProperties": true,
        "gloopProperties": []
    },
    "output": {
        "name": "output",
        "type": "model",
        "allowExtraProperties": true,
        "gloopProperties": []
    },
    "transitionContexts": [
        {}
    ]
}

Add a tag to a Event Based Workflow service

Method Path
POST /flux-api/context/tag
PUT /flux-api/context/tag

Request

Query Parameters

Parameter Name Data Type Required Multiple Description
contextId long true false The context ID of the running Event Based Workflow service that will receive the new tag.
tag string true true The tag to add.

Example

1
2
3
curl -X POST \
  'http://localhost:8080/flux-api/context/tag?contextId=241&tag=tag1,tag2' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

1
2
3
{
    "message": "Tags [tag1, tag2] successfully added to flux context with id '241'"
}

Remove a Event Based Workflow service's tag

Method Path
DELETE /flux-api/context/tag

Request

Query Parameters

Parameter Name Data Type Required Multiple Description
contextId long true false The context ID of the running Event Based Workflow service whose tag will be removed.
tag string true true The tag to remove.

Example

1
2
3
curl -X DELETE \
  'http://localhost:8080/flux-api/context/tag?contextId=257&tag=tag3,tag4' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

1
2
3
{
    "message": "Tags [tag3, tag4] successfully removed from flux context with id '257'"
}

Get a Event Based Workflow service's definition

Method Path
GET /flux-api/definition

Request

Query Parameters

The parameter fluxName and contextId are mutually exclusive; only one of them is required for the request. If both are specified, contextId takes precedence over fluxName.

Parameter Name Data Type Required Description
fluxName string false The name of the Event Based Workflow service whose definition is to be fetched. If the service is located inside a directory, its name should be prepended by the name of its subdirectories separated by periods. For example, org.your.SendAlerts.
contextId long false The context ID of the specific running Event Based Workflow service whose definition is to be fetched.

Example

1
2
3
curl -X GET \
  'http://localhost:8080/flux-api/definition?fluxName=flux.Event Based WorkflowWithTrigger' \
  -H 'Accept: application/json'

Response

Content Type

  • application/json
  • application/xml

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "comment" : "This Event Based Workflow service demonstrates how to use triggers. Triggers are events that can start a Event Based Workflow service, when the Event Based Workflow engine receives an event it will look for Event Based Workflow services with matching trigger events and start them.\n\nThis Event Based Workflow service has two triggers 'trigger1' and 'trigger2'. To send a trigger event, right click the Event Based Workflow editor and send an event using one of the trigger event. To monitor the execution of the Event Based Workflow service open a Martini console or the Martini Service Manager view.",
  "triggers" : [ "trigger2", "trigger1" ],
  "states" : [ {
    "name" : "Print_Trigger",
    "displayName" : "Print Trigger",
    "x" : 120,
    "y" : 120,
    "comment" : "This states logs the event data that triggered this Event Based Workflow service. The triggering event can be retrieved using the special property '$triggerEvent Based WorkflowEvent'.",
    "action" : {
    "type": "invokeCode",
    "className": "io.toro.martini.LoggerMethods",
    "methodName": "info",
    "parameters": [
        "String"
    ],
    "inputs": [
        {
            "type": "set",
            "expression": "\"This Event Based Workflow service was started using the trigger \\\"${$triggerEvent Based WorkflowEvent}\\\".\"",
            "evaluate": true,
            "to": [
                "message"
            ]
        }
    ]
},
    "input" : [ ],
    "output" : [ ]
  } ]
}