Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

Flux REST API

Aside from programmatically managing your Flux Services via FluxMethods, TORO Integrate also allows you to manage your workflows via the Flux REST API. With this API, you can:

The Flux REST API or FluxMethods?

If you are trying to handle Flux Service(s) from another service, it is recommended that you use FluxMethods instead.

Headers

By default, the Flux REST API allows access to all Flux Services. However, if the Flux Service is secured, an Authorization request header is needed.

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

Endpoints

All endpoints of the Flux 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 Flux REST API. Simply download and import this Postman Collection.

Execute a Flux Service

POST /flux-api/execute

Request

Query Parameters

Parameter Name Data Type Required Description
packageName string true The name of the package containing the Flux Service to be run.
fluxName string true The name of the Flux 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.

Body Parameters

Parameter Name Data Type Required Description
startState string false The name of the state where the Flux execution should start.
input object false The inputs which will be fed to the target Flux Service.
tags string[] false The tags to be added to the Flux Service during execution.

Example

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

Response

Content Type

  • application/json
  • application/xml

Example

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

Terminate a Flux Service

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 Flux 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" : "Flux terminated"
}

Send an Event to Flux Services

POST /flux-api/event

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long false The context ID of the running Flux Service you want to send the event to. Specify this parameter only when a single Flux 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 Flux Service(s).
tags string[] false The tags to use for determining which Flux 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 Flux Services which were transitioned by the external event.
executions object[] The Flux 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 Flux Services' Contexts

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 Flux Services whose names match the value of this parameter.
tag string false true Specify to fetch only the contexts of Flux Services whose tags match all the values of this parameter.
status string false false Specify to fetch only the contexts of Flux Services whose statuses match the value of this parameter.
currentState string false false Specify to fetch only the contexts of Flux Services whose current states match the value of this parameter.
startState string false false Specify to fetch only the contexts of Flux 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 Flux Service's Context

GET /flux-api/context

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long true The context ID of the running Flux 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 Flux State's Context

GET /flux-api/context/state

Request

Query Parameters

Parameter Name Data Type Required Description
contextId long true The context ID of the running Flux 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 Flux Service

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 Flux 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 Flux Service's Tag

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 Flux 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 Flux Service's Definition

GET /flux-api/definition

Request

Query Parameters

The parameterd 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 Flux 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 Flux Service whose definition is to be fetched.

Example

1
2
3
curl -X GET \
  'http://localhost:8080/flux-api/definition?fluxName=flux.FluxWithTrigger' \
  -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 Flux service demonstrates how to use triggers. Triggers are events that can start a Flux service, when the Flux engine receives an event it will look for Flux services with matching trigger events and start them.\n\nThis Flux service has two triggers 'trigger1' and 'trigger2'. To send a trigger event, right click the Flux editor and send an event using one of the trigger event. To monitor the execution of the Flux service open an Integrate console or the Integrate 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 Flux service. The triggering event can be retrieved using the special property '$triggerFluxEvent'.",
    "action" : {
    "type": "invokeCode",
    "className": "io.toro.integrate.LoggerMethods",
    "methodName": "info",
    "parameters": [
        "String"
    ],
    "inputs": [
        {
            "type": "set",
            "expression": "\"This Flux service was started using the trigger \\\"${$triggerFluxEvent}\\\".\"",
            "evaluate": true,
            "to": [
                "message"
            ]
        }
    ]
},
    "input" : [ ],
    "output" : [ ]
  } ]
}