Process Instances
Service for managing UiPath Maestro Process instances
Maestro process instances are the running instances of Maestro processes. UiPath Maestro Process Instances Guide
Methods¶
getAll()¶
getAll<T>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<ProcessInstanceGetResponse> : NonPaginatedResponse<ProcessInstanceGetResponse>>;
Get all process instances with optional filtering and pagination
The method returns either: - A NonPaginatedResponse with items array (when no pagination parameters are provided) - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
Type Parameters¶
Type Parameter | Default type |
---|---|
T extends ProcessInstanceGetAllWithPaginationOptions |
ProcessInstanceGetAllWithPaginationOptions |
Parameters¶
Parameter | Type | Description |
---|---|---|
options? |
T |
Query parameters for filtering instances and pagination |
Returns¶
Promise
<T
extends HasPaginationOptions
<T
> ? PaginatedResponse
<ProcessInstanceGetResponse
> : NonPaginatedResponse
<ProcessInstanceGetResponse
>>
Promise resolving to either an array of process instances NonPaginatedResponse
Example¶
// Get all instances (non-paginated)
const instances = await sdk.maestro.processes.instances.getAll();
// Cancel faulted instances using methods directly on instances
for (const instance of instances.items) {
if (instance.latestRunStatus === 'Faulted') {
await instance.cancel({ comment: 'Cancelling faulted instance' });
}
}
// With filtering
const instances = await sdk.maestro.processes.instances.getAll({
processKey: 'MyProcess'
});
// First page with pagination
const page1 = await sdk.maestro.processes.instances.getAll({ pageSize: 10 });
// Navigate using cursor
if (page1.hasNextPage) {
const page2 = await sdk.maestro.processes.instances.getAll({ cursor: page1.nextCursor });
}
getById()¶
Get a process instance by ID with operation methods (cancel, pause, resume)
Parameters¶
Parameter | Type | Description |
---|---|---|
id |
string |
The ID of the instance to retrieve |
folderKey |
string |
The folder key for authorization |
Returns¶
Promise
<ProcessInstanceGetResponse
>
Promise resolving to a process instance ProcessInstanceGetResponse
Example¶
// Get a specific process instance
const instance = await sdk.maestro.processes.instances.getById(
<instanceId>,
<folderKey>
);
// Access instance properties
console.log(`Status: ${instance.latestRunStatus}`);
getExecutionHistory()¶
Get execution history (spans) for a process instance
Parameters¶
Parameter | Type | Description |
---|---|---|
instanceId |
string |
The ID of the instance to get history for |
Returns¶
Promise
<ProcessInstanceExecutionHistoryResponse
[]>
Promise resolving to execution history ProcessInstanceExecutionHistoryResponse
Example¶
// Get execution history for a process instance
const history = await sdk.maestro.processes.instances.getExecutionHistory(
<instanceId>
);
// Analyze execution timeline
history.forEach(span => {
console.log(`Activity: ${span.name}`);
console.log(`Start: ${span.startTime}`);
console.log(`Duration: ${span.duration}ms`);
});
getBpmn()¶
Get BPMN XML file for a process instance
Parameters¶
Parameter | Type | Description |
---|---|---|
instanceId |
string |
The ID of the instance to get BPMN for |
folderKey |
string |
The folder key for authorization |
Returns¶
Promise
<string
>
Promise resolving to BPMN XML file BpmnXmlString
Example¶
// Get BPMN XML for a process instance
const bpmnXml = await sdk.maestro.processes.instances.getBpmn(
<instanceId>,
<folderKey>
);
// Render BPMN diagram in frontend using bpmn-js
import BpmnViewer from 'bpmn-js/lib/Viewer';
const viewer = new BpmnViewer({
container: '#bpmn-diagram'
});
await viewer.importXML(bpmnXml);
// Zoom to fit the diagram
viewer.get('canvas').zoom('fit-viewport');
cancel()¶
cancel(
instanceId: string,
folderKey: string,
options?: ProcessInstanceOperationOptions): Promise<OperationResponse<ProcessInstanceOperationResponse>>;
Cancel a process instance
Parameters¶
Parameter | Type | Description |
---|---|---|
instanceId |
string |
The ID of the instance to cancel |
folderKey |
string |
The folder key for authorization |
options? |
ProcessInstanceOperationOptions |
Optional cancellation options with comment |
Returns¶
Promise
<OperationResponse
<ProcessInstanceOperationResponse
>>
Promise resolving to operation result with instance data
Example¶
// Cancel a process instance
const result = await sdk.maestro.processes.instances.cancel(
<instanceId>,
<folderKey>
);
if (result.success) {
console.log(`Instance ${result.data.instanceId} now has status: ${result.data.status}`);
}
// Cancel with a comment
const result = await sdk.maestro.processes.instances.cancel(
<instanceId>,
<folderKey>,
{ comment: <comment> }
);
// Cancel multiple faulted instances
const instances = await sdk.maestro.processes.instances.getAll({
latestRunStatus: "Faulted"
});
for (const instance of instances.items) {
const result = await sdk.maestro.processes.instances.cancel(
instance.instanceId,
instance.folderKey,
{ comment: <comment> }
);
if (result.success) {
console.log(`Cancelled instance: ${result.data.instanceId}`);
}
}
pause()¶
pause(
instanceId: string,
folderKey: string,
options?: ProcessInstanceOperationOptions): Promise<OperationResponse<ProcessInstanceOperationResponse>>;
Pause a process instance
Parameters¶
Parameter | Type | Description |
---|---|---|
instanceId |
string |
The ID of the instance to pause |
folderKey |
string |
The folder key for authorization |
options? |
ProcessInstanceOperationOptions |
Optional pause options with comment |
Returns¶
Promise
<OperationResponse
<ProcessInstanceOperationResponse
>>
Promise resolving to operation result with instance data
resume()¶
resume(
instanceId: string,
folderKey: string,
options?: ProcessInstanceOperationOptions): Promise<OperationResponse<ProcessInstanceOperationResponse>>;
Resume a process instance
Parameters¶
Parameter | Type | Description |
---|---|---|
instanceId |
string |
The ID of the instance to resume |
folderKey |
string |
The folder key for authorization |
options? |
ProcessInstanceOperationOptions |
Optional resume options with comment |
Returns¶
Promise
<OperationResponse
<ProcessInstanceOperationResponse
>>
Promise resolving to operation result with instance data
getVariables()¶
getVariables(
instanceId: string,
folderKey: string,
options?: ProcessInstanceGetVariablesOptions): Promise<ProcessInstanceGetVariablesResponse>;
Get global variables for a process instance
Parameters¶
Parameter | Type | Description |
---|---|---|
instanceId |
string |
The ID of the instance to get variables for |
folderKey |
string |
The folder key for authorization |
options? |
ProcessInstanceGetVariablesOptions |
Optional options including parentElementId to filter by parent element |
Returns¶
Promise
<ProcessInstanceGetVariablesResponse
>
Promise resolving to variables response with elements and globals ProcessInstanceGetVariablesResponse
Example¶
// Get all variables for a process instance
const variables = await sdk.maestro.processes.instances.getVariables(
<instanceId>,
<folderKey>
);
// Access global variables
console.log('Global variables:', variables.globalVariables);
// Iterate through global variables with metadata
variables.globalVariables?.forEach(variable => {
console.log(`Variable: ${variable.name} (${variable.id})`);
console.log(` Type: ${variable.type}`);
console.log(` Element: ${variable.elementId}`);
console.log(` Value: ${variable.value}`);
});
// Get variables for a specific parent element
const variables = await sdk.maestro.processes.instances.getVariables(
<instanceId>,
<folderKey>,
{ parentElementId: <parentElementId> }
);