Overview of Lifecycle Workflows APIs

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.

Lifecycle Workflows is an Identity Governance service in Azure Active Directory (Azure AD) that enables organizations to automate basic lifecycle processes for their users at three levels:

  1. Joiner: When an individual comes into scope of needing access; for example, a new employee joining a company or organization.
  2. Mover: When an individual moves between boundaries within an organization; for example, a user who was in marketing is now a member of the sales organization. This movement might require more access or authorization, or revocation of other privileges.
  3. Leaver: When an individual leaves the scope of needing access, access might need to be revoked, and the user deprovisioned. For example, an employee who is retiring or has been terminated.

For this reason, Lifecycle Workflows can be referred to as the Joiner-Mover-Leaver (JML) workflow. Only the joiner and leaver processes are currently implemented.

The lifecycle workflows APIs in Microsoft Graph allow you to automate the Lifecycle Workflows capabilities for your organization. This article introduced the set of APIs that enable the Lifecycle Workflows service in Azure AD.

The lifecycle workflows APIs are defined in the OData subnamespace, microsoft.graph.identityGovernance.

Note

This article describes how to export personal data from a device or service. These steps can be used to support your obligations under the General Data Protection Regulation (GDPR). Authorized tenant admins can use Microsoft Graph to correct, update, or delete identifiable information about end users, including customer and employee user profiles or personal data, such as a user's name, work title, address, or phone number, in your Azure Active Directory (Azure AD) environment.

Workflows

Workflows are containers for the processes involved in managing the life cycle of users in the organization. At their core are tasks and execution conditions.

  • Tasks are specific actions that run automatically when a workflow is triggered.
  • Execution conditions define the scope of "who" and the trigger of "when" a workflow will run.

To create workflows, we recommend using one of the predefined workflow templates.

Workflow templates

Azure AD provides the following six predefined workflow templates that define the templates for combinations of tasks and execution conditions that can be part of a workflow. You can use the workflow templates to create your workflows programmatically.

Workflow template type Lifecycle category
Onboard pre-hire employee Joiner
Onboard new hire employee Joiner
Real-time employee termination Leaver
Pre-Offboarding of an employee Leaver
Offboard an employee Leaver
Post-Offboarding of an employee Leaver

Use the workflowTemplate resource type and its associated methods to identify the preconfigured templates, and the tasks and execution conditions that they support, and copy and use the templates to create your workflows programmatically.

General workflow information

Each workflow contains general descriptive information such as it's identifier, name, description, and whether it is enabled to run as scheduled or on-demand.

Workflow tasks

Workflow tasks are specific actions that run automatically when a workflow is triggered. Lifecycle Workflows defines the following preconfigured and read-only tasks that are allowed for the specified workflow categories. These task definitions show the settings for the task type, guiding you as you create tasks for your workflow.

Lifecycle Workflows currently support the following tasks:

Task taskdefinitionID Category
Send welcome email to new hire 70b29d51-b59a-4773-9280-8841dfd3f2ea Joiner
Send onboarding reminder email 3C860712-2D37-42A4-928F-5C93935D26A1 Joiner
Generate Temporary Access Pass and send via email to user's manager 1b555e50-7f65-41d5-b514-5894a026d10d Joiner
Add user to groups 22085229-5809-45e8-97fd-270d28d66910 Joiner, Leaver
Add user to teams e440ed8d-25a1-4618-84ce-091ed5be5594 Joiner, Leaver
Enable user account 6fc52c9d-398b-4305-9763-15f42c1676fc Joiner, Leaver
Run a custom task extension 4262b724-8dba-4fad-afc3-43fcbb497a0e Joiner, Leaver
Disable user account 1dfdfcc7-52fa-4c2e-bf3a-e3919cc12950 Leaver
Remove user from selected group 1953a66c-751c-45e5-8bfe-01462c70da3c Leaver
Remove users from all groups b3a31406-2a15-4c9a-b25b-a658fa5f07fc Leaver
Remove user from teams 06aa7acb-01af-4824-8899-b14e5ed788d6 Leaver
Remove user from all teams 81f7b200-2816-4b3b-8c5d-dc556f07b024 Leaver
Remove all license assignments from user 8fa97d28-3e52-4985-b3a9-a1126f9b8b4e Leaver
Delete user 8d18588d-9ad3-4c0f-99d0-ec215f0e3dff Leaver
Send email to manager before user last day 52853a3e-f4e5-4eb8-bb24-1ac09a1da935 Leaver
Send email on users last day 9c0a1eaf-5bda-4392-9d9e-6e155bb57411 Leaver
Send offboarding email to users manager after their last day 6f22ddd4-b3a5-47a4-a846-0d7c201a49ce Leaver

Use the taskDefinition resource type and its associated methods to discover all the predefined tasks that you can configure for your workflow and the settings for the properties The task resource type and its associated GET methods allow you to view the tasks that are configured for your workflow.

Execution conditions

For every workflow task, there's an execution condition that defines the scope of "who" and the trigger of "when" a workflow and it's associated tasks will run. For example, an execution condition can specify that a workflow runs for exiting employees, seven days before their employment end date, if they are in the R&D department. The associated task in the workflow can specify that the user is removed from the R&D teams and groups.

⁄⁄Sample snippet for the executionConditions object

"executionConditions": {
    "@odata.type": "#microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
    "scope": {
        "@odata.type": "#microsoft.graph.identityGovernance.ruleBasedSubjectSet",
        "rule": "department eq 'R&D'"
    },
    "trigger": {
        "@odata.type": "#microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
        "timeBasedAttribute": "employeeLeaveDateTime",
        "offsetInDays": -7
    }
}

When creating or updating a workflow, use the workflowExecutionConditions resource type to configure the execution conditions. Use this object to also configure a workflow that runs on-demand only.

Create and manage workflows

After identifying the tasks and execution conditions that you want to define for your workflow, use the workflow resource type, and its associated methods to create and manage the workflow. You can create up to 50 workflows in a tenant. The category of the task must match the category of the workflow. Each workflow can have up to 25 tasks. Therefore:

  • A task supported for only the "leaver" workflow category can't be specified in a "joiner" workflow scenario, and vice versa.
  • A task supported for both "leaver" and "joiner" workflow categories can be specified in either a "joiner" or "leaver" workflow scenario.

You can schedule a workflow to run based on the tenant-wide schedule or run it on-demand. The tenant schedule can take care of regular new hires and terminations, while you can run a workflow on-demand to immediately terminate an employee's access in case of a sensitive event.

The following JSON object shows an example workflow with the following settings:

  • The workflow is enabled and scheduled to run.
  • It is a "leaver" workflow that specifies the following tasks and execution conditions:
    • Execution conditions: Run the workflow for users in the R&D department, seven days before their employeeLeaveDateTime.
    • Tasks: Remove the user from one group and one team.

Workflow versions

While a workflow is in use, you may need to update execution conditions and tasks for a workflow. However, Lifecycle Workflows doesn't allow you to update these properties for an existing workflow.

Instead of creating new workflows, use the workflowVersion resource type and it's associated methods to create and manage a new workflow version, based off an existing workflow object. The workflow version can have similar or a different set of tasks and execution conditions.

Reports

Lifecycle Workflows supports extensive reporting capabilities to track the status of workflow processing at the workflow run-level, task-level, and user-level.

For more information about the reporting capabilities for Lifecycle Workflows, see the overview of Lifecycle Workflows reporting APIs

Extensions

Sometimes, the built-in tasks may not be adequate to fulfill all your business scenarios. To extend your lifecycle management scenarios, Lifecycle Workflows supports defining custom tasks to integrate with external systems via Azure Logic Apps. For example, for a "leaver" scenario, you may also want to grant the user's manager access to the user's email account.

Use the customTaskExtension resource type and its associated methods to define the settings for your Azure Logic App.

Settings

Each tenant defines a tenant-wide schedule when all scheduled workflows are run. The tenant can adopt the Azure AD-defined default schedule where workflows are run every three hours, or modify the schedule to run between 1 hour and 24 hours.

License checks

The Lifecycle Workflows feature, including the API, is included in the Azure AD Premium P2 license. The tenant where Lifecycle Workflows are being created must have a valid purchased, or trial, Azure AD Premium P2 or EMS E5 subscription. For more information about the license requirements, see Lifecycle Workflows license requirements.

Role and application permission authorization checks

The following Azure AD roles are required for a calling user to manage Lifecycle Workflows.

Operation Application permissions Required directory role of the calling user
Read LifecycleWorkflows.Read.All or LifecycleWorkflows.ReadWrite.All Global Admin, Global Reader or Lifecycle Workflows Administrator
Create, Update or Delete LifecycleWorkflows.ReadWrite.All Global Administrator or Lifecycle Workflows Administrator

See also