feat(insights): add getElementStats to MaestroProcesses and Cases [PLT-102911]

[ninja-shreyash]

Method Added

Layer	Method	Signature
Service	maestroProcesses.getElementStats()	getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>
Service	cases.getElementStats()	getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>
Bound	process.getElementStats()	getElementStats(startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>
Bound	case.getElementStats()	getElementStats(startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>

Endpoint Called

Method	HTTP	Endpoint	OAuth Scope
getElementStats()	POST	/insightsrtm_/agenticInstanceStatus/ElementCountByStatus	Insights.RealTimeData Insights OR.Folders.Read

• Shared buildElementCountByStatusBody() helper in src/services/maestro/insights.ts constructs the request body
• Both MaestroProcessesService and CasesService call this.post() directly (no delegation between services)
• Bound methods on process/case objects auto-fill processKey and packageId from the entity

Example Usage

import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';

const sdk = new UiPath(config);
await sdk.initialize();
const maestroProcesses = new MaestroProcesses(sdk);

// Get element metrics for a process
const elements = await maestroProcesses.getElementStats(
  '<processKey>',
  '<packageId>',
  new Date('2026-04-01'),
  new Date(),
  '1.0.1'
);

// Analyze element performance
for (const element of elements) {
  console.log(\`Element: \${element.elementId}\`);
  console.log(\`  Success: \${element.successCount}, Failed: \${element.failCount}\`);
  console.log(\`  Avg duration: \${element.avgDurationMs}ms, P95: \${element.p95DurationMs}ms\`);
}

// Using bound method on a process object
const processes = await maestroProcesses.getAll();
const metrics = await processes[0].getElementStats(
  new Date('2026-04-01'),
  new Date(),
  processes[0].packageVersions[0]
);

API Response vs SDK Response

Transform pipeline

No transform — response is returned as-is from the API (`data ?? []`).

Request body mapping

SDK Param	API Body Field	Notes
`processKey`	`commonParams.processKey`	Direct pass-through
`packageId`	`commonParams.packageId`	Direct pass-through
`startTime` (Date)	`commonParams.startTime` (number)	Converted via `.getTime()`
`endTime` (Date)	`commonParams.endTime` (number)	Converted via `.getTime()`
`packageVersion`	`commonParams.version`	Renamed: SDK uses `packageVersion`, API uses `version`

Sample SDK Response

getElementStats()

```json
[
{
"elementId": "Event_wYlKnG",
"successCount": 1,
"failCount": 0,
"terminatedCount": 0,
"pausedCount": 0,
"inProgressCount": 0,
"minDurationMs": 652,
"maxDurationMs": 652,
"avgDurationMs": 652,
"p50DurationMs": 652,
"p95DurationMs": 652,
"p99DurationMs": 652
},
{
"elementId": "Activity_Ii3Yl0",
"successCount": 1,
"failCount": 0,
"terminatedCount": 0,
"pausedCount": 0,
"inProgressCount": 0,
"minDurationMs": 8702,
"maxDurationMs": 8702,
"avgDurationMs": 8702,
"p50DurationMs": 8702,
"p95DurationMs": 8702,
"p99DurationMs": 8702
}
]
```

Files

Area	Files
Endpoint	`src/utils/constants/endpoints/maestro.ts`
Types	`src/models/maestro/insights.types.ts`
Models	`src/models/maestro/processes.models.ts`, `src/models/maestro/cases.models.ts`
Service	`src/services/maestro/processes/processes.ts`, `src/services/maestro/cases/cases.ts`
Shared helper	`src/services/maestro/insights.ts`
Barrel exports	`src/models/maestro/index.ts`
Unit tests	`tests/unit/services/maestro/processes.test.ts` (3 tests), `tests/unit/services/maestro/cases.test.ts` (1 test)
Model tests	`tests/unit/models/maestro/processes.test.ts` (3 tests), `tests/unit/models/maestro/cases.test.ts` (1 test)
Integration tests	`tests/integration/shared/maestro/processes.integration.test.ts` (1 test, skipped), `tests/integration/shared/maestro/cases.integration.test.ts` (1 test, skipped)
Test utils	`tests/integration/utils/helpers.ts`, `tests/utils/constants/maestro.ts`
Docs	`docs/oauth-scopes.md`

Refs PLT-102911

[claude]

Two issues found this run:

1. package-lock.json:3 — Lock file was committed with version 1.0.0-test.2 (a local test version), downgrading from 1.3.6. This is an accidental inclusion; revert it to the current main version.

2. src/models/maestro/index.ts:24 — Missing newline at end of file.

The implementation itself looks clean: delegation pattern (CaseInstances -> ProcessInstances) is correct, @track decorators are present on both methods, types are well-defined, tests cover success/error/empty paths, OAuth scopes doc is updated, and the endpoint constant follows conventions.

[claude]

Two new findings this run:

1. src/utils/constants/endpoints/maestro.ts:38 — ELEMENT_COUNT_BY_STATUS is missing a JSDoc comment; SLA_SUMMARY immediately above it has one. Per conventions every constant needs its own description.

2. src/services/maestro/cases/case-instances.ts:182 — Delegating to this.processInstancesService.getElementCountByStatus() causes double @track firing for a single user call (CaseInstances.GetElementCountByStatus + ProcessInstances.GetElementCountByStatus). Suggested fix: extract the HTTP logic into an undecorated getElementCountByStatusImpl on ProcessInstancesService and have both public methods call that.

[claude]

Two items from this run:

1. Re-opened: package-lock.json — The previous thread asking to revert the lock file was resolved, but the version change is still present: the diff now shows 1.3.8 → 1.3.7. Per conventions, version changes (bumps or downgrades) must not appear in feature PRs — they belong in a dedicated version-bump PR. Please run git checkout origin/main -- package-lock.json to restore the lock file to its main-branch state.

2. New: src/utils/constants/endpoints/maestro.ts:38 — ELEMENT_COUNT_BY_STATUS is missing a JSDoc comment. SLA_SUMMARY directly above it has one; each constant needs its own.

[claude]

New finding this run:

• tests/unit/services/maestro/process-instances.test.ts:604 and case-instances.test.ts:950 — Both new options objects for getElementCountByStatus are untyped. Every other options variable in those files has an explicit type annotation; these should be ElementCountByStatusOptions. Convention: "Type request objects in tests — don't leave as untyped objects."

[claude]

Two new findings this run (all prior issues were addressed):

1. src/services/maestro/processes/process-instances.ts:213 — getElementCountByStatusImpl is missing an @internal JSDoc tag. The method is not on the ServiceModel interface but is publicly callable; per conventions, internal code must be tagged @internal or @ignore.

2. src/services/maestro/processes/process-instances.ts:232–235 — getElementCountByStatus has no JSDoc of its own — the comment at lines 208–212 belongs to getElementCountByStatusImpl. Per conventions, service class methods must have JSDoc identical to the ServiceModel entry (which has a full @example block).

[claude]

New finding this run:

• src/services/maestro/cases/case-instances.ts:175–181 — The JSDoc on getElementCountByStatus in the service implementation is not in sync with CaseInstancesServiceModel. The ServiceModel has a full extended description, {@link ElementCountByStatus} in @returns, and a @example block; the service class has none of these. Per conventions, both must be identical.

[claude]

Two previously-resolved threads re-opened because the requested changes were not applied:

1. Re-opened: src/services/maestro/processes/process-instances.ts — getElementCountByStatusImpl missing @internal
   The JSDoc was added, but the @internal tag requested in the prior review was not included. Without it, TypeDoc will include this implementation-detail method in the public API docs and consumers will see it as callable. Please add @internal to the JSDoc.

2. Re-opened: src/services/maestro/processes/process-instances.ts — getElementCountByStatus has no JSDoc
   The public method immediately following getElementCountByStatusImpl has only a @track decorator and no JSDoc at all. Per conventions, service class methods must carry JSDoc identical to their ProcessInstancesServiceModel entry (which has the full @example, @param, and @returns block). Please copy that JSDoc onto the service implementation method.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

New finding this run:

• tests/unit/services/maestro/case-instances.test.ts:938 — The getElementCountByStatus describe block only has a success test. Per conventions, every public method must have both success and error scenarios tested. Missing: an error propagation test (see inline comment).

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

1 new finding this run:

Both new getElementCountByStatus() entries in docs/oauth-scopes.md (lines 78 and 103) use separate backtick groups for each scope — Insights.RealTimeData Insights PIMS OR.Folders.Read — while every other row in the table uses a single backtick group for all scopes (e.g. Insights.RealTimeData Insights OR.Folders.Read). Two inline suggestions posted.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[sonarqubecloud]

Quality Gate passed

Issues
11 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud