Automatizar tarefas de integração de funcionários antes do primeiro dia de trabalho usando APIs de fluxos de trabalho do ciclo de vida

Este tutorial fornece diretrizes passo a passo para automatizar tarefas de pré-venda com APIs de fluxos de trabalho do ciclo de vida.

Captura de tela do cenário fluxos de trabalho do ciclo de vida.

Neste tutorial, você aprende a:

  • Configure um fluxo de trabalho de ciclo de vida para marcar para novos funcionários em um departamento específico, dois dias antes da data de contratação.
  • Configure uma tarefa para gerar um TAP (passe de acesso temporário) para o novo funcionário e envie-a para o novo gerente do funcionário.
  • Monitore o status do fluxo de trabalho e suas tarefas associadas.

Pré-requisitos

Para concluir este tutorial, você precisa dos seguintes recursos e privilégios:

  • Esse recurso requer licenças Microsoft Entra ID Governance. Para encontrar a licença certa para seus requisitos, consulte Microsoft Entra ID Governance os fundamentos de licenciamento.

  • Entre em um cliente de API, como o Graph Explorer chamar o Microsoft Graph com uma conta que tenha pelo menos a função administrador do ciclo de vida Microsoft Entra.

  • Conceda a si mesmo a permissão delegada LifecycleWorkflows.ReadWrite.All Microsoft Graph.

  • Crie duas contas de usuário a serem usadas neste tutorial: uma para a nova contratação e outra para seu gerente e tenha as seguintes configurações configuradas conforme aplicável.

    Propriedade user Descrição Definido como
    Email Usado para notificar o gerente do TAP (passe de acesso temporário) do novo funcionário. O gerente e o funcionário devem ter caixas de correio ativas para receber emails. Funcionário, Gerente
    manager Esse atributo usado pelo fluxo de trabalho do ciclo de vida. Funcionário
    employeeHireDate Usado para disparar o fluxo de trabalho. Defina como a data de hoje. Funcionário
    department Usado para fornecer o escopo do fluxo de trabalho. Definido como Sales Funcionário, Gerente
  • Habilite a política TAP (Passe de Acesso Temporário) no locatário e o novo usuário habilitado para usar o método de autenticação.

Criar um fluxo de trabalho "joiner"

Solicitação

A solicitação a seguir cria um fluxo de trabalho de pré-venda com as seguintes configurações:

  • Ele pode ser executado sob demanda, mas não agendado.
  • O fluxo de trabalho é executado dois dias antes da data de contratação do funcionário e se ele estiver no departamento "Vendas".
  • Apenas uma tarefa interna é executada neste fluxo de trabalho: gerar o TAP e enviá-lo para o gerente do novo contratado. Essa tarefa é identificada nos fluxos de trabalho do ciclo de vida pela tarefaDefinitionId1b555e50-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" 
            }
          ]
       }  
    ]     
} 

Resposta

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

Executar o fluxo de trabalho

Como o fluxo de trabalho não está agendado para ser executado, ele deve ser executado manualmente. Na solicitação a seguir, o usuário que é o destino do fluxo de trabalho é identificado pela ID 8930f0c7-cdd7-4885-9260-3b4a8111de5c. A solicitação retorna uma 204 No Content resposta.

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

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

Verificar tarefas e status de fluxo de trabalho

A qualquer momento, você pode monitorar o status dos fluxos de trabalho e suas tarefas associadas em três níveis.

  • Monitore as tarefas no nível do usuário.
  • Monitore o resumo agregado de alto nível dos resultados do nível do usuário para um fluxo de trabalho, dentro de um período especificado.
  • Recupere o log detalhado de todas as tarefas executadas para um usuário específico no fluxo de trabalho.

Opção 1: Monitorar tarefas para um fluxo de trabalho no nível do usuário

Solicitação

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

Resposta

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

Opção 2: obter o resumo agregado de alto nível dos resultados no nível do usuário para um fluxo de trabalho, dentro de um período especificado

Solicitação

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)

Resposta

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
}

Opção 3: recuperar o log detalhado de todas as tarefas executadas para um usuário específico no fluxo de trabalho

Solicitação

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

Resposta

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

[Opcional] Agendar o fluxo de trabalho a ser executado automaticamente

Depois de executar seu fluxo de trabalho sob demanda e verificar se tudo está funcionando bem, talvez você queira habilitar o fluxo de trabalho para que ele possa ser executado automaticamente em uma agenda definida pelo locatário. Execute a solicitação a seguir.

A solicitação retorna uma 204 No Content resposta. Quando um fluxo de trabalho é agendado, o mecanismo de fluxos de trabalho do ciclo de vida verifica a cada três horas objetos de usuário que correspondem à condição de execução associada e executa as tarefas configuradas para esses usuários. Você pode personalizar essa recorrência entre uma hora e 24 horas.

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

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