Skip to content

identitygovernance-lifecycleworkflowscontainer-post-workflows.md

Latest commit

 

History

History
493 lines (424 loc) · 18.9 KB

identitygovernance-lifecycleworkflowscontainer-post-workflows.md

File metadata and controls

493 lines (424 loc) · 18.9 KB
title Create workflow
description Create a new workflow object. You can create up to 100 workflows in a tenant.
author KristinaSmith
ms.localizationpriority medium
ms.subservice entra-id-governance
doc_type apiPageType
ms.date 04/18/2024

Create workflow

Namespace: microsoft.graph.identityGovernance

Create a new workflow object. You can create up to 100 workflows in a tenant.

[!INCLUDE national-cloud-support]

Permissions

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. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

[!INCLUDE rbac-lifecycle-workflows-apis-write]

HTTP request

POST /identityGovernance/lifecycleWorkflows/workflows

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, supply a JSON representation of the workflow object.

You can specify the following properties when creating a workflow.

Property Type Description
category microsoft.graph.identityGovernance.lifecycleWorkflowCategory The category of the workflow. The possible values are: joiner, leaver, unknownFutureValue. Can be only one value. Required.
description String A string that describes the purpose of the workflow for administrative use.
displayName String A unique string that identifies the workflow. Required.
executionConditions microsoft.graph.identityGovernance.workflowExecutionConditions Defines for who and when a workflow will run. Required.
id String Identifier used for individually addressing a specific workflow.
isEnabled Boolean A Boolean value that denotes whether the workflow is set to run or not.
isSchedulingEnabled Boolean A Boolean value that denotes whether scheduling is enabled or not.
tasks microsoft.graph.identityGovernance.task collection Represents the configured tasks to execute and their execution sequence within the workflow. Required.

Response

If successful, this method returns a 201 Created response code and a microsoft.graph.identityGovernance.workflow object in the response body.

Examples

Example 1: Create a new workflow

Request

The following example shows a request that creates a workflow with the following configuration:

  • It's a "joiner" workflow that's enabled and schedule to run.
  • It runs for new users that are based in Australia, on their employeeHireDate.
  • Two tasks are carried out when the workflow runs: the user's account is enabled and a "Welcome" email is sent to the user.

HTTP

POST https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows
Content-Type: application/json

{
    "category": "joiner",
    "description": "Configure new hire tasks for onboarding employees on their first day",
    "displayName": "Australia Onboard new hire employee",
    "isEnabled": true,
    "isSchedulingEnabled": true,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
            "rule": "(country eq 'Australia')"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
            "timeBasedAttribute": "employeeHireDate",
            "offsetInDays": 0
        }
    },
    "tasks": [
        {
            "continueOnError": false,
            "description": "Enable user account in the directory",
            "displayName": "Enable User Account",
            "isEnabled": true,
            "taskDefinitionId": "6fc52c9d-398b-4305-9763-15f42c1676fc",
            "arguments": []
        },
        {
            "continueOnError": false,
            "description": "Send welcome email to new hire",
            "displayName": "Send Welcome Email",
            "isEnabled": true,
            "taskDefinitionId": "70b29d51-b59a-4773-9280-8841dfd3f2ea",
            "arguments": []
        }
    ]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows/$entity",
    "category": "joiner",
    "description": "Configure new hire tasks for onboarding employees on their first day",
    "displayName": "New Zealand new hire",
    "lastModifiedDateTime": "2022-08-26T04:51:27.521792Z",
    "createdDateTime": "2022-08-26T04:51:27.5217824Z",
    "deletedDateTime": null,
    "id": "818cd47f-138c-4a83-b3f5-afa92bfcf391",
    "isEnabled": true,
    "isSchedulingEnabled": false,
    "nextScheduleRunDateTime": null,
    "version": 1,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
            "rule": "(country eq 'New Zealand')"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
            "timeBasedAttribute": "employeeHireDate",
            "offsetInDays": 0
        }
    }
}

Example 2: Create a new version of a task with customized email

Request

The following example shows a request.

HTTP

POST https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows
Content-Type: application/json
Content-length: 631

{
    "category": "joiner",
    "description": "Configure new hire tasks for onboarding employees on their first day",
    "displayName": "custom email marketing API test",
    "isEnabled": true,
    "isSchedulingEnabled": false,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
            "rule": "(department eq 'Marketing')"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
            "timeBasedAttribute": "employeeHireDate",
            "offsetInDays": 0
        }
    },
    "tasks": [
        {
            "continueOnError": false,
            "description": "Enable user account in the directory",
            "displayName": "Enable User Account",
            "isEnabled": true,
            "taskDefinitionId": "6fc52c9d-398b-4305-9763-15f42c1676fc",
            "arguments": []
        },
        {
            "continueOnError": false,
            "description": "Send welcome email to new hire",
            "displayName": "Send Welcome Email",
            "isEnabled": true,
            "taskDefinitionId": "70b29d51-b59a-4773-9280-8841dfd3f2ea",
            "arguments": [
                {
                    "name": "cc",
                    "value": "1baa57fa-3c4e-4526-ba5a-db47a9df95f0"
                },
                {
                    "name": "customSubject",
                    "value": "Welcome to the organization {{userDisplayName}}!"
                },
                {
                    "name": "customBody",
                    "value": "Welcome to our organization {{userGivenName}}!"
                },
                {
                    "name": "locale",
                    "value": "en-us"
                }
            ]
        }
    ]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "workflow":{
        "category": "joiner",
        "description": "Configure new hire tasks for onboarding employees on their first day",
        "displayName": "Global onboard new hire employee",
        "isEnabled": true,
        "isSchedulingEnabled": false,
        "executionConditions": {
            "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
            "scope": {
                "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
                "rule": "(department eq 'Marketing')"
            },
            "trigger": {
                "@odata.type": "#microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
                "timeBasedAttribute": "employeeHireDate",
                "offsetInDays": 1
            }
        },
        "tasks": [
            {
                "continueOnError": false,
                "description": "Enable user account in the directory",
                "displayName": "Enable User Account",
                "isEnabled": true,
                "taskDefinitionId": "6fc52c9d-398b-4305-9763-15f42c1676fc",
                "arguments": []
            },
            {
                "continueOnError": false,
                "description": "Send welcome email to new hire",
                "displayName": "Send Welcome Email",
                "isEnabled": true,
                "taskDefinitionId": "70b29d51-b59a-4773-9280-8841dfd3f2ea",
                "arguments": [
                    {
                    "name": "cc",
                    "value": "b47471b9-af8f-4a5a-bfa2-b78e82398f6e, a7a23ce0-909b-40b9-82cf-95d31f0aaca2"
                },
                {
                "name": "customSubject",
                "value": "Welcome to the organization {{userDisplayName}}!"
                },
                {
                "name": "customBody",
                "value": "Welcome to our organization {{userGivenName}} {{userSurname}}. \nFor more information, reach out to your manager {{managerDisplayName}} at {{managerEmail}}."
                },
                {
                "name": "locale",
                "value": "en-us"
                }, 
    ]
            }
        ]
    }
}

Example 3: Create a mover workflow with a set target scope

Request

The following example shows a request that creates a workflow with the following configuration:

  • It's a "mover" workflow-enabled and set to run on-demand only.
  • It runs for users within the set target scope of the administrative units "4f9dc456-0574-4122-9e55-8b4cc494b27d" and "2c987843-e9b1-4b1a-b924-ff1d2a9b054d".
  • One task is carried out, which is to send an email to notify the user's manager of the move.

HTTP

POST https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows
Content-Type: application/json

{
  "category": "mover",
  "displayName": "On Demand workflow move",
  "description": "Execute real-time tasks for employee job changes",
  "tasks": [
    {
      "arguments": [],
      "description": "Send email to notify user's manager of user move",
      "displayName": "Send email to notify manager of user move",
      "isEnabled": true,
      "continueOnError": false,
      "taskDefinitionId": "aab41899-9972-422a-9d97-f626014578b7",
      "category": "mover"
    }
  ],
  "executionConditions": {
    "@odata.type": "#microsoft.graph.identityGovernance.onDemandExecutionOnly"
  },
  "isEnabled": true,
  "isSchedulingEnabled": false,
  "administrationScopeTargets": [
    {
      "@odata.type": "#microsoft.graph.administrativeUnit",
      "id": "4f9dc456-0574-4122-9e55-8b4cc494b27d"
    },
    {
      "@odata.type": "#microsoft.graph.administrativeUnit",
      "id": "2c987843-e9b1-4b1a-b924-ff1d2a9b054d"
    }
  ]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows/$entity",
  "category": "mover",
  "description": "Execute real-time tasks for employee job changes",
  "displayName": "On Demand workflow move",
  "isEnabled": true,
  "isSchedulingEnabled": false,
  "lastModifiedDateTime": "2025-01-09T15:28:24.0565594Z",
  "createdDateTime": "2025-01-09T15:28:24.0565526Z",
  "id": "465d0d08-3099-483f-9d93-16aad77bcd22",
  "version": 1,
  "administrationScopeTargets": [
    {
      "@odata.type": "#microsoft.graph.administrativeUnit",
      "id": "4f9dc456-0574-4122-9e55-8b4cc494b27d"
    },
    {
      "@odata.type": "#microsoft.graph.administrativeUnit",
      "id": "2c987843-e9b1-4b1a-b924-ff1d2a9b054d"
    }
  ]
}