Edit

Share via

Automate employee offboarding tasks after their last day of work using Lifecycle Workflows APIs

  • Article

This tutorial provides step-by-step guidance for configuring offboarding tasks for employees after their last day of work using Lifecycle Workflows APIs. In this scenario, the employee termination is scheduled, possibly including a notice period. See Complete employee offboarding tasks in real-time on their last day of work using Lifecycle Workflows APIs for an unscheduled, real-time termination scenario.

In this tutorial, you learn how to:

  • Configure a lifecycle workflow to check for employees in a specific department, days after their last day of work.
  • Configure a task to run the following tasks in sequence:
    • Remove all licenses for user
    • Remove user from all Teams
    • Delete user account
  • Monitor the status of the workflow and its associated tasks.

Prerequisites

To complete this tutorial, you need the following resources and privileges:

  • This feature requires Microsoft Entra ID Governance licenses. To find the right license for your requirements, see Microsoft Entra ID Governance licensing fundamentals.
  • Sign in to an API client such as Graph Explorer to call Microsoft Graph with an account that has at least the Lifecycle Administrator Microsoft Entra role.
  • Grant yourself the LifecycleWorkflows.ReadWrite.All Microsoft Graph delegated permission.
  • Create a test user account to represent an employee leaving your organization. This test user account is deleted when the workflow runs. Assign licenses and Teams memberships to the test user account.

Create a "leaver" workflow

Request

The following request creates an offboarding workflow with these settings:

  • It can run on-demand but not on schedule. This step lets us validate the workflow using the test user's account. The workflow is updated to run on schedule later in this tutorial.
  • The workflow runs seven days after the employee's employeeLeaveDateTime if the employee is in the "Marketing" department.
  • Three workflow tasks run in sequence: the user is unassigned all licenses, removed from all teams, and then their user account is deleted.
POST https://graph.microsoft.com/v1.0/identityGovernance/LifecycleWorkflows/workflows
Content-type: application/json

{
    "category": "leaver",
    "displayName": "Post-Offboarding of an employee",
    "description": "Configure offboarding tasks for employees after their last day of work",
    "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": "employeeLeaveDateTime",
            "offsetInDays": 7
        }
    },
    "tasks": [
        {
            "category": "leaver",
            "continueOnError": false,
            "description": "Remove all licenses assigned to the user",
            "displayName": "Remove all licenses for user",
            "executionSequence": 1,
            "isEnabled": true,
            "taskDefinitionId": "8fa97d28-3e52-4985-b3a9-a1126f9b8b4e",
            "arguments": []
        },
        {
            "category": "leaver",
            "continueOnError": false,
            "description": "Remove user from all Teams memberships",
            "displayName": "Remove user from all Teams",
            "executionSequence": 2,
            "isEnabled": true,
            "taskDefinitionId": "81f7b200-2816-4b3b-8c5d-dc556f07b024",
            "arguments": []
        },
        {
            "category": "leaver",
            "continueOnError": false,
            "description": "Delete user account in Azure AD",
            "displayName": "Delete User Account",
            "executionSequence": 3,
            "isEnabled": true,
            "taskDefinitionId": "8d18588d-9ad3-4c0f-99d0-ec215f0e3dff",
            "arguments": []
        }
    ]
}

Response

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows/$entity",
    "category": "leaver",
    "description": "Configure offboarding tasks for employees after their last day of work",
    "displayName": "Post-Offboarding of an employee",
    "lastModifiedDateTime": "2024-03-03T18:29:10.8412536Z",
    "createdDateTime": "2024-03-03T18:29:10.8412352Z",
    "deletedDateTime": null,
    "id": "15239232-66ed-445b-8292-2f5bbb2eb833",
    "isEnabled": true,
    "isSchedulingEnabled": false,
    "nextScheduleRunDateTime": null,
    "version": 1,
    "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": "employeeLeaveDateTime",
            "offsetInDays": 7
        }
    }
}

Run the workflow

Because the workflow isn't scheduled to run, you must run it manually, on-demand. In this request, the user targeted by the workflow is identified by ID df744d9e-2148-4922-88a8-633896c1e929.

When you run a workflow on demand, the tasks execute regardless of whether the user state matches the scope and trigger execution conditions. Therefore, even if the user isn't in the "Marketing" department or their employeeLeaveDateTime is set to null, this command still runs the tasks defined in the workflow for the user.

The request returns a 204 No Content response code.

POST https://graph.microsoft.com/v1.0/identityGovernance/LifecycleWorkflows/workflows/15239232-66ed-445b-8292-2f5bbb2eb833/activate

{
    "subjects": [
        {
            "id": "df744d9e-2148-4922-88a8-633896c1e929"
        }
    ]
}

Check tasks and workflow status

You can monitor the status of the workflows and tasks at three levels.

  • Monitor tasks at the user level.
  • Monitor the aggregate high-level summary of the user-level results for a workflow within a specified period.
  • Retrieve the detailed log of all tasks that were executed for a specific user in the workflow.

Option 1: Monitor tasks for a workflow at the user level

Request

GET https://graph.microsoft.com/v1.0/identityGovernance/LifecycleWorkflows/workflows/15239232-66ed-445b-8292-2f5bbb2eb833/userProcessingResults

Response

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows('15239232-66ed-445b-8292-2f5bbb2eb833')/userProcessingResults",
    "value": [
        {
            "id": "40efc576-840f-47d0-ab95-5abca800f8a2",
            "completedDateTime": "2024-03-03T18:31:00.3581066Z",
            "failedTasksCount": 0,
            "processingStatus": "completed",
            "scheduledDateTime": "2024-03-03T18:30:43.154495Z",
            "startedDateTime": "2024-03-03T18:30:46.9357178Z",
            "totalTasksCount": 3,
            "totalUnprocessedTasksCount": 0,
            "workflowExecutionType": "onDemand",
            "workflowVersion": 1,
            "subject": {
                "id": "df744d9e-2148-4922-88a8-633896c1e929"
            }
        }
    ]
}

Option 2: Get the aggregate high-level summary of the user-level results for a workflow, within a specified period

Request

GET https://graph.microsoft.com/v1.0/identityGovernance/LifecycleWorkflows/workflows/15239232-66ed-445b-8292-2f5bbb2eb833/userProcessingResults/summary(startDateTime=2024-03-01T00:00:00Z,endDateTime=2024-03-30T00:00:00Z)

Response

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.identityGovernance.userSummary",
    "failedTasks": 0,
    "failedUsers": 0,
    "successfulUsers": 1,
    "totalTasks": 3,
    "totalUsers": 1
}

Option 3: Retrieve the detailed log of all tasks that were executed for a specific user in the workflow

Request

GET https://graph.microsoft.com/v1.0/identityGovernance/LifecycleWorkflows/workflows/15239232-66ed-445b-8292-2f5bbb2eb833/userProcessingResults/40efc576-840f-47d0-ab95-5abca800f8a2/taskProcessingResults

Response

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows('15239232-66ed-445b-8292-2f5bbb2eb833')/userProcessingResults('40efc576-840f-47d0-ab95-5abca800f8a2')/taskProcessingResults",
    "value": [
        {
            "completedDateTime": "2024-03-03T18:30:50.483365Z",
            "createdDateTime": "2024-03-03T18:30:47.6125438Z",
            "id": "78650318-7238-4e7e-852f-2c36cbeff340",
            "processingStatus": "completed",
            "startedDateTime": "2024-03-03T18:30:50.0549446Z",
            "failureReason": null,
            "subject": {
                "id": "df744d9e-2148-4922-88a8-633896c1e929"
            },
            "task": {
                "category": "leaver",
                "continueOnError": false,
                "description": "Remove all licenses assigned to the user",
                "displayName": "Remove all licenses for user",
                "executionSequence": 1,
                "id": "f71246b2-269c-4ba6-ab8e-afc1a05114cb",
                "isEnabled": true,
                "taskDefinitionId": "8fa97d28-3e52-4985-b3a9-a1126f9b8b4e",
                "arguments": []
            }
        },
        {
            "completedDateTime": "2024-03-03T18:30:57.6034021Z",
            "createdDateTime": "2024-03-03T18:30:47.8824313Z",
            "id": "3d2e459d-5614-42e4-952b-0e917b5f6646",
            "processingStatus": "completed",
            "startedDateTime": "2024-03-03T18:30:53.6770279Z",
            "failureReason": null,
            "subject": {
                "id": "df744d9e-2148-4922-88a8-633896c1e929"
            },
            "task": {
                "category": "leaver",
                "continueOnError": false,
                "description": "Remove user from all Teams memberships",
                "displayName": "Remove user from all Teams",
                "executionSequence": 2,
                "id": "ed545f03-e8d8-45fb-9cbd-15c937f2a866",
                "isEnabled": true,
                "taskDefinitionId": "81f7b200-2816-4b3b-8c5d-dc556f07b024",
                "arguments": []
            }
        },
        {
            "completedDateTime": "2024-03-03T18:31:00.0894515Z",
            "createdDateTime": "2024-03-03T18:30:48.0004721Z",
            "id": "03359fa6-c63c-4573-92c2-4c9518ca98aa",
            "processingStatus": "completed",
            "startedDateTime": "2024-03-03T18:30:59.6195169Z",
            "failureReason": null,
            "subject": {
                "id": "df744d9e-2148-4922-88a8-633896c1e929"
            },
            "task": {
                "category": "leaver",
                "continueOnError": false,
                "description": "Delete user account in Azure AD",
                "displayName": "Delete User Account",
                "executionSequence": 3,
                "id": "b4cefaa0-6ceb-461d-bbf5-ec69246463fd",
                "isEnabled": true,
                "taskDefinitionId": "8d18588d-9ad3-4c0f-99d0-ec215f0e3dff",
                "arguments": []
            }
        }
    ]
}

[Optional] Schedule the workflow to run automatically

After running your workflow on-demand and checking that everything works fine, you might want to enable the workflow to run automatically on a tenant-defined schedule. Run this request.

The request returns a 204 No Content response code. When a workflow is scheduled, the Lifecycle Workflows engine checks every three hours for users in the associated execution condition and executes the configured tasks for those users. You can customize this recurrence from one hour to 24 hours.

PATCH https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows/15239232-66ed-445b-8292-2f5bbb2eb833
Content-type: application/json

{
    "isEnabled": true,
    "isSchedulingEnabled": true
}

Related content