v2.1.5+ REST API endpoints for expression evaluation and context retrieval

Reference for the HCL Universal Orchestrator REST API v2 endpoints that support task context retrieval, run history retrieval, and expression evaluation.

The endpoints described follow the /twsd/api/v2/ convention and inherit the existing HCL Universal Orchestrator authentication and authorization model. Context retrieval is run-scoped and tenant-isolated. For the full interactive specification, connect to the Swagger UI at:

https://hostname:port/q/swagger-ui/#/

Endpoints

  • GET /twsd/api/v2/plan/task-history/runs

    Returns a paginated list of previous run entries for a specific task node within a workflow definition. The workflow and task identifiers are not path parameters; they are provided as OQL filter criteria in the query string, typically as the workflow abstract ID and the task abstract ID. Results are sorted by most recent submission time by default.

    Query parameters: limit, offset, from, to, plan_id, status.

    Response: items[] — each entry includes runId, workflowRunId, planId, taskId, taskName, status, submittedTime, actualStartTime, actualEndTime, returnCode, runAttempt, hasContext — plus total, limit, offset.

  • GET /twsd/api/v2/plan/workflow-history/runs

    Returns a paginated list of previous run entries for a specific workflow. The workflow identifier is provided as an OQL filter criterion in the query string, typically as the workflow abstract ID. Results follow the same response structure as the GET /twsd/api/v2/plan/task-history/runs endpoint.

  • GET /twsd/api/v2/plan/task/run/{runId}/context
    Returns the full JSON context recorded for the specified task run. The response body is the context item containing RC, var, js, and jobs properties.
  • POST /twsd/api/v2/engine/expression/evaluate

    Evaluates a JSONata expression against a provided context using the same runtime used by the orchestration engine, including all HCL Universal Orchestrator proprietary functions.

    Request body:

    {
  "context": object,
  "expression": string,
  "expressionType": NONE | BOOLEAN_EXPRESSION | EMBEDDED,
  "settings": {
    "defaultFolder": string,
    "zoneId": string,
    "freeDaysCalendarId": string,
    "saturdayFree": boolean,
    "sundayFree": boolean
  }
}

    Response body:

    {
  "result": string,
  "validType": boolean,
  "errors": string[],
  "warnings": string[]
}

    The expressionType field accepts the following values:

    Value Description
    NONE Evaluates the expression without type validation. The result is returned as-is.
    BOOLEAN_EXPRESSION Evaluates the expression and validates that the result is a boolean. If the result type does not match, validType is set to false and a localized validation message is included in errors.
    EMBEDDED Processes the expression as an embedded template string, resolving each ${...} block individually and returning the final interpolated string.
  • v2.1.7+
    post/twsd/api/v2/plan/task/run/{run_id}/action/rerun or /twsd/api/v2/plan/task/action/rerun
    Overwrites the original task definition before rerun.
    • post/twsd/api/v2/plan/task/run/{run_id}/action/rerun: Enter the {run_id} of the specific run instance to rerun only that instance.
    • /twsd/api/v2/plan/task/action/rerun: Reruns all tasks in the plan that completed with a final status.
    Request body: 
    {  
 "rerunJobOnSameWorkstation": [true | false],  
 "startTime": "Date_time",  
 "jobDefinitionInPlan": {  
 "task": {  
 "wait": {  
 "Action": {  
 "actionInfo": {  
 "duration": "PT1S"  
 }  
 }  
 }  
 },  
 "workstationId":"Workstation_ID",  
 "workstation": "Workstation_name"  
 },  
 "stepName":"Task_step"  
}
    You can provide values for each fields as follows:
    Fields Description
    rerunJobOnSameWorkstation Specify true if you want to rerun the task on the workstation where it previously ran. Otherwise, specify false.
    startTime Specify the start time. For example, 2026-04-27T06:57:00Z.
    task Specify the task type. The above example shows the wait task.
    workstationId Specify the workstation ID if you want to run the task on a specific workstation. This field is ignored when you specify the rerunJobOnSameWorkstation attribute as true.
    workstation Specify the name of the workstation.
    stepName Enter a specific task in the task definition from which to rerun the task.