Skip to content

Commit 3b82f5f

Browse files
OWinfreyATLOWinfreyATL
committed
[Public Preview] Cancel Lifecycle Workflows
1 parent dceab0b commit 3b82f5f

7 files changed

Lines changed: 502 additions & 1 deletion

‎api-reference/beta/api/identitygovernance-workflow-cancelprocessing.md‎

Lines changed: 371 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,371 @@
1+
---
2+
title: "workflow: cancelProcessing"
3+
description: "Cancel workflow runs that are currently in progress or queued."
4+
author: "AlexFilipin"
5+
ms.localizationpriority: medium
6+
ms.subservice: "entra-id-governance"
7+
doc_type: apiPageType
8+
ms.date: 03/26/2026
9+
---
10+
11+
# workflow: cancelProcessing
12+
13+
Namespace: microsoft.graph.identityGovernance
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Cancel one or more [workflow](../resources/identitygovernance-workflow.md) runs that are currently in progress or queued. This action allows administrators to stop processing of workflow runs on demand.
18+
19+
Only runs in `queued` or `inProgress` status can be cancelled. Completed, failed, or already cancelled runs cannot be cancelled. Currently limited to cancelling 1 run per request.
20+
21+
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
22+
23+
## Permissions
24+
25+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
26+
27+
<!-- { "blockType": "permissions", "name": "identitygovernance_workflow_cancelprocessing" } -->
28+
29+
[!INCLUDE [permissions-table](../includes/permissions/identitygovernance-workflow-cancelprocessing-permissions.md)]
30+
31+
[!INCLUDE [rbac-lifecycle-workflows-apis-write](../includes/rbac-for-apis/rbac-lifecycle-workflows-apis-write.md)]
32+
33+
## HTTP request
34+
35+
<!-- {
36+
"blockType": "ignored"
37+
}
38+
-->
39+
```http
40+
POST /identityGovernance/lifecycleWorkflows/workflows/{workflow-id}/cancelProcessing
41+
```
42+
43+
## Request headers
44+
45+
|Name|Description|
46+
|:---|:---|
47+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
48+
|Content-Type|application/json. Required.|
49+
50+
## Request body
51+
52+
In the request body, supply a JSON representation of the parameters.
53+
54+
The following table shows the parameters that are required with this action.
55+
56+
|Parameter|Type|Description|
57+
|:---|:---|:---|
58+
|scope|[microsoft.graph.identityGovernance.cancelScope](../resources/identitygovernance-cancelscope.md)|Defines the scope of workflow runs to cancel. Currently only [cancelRunsScope](../resources/identitygovernance-cancelrunsscope.md) is supported. Required.|
59+
60+
### cancelRunsScope properties
61+
62+
When using [cancelRunsScope](../resources/identitygovernance-cancelrunsscope.md), the `@odata.type` property is required in the request body.
63+
64+
|Property|Type|Description|
65+
|:---|:---|:---|
66+
|@odata.type|String|Must be `#microsoft.graph.identityGovernance.cancelRunsScope`. Required.|
67+
|runs|[microsoft.graph.identityGovernance.run](../resources/identitygovernance-run.md) collection|The workflow runs to cancel. Currently limited to 1 run per request. Required.|
68+
69+
## Response
70+
71+
If successful, this action returns a `204 No Content` response code.
72+
73+
## Examples
74+
75+
### Example 1: Successfully cancel a workflow run
76+
77+
The following example shows a request that successfully cancels a single workflow run.
78+
79+
#### Request
80+
81+
The following example shows a request.
82+
83+
# [HTTP](#tab/http)
84+
<!-- {
85+
"blockType": "request",
86+
"name": "lifecycleworkflows_workflow_cancelprocessing_success"
87+
}
88+
-->
89+
```http
90+
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows/14879e66-9ea9-48d0-804d-8fea672d0341/cancelProcessing
91+
Content-Type: application/json
92+
93+
{
94+
"scope": {
95+
"@odata.type": "#microsoft.graph.identityGovernance.cancelRunsScope",
96+
"runs": [
97+
{
98+
"id": "8cdf25a8-c9d2-423e-a03d-3f39f03c3e97"
99+
}
100+
]
101+
}
102+
}
103+
```
104+
105+
---
106+
107+
#### Response
108+
109+
The following example shows the response.
110+
111+
<!-- {
112+
"blockType": "response",
113+
"truncated": true
114+
} -->
115+
```http
116+
HTTP/1.1 204 No Content
117+
```
118+
119+
### Example 2: Workflow not found
120+
121+
The following example shows a request where the specified workflow doesn't exist.
122+
123+
#### Request
124+
125+
The following example shows a request.
126+
127+
<!-- {
128+
"blockType": "request",
129+
"name": "lifecycleworkflows_workflow_cancelprocessing_workflownotfound"
130+
}
131+
-->
132+
```http
133+
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows/00000000-0000-0000-0000-000000000000/cancelProcessing
134+
Content-Type: application/json
135+
136+
{
137+
"scope": {
138+
"@odata.type": "#microsoft.graph.identityGovernance.cancelRunsScope",
139+
"runs": [
140+
{
141+
"id": "8cdf25a8-c9d2-423e-a03d-3f39f03c3e97"
142+
}
143+
]
144+
}
145+
}
146+
```
147+
148+
#### Response
149+
150+
The following example shows the response.
151+
152+
<!-- {
153+
"blockType": "response",
154+
"truncated": true
155+
} -->
156+
```http
157+
HTTP/1.1 404 Not Found
158+
Content-Type: application/json
159+
160+
{
161+
"error": {
162+
"code": "Resource not found",
163+
"message": "Workflow with id '00000000-0000-0000-0000-000000000000' was not found."
164+
}
165+
}
166+
```
167+
168+
### Example 3: No valid runs provided
169+
170+
The following example shows a request where no valid run IDs are provided. An error is returned when a request contains zero valid runs, either from an empty runs array or only invalid run IDs.
171+
172+
#### Request
173+
174+
The following example shows a request.
175+
176+
<!-- {
177+
"blockType": "request",
178+
"name": "lifecycleworkflows_workflow_cancelprocessing_novalid"
179+
}
180+
-->
181+
```http
182+
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows/14879e66-9ea9-48d0-804d-8fea672d0341/cancelProcessing
183+
Content-Type: application/json
184+
185+
{
186+
"scope": {
187+
"@odata.type": "#microsoft.graph.identityGovernance.cancelRunsScope",
188+
"runs": [
189+
{
190+
"id": "00000000-0000-0000-0000-000000000001"
191+
},
192+
{
193+
"id": "00000000-0000-0000-0000-000000000002"
194+
}
195+
]
196+
}
197+
}
198+
```
199+
200+
#### Response
201+
202+
The following example shows the response.
203+
204+
<!-- {
205+
"blockType": "response",
206+
"truncated": true
207+
} -->
208+
```http
209+
HTTP/1.1 406 Not Acceptable
210+
Content-Type: application/json
211+
212+
{
213+
"error": {
214+
"code": "Not Acceptable Request",
215+
"message": "No valid runs in cancelRunsScope supplied. 2 runs were specified and none were valid."
216+
}
217+
}
218+
```
219+
220+
### Example 4: Run doesn't belong to workflow
221+
222+
The following example shows a request where the provided run doesn't belong to the specified workflow.
223+
224+
#### Request
225+
226+
The following example shows a request.
227+
228+
<!-- {
229+
"blockType": "request",
230+
"name": "lifecycleworkflows_workflow_cancelprocessing_wrongworkflow"
231+
}
232+
-->
233+
```http
234+
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows/14879e66-9ea9-48d0-804d-8fea672d0341/cancelProcessing
235+
Content-Type: application/json
236+
237+
{
238+
"scope": {
239+
"@odata.type": "#microsoft.graph.identityGovernance.cancelRunsScope",
240+
"runs": [
241+
{
242+
"id": "8cdf25a8-c9d2-423e-a03d-3f39f03c3e97"
243+
}
244+
]
245+
}
246+
}
247+
```
248+
249+
#### Response
250+
251+
The following example shows the response.
252+
253+
<!-- {
254+
"blockType": "response",
255+
"truncated": true
256+
} -->
257+
```http
258+
HTTP/1.1 400 Bad Request
259+
Content-Type: application/json
260+
261+
{
262+
"error": {
263+
"code": "Bad Request",
264+
"message": "Run with id '8cdf25a8-c9d2-423e-a03d-3f39f03c3e97' does not belong to workflow '14879e66-9ea9-48d0-804d-8fea672d0341'."
265+
}
266+
}
267+
```
268+
269+
### Example 5: Run not in cancellable state
270+
271+
The following example shows a request where the run isn't in a cancellable state. Only runs with status `queued` or `inProgress` can be cancelled.
272+
273+
#### Request
274+
275+
The following example shows a request.
276+
277+
<!-- {
278+
"blockType": "request",
279+
"name": "lifecycleworkflows_workflow_cancelprocessing_notcancellable"
280+
}
281+
-->
282+
```http
283+
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows/14879e66-9ea9-48d0-804d-8fea672d0341/cancelProcessing
284+
Content-Type: application/json
285+
286+
{
287+
"scope": {
288+
"@odata.type": "#microsoft.graph.identityGovernance.cancelRunsScope",
289+
"runs": [
290+
{
291+
"id": "8cdf25a8-c9d2-423e-a03d-3f39f03c3e97"
292+
}
293+
]
294+
}
295+
}
296+
```
297+
298+
#### Response
299+
300+
The following example shows the response.
301+
302+
<!-- {
303+
"blockType": "response",
304+
"truncated": true
305+
} -->
306+
```http
307+
HTTP/1.1 409 Conflict
308+
Content-Type: application/json
309+
310+
{
311+
"error": {
312+
"code": "Conflict",
313+
"message": "Run with id '8cdf25a8-c9d2-423e-a03d-3f39f03c3e97' is not in a cancellable state. Current status: 'completed'. Must be 'queued' or 'in-progress' to cancel."
314+
}
315+
}
316+
```
317+
318+
### Example 6: Too many runs
319+
320+
The following example shows a request that exceeds the maximum number of runs allowed per request. Currently, only 1 run can be cancelled per request.
321+
322+
#### Request
323+
324+
The following example shows a request.
325+
326+
<!-- {
327+
"blockType": "request",
328+
"name": "lifecycleworkflows_workflow_cancelprocessing_toomany"
329+
}
330+
-->
331+
```http
332+
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows/14879e66-9ea9-48d0-804d-8fea672d0341/cancelProcessing
333+
Content-Type: application/json
334+
335+
{
336+
"scope": {
337+
"@odata.type": "#microsoft.graph.identityGovernance.cancelRunsScope",
338+
"runs": [
339+
{
340+
"id": "8cdf25a8-c9d2-423e-a03d-3f39f03c3e97"
341+
},
342+
{
343+
"id": "2b08131a-8083-450d-9a1f-2aecb406a6f4"
344+
},
345+
{
346+
"id": "e7904bb5-df48-48ee-a0e1-264d5c121355"
347+
}
348+
]
349+
}
350+
}
351+
```
352+
353+
#### Response
354+
355+
The following example shows the response.
356+
357+
<!-- {
358+
"blockType": "response",
359+
"truncated": true
360+
} -->
361+
```http
362+
HTTP/1.1 400 Bad Request
363+
Content-Type: application/json
364+
365+
{
366+
"error": {
367+
"code": "Bad Request",
368+
"message": "Too many runs provided. Received 3, but the maximum allowed in a single cancelProcessing call is 1."
369+
}
370+
}
371+
```

‎api-reference/beta/includes/permissions/identitygovernance-workflow-cancelprocessing-permissions.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: "Automatically generated file. DO NOT MODIFY"
3+
ms.topic: include
4+
ms.localizationpriority: medium
5+
---
6+
7+
|Permission type|Least privileged permissions|Higher privileged permissions|
8+
|:---|:---|:---|
9+
|Delegated (work or school account)|LifecycleWorkflows-Workflow.ReadWrite.All|LifecycleWorkflows.ReadWrite.All|
10+
|Delegated (personal Microsoft account)|Not supported.|Not supported.|
11+
|Application|LifecycleWorkflows-Workflow.ReadWrite.All|LifecycleWorkflows.ReadWrite.All|

0 commit comments

Comments
 (0)