Edit

Share via

Create workflow

  • Article

Namespace: microsoft.graph.identityGovernance

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

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

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ✅ ✅ ❌

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.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) LifecycleWorkflows.CreateWorkflows LifecycleWorkflows.ReadWrite.All, LifecycleWorkflows.ReadWrite.Workflows
Delegated (personal Microsoft account) Not supported. Not supported.
Application LifecycleWorkflows.CreateWorkflows LifecycleWorkflows.ReadWrite.All, LifecycleWorkflows.ReadWrite.Workflows

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. Lifecycle Workflows Administrator is the least privileged role supported for this operation.

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. It 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 runs. 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 joiner workflow using the time based trigger

Request

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

  • It's a "joiner" workflow-enabled and scheduled to run.
  • It runs for new users based in Australia, on their employeeHireDate using the time-based attribute trigger.
  • Two tasks are carried out when the workflow runs: the user's account is enabled and a "Welcome" email is sent to the user.
POST https://graph.microsoft.com/beta/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": []
        }
    ]
}

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/beta/$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 mover workflow using the attribute changes trigger

Request

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

  • It's a "mover" workflow-enabled and scheduled to run.
  • It runs for existing users added to the "Sales" department using the attribute changes trigger.
  • One task is carried out, which is to send an email to notify the user's manager of the move.
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows
Content-Type: application/json
Content-length: 631

{
    "category": "mover",
    "description": "Configure mover tasks for a user when their job profile changes",
    "displayName": "Sales contractor moves to full-time employee",
    "isEnabled": true,
    "isSchedulingEnabled": true,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
            "rule": "(department eq 'Sales')"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.attributeChangeTrigger",
            "triggerAttributes": [
                {
                    "name": "department"
                }
            ]
        }
    },
    "tasks": [
        {
            "continueOnError": false,
            "description": "Send email to moving employee's manager",
            "displayName": "Notify manager of move",
            "isEnabled": true,
            "taskDefinitionId": "aab41899-9972-422a-9d97-f626014578b7",
            "arguments": []
        }
    ]
}

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

{
    "category": "mover",
    "description": "Configure mover tasks for a user when their job profile changes",
    "displayName": "Sales contractor moves to full time employee",
    "isEnabled": true,
    "isSchedulingEnabled": true,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
            "rule": "(department eq 'Sales')"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.attributeChangeTrigger",
            "triggerAttributes": [
                {
                    "name": "department"
                }
            ]
        }
    },
    "tasks": [
        {
            "continueOnError": false,
            "description": "Send email to moving employee's manager",
            "displayName": "Notify manager of move",
            "isEnabled": true,
            "taskDefinitionId": "aab41899-9972-422a-9d97-f626014578b7",
            "arguments": []
        }
    ]
}

Example 3: Create a leaver workflow using the group based trigger

Request

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

  • It's a "leaver" workflow enabled and scheduled to run.
  • It runs for users who are removed from the Sales group using the group-based trigger.
  • Two tasks are carried out when the workflow runs: Remove user from all Teams, Remove user from all groups.
POST https://graph.microsoft.com/beta/identityGovernance/lifecycleWorkflows/workflows
Content-Type: application/json

{
    "category": "leaver",
    "description": "Configure offboarding tasks for employees on their last day of work",
    "displayName": "Offboard an employee",
    "isEnabled": true,
    "isSchedulingEnabled": true,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.groupBasedSubjectSet",
            "groups": [
                {
                    "id": "668e7540-7f8e-4ca4-a207-b7dffbb6d038"
                }
            ]
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.membershipChangeTrigger",
            "changeType": "remove"
        }
    },
    "tasks": [
        {
            "category": "leaver",
            "continueOnError": false,
            "description": "Remove user from all Teams memberships",
            "displayName": "Remove user from all Teams",
            "isEnabled": true,
            "taskDefinitionId": "81f7b200-2816-4b3b-8c5d-dc556f07b024",
            "arguments": []
        },
        {
            "category": "leaver",
            "continueOnError": false,
            "description": "Remove user from all Azure AD groups memberships",
            "displayName": "Remove user from all groups",
            "isEnabled": true,
            "taskDefinitionId": "b3a31406-2a15-4c9a-b25b-a658fa5f07fc",
            "arguments": []
        }
    ]
}

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/beta/$metadata#identityGovernance/lifecycleWorkflows/workflows/$entity",
    "category": "leaver",
    "description": "Configure offboarding tasks for employees on their last day of work",
    "displayName": "Offboard an employee",
    "isEnabled": true,
    "isSchedulingEnabled": true,
    "lastModifiedDateTime": "2024-03-28T20:20:05.6599449Z",
    "createdDateTime": "2024-03-28T20:20:05.6599142Z",
    "deletedDateTime": null,
    "id": "73ed8912-6a04-4f5d-bef8-61fcc94336a7",
    "nextScheduleRunDateTime": "2024-03-28T20:37:08Z",
    "version": 1,
    "executionConditions": {
        "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "#microsoft.graph.identityGovernance.groupBasedSubjectSet"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.membershipChangeTrigger",
            "changeType": "remove"
        }
    }
}