Driving HCL Universal Orchestrator with REST API

HCL Universal Orchestrator provides a set of fully functional APIs that are implemented based on the Representational State Transfer (REST) services. The REST API helps you easily integrate workload scheduling capabilities with external products and solutions. The same product functionality covered by the existing J2EE API is available with the REST API. The REST API is programming language independent and favors easier network configuration and firewall traversal. With the APIs, you can exploit heterogeneous environments and provide new automation opportunities with direct impact on productivity. The following are few key characteristics of REST APIs:
  • Enhanced filtering opportunities.
  • Improved payloads for easier consumption.
  • Introduction of efficient multi-item endpoints.
  • Easy communication with external apps.

HCL Universal Orchestrator provides REST APIs V2, which are based on the REST APIs of Workload Automation, but they are quicker and simpler and help you perform the actions much faster.

REST APIs V2 provide several services to administer engines, workload modelling, plans, and security.

The following are some examples or scenarios where the APIs can be implemented:
  • Create your own graphical interface to create and modify scheduling definitions, and update items in the plan.
  • Update definitions or plan items within a script for integration or automation.
  • In a managed file transfer solution, when a specific file arrives, you can submit one or more task flows that elaborate the file, closing the loop on your business process, whether it be bank transactions, a payroll process, or report generation. Your external managed file transfer product starts the business process and HCL Universal Orchestrator takes care of the processing, assuring that it be monitored with the rest of the processes from a single point of control and eventually linked with other processes.
  • Customize your environment to improve your business. For example, see the following business scenario: HCL Universal Orchestrator business scenario.
After you installed the engine, you can access the available REST API services by connecting to the following URL:
https://hostname:port_number/q/swagger-ui/#/
where,
hostname
The hostname of the gateway microservice.
port_number
The valid port exposed for API gateway. The default port is 443.
Note: When using REST API, if you run a query defining a time zone for the task in plan, the results are displayed in UTC format even if the defined value is different.

Evaluating run cycles using REST APIs

You can programmatically evaluate and forecast your scheduling rules for workflows and run cycle groups without needing to use the UI calendar by leveraging the run cycle preview REST APIs. This enables you to pull scheduling forecasts into external tools or generate custom reports.

Evaluate run cycles for an item (existing or not existing)

Use this API to pass an item definition (such as a workflow or run cycle group) and receive the calculated run instances over a specified date range.

Method: POST

URL: /twsd/api/v2/model/<objectType>/rc-evaluation?from=${from}&to=${to}

Table 1. Parameters for evaluating run cycles of an item
Name Description Format Type Constraints
from Date from which the preview must be calculated from the calendar controls. Default is 1 Jan of current Year. yyyy-mm-dd Query param Mandatory
to Ending date to use to calculate the preview from the calendar controls. Default is 31 Dec of current Year. yyyy-mm-dd Query param Mandatory
runCycleId The identifier of a single run cycle to evaluate. If not present, evaluates all run cycles. - Body param Optional
subsetId The identifier of a subset to evaluate all contained run cycles. If not present, evaluates all run cycles. - Body param Optional
jobStream/runCycleGroup The whole item definition. V2 format Body param Mandatory
objectType The type of the item being evaluated. jobstream / runcyclegroup Path param Mandatory
Evaluate run cycles for an existing item only

Use this API to evaluate the schedule for an item that is already saved in the database by referencing its ID.

Method: POST

URL: /twsd/api/v2/model/<objectType>/${objectId}/rc-evaluation?from=${from}&to=${to}

Table 2. Parameters for evaluating run cycles of an existing item
Name Description Format Type Constraints
from Date from which the preview must be calculated from the calendar controls. Default is 1 Jan of current Year. yyyy-mm-dd Query param Mandatory
to Ending date to use to calculate the preview from the calendar controls. Default is 31 Dec of current Year. yyyy-mm-dd Query param Mandatory
objectId The identifier of the item. It evaluates all run cycles. - Body param Optional
objectType The type of the item being evaluated. jobstream / runcyclegroup Path param Mandatory
Retrieve run instance details

Use this API to provide the granular details of the run instances for a given period.

Method: POST

URL: /twsd/api/v2/model/<objectType>/rc-evaluation-details?from=${from}&to=${to}

Table 3. Parameters for retrieving run instance details
Name Description Format Type Constraints
from Date from which the preview must be calculated from the calendar controls. Default is 1 Jan of current Year. yyyy-mm-dd Query param Mandatory
to Same value as from. yyyy-mm-dd Query param Mandatory
runCycleId The identifier of a single run cycle to evaluate. If not present, evaluates all run cycles. - Body param Optional
subsetId The identifier of a subset to evaluate all contained run cycles. If not present, evaluates all run cycles. - Body param Optional
jobStream/runCycleGroup The whole item definition. V2 format Body param Mandatory
objectType The type of the item being evaluated. jobstream / runcyclegroup Path param Mandatory
maxResults The max number of instances you want to view in the preview. The default value is 1440. - Query param Optional
Retrieve run instance details for an existing item only

Use this API to provide the granular details of the run instances for a given period for an item that is already saved in the database by referencing its ID.

Method: POST

URL: /twsd/api/v2/model/<objectType>/${objectId}/rc-evaluation-details?from=${from}&to=${to}

Table 4. Parameters for retrieving run instance details of an existing item
Name Description Format Type Constraints
from Date from which the preview must be calculated from the calendar controls. Default is 1 Jan of current Year. yyyy-mm-dd Query param Mandatory
to Ending date to use to calculate the preview from the calendar controls. Default is 31 Dec of current Year. yyyy-mm-dd Query param Mandatory
objectId The identifier of the item. It evaluates all run cycles. - Path param Optional
objectType The type of the item being evaluated. jobstream / runcyclegroup Path param Mandatory
maxResults The max number of instances you want to view in the preview. Default value 1440. - Query param Optional
Evaluate run cycles from Assets
Use this API to evaluate run cycles for workflows and run cycle groups directly from the Assets list. Items must have at least DISPLAY permission.
Note: This is available for "All run cycles" only mode. There is no possibility to switch between run cycles or subsets, or require details for the instances.

Method: GET

URL: /twsd/api/v2/model/${objectType}/${objectId}/rc-evaluation?from=${from}&to=${to}

Table 5. Parameters for evaluating run cycles from Assets
Name Description Format Type Constraints
from Date from which the preview must be calculated. Default is 01-01-<current year>. yyyy-mm-dd Query param Mandatory
to Ending date to use to calculate the preview. Default is 31-12-<current-year>. yyyy-mm-dd Query param Mandatory
objectId The identifier of the item. - Path param Mandatory
objectType The type of the item being evaluated. jobstream / runcyclegroup Path param Mandatory