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

Este tutorial explica como automatizar tarefas de pré-contratação 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 se há novos funcionários em um departamento específico, dois dias antes da data de contratação.
  • Configure uma tarefa para gerar um TAP (senha de acesso temporária) para o novo funcionário e enviá-lo ao gerente do novo funcionário.
  • Monitore o status do fluxo de trabalho e suas tarefas associadas.

Pré-requisitos

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

  • Esse recurso requer licenças de Governança do Microsoft Entra ID Governance. Confira os conceitos básicos de licenciamento de Governança do Microsoft Entra ID Governance para encontrar a licença certa para suas necessidades.

  • Entre em um cliente de API como o Graph Explorer para chamar o Microsoft Graph com uma conta que tenha pelo menos a função de Administrador do Ciclo de Vida do Microsoft Entra.

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

  • Crie duas contas de usuário para este tutorial: uma para o novo contratado e outra para o gerente. Defina as configurações a seguir, conforme aplicável.

    Propriedade do usuário Descrição Definido em
    Email Usado para notificar o gerente sobre o TAP (senha 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. Definido para a data de hoje. Funcionário
    department Usado para fornecer o escopo para o fluxo de trabalho. Definido como Sales Funcionário, gerente
  • Habilite a política TAP (Senha de Acesso Temporária) em seu locatário e certifique-se de que o novo usuário esteja habilitado para usar o método de autenticação.

Criar um fluxo de trabalho de "marceneiro"

Solicitação

Essa solicitação cria um fluxo de trabalho de pré-contratação com estas configurações:

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

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 foi agendado, você deve executá-lo 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 do fluxo de trabalho

Você pode monitorar o status dos fluxos de trabalho e suas tarefas associadas em três níveis.

  • Monitorar tarefas no nível do usuário.
  • Monitore o resumo de alto nível dos resultados no 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 de 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 que foram 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 para execução automática

Depois de executar o fluxo de trabalho sob demanda e confirmar que ele funciona, permita que o fluxo de trabalho seja executado automaticamente em um agendamento definido pelo locatário. Execute a seguinte solicitação.

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 os objetos de usuário que correspondem à condição de execução e executa as tarefas configuradas. Você pode personalizar essa recorrência de uma a 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
}