Omniscope Evo allows you to execute workflows, and monitor their executions via simple REST APIs. Given the correct permissions (below), these allow custom views or 3rd party apps to control workflow execution, e.g. to refresh data in a report when a user clicks a button.


Submit a Workflow execution request


To start a workflow execution submit a POST request on the /w/execute endpoint under the file URL scheme.
For example, POST (with appropriate request body) to: http://192.168.227.2/Folder/File.iox/w/execute 

will request a workflow execution on the File "File.iox" located in the "Folder" directory.


In general, the endpoint is:

http[s]://<hostname>:[port]/<path-to-file>/w/execute


where <path-to-file> is the path of the iox file starting from the Omniscope  files folder (Folder/File.iox in the example).


The body of the POST is a json document:

{

    "blocks": ["Demo: Bond Prices", "Field organiser"],

    "refreshFromSource": true,

    "cancelExisting": false

}


blocks is an array containing the names of the blocks to execute. If empty, then all the blocks will be executed. N.B. other blocks might be involved in the execution if necessary.


refreshFromSource : if true data already available in upstream blocks will be disregarded, causing all blocks involved in the execution to reload data from the sources. If false, the workflow execution is allowed to reuse data from previously executed upstream blocks.


cancelExisting: If there is another workflow running/queued for this file, interrupt its execution to start the new execution. 



Provided the file /Folder/File.iox exists, and the user has enough permissions (see permission section below), the server will reply with a json document. The structure of the json is different depending on whether the workflow execution could have been started successfully or not


If the workflow execution has been started correctly, then the response will contain the jobId. For example:

{

  "jobId": "EA238_3"

}


The id can be used to monitor the workflow execution. (see check workflow state section). In this case the HTTP status code will be 200.


If the workflow could not be started the server response will contain the errorType and an errorMessage. For example:

{

  "errorType": "BLOCKS_NOT_FOUND",

  "errorMessage": "One or more blocks could not be found in the workflow: Custom block could not be found."

}


errorMessage will contain some information regarding the message. This is not meant for programmatic use.


errorType represent the reason why the workflow execution could not be started. Its value can be one of the following:


  • BLOCKS_NOT_FOUND: One or more blocks specified in the requested could not be found in the workflow. The HTTP status code will be 404

  • WORKFLOW_ALREADY_RUNNING : there is another execution running/queued for this file. In this case you can retry in the future, or setting the cancelExisting flag to true. The HTTP status code will be 409 



Monitoring the state of a workflow execution


Once the workflow execution requests has been submitted successfully, an id is generated and given back in the response. This id can be used to monitor the state of the workflow execution via a GET request. For the example above, it is possible to get the state of the workflow execution:

http://192.168.227.2/Folder/File.iox/w/job/EA238_3/state


The URL scheme is the following:

http[s]://<hostname>:[port]/<path-to-file>/w/job/<jobId>/state


where <jobId> is the id of the job given by the server (EA238_3 in the example)


Provided the file exists, and the user has enough permission to check the workflow state on the project, the response will be a json document.


If Omniscope was able to determine the state of the workflow execution the response will look like:

{

    "jobState" : "RUNNING"

}


The value of jobState could be one of the following:

  • QUEUED The workflow execution is queued for execution
  • RUNNING The workflow execution is in progress
  • BLOCKED  The workflow execution is in progress, but it is waiting for a resource held by another workflow execution instance 
  • COMPLETED The workflow execution completed successfully
  • FAILED The workflow execution did not completed successfully (e.g., there was a configuration error, or an issue during execution)
  • CANCELLED The workflow execution has been cancelled, either explicitly, or by another workflow execution on the same file.

 In all these cases the HTTP status code will be 200


If Omniscope was not able to determine the state of the workflow execution, the response will be a json like

{

  "errorType": "JOB_NOT_FOUND",

  "errorMessage": "Job with id EA238_3 could not be found"

}


This could happen if for example the job is wrong, the server has been restarted or the server no longer has the information about the workflow job execution: Omniscope retains the information of the latest 10000 workflow executions.  The HTTP status code will be 404.


Permission


In order to use Workflow APIs the "Workflow Execution via APIs" permission must be granted to the user:



This permission is disabled by default.
If the permission is not enabled for the group each request will fail with a 401 HTTP status code.

More information about server permissions can be found here.