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.