Compartilhar via


Automatizar tarefas de integração de colaboradores antes do primeiro dia de trabalho com as APIs de Fluxos de Trabalho do Ciclo de Vida

Este tutorial fornece orientações passo a passo para automatizar tarefas de pré-contratação com APIs de Fluxos de Trabalho do Ciclo de Vida.

Captura de ecrã a mostrar o cenário de Fluxos de Trabalho de Ciclo de Vida.

Neste tutorial, você aprende a:

  • Configure um fluxo de trabalho de ciclo de vida para verificar a existência de novos funcionários num departamento específico, dois dias antes da data de contratação.
  • Configure uma tarefa para gerar um passe de acesso temporário (TAP) para o novo funcionário e envie-o para o gestor do novo funcionário.
  • Monitorize o estado do fluxo de trabalho e as respetivas tarefas associadas.

Pré-requisitos

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

  • Esta funcionalidade requer licenças de Governação do Microsoft Entra ID. Para encontrar a licença certa para os seus requisitos, consulte Noções básicas de licenciamento de Governação do Microsoft Entra ID.

  • Inicie sessão num cliente de API, como o Graph Explorer , para chamar o Microsoft Graph com uma conta que tenha, pelo menos, a função Administrador de Ciclo de Vida Microsoft Entra.

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

  • Crie duas contas de utilizador a utilizar neste tutorial: uma para a nova contratação e outra para o respetivo gestor e tenha as seguintes definições configuradas conforme aplicável.

    Propriedade do utilizador Descrição Definir em
    Email Utilizado para notificar o gestor do passe de acesso temporário do novo funcionário (TAP). Tanto o gestor como o funcionário devem ter caixas de correio ativas para receber e-mails. Funcionário, Gestor
    manager Este atributo que é utilizado pelo fluxo de trabalho do ciclo de vida. Funcionário
    employeeHireDate Utilizado para acionar o fluxo de trabalho. Definido como a data de hoje. Funcionário
    department Utilizado para fornecer o âmbito do fluxo de trabalho. Definido como Sales Funcionário, Gestor
  • Ative a política De Acesso Temporário (TAP) no inquilino e o novo utilizador ativado para utilizar o método de autenticação.

Criar um fluxo de trabalho "joiner"

Solicitação

O pedido seguinte cria um fluxo de trabalho de pré-contratação com as seguintes definições:

  • Pode ser executado a pedido, mas não dentro do prazo.
  • O fluxo de trabalho é executado dois dias antes da data de contratação do funcionário e, se estiver no departamento de "Vendas".
  • Apenas uma tarefa incorporada é executada neste fluxo de trabalho: para gerar o TAP e enviá-lo para o gestor da nova contratação. Esta tarefa é identificada nos Fluxos de Trabalho do Ciclo de Vida pelo 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

Uma vez que o fluxo de trabalho não está agendado para ser executado, tem de ser executado manualmente. No pedido seguinte, o utilizador que é o destino do fluxo de trabalho é identificado pelo ID 8930f0c7-cdd7-4885-9260-3b4a8111de5c. O pedido devolve 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 estado do fluxo de trabalho

Em qualquer altura, pode monitorizar o estado dos fluxos de trabalho e as respetivas tarefas associadas a três níveis.

  • Monitorizar tarefas ao nível do utilizador.
  • Monitorize o resumo agregado de alto nível dos resultados ao nível do utilizador de um fluxo de trabalho, dentro de um período especificado.
  • Obtenha o registo detalhado de todas as tarefas que foram executadas para um utilizador específico no fluxo de trabalho.

Opção 1: Monitorizar tarefas de um fluxo de trabalho ao nível do utilizador

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 ao nível do utilizador 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: Obter o registo detalhado de todas as tarefas que foram executadas para um utilizador 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 a execução automática do fluxo de trabalho

Depois de executar o fluxo de trabalho a pedido e verificar se está tudo a funcionar corretamente, poderá querer ativar o fluxo de trabalho para que possa ser executado automaticamente com base numa agenda definida pelo inquilino. Execute o seguinte pedido.

O pedido devolve uma 204 No Content resposta. Quando um fluxo de trabalho é agendado, o motor de Fluxos de Trabalho de Ciclo de Vida verifica a cada três horas os objetos de utilizador que correspondem à condição de execução associada e executa as tarefas configuradas para esses utilizadores. Pode personalizar esta periodicidade 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
}