Articles in this section

See more

Run Flow by name API

  • Updated
Follow

Overview

You can incorporate Etlworks into your own automation workflow by delegating heavy-duty integration tasks and executing Flows on demand.

Flow can be executed asynchronously (default behavior, the response is returned to the client immediately) and synchronously (the response is returned to the client after the Flow is executed).

Authentication

Before making a call to the built-in API, the user must receive a JWT token from the authentication API.

Step 1. Use any user with the Operator, Editor, or Administrator role to call Etlworks authentication endpoint and receive an access token.

Step 2. Use the access token received in Step 1 to call Etlworks API endpoints. The access token must be submitted as a header parameter, as in: Authorization:Bearer access-token.

Note: Access tokens in Etlworks are short-lived and self-expiring. An access token gives you access to the APIs for approximately 10 minutes. It is recommended that you refresh the access token before each call to the API.

The API endpoint parameters

  • PATH: /rest/v1/flows/flow-name/{flowName}/run?optional_parameters.
  • LEGACY PATH (we keep it for backward compatibility): /plugins/flows/rest/v1/flows/flow-name/{flowName}/run?optional_parameters.
  • Note: Make sure that the URL isNote: properly encodedNote:.
  • METHOD: POST.
  • HEADER: Authorization:Bearer access-token.
  • REQUEST BODY: none.
  • REQUEST CONTENT TYPE: none.

Response

The response is a JSON document in the following Format:

{"flowId":flodId,
 "messageUuid":"UUID of the message if flow was executed by sending payload to the custom endpoint", 
 "auditId":"ID of the record in audit table if flow was executed by name or by ID", 
 "status": status of the flow
 "exception":"exception-stack-trace"
}

The status can be one of the following:

  • 0: started. Just started.
  • 1: running. Flow is still running.
  • 2: canceled. Flow has been canceled.
  • 3: wasn't running. Flow has not been executed.
  • 4: success. Flow executed successfully. 
  • 5: error. Flow executed with an error (exception).

Response Codes

  • 200 for success
  • 401 and 403 for not authorized
  • 500 for an internal error

Example with no URL parameters

https://app.etlworks.com/rest/v1/flows/flow-name/my-flow/run,

  • my-flow is the name of the Flow to execute.

Optional URL parameters

This API endpoint accepts optional URL parameters. Parameters are passed to the Flow as Flow variables and global variables and can be referenced as {parameter_name}. They can be also accessed programmatically.

The global variables can be used in the FROM and TO fields in the source-to-destination transformation, as well as Connection parameters. The Flow variables can be referenced in the source and destination queries. 

There can be both multiple & separated parameters: ?parameter1=value&parameter2=value

Example of the URL with parameters

https://app.etlworks.com/rest/v1/flows/flow-name/my-flow/run?patientid=123

  • my-flow: the name of the Flow to execute.
  • patientid: a parameter.
  • 123: is the value of the parameter.

Example of the Source query with parameters passed from the URL

select * from patient where patientid = {patientid}

Execute Flow in parallel

To allow multiple instances of the same Flow to run in parallel, set the allowParallel parameter to true.

PATH: /rest/v1/flows/flow-name/{flowName}/run?allowParallel=true

Serialize execution

When the same API endpoint, which executes the same Flow, is called while the flow is already running, status 1 (running) will be returned and this new execution request ignored. If you wish request to be added to the queue and executed in the order that the Flows were called you need to add waitIfRunning=true query parameter.

Execute Flow synchronously

By default, when you call this endpoint, the Flow is executed asynchronously, meaning the response is returned immediately after the call. Use the optional URL parameter sync=true to execute Flow synchronously.

  • PATH: /rest/v1/flows/flow-name/{flowName}/run?sync=true&optional_parameters.
  • LEGACY PATH (we keep it for backward compatibility): /plugins/flows/rest/v1/flows/flow-name/{flowName}/run?sync=true&optional_parameters.

Read how to parse the response from API when the Flow is executed synchronously.

Return error code

Typically, when the Flow is executed by calling this API endpoint, the server returns response code 200 as long as the call successfully went through, regardless of the status of the Flow which has been executed.

When the Flow is executed synchronously and finished with an error or has been canceled, it is possible to return an error code (500), together with an actual exception.

Note: If the call to the API is made from the other Flow and the API returned HTTP 500, the calling Flow will fail with an exception.

  • PATH:/rest/v1/flows/flow-name/{flowName}/run?sync=true&returnErrorCode=true&optonal_parameters.
  • LEGACY PATH (we keep it for backward compatibility): /plugins/flows/rest/v1/flows/flow-name/{flowName}/run?sync=true&returnErrorCode=true&optonal_parameters.
  • RESPONSE CODE: 500.
  • RESPONSE:
  • {"flowId":flodId,
 "messageUuid":"UUID of the message", 
 "auditId":"ID of the record in audit table", 
 "status": 5 or 2
 "exception":"exception-stack-trace"
}

Send email notifications

There are several parameters that you can specify to receive email notifications based on execution status or duration.

  • emailOnSuccess: boolean (default value:false). If set to true and Flow was successfully executed, an email notification will be sent to the specified list of emails. Example: emailOnSuccess=true&emails=support@etlworks.com.
  • emailOnFailure: boolean (default value: false). If set to true and Flow has failed during the execution, an email notification will be sent to the specified list of emails. Example: emailOnFailure=true&emails=support@etlworks.com.
  • expectedTime: number of minutes. If Flow execution lasts longer than the specified number of minutes, an email notification will be sent to the specified list of emails. For example, send a warning notification if Flow runs longer than 5 minutes: expectedTime=5&emails=support@etlworks.com.
  • emails: URL encoded string. The comma or whitespace-separated list of email addresses that should receive notifications. This parameter is required if any of the three above were used.

Console log capturing

Console log capturing related parameters:

  • debug: boolean (default value: true). By default (if not specified explicitly in the URL) this parameter value is true and that means that system will record and store console logs captured during the Flow execution. Console log can be later viewed on the Flow statistics screen. If you don't want console log to be recorded by the system for performance gains set debug=false.
  • logStep: number (must be equal or greater than 100). Extra checkpoint records will be added to the log after every specified number of processed data records. For this parameter to take effect, debug parameter must be true, so either not specified, or explicitly set to true. Example: logStep=1000.

Call the same API endpoint in parallel

When the same API endpoint, which executes the same Flow, is called in parallel, the Flows will be added to the queue and executed in the order that the Flows were called.

Stop flow executed by calling run Flow by name API endpoint

If you have multiple queued Flows and attempt to stop the Flow that is currently running, all Flows, current and queued, will be stopped.  

Related articles