Workflow REST API

Modified on Thu, 23 Nov 2023 at 05:01 PM

Omniscope Evo allows you to perform actions on project workflows via simple REST APIs.


This allows to use Custom block or views as well as 3rd party software to perform actions on Omiscope Evo Workflows.


This page describes what can be achieved with these APIs, and how to submit requests.


Workflow execution API


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 



Lambda Workflow execution request

A "lambda execution" allows you to trigger a parametrised atomic workflow execution, where Omniscope generates a new instance of a project, edits the project parameters and triggers an isolated execution, optionally deleting the instantiated per-request project and cached execution data when the job execution is over.


To submit a request you have to specify:

  • blocks:   the list of blocks you want to execute (similar to the normal workflow execution above)
  • params:  the parameters (optional) to set before starting the execution
  • deleteExecutionOnFinish: whether Omniscope will delete (or keep) the workflow and the execution data when the execution terminates.


The response will be a JSON containing same properties as the one returned when you submit a normal execution, together with an important property, "lambdaProjectPath",which is the path to the project generated where the execution is running.



Executing Workflow via file upload from Report 


We have added a new API endpoint that allows you to upload file and trigger execution of the Workflow from within the Report interface.


The URL scheme is the following:

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


A fully working example of how this can done is documented here:


https://help.visokio.com/support/solutions/articles/42000100322-how-to-upload-a-file-from-the-report-ui-and-trigger-a-workflow-execution

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 execute Workflows via 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.


Project Parameters API


Retrieving project parameters


It is possible to retrieve and update project parameters via rest apis. It is possible to retrieve all project parameters via a GET request to:


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


For example:


GET http://localhost:24679/ParamsDemo.iox/w/param/


The server response will be a json string containing an array element describing a parameter. 



{

  "paramValues": [

    {

      "type": "TEXT",

      "name": "City Name",

      "value": "London"

    },

    {

      "type": "NUMBER",

      "name": "Minimum Level",

      "value": 3

    },

    {

      "type": "TEXT",

      "name": "Performance Score",

      "value": "Good"

    }

  ]

}


GET request to http[s]://<hostname>:[port]/<path-to-file>/w/param/<param-name> will retrieve information regarding a single parameter (<param-name> is the name of the parameter):


For example,


GET http://localhost:24679/ParamsDemo.iox/w/param/City%20Name


will produce the output:


{

  "type": "TEXT",

  "name": "City Name",

  "value": "London"

}


Update project parameters


Project parameter values can be updated via a POST request to 


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


The request can contain one or more value update:


For example, 


POST http://localhost:24679/ParamsDemo.iox/w/updateparams

{

    "updates" : [

    {

            "name" : "City Name",

        "value" : "Frankfurt"

        },

    {

            "name" : "Minimum Level",

        "value" : 2.0

        }

    ]

}


If the update has been successful the response will have a 200 status code, and the reponse will look like:


{

  "status": "SUCCESS"

}


If on the other hand, an error occurred updating the param value (e.g., a parameter specified in the request is not present), the server response will include information regarding the error (and a non 200 status code):


{

  "status": "FAIL",

  "errorType": "PARAM_NOT_FOUND",

  "errorMessage": "Parameter 'City' not found"

}


Values will be updated in the project only if all the values could be updated. For example if the request contains three value updates, two are valid but one of them refers to a parameter that does not exist (or has an incompatible type ....), then none of the updates will be applied.


As of this writing it is not possible to create, rename or change the type of project parameters.


Permission

In order to retrieve and update project parameters on the external web server, the "Project parameters access via APIs" permission is required: 



Swagger: explore and test 


You can explore and test workflow apis via a swagger page hosted by your Omniscope: 

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

or on any Omniscope file on our public sandbox, e.g. here http://daily.omniscope.me/Demo/Test.iox/w/meta/



Custom Views: JS wrapper

We have deployed some custom views developed around the Workflow API 

You can explore the JS code or just add them as they are in your reports to expose the API to your end users.

For example here is a view to trigger a lambda workflow execution : https://github.com/visokio/omniscope-custom-views/tree/master/lambdaworkflowexecution , and here's another that allows you to switch a project parameter value: https://github.com/visokio/omniscope-custom-views/tree/master/switchparam 



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article