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:
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
Feedback sent
We appreciate your effort and will try to fix the article