The Advanced CIS REST Web API supports the ability to run, check status, and retrieve results from CIS runnable processes like AIM exports, AIM imports, reports, interface table synchronization processes, and CIS pickup processes. This document will describe the REST interactions that support these functions and how to use them to successfully create a runnable process run with run-time settings and then check the progress of the run and retrieve the results afterwards.
All runnable process support in Advanced REST Web API is located in the /run end point. Each of the runnable types has a different URL inside /run to work with, but all support the same set of interactions. We will use an AIM export in this document as an example, but imports, pickups, reports, and ITS processes work exactly the same way.
| AIM Exports | /run/export/{type} |
| AIM Imports | /run/import/{type} |
| Interface Table Synchronization Processing | /run/its/{type} |
| Pickup Processes | /run/pickup/{type} |
| Ad Hoc Reports | /run/report |
| Specialized Reports | /run/report/{type} |
Running a CIS runnable process follows the following steps:
CompletedEach type of runnable has a specific end point dedicated to handling that runnable.
For example, an AIM export for generic export definitions uses end point /run/export/genericexportinterface.
Each runnable end point supports the NEW HTTP action and will return a template model for that type of run when called.
The runnable names available at each end point can be looked up in the Swagger/OpenAPI documentation for Advanced REST Web API or in the CIS API Reference document (the end point names match the runnable process class names in the AdvancedUtility.Services.Processes namespace).
Note that if your client does not support atypical HTTP verbs like NEW, you can use the X-HTTP-Method-Override header.
Here is a sample response from a NEW call against the generic export run end point:
NEW: /run/export/genericexportinterface/
(without body content)
{
"_links": {},
"_embedded": null,
"fileNameOverride": "",
"errorThreshold": null,
"promptDataTree": "",
"definitionKey": "",
"interfaceParameters": {},
"packagedParameters": null,
"promptData": "",
"criteriaId": 0,
"filterTree": "",
"logFile": "",
"logWritingPolicy": "WriteOnException",
"securityId": 40059,
"version": 0
}
Some of the properties are common to all CIS REST responses (_links, _embedded); some properties will be common to all runnables (packagedParameters, promptData, criteriaId); some properties will be common to all runnables of the same family (fileNameOverride, interfaceParameters, etc); and some will be specific to this one type of runnable (definitionKey, etc). Again, refer to Swagger/OpenAPI or the CIS API Reference for details on each property supported by each runnable. In this example, the definitionKey property identifies the export definition code to run.
The HTTP NEW action supports two modes of operation. When called without a body, it returns a sample default run model for the end point it is called against. It can also be called with a JSON body matching the run model of the end point called. In this mode it will inspect the packagedParameters property and either serialize or deserialize a runnable process definition. If the packagedParameters is not null or empty, it will assume the packagedParameters string represents a serialized version of the current runnable type and deserialize it into the corresponding properties on the model. If the packagedParameters is null or empty, it will serialize any existing properties on the passed JSON model and return that serialized in the packagedParameters property. Serialized runnable process strings are safe to store and restore and can be used on these REST end points in future calls. They are also the same packages that are used by the scheduler and by the CIS API to instantiate and run saved processes. You could also save them other ways as needed and retrieve and apply them to meet your needs. Anything that stores a string safely will do.
Here is a sample response from the NEW call once the definitionKey and fileNameOverride were populated and the JSON included in the body of the NEW call. Notice the interfaceParameters property is now populated from the data from the EBP export definition and the packagedParameters contains a base-64 string containing the serialized export definition.:
NEW: /run/export/genericexportinterface/
(with JSON export model body content as above but with definitionKey and fileNameOverride populated, and packagedParameters not populated)
{
"_links": {},
"_embedded": null,
"fileNameOverride": "ebp20240403.csv",
"errorThreshold": null,
"promptDataTree": "",
"definitionKey": "EBP",
"interfaceParameters": {
"includeInformationRate": 1,
"useBillBlockDetails": 1
},
"packagedParameters": "AAEAAAD/////AQAAAAAAAAAEAQAAAOIBU3lzdGVtLkNvbGxlY3Rpb25zLkdlbmVyaWMuRGljdGlvbmFyeWAyW1tTeXN0ZW0uU3RyaW5nLCBtc2NvcmxpYiwgVmVyc2lvbj00LjAuMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPWI3N2E1YzU2MTkzNGUwODldLFtTeXN0ZW0uT2JqZWN0LCBtc2NvcmxpYiwgVmVyc2lvbj00LjAuMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPWI3N2E1YzU2MTkzNGUwODldXQQAAAAHVmVyc2lvbghDb21wYXJlcghIYXNoU2l6ZQ1LZXlWYWx1ZVBhaXJzAAMAAwiSAVN5c3RlbS5Db2xsZWN0aW9ucy5HZW5lcmljLkdlbmVyaWNFcXVhbGl0eUNvbXBhcmVyYDFbW1N5c3RlbS5TdHJpbmcsIG1zY29ybGliLCBWZXJzaW9uPTQuMC4wLjAsIEN1bHR1cmU9bmV1dHJhbCwgUHVibGljS2V5VG9rZW49Yjc3YTVjNTYxOTM0ZTA4OV1dCOYBU3lzdGVtLkNvbGxlY3Rpb25zLkdlbmVyaWMuS2V5VmFsdWVQYWlyYDJbW1N5c3RlbS5TdHJpbmcsIG1zY29ybGliLCBWZXJzaW9uPTQuMC4wLjAsIEN1bHR1cmU9bmV1dHJhbCwgUHVibGljS2V5VG9rZW49Yjc3YTVjNTYxOTM0ZTA4OV0sW1N5c3RlbS5PYmplY3QsIG1zY29ybGliLCBWZXJzaW9uPTQuMC4wLjAsIEN1bHR1cmU9bmV1dHJhbCwgUHVibGljS2V5VG9rZW49Yjc3YTVjNTYxOTM0ZTA4OV1dW10RAAAACQIAAAARAAAACQMAAAAEAgAAAJIBU3lzdGVtLkNvbGxlY3Rpb25zLkdlbmVyaWMuR2VuZXJpY0VxdWFsaXR5Q29tcGFyZXJgMVtbU3lzdGVtLlN0cmluZywgbXNjb3JsaWIsIFZlcnNpb249NC4wLjAuMCwgQ3VsdHVyZT1uZXV0cmFsLCBQdWJsaWNLZXlUb2tlbj1iNzdhNWM1NjE5MzRlMDg5XV0AAAAABwMAAAAAAQAAABEAAAAD5AFTeXN0ZW0uQ29sbGVjdGlvbnMuR2VuZXJpYy5LZXlWYWx1ZVBhaXJgMltbU3lzdGVtLlN0cmluZywgbXNjb3JsaWIsIFZlcnNpb249NC4wLjAuMCwgQ3VsdHVyZT1uZXV0cmFsLCBQdWJsaWNLZXlUb2tlbj1iNzdhNWM1NjE5MzRlMDg5XSxbU3lzdGVtLk9iamVjdCwgbXNjb3JsaWIsIFZlcnNpb249NC4wLjAuMCwgQ3VsdHVyZT1uZXV0cmFsLCBQdWJsaWNLZXlUb2tlbj1iNzdhNWM1NjE5MzRlMDg5XV0E/P///+QBU3lzdGVtLkNvbGxlY3Rpb25zLkdlbmVyaWMuS2V5VmFsdWVQYWlyYDJbW1N5c3RlbS5TdHJpbmcsIG1zY29ybGliLCBWZXJzaW9uPTQuMC4wLjAsIEN1bHR1cmU9bmV1dHJhbCwgUHVibGljS2V5VG9rZW49Yjc3YTVjNTYxOTM0ZTA4OV0sW1N5c3RlbS5PYmplY3QsIG1zY29ybGliLCBWZXJzaW9uPTQuMC4wLjAsIEN1bHR1cmU9bmV1dHJhbCwgUHVibGljS2V5VG9rZW49Yjc3YTVjNTYxOTM0ZTA4OV1dAgAAAANrZXkFdmFsdWUBAgYFAAAADFByb2Nlc3NDbGFzcwYGAAAAUkFkdmFuY2VkVXRpbGl0eS5TZXJ2aWNlcy5Qcm9jZXNzZXMuQWR2YW5jZWRJbnRlcmZhY2UuRXhwb3J0LkdlbmVyaWNFeHBvcnRJbnRlcmZhY2UB+f////z///8GCAAAAA9TdGFuZGFyZE1lc3NhZ2UKAff////8////BgoAAAAQRmlsZU5hbWVPdmVycmlkZQYLAAAAD2VicDIwMjQwNDAzLmNzdgH0/////P///wYNAAAADURlZmluaXRpb25LZXkGDgAAAANFQlAB8f////z///8GEAAAAA5FcnJvclRocmVzaG9sZAoB7/////z///8GEgAAAA1Qcm9tcHREYXRhWG1sBhMAAAAAAez////8////BhUAAAAPU3VjY2Vzc0FjdGlvbklkCgHq/////P///wYXAAAAEUV4Y2VwdGlvbkFjdGlvbklkCgHo/////P///wYZAAAAClByb21wdERhdGEJEwAAAAHl/////P///wYcAAAACFF1ZXJ5WG1sCRMAAAAB4v////z///8GHwAAAApDcml0ZXJpYUlkCAkAAAAAAAAAAAHg/////P///wYhAAAAB0xvZ0ZpbGUJEwAAAAwkAAAAW0FkdmFuY2VkVXRpbGl0eS5TZXJ2aWNlcywgVmVyc2lvbj0xLjAuMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPTc4OWVmODNmMDE2MTZhNjcB3f////z///8GJQAAABBMb2dXcml0aW5nUG9saWN5CSYAAAAB2f////z///8GKAAAAApTZWN1cml0eUlkCAl7nAAAAAAAAAHX/////P///wYqAAAAB1ZlcnNpb24ICAAAAAAB1f////z///8GLAAAABdJbnRlcmZhY2VQYXJhbWV0ZXJOYW1lcwktAAAAAdL////8////Bi8AAAAYSW50ZXJmYWNlUGFyYW1ldGVyVmFsdWVzCTAAAAAFJgAAADtBZHZhbmNlZFV0aWxpdHkuU2VydmljZXMuUHJvY2Vzc2VzLkxvZ2dpbmcuTG9nV3JpdGluZ1BvbGljeQEAAAAHdmFsdWVfXwAIJAAAAAEAAAAELQAAAH9TeXN0ZW0uQ29sbGVjdGlvbnMuR2VuZXJpYy5MaXN0YDFbW1N5c3RlbS5PYmplY3QsIG1zY29ybGliLCBWZXJzaW9uPTQuMC4wLjAsIEN1bHR1cmU9bmV1dHJhbCwgUHVibGljS2V5VG9rZW49Yjc3YTVjNTYxOTM0ZTA4OV1dAwAAAAZfaXRlbXMFX3NpemUIX3ZlcnNpb24FAAAICAkxAAAAAgAAAAIAAAABMAAAAC0AAAAJMgAAAAIAAAACAAAAEDEAAAAEAAAABjMAAAAWSW5jbHVkZUluZm9ybWF0aW9uUmF0ZQY0AAAAE1VzZUJpbGxCbG9ja0RldGFpbHMNAhAyAAAABAAAAAgHAQAIBwEADQIL",
"promptData": "",
"criteriaId": 0,
"filterTree": "",
"logFile": "",
"logWritingPolicy": "WriteOnException",
"securityId": 40059,
"version": 0
}
Once you have a complete and populated run model JSON for your type of runnable process, you can send it to REST to execute. To start a runnable process job, perform a POST against the applicable /run end point with the fully configured run model JSON in the body. The job will use the property settings in the POST body to configure and run the job. The packagedParameters value is not applicable in this call and is ignored.
Attempting to run a job with incomplete or incorrect settings will return a validation feedback (HTTP 400 / Validation failed) with the details that need to be fixed.
The POST response will return a HTTP 200 indicating the success of the run start and a body with a reference link to the job resource and the job runId.
POST: /run/export/genericexportinterface/
(with fully populated JSON export model body as above)
{
"_links": {
"self": {
"href": "/run/export/genericexportinterface/5304"
}
},
"_embedded": null,
"runId": 5304
}
With the runid or the job resource link, you will be able to check the status of the running job, retrieve progress information, and eventually retrieve the run results. It is also possible to cancel a running job from this end point by using the HTTP DELETE call against it.
Once you POST a job run, it can be in one of several statuses: Created, Running, CancelRequested, or Completed. If the job status is Created, it is because there could be a slight delay allocating a service to run it and it is pending start.
If the job is running, you will be able to review progress messages and progress percent for each step of the job using the progressMessage and progressValue properties of the status response.
Once the job finishes, you can identify the available outputs using the outputs array property of the status response.
You can access the job details at any time in the future using this URL for this job. It becomes a REST resource URL and will only disappear when the process log run history is purged by the CIS system administrator.
A sample status response of a completed job:
GET: /run/export/genericexportinterface/5304
{
"_links": {
"self": {
"href": "/run/export/genericexportinterface/5304"
}
},
"_embedded": null,
"runId": 5304,
"startDateTime": "2024-04-09T15:56:12.317",
"endDateTime": "2024-04-09T15:56:13.493",
"processName": "GenericExportInterface",
"summary": "Generic Export",
"title": "Generic Export",
"status": "Completed",
"canCancel": false,
"progressValue": 100,
"progressMessage": "",
"stationId": "10.253.9.70",
"notes": ".....",
"sessionId": 0,
"userId": "ADVANCED",
"processType": "Export",
"outputs": [
{
"_links": {
"self": {
"href": "/run/export/genericexportinterface/5304/1"
}
},
"_embedded": null,
"reference": "1",
"fileName": "ebp20240403.csv",
"fileType": "CSV",
"sourceType": "Exp",
"destination": "FILE",
"emailAdress": null,
"subject": null,
"size": "0"
}
],
"isSuccess": true,
"processedCount": 1798,
"successfulCount": 1798,
"failedCount": 0,
"skippedCount": 0,
"feedback": "[]",
"customReturn": "",
"resultDetails": "",
"o_Code": "5304",
"updatedObjectTypes": null
}
Cancel a Running Job
It is possible to cancel a running job if it supports this. Each job determines whether it supports cancelling, and some jobs even support cancelling during some phases of the job run and not others.
You can see whether the job is cancelleable right now by checking the status of the job and reviewing the canCancel property.
To cancel a running job, issue the HTTP DELETE action against the job resource URL:
DELETE: /run/export/genericexportinterface/5304
If the job is cancelleable and the cancel request succeeds, you will receive a 200 response and the job will go into status CancelRequested, else you will receive a 400 response. Once a cancel has been requested, the job will terminate itself at a appropriate unit of work point during the first cancelleable phase of the job. A cancel request cannot be undone.
Retrieve Job Output
Once a job has finished, it is possible to access any potential outputs the job produced.
Calling the job resource end point on a completed job will return information on the job, including the outputs array.
This array will list the outputs associated with the job run. Those outputs can be retrieved by using the self link associated with each output item, or by using the output reference property to address the output child specifically on the job run resource URL.
In the example above, the output can be accessed via a GET to child "1" of the job URL:
GET: /run/export/genericexportinterface/5304/1
The output data will be returned as body content and identified with the best possible content-type header settings for the file extension of the output file.
Miscellaneous Other Runnable Process URLs
GET: /run/export/genericexportinterface
Each runnable process end point supports a standard CIS REST list level GET that returns process log run status records for that runnable process class.
Additional filtering and data shaping can be done using the standard CIS REST query string parameters such as where=, fields=, order=, etc.
GET: /run/export
Each runnable process type end point supports a standard CIS REST list level GET that returns process log run status records for that subset of runnable process types.
Additional filtering and data shaping can be done using the standard CIS REST query string parameters such as where=, fields=, order=, etc.
GET: /run
A get at the top level /run end point returns run process log information for all runnable process jobs in the system.
Additional filtering and data shaping can be done using the standard CIS REST query string parameters such as where=, fields=, order=, etc.
A common use for this level of filtered runnable process request is to generically check the status of a specific runnable process by runId, or to check for all runnable processes associated with a specific user or for a period of time.
GET: /run?where=runid eq 5304
GET: /run?where=userid eq 'ADVANCED'&order=-runid
GET: /run?where=status in ('Running', 'Created')
GET: /run?where=status eq 'Completed' and issuccess eq false and startdatetime ge 2024-03-01 and startdatetime lt 2024-04-01
etc.
/run/report
All CIS ad hoc reports use this same end point. These reports are identified by the report package name contained in the reportContainerLocation property of the report run JSON body.
This container location value corresponds to the name of the report definition package zip file inside the CIS Reports folder. For example, BackFlowListing.zip.
All interactions on this end point for ad hoc reports work the same way as described above for exports, but with a run model specific to the report end point.
Ad hoc reports are those whose report definition contains a null customDLLClass property. See /application/report end point for report definitions.
/run/report/{type}
Some canned or custom reports may have specialized end points under /run/report because their run model payload is specific to that report. For example, /run/report/billjournal.
These specialized reports are those whose report definition contains a non-null customDLLClass property. See /application/report end point for report definitions.
Other than the specialized end point and specialized JSON run model, the procedure for loading, running, checking status, and retrieving outputs are exactly as described above for the other runnable process types.
The custom report names can be looked up in the Swagger/OpenAPI documentation for Advanced REST Web API or in the CIS API Reference document (the end point names match the class names in the AdvancedUtility.Services.Reports namespace).
/application/report
End point root responsible for exposing and maintaining the report definitions of the CIS system.
A full list of existing reports can be retrieved with an HTTP GET on this end point.
Reports can be listed, retrieved, added, edited, and deleted via individual resource links within this URL tree.
/data/advancedimportinterfacedefinition
End point root responsible for exposing and maintaining the AIM import definitions of the CIS system.
This is where AIM import definitions live. /run/import runs use the import definition codes defined here to drive the AIM import runs.
Import definitions can be listed, retrieved, added, edited, and deleted via individual resource links within this URL tree.
/data/advancedexportinterfacedefinition
End point root responsible for exposing and maintaining the AIM export definitions of the CIS system.
This is where AIM export definitions live. /run/export runs use the export definition codes defined here to drive the AIM export runs.
Export definitions can be listed, retrieved, added, edited, and deleted via individual resource links within this URL tree.