Skip to content

Commit 43ad4d7

Browse files
ninja-shreyashclaude
ninja-shreyash
and
claude
committed
feat(insights): add getElementCountByStatus to ProcessInstances and CaseInstances
Add Insights RTM endpoint for retrieving per-element execution counts and duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements. - Use Date input for startTime/endTime, convert internally via .getTime() - CaseInstancesService delegates to ProcessInstancesService - Extract getElementCountByStatusImpl to avoid double @track - Add JSDoc, type annotations, and trailing newlines PLT-102911 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent f350702 commit 43ad4d7

14 files changed

Lines changed: 416 additions & 9 deletions

File tree

‎docs/oauth-scopes.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ This page lists the specific OAuth scopes required in external app for each SDK
8585
| `cancel()` | `PIMS` |
8686
| `pause()` | `PIMS` |
8787
| `resume()` | `PIMS` |
88+
| `getElementCountByStatus()` | `Insights.RealTimeData` `Insights` `PIMS` `OR.Folders.Read` |
8889

8990
## Maestro Cases
9091

@@ -106,6 +107,7 @@ This page lists the specific OAuth scopes required in external app for each SDK
106107
| `getStages()` | `PIMS OR.Execution.Read` |
107108
| `getActionTasks()` | `OR.Tasks` or `OR.Tasks.Read` |
108109
| `getSlaSummary()` | `Insights.RealTimeData Insights OR.Folders.Read PIMS` |
110+
| `getElementCountByStatus()` | `Insights.RealTimeData` `Insights` `PIMS` `OR.Folders.Read` |
109111

110112
## Conversational Agent
111113

‎src/models/maestro/case-instances.models.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../utils/pagination';
1313
import { OperationResponse } from '../common/types';
1414
import { TaskGetResponse, TaskGetAllOptions } from '../action-center';
15+
import type { ElementCountByStatus, ElementCountByStatusOptions } from './insights.types';
1516

1617
/**
1718
* Service model for managing Maestro Case Instances
@@ -326,6 +327,34 @@ export interface CaseInstancesServiceModel {
326327
? PaginatedResponse<SlaSummaryResponse>
327328
: NonPaginatedResponse<SlaSummaryResponse>
328329
>;
330+
331+
/**
332+
* Get element count by status for case instances
333+
*
334+
* Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
335+
* duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a case.
336+
*
337+
* @param options - Options containing processKey, packageId, time range, and version
338+
* @returns Promise resolving to an array of {@link ElementCountByStatus}
339+
* @example
340+
* ```typescript
341+
* // Get element metrics for a case
342+
* const elements = await caseInstances.getElementCountByStatus({
343+
* processKey: '<processKey>',
344+
* packageId: '<packageId>',
345+
* startTime: new Date('2026-04-01'),
346+
* endTime: new Date(),
347+
* version: '1.0.1'
348+
* });
349+
*
350+
* // Find elements with failures
351+
* const failedElements = elements.filter(e => e.failCount > 0);
352+
* for (const element of failedElements) {
353+
* console.log(`Failed element: ${element.elementId}, failures: ${element.failCount}`);
354+
* }
355+
* ```
356+
*/
357+
getElementCountByStatus(options: ElementCountByStatusOptions): Promise<ElementCountByStatus[]>;
329358
}
330359

331360
// Method interface that will be added to case instance objects

‎src/models/maestro/index.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,7 @@ export * from './cases.models';
1818

1919
// Case instance types and models
2020
export * from './case-instances.types';
21-
export * from './case-instances.models';
21+
export * from './case-instances.models';
22+
23+
// Insights types (shared across process and case instances)
24+
export * from './insights.types';

‎src/models/maestro/insights.types.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/**
2+
* Insights Types
3+
* Shared types for Maestro insights analytics endpoints
4+
*/
5+
6+
/**
7+
* Element count by status for a BPMN element within a process or case
8+
*/
9+
export interface ElementCountByStatus {
10+
/** BPMN element identifier */
11+
elementId: string;
12+
/** Number of successful executions */
13+
successCount: number;
14+
/** Number of failed executions */
15+
failCount: number;
16+
/** Number of terminated executions */
17+
terminatedCount: number;
18+
/** Number of paused executions */
19+
pausedCount: number;
20+
/** Number of in-progress executions */
21+
inProgressCount: number;
22+
/** Minimum duration in milliseconds */
23+
minDurationMs: number;
24+
/** Maximum duration in milliseconds */
25+
maxDurationMs: number;
26+
/** Average duration in milliseconds */
27+
avgDurationMs: number;
28+
/** 50th percentile (median) duration in milliseconds */
29+
p50DurationMs: number;
30+
/** 95th percentile duration in milliseconds */
31+
p95DurationMs: number;
32+
/** 99th percentile duration in milliseconds */
33+
p99DurationMs: number;
34+
}
35+
36+
/**
37+
* Options for getting element count by status
38+
*/
39+
export interface ElementCountByStatusOptions {
40+
/** Process key to filter by */
41+
processKey: string;
42+
/** Package identifier */
43+
packageId: string;
44+
/** Start of the time range to query */
45+
startTime: Date;
46+
/** End of the time range to query */
47+
endTime: Date;
48+
/** Package version to filter by */
49+
version: string;
50+
}

‎src/models/maestro/process-instances.models.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import type {
99
ProcessInstanceGetVariablesOptions
1010
} from './process-instances.types';
1111
import type { ProcessIncidentGetResponse } from './process-incidents.types';
12+
import type { ElementCountByStatus, ElementCountByStatusOptions } from './insights.types';
1213
import { OperationResponse } from '../common/types';
1314
import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../utils/pagination';
1415

@@ -255,6 +256,35 @@ export interface ProcessInstancesServiceModel {
255256
* ```
256257
*/
257258
getIncidents(instanceId: string, folderKey: string): Promise<ProcessIncidentGetResponse[]>;
259+
260+
/**
261+
* Get element count by status for process instances
262+
*
263+
* Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
264+
* duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a process.
265+
*
266+
* @param options - Options containing processKey, packageId, time range, and version
267+
* @returns Promise resolving to an array of {@link ElementCountByStatus}
268+
* @example
269+
* ```typescript
270+
* // Get element metrics for a process
271+
* const elements = await processInstances.getElementCountByStatus({
272+
* processKey: '<processKey>',
273+
* packageId: '<packageId>',
274+
* startTime: new Date('2026-04-01'),
275+
* endTime: new Date(),
276+
* version: '1.0.1'
277+
* });
278+
*
279+
* // Analyze element performance
280+
* for (const element of elements) {
281+
* console.log(`Element: ${element.elementId}`);
282+
* console.log(` Success: ${element.successCount}, Failed: ${element.failCount}`);
283+
* console.log(` Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
284+
* }
285+
* ```
286+
*/
287+
getElementCountByStatus(options: ElementCountByStatusOptions): Promise<ElementCountByStatus[]>;
258288
}
259289

260290
// Method interface that will be added to process instance objects

‎src/services/maestro/cases/case-instances.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ import {
1515
CaseInstanceExecutionHistoryResponse,
1616
SlaSummaryResponse,
1717
CaseInstanceSlaSummaryOptions,
18+
ElementCountByStatus,
19+
ElementCountByStatusOptions
1820
} from '../../../models/maestro';
21+
import { ProcessInstancesService } from '../processes/process-instances';
1922
import { TaskGetResponse } from '../../../models/action-center';
2023
import {
2124
CaseJsonResponse
@@ -45,6 +48,7 @@ import { TaskGetAllOptions } from '../../../models/action-center';
4548

4649
export class CaseInstancesService extends BaseService implements CaseInstancesServiceModel {
4750
private taskService: TaskService;
51+
private processInstancesService: ProcessInstancesService;
4852

4953
/**
5054
* Creates an instance of the Case Instances service.
@@ -54,6 +58,7 @@ export class CaseInstancesService extends BaseService implements CaseInstancesSe
5458
constructor(instance: IUiPath) {
5559
super(instance);
5660
this.taskService = new TaskService(instance);
61+
this.processInstancesService = new ProcessInstancesService(instance);
5762
}
5863

5964
/**
@@ -167,6 +172,16 @@ export class CaseInstancesService extends BaseService implements CaseInstancesSe
167172
return this.enhanceInstanceWithCaseJson(instanceWithMethods);
168173
}
169174

175+
/**
176+
* Get element count by status for case instances
177+
* @param options Options containing processKey, packageId, time range, and version
178+
* @returns Promise resolving to an array of element count by status
179+
*/
180+
@track('CaseInstances.GetElementCountByStatus')
181+
async getElementCountByStatus(options: ElementCountByStatusOptions): Promise<ElementCountByStatus[]> {
182+
return this.processInstancesService.getElementCountByStatusImpl(options);
183+
}
184+
170185
/**
171186
* Enhance a single case instance with case JSON data
172187
* @param instance - The case instance to enhance

‎src/services/maestro/cases/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,4 @@ export * from '../../../models/maestro/cases.types';
2929
export * from '../../../models/maestro/cases.models';
3030
export * from '../../../models/maestro/case-instances.types';
3131
export * from '../../../models/maestro/case-instances.models';
32+
export * from '../../../models/maestro/insights.types';

‎src/services/maestro/processes/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,4 @@ export * from '../../../models/maestro/process-instances.types';
3838
export * from '../../../models/maestro/process-instances.models';
3939
export * from '../../../models/maestro/process-incidents.types';
4040
export * from '../../../models/maestro/process-incidents.models';
41+
export * from '../../../models/maestro/insights.types';

‎src/services/maestro/processes/process-instances.ts‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ import {
1111
ProcessInstanceGetVariablesResponse,
1212
ProcessInstanceGetVariablesOptions,
1313
GlobalVariableMetaData,
14-
ProcessIncidentGetResponse
14+
ProcessIncidentGetResponse,
15+
ElementCountByStatus,
16+
ElementCountByStatusOptions
1517
} from '../../../models/maestro';
1618
import { BpmnHelpers } from './helpers';
1719
import { OperationResponse } from '../../../models/common/types';
@@ -203,6 +205,35 @@ export class ProcessInstancesService extends BaseService implements ProcessInsta
203205
};
204206
}
205207

208+
/**
209+
* Get element count by status for process instances
210+
* @param options Options containing processKey, packageId, time range, and version
211+
* @returns Promise resolving to an array of element count by status
212+
*/
213+
async getElementCountByStatusImpl(options: ElementCountByStatusOptions): Promise<ElementCountByStatus[]> {
214+
const requestBody = {
215+
commonParams: {
216+
processKey: options.processKey,
217+
packageId: options.packageId,
218+
startTime: options.startTime.getTime(),
219+
endTime: options.endTime.getTime(),
220+
version: options.version
221+
}
222+
};
223+
224+
const response = await this.post<ElementCountByStatus[]>(
225+
MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS,
226+
requestBody
227+
);
228+
229+
return response.data;
230+
}
231+
232+
@track('ProcessInstances.GetElementCountByStatus')
233+
async getElementCountByStatus(options: ElementCountByStatusOptions): Promise<ElementCountByStatus[]> {
234+
return this.getElementCountByStatusImpl(options);
235+
}
236+
206237
/**
207238
* Parses BPMN XML to extract variable metadata from uipath:inputOutput elements
208239
* @private

‎src/utils/constants/endpoints/maestro.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,7 @@ export const MAESTRO_ENDPOINTS = {
3535
INSIGHTS: {
3636
/** SLA summary for case instances */
3737
SLA_SUMMARY: `${INSIGHTS_RTM_BASE}/caseManagement/slaSummary`,
38+
/** Element count by status for agentic instances (process and case) */
39+
ELEMENT_COUNT_BY_STATUS: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/ElementCountByStatus`,
3840
},
3941
} as const;

0 commit comments

Comments
 (0)