fix(maestro-processes): update getExecutionHistory to use element-executions and Traces APIs [PLT-97257]

[Sarath1018]

Method Added

Layer	Method	Signature
Service	processInstances.getExecutionHistory()	getExecutionHistory(instanceId: string, options: ProcessInstanceGetExecutionHistoryOptions): Promise<ProcessInstanceExecutionHistoryResponse[]>

Endpoint Called

Method	HTTP	Endpoint	OAuth Scope
getExecutionHistory()	GET	pims_/api/v1/instances/{instanceId}/element-executions	PIMS
getExecutionHistory()	GET	llmopstenant_/api/Traces/spans?traceId={traceId}	Traces.Api

• options extends FolderScopedOptions (folderKey, folderId, folderPath) — uses resolveFolderHeaders() for consistent folder context resolution, matching the pattern from feat(orchestrator): getByName for Assets + Processes, encoded folder header, meta-tag fallback [PLT-92768][PLT-92817][PLT-92813] #386
• Both endpoints receive the same resolved folder headers
• Only span entries matched to an elementRunId from the element-executions response are returned — the root ProcessRun span (covers the whole instance, no elementRunId) is dropped automatically

Sample SDK response (live API)

[
  {
    "id": "00000000-0000-0000-0b6a-051ca7aec9ce",
    "traceId": "910e3f56-1fbd-4947-9cee-148355c38d08",
    "parentId": "00000000-0000-0000-9b54-950bbe5a2e63",
    "name": "Start event",
    "startedTime": "2026-05-12T11:48:06.077714Z",
    "endTime": "2026-05-12T11:48:06.8733245Z",
    "attributes": "{\"spanType\":\"ElementRun\",\"status\":\"Completed\",\"elementId\":\"Event_start\",\"elementRunId\":\"88952b06-da40-4ab5-8cf3-2fecfbc53164\",\"elementType\":\"StartEvent\",\"runIndex\":1,...}",
    "updatedTime": "2026-05-12T11:48:07.1584589Z",
    "expiredTime": null
  },
  {
    "id": "00000000-0000-0000-42ef-2088c0ac72ac",
    "traceId": "910e3f56-1fbd-4947-9cee-148355c38d08",
    "parentId": "00000000-0000-0000-9b54-950bbe5a2e63",
    "name": "Activity_tblfOr",
    "startedTime": "2026-05-12T11:48:07.4381836Z",
    "endTime": "2026-05-12T11:48:07.7687194Z",
    "attributes": "{\"spanType\":\"ElementRun\",\"status\":\"Completed\",\"elementId\":\"Activity_tblfOr\",\"elementRunId\":\"c0322c6a-16fb-4232-bee2-8811445c16ca\",\"elementType\":\"Task\",\"runIndex\":1,...}",
    "updatedTime": "2026-05-12T11:48:08.2378818Z",
    "expiredTime": null
  },
  {
    "id": "00000000-0000-0000-38ec-7544ef9d965d",
    "traceId": "910e3f56-1fbd-4947-9cee-148355c38d08",
    "parentId": "00000000-0000-0000-9b54-950bbe5a2e63",
    "name": "Event_lLnUK8",
    "startedTime": "2026-05-12T11:48:08.5335271Z",
    "endTime": "2026-05-12T11:48:09.1996998Z",
    "attributes": "{\"spanType\":\"ElementRun\",\"status\":\"Completed\",\"elementId\":\"Event_lLnUK8\",\"elementRunId\":\"23f305b7-ffbf-4d0b-bba7-5fe2b4127aab\",\"elementType\":\"EndEvent\",\"runIndex\":1,...}",
    "updatedTime": "2026-05-12T11:48:09.4081965Z",
    "expiredTime": null
  }
]

Example Usage

import { UiPath } from '@uipath/uipath-typescript/core';
import { ProcessInstances } from '@uipath/uipath-typescript/maestro-processes';

const sdk = new UiPath(config);
await sdk.initialize();
const processInstances = new ProcessInstances(sdk);

// By folder key
const history = await processInstances.getExecutionHistory(
  '<instanceId>',
  { folderKey: '<folderKey>' }
);

// Analyze execution timeline
history.forEach(span => {
  console.log(`Activity: ${span.name}`);
  console.log(`Start: ${span.startedTime}`);
});

API Response vs SDK Response

Composition flow

getExecutionHistory(instanceId, options)
  │
  ├─ resolveFolderHeaders(options) → folder headers
  │
  ├─ GET pims_/api/v1/instances/{instanceId}/element-executions
  │     → ElementExecutionsApiResponse { traceId, elementExecutions[] }
  │
  ├─ GET llmopstenant_/api/Traces/spans?traceId={traceId}
  │     → TraceSpan[] (PascalCase fields; elementRunId inside Attributes JSON)
  │
  └─ Merge: build map of Attributes.elementRunId → span
            for each elementExecution.elementRun, look up by elementRunId
            map matched spans → ProcessInstanceExecutionHistoryResponse[]
            (spans without elementRunId in Attributes dropped — e.g. root ProcessRun span)

Fixes #265

🤖 Auto-generated using onboarding skills

[Sarath1018]

should we parse attributes as this is a json string?

[claude]

Per convention: "Always throw new Error() when test preconditions are not met — whether it's missing config (e.g., no folderId) or missing test data." config.folderKey || '' silently passes an empty string when folderKey is not configured. This changes folder-resolution behaviour in resolveFolderHeaders (an empty string is not the same as undefined) and masks an unrunnable test.

Suggested change

	const result = await processInstances.getExecutionHistory(testInstanceId, { folderKey: config.folderKey || '' });
	if (!config.folderKey) throw new Error('folderKey not configured — set UIPATH_FOLDER_KEY in test env to run this test');
	const result = await processInstances.getExecutionHistory(testInstanceId, { folderKey: config.folderKey });

[claude]

Per convention: "Validate transform completeness — verify both: (a) transformed fields have correct values, AND (b) original PascalCase fields are absent. This catches transform regressions that value-only assertions miss."

mapSpanToHistory explicitly maps span.Id → id, span.TraceId → traceId, span.Name → name, span.StartTime → startedTime, etc. The test verifies the camelCase values are present but never checks that the raw PascalCase fields are absent. A regression where mapSpanToHistory accidentally spreads the whole span (exposing Id, TraceId, StartTime, …) would pass these assertions undetected.

Add absence checks after the existing ones:

expect(result[0]).toHaveProperty('id', MAESTRO_TEST_CONSTANTS.SPAN_ID);
expect(result[0]).toHaveProperty('traceId', MAESTRO_TEST_CONSTANTS.TRACE_ID);
expect(result[0]).toHaveProperty('name', MAESTRO_TEST_CONSTANTS.ACTIVITY_NAME);
// transform completeness: raw PascalCase fields must not leak through
expect((result[0] as any).Id).toBeUndefined();
expect((result[0] as any).TraceId).toBeUndefined();
expect((result[0] as any).StartTime).toBeUndefined();

[claude]

Review findings

Two new issues found this run:

1. Integration test silently accepts missing folderKey — process-instances.integration.test.ts line 251

config.folderKey || '' passes an empty string when the config value is absent. This changes resolveFolderHeaders behaviour (empty string ≠ undefined) and masks an unrunnable test. Should guard with throw new Error() per convention.

2. Transform completeness not validated — process-instances.test.ts lines 239–241

mapSpanToHistory maps PascalCase span fields (Id, TraceId, Name, StartTime, …) to camelCase. The test checks transformed values are present but never asserts the original PascalCase fields are absent. Per convention, both directions must be verified to catch spread-regressions.

[claude]

Per convention: "Keep JSDoc on service class methods in sync with {Entity}ServiceModel — both the models file and the service implementation file must have identical JSDoc for each public method."

The ProcessInstancesServiceModel interface in process-instances.models.ts has:

 * @returns Promise resolving to execution history
 * {@link ProcessInstanceExecutionHistoryResponse}
 * @example
 * ```typescript
 * // Get execution history for a process instance
 * const history = await processInstances.getExecutionHistory(
 *   <instanceId>,
 *   <folderKey>
 * );
 *
 * // Analyze execution timeline
 * history.forEach(span => {
 *   console.log(`Activity: ${span.name}`);
 *   console.log(`Start: ${span.startedTime}`);
 *   console.log(`End: ${span.endTime}`);
 * });
 * ```

The service implementation has only @returns Promise<ProcessInstanceExecutionHistoryResponse[]> — missing the {@link} and the entire @example block. The service copy must be brought to match the model.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud