Basic Guide

Executing Flows

Executing Flows from external applications

You can execute Flows from external applications using a web API. You can also check the status of an executed Flow and get the values of variables.

These functions are supported by the following APIs:

Flow Execution API

This API allows for executing Flows from external applications by using the HTTP/HTTPS POST method with the following URL:

[POST] Flow Designer URL/flows/ID.json

Item Explanation
Flow Designer URL The URL of the Flow Designer that contains the Flow you want to execute. Get it by opening the Flow Designer and copying the URL from the address bar of your web browser.
ID

The ID of the Flow you want to execute. You can view and edit Flow IDs in the Flow list. Flow IDs must follow these naming conventions:

  • Only letters (a–z, A–Z), numbers (0–9), hyphens (-), and underscores (_) may be used.
  • 64 character limit

Accessing this API requires the use of an API token for authentication. Include the following authorization request header when accessing it:

Authorization: Bearer API token

Item Explanation
API token Generate this API token in the API token section of the Settings menu.

You can specify the following parameters within the body of the HTTP request when the HTTP request's Content-Type header is x-www-form-urlencoded:

Parameter Explanation
api_token Designate the API token. Do this if you are unable to use an authorization request header.
target_time Designate the time for the Flow to execute.
dependent_job_id Designate the Job ID of a dependent Flow. Job IDs are included in responses from the Flow Execution API.
User-set parameters You can also send your own parameters. These can be referenced within the Flow using a variable with the same name as the parameter. All values passed by parameters are treated as strings.

When the HTTP request’s Content-Type header is application/json, BLOCKS variables are set with values from parsing JSON text in the body of the HTTP request.

For example, assume the follow JSON text has been defined in the request body:

{"foo": 100, "bar": "baz"}

With the above, a variable foo would be set to the numerical value 100, while a variable bar would be set as the string "baz".

In this way, you can set the name portion of each member in a JSON object as a variable name, and the value portion as the variable’s value.

Example HTTP body JSON text

The method using parameters explained previously only allows variables to be set as string values. However, by using this method, you can also set variables to other types list numbers or arrays.

The response will come in JSON format.

See below for an example response from a successful Flow execution:

{
  "result": true,
  "job_id": 1
}

When a Flow executes successfully, "result" will contain true. The "job_id" refers to a unique identifier assigned within a Flow Designer each time a Flow is executed. You will need this Job ID if you want to check on the status of an executed Flow.

The following example shows a response for a failed Flow execution:

{
  "result": false,
  "message": "Flow Alias not found"
}

When the Flow fails to execute, "result" will contain false and "message" will contain an explanation for the failure.

The following Unix curl command is an example call to execute a Flow (response shown in blue):

curl -X POST -H "Authorization: Bearer 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179" --data "city=Fukuoka,jp" https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net/flows/example.json
{"result":true,"job_id":1}

Item Value
Flow Designer URL https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net
API token 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179
ID example
Parameter Value Explanation
city Fukuoka, jp An optional parameter that can be referenced within the Flow with the variable ${city}

The following example sets the Content-Type header as application/json with JSON text in the request body:

curl -X POST -H 'Authorization: Bearer 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179' -H 'Content-Type: application/json' --data '{"city", "Fukuoka,jp"}' https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net/flows/example.json

Check Executed Flow Status API

This API allows you to check on the status of an executed Flow.

This is done using the HTTP/HTTPS GET method with one of the following URLs:

[GET] Flow Designer URL/flows/ID/jobs/Job ID/status.json

or

[GET] Flow Designer URL/flows/ID/jobs/Job ID/status.txt

The URL's endings differ as either json or txt.

Item Explanation
Flow Designer URL The URL of the Flow Designer containing the Flow whose status you want to check. Get it by opening the Flow Designer and copying the URL from the address bar of your web browser.
ID

The ID of the Flow whose status you want to check. You can view and edit Flow IDs in the Flow list. Flow IDs must follow these naming conventions:

  • Only letters (a–z, A–Z), numbers (0–9), hyphens (-), and underscores (_) may be used.
  • 64 character limit.
Job ID The Job ID of the Flow whose status you want to check. This is contained within the response of the Flow Execution API

Accessing this API requires the use of an API token for authentication. Please include the following authorization request header when accessing it:

Authorization: Bearer API token

Item Explanation
API token Generate this API token in the API token section of the Settings menu.

If you are unable to use a authorization request header, include the following parameter within your URL query instead:

Parameter Explanation
api_token Designate the API token.

If your URL ends in status.json, information about the Flow’s status will be returned in JSON format. If the URL ends in status.txt, the status will be returned as a string.

These two types are responses can be seen in the following examples:

{
  "status": "finished"
}

or

finished

The following strings can be returned when a Flow’s status is successfully checked:

"status" Explanation
"planning" The Flow is preparing to execute.
"running" The Flow is currently executing.
"finished" The Flow completed execution successfully.
"failed" The Flow’s execution failed.
"canceled" The Flow’s execution was cancelled.

The following responses are examples of a failed status check:

{
  "message": "Job not found."
}

or

Job not found.

When a status check fails, a message explaining why will be returned.

See the following Unix curl command for an example of checking a Flow’s status (response shown in blue):

curl -H "Authorization: Bearer 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179" https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net/flows/example/jobs/1/status.json
{"status":"finished"}

Item Value
Flow Designer URL https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net
API token 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179
ID example
Job ID 1

Get Variable's Value API

You can get the value of a variable from an executed Flow with this API by using the HTTP/HTTPS GET method to access the following URL.

[GET] Flow Designer URL/flows/ID/jobs/Job ID/variable.json

Item Explanation
Flow Designer URL The URL of the Flow Designer containing the Flow whose variable’s value you want to get. Get it by opening the Flow Designer and copying the URL from the address bar of your web browser.
ID

The Flow ID of the Flow whose variable’s value you want to get. You can view and edit Flow IDs in the Flow list. Flow IDs must follow these naming conventions:

  • Only letters (a–z, A–Z), numbers (0–9), hyphens (-), and underscores (_) may be used.
  • 64 character limit.
Job ID The Job ID of the Flow whose variable’s value you want to get. This is contained within the response of the Flow Execution API

Accessing this API requires the use of an API token for authentication. Please include the following authorization request header when accessing it:

Authorization: Bearer API token

Item Explanation
API token Generate this API token in the API token section of the Settings menu.

If you are unable to use a authorization request header, include the following parameter within your URL query instead:

Parameter Explanation
api_token Designate the API token.

By setting a query parament variable to a variable’s name, you can get the value of that variable. You can set the variable name using notation to reference a portion of hash or array format data.

If the query parameter variable is omitted, the API will get the value of the variable named _ by default.

The following Unix curl command is an example of using this API.

curl -H 'Authorization: Bearer f38a9f8d0b3b999e279759f68abca69c4ce73dd9b53f4a4ded52b1357a435d0f' 'https://foobarblocksboard8fec513f.magellanic-clouds.net/flows/ml-image/jobs/23/variable.json?variable=_.predictions'

Below is an example response.

[{"score":[0.9999089241027832,9.108754602493718e-05],"key":"gs://my-storage-1703/blocks_ml_image_example/prediction/sample_01.jpg","label":"cat"},{"score":[0.0008647672948427498,0.9991353154182434],"key":"gs://my-storage-1703/blocks_ml_image_example/prediction/sample_02.jpg","label":"dog"}]