使用生命周期工作流 API 在员工工作的第一天之前自动执行入职任务

本教程提供使用生命周期工作流 API 自动执行预用任务的分步指南。

生命周期工作流方案的屏幕截图。

在本教程中,你将了解如何:

  • 配置生命周期工作流,以在雇用日期前两天检查特定部门的新员工。
  • 将任务配置为为新员工生成临时访问通行证 (TAP) ,并将其发送给新员工的经理。
  • 监视工作流的状态及其关联任务。

先决条件

若要完成本教程,需要以下资源和特权:

  • 此功能需要Microsoft Entra ID 治理许可证。 若要查找符合要求的正确许可证,请参阅 Microsoft Entra ID 治理许可基础知识

  • 登录到 图形资源管理器 等 API 客户端,使用至少具有 生命周期管理员 Microsoft Entra 角色的帐户调用 Microsoft Graph。

  • 向自己授予 LifecycleWorkflows.ReadWrite.All Microsoft Graph 委托的权限。

  • 创建两个在本教程中使用的用户帐户:一个用于新员工,另一个用于其经理,并配置以下设置(如果适用)。

    User 属性 说明 设置为
    mail 用于通知经理有关新员工的临时访问通行证 (TAP) 。 经理和员工都应具有活动邮箱来接收电子邮件。 员工、经理
    manager 生命周期工作流使用的此属性。 员工
    employeeHireDate 用于触发工作流。 设置为今天的日期。 员工
    department 用于提供工作流的范围。 设置为 Sales 员工、经理
  • 在租户中启用 临时访问传递 (TAP) 策略 ,并启用新用户以使用身份验证方法。

创建“联接器”工作流

请求

以下请求使用以下设置创建预用工作流:

  • 它可以按需运行,但不能按计划运行。
  • 工作流在员工的雇用日期前两天运行,如果他们在“销售”部门,则运行。
  • 此工作流中只运行一个内置任务:生成 TAP 并将其发送给新员工的经理。 此任务在生命周期工作流中由 taskDefinitionId1b555e50-7f65-41d5-b514-5894a026d10d 标识。
POST https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows
Content-type: application/json

{
   "displayName":"Onboard pre-hire employee", 
   "description":"Configure pre-hire tasks for onboarding employees before their first day", 
   "isEnabled":true, 
   "isSchedulingEnabled": false,
   "executionConditions": {
       "@odata.type": "microsoft.graph.identityGovernance.triggerAndScopeBasedConditions",
        "scope": {
            "@odata.type": "microsoft.graph.identityGovernance.ruleBasedSubjectSet",
            "rule": "(department eq 'Sales')"
        },
        "trigger": {
            "@odata.type": "microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
            "timeBasedAttribute": "employeeHireDate",
            "offsetInDays": -2
        }
    }, 
   "tasks":[ 
      {
         "isEnabled":true, 
         "category": "Joiner",
         "taskDefinitionId":"1b555e50-7f65-41d5-b514-5894a026d10d", 
         "displayName":"Generate TAP And Send Email", 
         "description":"Generate Temporary Access Pass and send via email to user's manager", 
         "arguments":[ 
            { 
                "name": "tapLifetimeMinutes", 
                "value": "480" 
            }, 
            { 
                "name": "tapIsUsableOnce", 
                "value": "true" 
            }
          ]
       }  
    ]     
} 

响应

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 pre-hire tasks for onboarding employees before their first day",
    "displayName": "Onboard pre-hire employee",
    "lastModifiedDateTime": "2024-03-04T07:45:14.3410141Z",
    "createdDateTime": "2024-03-04T07:45:14.3410017Z",
    "deletedDateTime": null,
    "id": "ea71190c-075a-4ae7-9bca-34abf3b7b056",
    "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 'Sales')"
        },
        "trigger": {
            "@odata.type": "#microsoft.graph.identityGovernance.timeBasedAttributeTrigger",
            "timeBasedAttribute": "employeeHireDate",
            "offsetInDays": -2
        }
    }
}

运行工作流

由于工作流未计划运行,因此必须手动运行。 在以下请求中,将按 ID 8930f0c7-cdd7-4885-9260-3b4a8111de5c标识工作流目标的用户。 请求返回 204 No Content 响应。

POST https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows/ea71190c-075a-4ae7-9bca-34abf3b7b056/activate

{
    "subjects": [
        {
            "id": "8930f0c7-cdd7-4885-9260-3b4a8111de5c"
        }
    ]
}

检查任务和工作流状态

随时可以在三个级别监视工作流的状态及其关联任务。

  • 监视用户级别的任务。
  • 在指定时间段内监视工作流的用户级结果的聚合高级摘要。
  • 检索工作流中为特定用户执行的所有任务的详细日志。

选项 1:在用户级别监视工作流的任务

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows/ea71190c-075a-4ae7-9bca-34abf3b7b056/userProcessingResults

响应

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows('ea71190c-075a-4ae7-9bca-34abf3b7b056')/userProcessingResults",
    "value": [
        {
            "id": "5772d894-3bcf-4d1c-9cfc-8c182331215b",
            "completedDateTime": "2024-03-04T08:07:23.2591226Z",
            "failedTasksCount": 0,
            "processingStatus": "completed",
            "scheduledDateTime": "2024-03-04T08:07:03.8706523Z",
            "startedDateTime": "2024-03-04T08:07:09.4670969Z",
            "totalTasksCount": 1,
            "totalUnprocessedTasksCount": 0,
            "workflowExecutionType": "onDemand",
            "workflowVersion": 1,
            "subject": {
                "id": "8930f0c7-cdd7-4885-9260-3b4a8111de5c"
            }
        }
    ]
}

选项 2:获取指定时间段内工作流的用户级结果的聚合高级摘要

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows/ea71190c-075a-4ae7-9bca-34abf3b7b056/userProcessingResults/summary(startDateTime=2024-03-01T00:00:00Z,endDateTime=2024-03-30T00:00:00Z)

响应

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": 1,
    "totalUsers": 1
}

选项 3:检索工作流中为特定用户执行的所有任务的详细日志

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows/ea71190c-075a-4ae7-9bca-34abf3b7b056/userProcessingResults/5772d894-3bcf-4d1c-9cfc-8c182331215b/taskProcessingResults

响应

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/lifecycleWorkflows/workflows('ea71190c-075a-4ae7-9bca-34abf3b7b056')/userProcessingResults('5772d894-3bcf-4d1c-9cfc-8c182331215b')/taskProcessingResults",
    "value": [
        {
            "completedDateTime": "2024-03-04T08:07:15.9906441Z",
            "createdDateTime": "2024-03-04T08:07:09.8072395Z",
            "id": "227c85e4-7b84-461f-8df5-c347c2435eb2",
            "processingStatus": "completed",
            "startedDateTime": "2024-03-04T08:07:11.1595421Z",
            "failureReason": null,
            "subject": {
                "id": "8930f0c7-cdd7-4885-9260-3b4a8111de5c"
            },
            "task": {
                "category": "joiner",
                "continueOnError": false,
                "description": "Generate Temporary Access Pass and send via email to user's manager",
                "displayName": "Generate TAP And Send Email",
                "executionSequence": 1,
                "id": "8b9b47c0-957b-4a52-8f2d-816e59c40fd2",
                "isEnabled": true,
                "taskDefinitionId": "1b555e50-7f65-41d5-b514-5894a026d10d",
                "arguments": [
                    {
                        "name": "tapLifetimeMinutes",
                        "value": "480"
                    },
                    {
                        "name": "tapIsUsableOnce",
                        "value": "true"
                    }
                ]
            }
        }
    ]
}

[可选]将工作流计划为自动运行

按需运行工作流并检查一切是否正常工作后,你可能希望启用工作流,以便它可以按照租户定义的计划自动运行。 运行以下请求。

请求返回 204 No Content 响应。 安排工作流时,生命周期工作流引擎每三小时检查一次与关联的执行条件匹配的用户对象,并为这些用户执行配置的任务。 可以自定义此重复周期,范围为 1 小时到 24 小时。

PATCH https://graph.microsoft.com/v1.0/identityGovernance/lifecycleWorkflows/workflows/ea71190c-075a-4ae7-9bca-34abf3b7b056
Content-type: application/json

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