Skip to content

identitygovernance-lifecycleworkflowscontainer-post-workflows.md

Latest commit

 

History

History
584 lines (498 loc) · 22.4 KB

identitygovernance-lifecycleworkflowscontainer-post-workflows.md

File metadata and controls

584 lines (498 loc) · 22.4 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/17/2024

Create workflow

Namespace: microsoft.graph.identityGovernance

[!INCLUDE beta-disclaimer]

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. 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.

HTTP

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": []
        }
    ]
}

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/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.

HTTP

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": []
        }
    ]
}

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

{
    "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.

HTTP

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": []
        }
    ]
}

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/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"
        }
    }
}

Example 4: 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/beta/identityGovernance/lifecycleWorkflows/workflows

{
  "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/beta/$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"
    }
  ]
}