Update to powershell SDK docs: 13122455471

This commit is contained in:
developer-relations-sp
2025-02-03 20:42:04 +00:00
parent aeda961e54
commit bdb088c15d
207 changed files with 3520 additions and 8694 deletions

View File

@@ -1,3 +1,4 @@
---
id: workflows
title: Workflows
@@ -9,7 +10,6 @@ slug: /tools/sdk/powershell/v3/methods/workflows
tags: ['SDK', 'Software Development Kit', 'Workflows', 'Workflows']
---
# Workflows
Workflows allow administrators to create custom automation scripts directly within Identity Security Cloud. These automation scripts respond to [event triggers](https://developer.sailpoint.com/docs/extensibility/event-triggers/#how-to-get-started-with-event-triggers) and perform a series of actions to perform tasks that are either too cumbersome or not available in the Identity Security Cloud UI. Workflows can be configured via a graphical user interface within Identity Security Cloud, or by creating and uploading a JSON formatted script to the Workflow service. The Workflows API collection provides the necessary functionality to create, manage, and test your workflows via REST.
@@ -38,9 +38,7 @@ Method | HTTP request | Description
[**Test-ExternalExecuteWorkflow**](#test-external-execute-workflow) | **POST** `/workflows/execute/external/{id}/test` | Test Workflow via External Trigger
[**Test-Workflow**](#test-workflow) | **POST** `/workflows/{id}/test` | Test Workflow By Id
## cancel-workflow-execution
Use this API to cancel a running workflow execution.
### Parameters
@@ -49,7 +47,6 @@ Param Type | Name | Data Type | Required | Description
Path | Id | **String** | True | The workflow execution ID
### Return type
(empty response body)
### Responses
@@ -64,14 +61,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | The workflow execution ID
# Cancel Workflow Execution by ID
try {
Suspend-WorkflowExecution-Id $Id
@@ -82,11 +80,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## create-external-execute-workflow
This endpoint allows a service outside of IdentityNow to initiate a workflow that uses the "External Trigger" step. The external service will invoke this endpoint with the input data it wants to send to the workflow in the body.
### Parameters
@@ -96,7 +91,6 @@ Path | Id | **String** | True | Id of the workflow
Body | CreateExternalExecuteWorkflowRequest | [**CreateExternalExecuteWorkflowRequest**](../models/create-external-execute-workflow-request) | (optional) |
### Return type
[**CreateExternalExecuteWorkflow200Response**](../models/create-external-execute-workflow200-response)
### Responses
@@ -110,7 +104,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json
@@ -118,7 +111,9 @@ Code | Description | Data Type
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the workflow
$CreateExternalExecuteWorkflowRequest = @""@
# Execute Workflow via External Trigger
try {
New-ExternalExecuteWorkflow-Id $Id
@@ -129,11 +124,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## create-workflow
Create a new workflow with the desired trigger and steps specified in the request body.
### Parameters
@@ -142,7 +134,6 @@ Param Type | Name | Data Type | Required | Description
Body | CreateWorkflowRequest | [**CreateWorkflowRequest**](../models/create-workflow-request) | True |
### Return type
[**Workflow**](../models/workflow)
### Responses
@@ -156,14 +147,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json
### Example
```powershell
$CreateWorkflowRequest = @"{name=Send Email, owner={type=IDENTITY, id=2c91808568c529c60168cca6f90c1313, name=William Wilson}, description=Send an email to the identity who's attributes changed., definition={start=Send Email Test, steps={Send Email={actionId=sp:send-email, attributes={body=This is a test, from=sailpoint@sailpoint.com, recipientId.$=$.identity.id, subject=test}, nextStep=success, selectResult=null, type=action}, success={type=success}}}, enabled=false, trigger={type=EVENT, attributes={id=idn:identity-attributes-changed, filter=$.changes[?(@.attribute == 'manager')]}}}"@
# Create Workflow
try {
$Result = ConvertFrom-JsonToCreateWorkflowRequest -Json $CreateWorkflowRequest
New-Workflow-CreateWorkflowRequest $Result
@@ -175,11 +167,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## create-workflow-external-trigger
Create OAuth client ID, client secret, and callback URL for use in an external trigger. External triggers will need this information to generate an access token to authenticate to the callback URL and submit a trigger payload that will initiate the workflow.
### Parameters
@@ -188,7 +177,6 @@ Param Type | Name | Data Type | Required | Description
Path | Id | **String** | True | Id of the workflow
### Return type
[**WorkflowOAuthClient**](../models/workflow-o-auth-client)
### Responses
@@ -202,14 +190,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the workflow
# Generate External Trigger OAuth Client
try {
New-WorkflowExternalTrigger-Id $Id
@@ -220,11 +209,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## delete-workflow
Delete a workflow. **Enabled workflows cannot be deleted**. They must first be disabled.
### Parameters
@@ -233,7 +219,6 @@ Param Type | Name | Data Type | Required | Description
Path | Id | **String** | True | Id of the Workflow
### Return type
(empty response body)
### Responses
@@ -247,14 +232,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the Workflow
# Delete Workflow By Id
try {
Remove-Workflow-Id $Id
@@ -265,11 +251,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## get-workflow
Get a single workflow by id.
### Parameters
@@ -278,7 +261,6 @@ Param Type | Name | Data Type | Required | Description
Path | Id | **String** | True | Id of the workflow
### Return type
[**Workflow**](../models/workflow)
### Responses
@@ -292,14 +274,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the workflow
# Get Workflow By Id
try {
Get-Workflow-Id $Id
@@ -310,11 +293,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## get-workflow-execution
Use this API to get a single workflow execution. Workflow executions are available for up to 90 days before being archived. If you attempt to access a workflow execution that has been archived, you will receive a "404 Not Found" response.
### Parameters
@@ -323,7 +303,6 @@ Param Type | Name | Data Type | Required | Description
Path | Id | **String** | True | Workflow execution ID.
### Return type
[**SystemCollectionsHashtable**](https://learn.microsoft.com/en-us/dotnet/api/system.collections.hashtable?view=net-9.0)
### Responses
@@ -338,14 +317,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Workflow execution ID.
# Get Workflow Execution
try {
Get-WorkflowExecution-Id $Id
@@ -356,11 +336,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## get-workflow-execution-history
Get a detailed history of a single workflow execution. Workflow executions are available for up to 90 days before being archived. If you attempt to access a workflow execution that has been archived, you will receive a 404 Not Found.
### Parameters
@@ -369,7 +346,6 @@ Param Type | Name | Data Type | Required | Description
Path | Id | **String** | True | Id of the workflow execution
### Return type
[**WorkflowExecutionEvent[]**](../models/workflow-execution-event)
### Responses
@@ -384,14 +360,15 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the workflow execution
# Get Workflow Execution History
try {
Get-WorkflowExecutionHistory-Id $Id
@@ -402,11 +379,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## get-workflow-executions
Use this API to list a specified workflow's executions. Workflow executions are available for up to 90 days before being archived. By default, you can get a maximum of 250 executions. To get executions past the first 250 records, you can do the following:
1. Use the [Get Workflows](https://developer.sailpoint.com/idn/api/beta/list-workflows) endpoint to get your workflows.
2. Get your workflow ID from the response.
@@ -429,7 +403,6 @@ Path | Id | **String** | True | Workflow ID.
Query | Filters | **String** | (optional) | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **start_time**: *eq, lt, le, gt, ge* **status**: *eq*
### Return type
[**WorkflowExecution[]**](../models/workflow-execution)
### Responses
@@ -444,7 +417,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
@@ -455,7 +427,9 @@ $Limit = 250 # Int32 | Max number of results to return. See [V3 API Standard Col
$Offset = 0 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 0)
$Count = $true # Boolean | If *true* it will populate the *X-Total-Count* response header with the number of results that would be returned if *limit* and *offset* were ignored. Since requesting a total count can have a performance impact, it is recommended not to send **count=true** if that value will not be used. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to $false)
$Filters = 'status eq "Failed"' # String | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **start_time**: *eq, lt, le, gt, ge* **status**: *eq* (optional)
# List Workflow Executions
try {
Get-WorkflowExecutions-Id $Id
@@ -466,11 +440,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## list-complete-workflow-library
This lists all triggers, actions, and operators in the library
### Parameters
@@ -480,7 +451,6 @@ Param Type | Name | Data Type | Required | Description
Query | Offset | **Int32** | (optional) (default to 0) | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information.
### Return type
[**ListCompleteWorkflowLibrary200ResponseInner[]**](../models/list-complete-workflow-library200-response-inner)
### Responses
@@ -494,7 +464,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
@@ -502,7 +471,9 @@ Code | Description | Data Type
```powershell
$Limit = 250 # Int32 | Max number of results to return. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 250)
$Offset = 0 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 0)
# List Complete Workflow Library
try {
Get-CompleteWorkflowLibrary
@@ -513,11 +484,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## list-workflow-library-actions
This lists the workflow actions available to you.
### Parameters
@@ -528,7 +496,6 @@ Param Type | Name | Data Type | Required | Description
Query | Filters | **String** | (optional) | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **id**: *eq*
### Return type
[**WorkflowLibraryAction[]**](../models/workflow-library-action)
### Responses
@@ -542,7 +509,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
@@ -551,7 +517,9 @@ Code | Description | Data Type
$Limit = 250 # Int32 | Max number of results to return. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 250)
$Offset = 0 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 0)
$Filters = 'id eq "sp:create-campaign"' # String | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **id**: *eq* (optional)
# List Workflow Library Actions
try {
Get-WorkflowLibraryActions
@@ -562,11 +530,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## list-workflow-library-operators
This lists the workflow operators available to you
### Parameters
@@ -574,7 +539,6 @@ Param Type | Name | Data Type | Required | Description
------------- | ------------- | ------------- | ------------- | -------------
### Return type
[**WorkflowLibraryOperator[]**](../models/workflow-library-operator)
### Responses
@@ -588,13 +552,14 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
# List Workflow Library Operators
try {
Get-WorkflowLibraryOperators
@@ -605,11 +570,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## list-workflow-library-triggers
This lists the workflow triggers available to you
### Parameters
@@ -620,7 +582,6 @@ Param Type | Name | Data Type | Required | Description
Query | Filters | **String** | (optional) | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **id**: *eq*
### Return type
[**WorkflowLibraryTrigger[]**](../models/workflow-library-trigger)
### Responses
@@ -634,7 +595,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
@@ -643,7 +603,9 @@ Code | Description | Data Type
$Limit = 250 # Int32 | Max number of results to return. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 250)
$Offset = 0 # Int32 | Offset into the full result set. Usually specified with *limit* to paginate through the results. See [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters) for more information. (optional) (default to 0)
$Filters = 'id eq "idn:identity-attributes-changed"' # String | Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) Filtering is supported for the following fields and operators: **id**: *eq* (optional)
# List Workflow Library Triggers
try {
Get-WorkflowLibraryTriggers
@@ -654,11 +616,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## list-workflows
List all workflows in the tenant.
### Parameters
@@ -666,7 +625,6 @@ Param Type | Name | Data Type | Required | Description
------------- | ------------- | ------------- | ------------- | -------------
### Return type
[**Workflow[]**](../models/workflow)
### Responses
@@ -680,13 +638,14 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json
### Example
```powershell
# List Workflows
try {
Get-Workflows
@@ -697,11 +656,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## patch-workflow
Partially update an existing Workflow using [JSON Patch](https://tools.ietf.org/html/rfc6902) syntax.
### Parameters
@@ -711,7 +667,6 @@ Path | Id | **String** | True | Id of the Workflow
Body | JsonPatchOperation | [**[]JsonPatchOperation**](../models/json-patch-operation) | True |
### Return type
[**Workflow**](../models/workflow)
### Responses
@@ -725,21 +680,21 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: application/json-patch+json
- **Accept**: application/json
### Example
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the Workflow
# JsonPatchOperation[] |
$JsonPatchOperation = @"{
"op" : "replace",
"path" : "/description",
"value" : "New description"
}"@
}"@ # JsonPatchOperation[] |
# Patch Workflow
try {
$Result = ConvertFrom-JsonToJsonPatchOperation -Json $JsonPatchOperation
Update-Workflow-Id $Id -JsonPatchOperation $Result
@@ -751,11 +706,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## put-workflow
Perform a full update of a workflow. The updated workflow object is returned in the response.
### Parameters
@@ -765,7 +717,6 @@ Path | Id | **String** | True | Id of the Workflow
Body | WorkflowBody | [**WorkflowBody**](../models/workflow-body) | True |
### Return type
[**Workflow**](../models/workflow)
### Responses
@@ -779,7 +730,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json
@@ -825,7 +775,9 @@ $WorkflowBody = @"{
},
"enabled" : false
}"@
# Update Workflow
try {
$Result = ConvertFrom-JsonToWorkflowBody -Json $WorkflowBody
Send-Workflow-Id $Id -WorkflowBody $Result
@@ -837,11 +789,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## test-external-execute-workflow
Validate a workflow with an "External Trigger" can receive input. The response includes the input that the workflow received, which can be used to validate that the input is intact when it reaches the workflow.
### Parameters
@@ -851,7 +800,6 @@ Path | Id | **String** | True | Id of the workflow
Body | TestExternalExecuteWorkflowRequest | [**TestExternalExecuteWorkflowRequest**](../models/test-external-execute-workflow-request) | (optional) |
### Return type
[**TestExternalExecuteWorkflow200Response**](../models/test-external-execute-workflow200-response)
### Responses
@@ -865,7 +813,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json
@@ -873,7 +820,9 @@ Code | Description | Data Type
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the workflow
$TestExternalExecuteWorkflowRequest = @""@
# Test Workflow via External Trigger
try {
Test-ExternalExecuteWorkflow-Id $Id
@@ -884,11 +833,8 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)
## test-workflow
Test a workflow with the provided input data. The input data should resemble the input that the trigger will send the workflow. See the [event trigger documentation](https://developer.sailpoint.com/idn/docs/event-triggers/available) for an example input for the trigger that initiates this workflow.
This endpoint will return an execution ID, which can be used to lookup more information about the execution using the `Get a Workflow Execution` endpoint.
**This will cause a live run of the workflow, which could result in unintended modifications to your IDN tenant.**
@@ -900,7 +846,6 @@ Path | Id | **String** | True | Id of the workflow
Body | TestWorkflowRequest | [**TestWorkflowRequest**](../models/test-workflow-request) | True |
### Return type
[**TestWorkflow200Response**](../models/test-workflow200-response)
### Responses
@@ -914,7 +859,6 @@ Code | Description | Data Type
500 | Internal Server Error - Returned if there is an unexpected error. | ErrorResponseDto
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json
@@ -922,7 +866,9 @@ Code | Description | Data Type
```powershell
$Id = "c17bea3a-574d-453c-9e04-4365fbf5af0b" # String | Id of the workflow
$TestWorkflowRequest = @"{input={identity={id=ee769173319b41d19ccec6cea52f237b, name=john.doe, type=IDENTITY}, changes=[{attribute=department, oldValue=sales, newValue=marketing}, {attribute=manager, oldValue={id=ee769173319b41d19ccec6c235423237b, name=nice.guy, type=IDENTITY}, newValue={id=ee769173319b41d19ccec6c235423236c, name=mean.guy, type=IDENTITY}}, {attribute=email, oldValue=john.doe@hotmail.com, newValue=john.doe@gmail.com}]}}"@
# Test Workflow By Id
try {
$Result = ConvertFrom-JsonToTestWorkflowRequest -Json $TestWorkflowRequest
Test-Workflow-Id $Id -TestWorkflowRequest $Result
@@ -934,7 +880,4 @@ try {
Write-Host $_.ErrorDetails
}
```
[[Back to top]](#)