Compartilhar via

Criar uma integração personalizada para sincronizar o seu sistema de gestão da força de trabalho com o Shifts

  • Artigo
  • Aplica-se a:
    Microsoft Teams, Microsoft 365 for frontline workers

Visão Geral

Integre o Turnos, a aplicação de gestão de agendas no Microsoft Teams, com o seu sistema de gestão da força de trabalho (WFM). Esta integração permite que a sua força de trabalho de primeira linha veja e faça a gestão das respetivas agendas diretamente no Turnos.

Este artigo orienta-o ao longo de como criar um conector com o Microsoft API do Graph para facilitar esta integração.

Pode configurar a sua integração para uma sincronização de dados unidirecional ou para uma sincronização de dados bidirecional.

  • Sincronização unidirecional (WFM sistema para Turnos): nesta configuração, agendar dados no seu sistema de WFM é sincronizado com Shifts. O conector lê os dados no seu sistema de WFM e escreve-os em Turnos. No entanto, as alterações efetuadas em Turnos pelos utilizadores não são refletidas no seu sistema de WFM.

  • Sincronização bidirecional (WFM sistema e Turnos): esta configuração permite uma sincronização bidirecional. A opção Agendar dados no seu sistema de WFM é sincronizada com Turnos e todas as alterações efetuadas em Turnos por utilizadores são sincronizadas de volta com o seu sistema de WFM. O conector valida e aprova as alterações que os utilizadores efetuam nos Turnos de acordo com as regras de negócio impostas pelo seu sistema de WFM antes de as alterações serem escritas em Turnos.

Observação

Se estiver a utilizar WFM UkG Pro, Blue Yonder WFM ou Reflexis WFM, também pode utilizar um conector gerido para integrar Os Turnos no seu sistema de WFM. Para saber mais, veja Conectores de turnos.

Terminologia utilizada neste artigo

Termo Descrição
conector Uma aplicação que sincroniza os dados agendados entre o sistema WFM e os Turnos.
integração da força de trabalho Uma entidade que define o método de encriptação para comunicação, o URL de chamada de retorno para o conector e as entidades Shifts a sincronizar.

Antes de começar

Pré-requisitos

  • Determine os dados que pretende sincronizar de acordo com as suas necessidades empresariais.
  • Compreenda os conceitos de autenticação e autorização no plataforma de identidade da Microsoft. Veja Noções básicas de autenticação e autorização.
  • Administração funções necessárias:
    • Pelo menos, um Administrador de Aplicações na Cloud para registar uma aplicação no centro de administração do Microsoft Entra
    • Administrador Global para registar a integração da força de trabalho

Familiarize-se com o processo de integração

Eis uma descrição geral dos passos de integração. Reveja estas informações para compreender o processo geral, incluindo quem efetua cada passo.

Etapa Sincronização unidirecional Sincronização bidirecional Quem executa este passo
1 Crie o conector: Crie o conector: Developer
2 Registar uma aplicação no centro de administração do Microsoft Entra Registar uma aplicação no centro de administração do Microsoft Entra Uma conta que é, pelo menos, um Administrador de Aplicações na Cloud
3 Criar equipas e agendas para sincronização Criar equipas e agendas para sincronização Programador ou Administrador do Teams
4 Registe e ative a integração da força de trabalho: Registe e ative a integração da força de trabalho: Passo 4a: Administrador Global
Passo 4b: Programador

Passo 1: criar o conector

Para criar o conector, conclua os seguintes passos:

Passo 1a: Sincronizar as alterações efetuadas em Turnos para o seu sistema de WFM

Para configurar o conector para receber e processar pedidos de Turnos, tem de implementar os seguintes pontos finais:

Determinar o URL base e os URLs de ponto final

O URL base (webhook) é {url}/v{apiVersion}, em que URL e apiVersion são as propriedades que definiu no objeto workforceIntegration quando regista a integração da força de trabalho.

Os caminhos relativos dos URLs do ponto final são os seguintes:

  • /connect: /connect
  • /update: /teams/{teamid}/update
  • /read: /teams/{teamid}/read

Por exemplo, se url for https://contosoconnector.com/wfi e apiVersion for 1:

  • O URL base é https://contosoconnector/com/wfi/v1.
  • O ponto final /connect é https://contosoconnector/wfi/v1/connect.
  • O ponto final /update é https://contosoconnector/wfi/v1/teams/{teamid}/update.
  • O ponto final /read é https://contosoconnector/wfi/v1/teams/{teamid}/read.

Encryption

Todos os pedidos são encriptados com AES-256-CBC-HMAC-SHA256. Especifica a chave secreta partilhada quando regista a integração da força de trabalho. As respostas enviadas para os Turnos não devem ser encriptadas.

Pontos de extremidade

POST /connect

Os turnos chamam este ponto final para testar a ligação quando regista a integração da força de trabalho. Uma resposta com êxito só é devolvida se este ponto final devolver uma resposta HTTP 200 OK .

Exemplo

Solicitação
ConnectRequest

{
   "tenantId": "a1s2s355-a2s3-j7h6-f4d3-k2h9j4mqpz",
   "userId": "4fbc12d7-1234-56ef-8a90-bc123d45678f"
}

Response
Devolver HTTP 200 OK

POST /teams/{teamid}/update

Os turnos chamam este ponto final para obter aprovação quando é efetuada uma alteração a uma entidade Shifts numa agendaque está ativada para a integração da força de trabalho. Se este ponto final aprovar o pedido, a alteração será guardada em Turnos.

Uma vez que o sistema de WFM é o sistema de registos, quando o conector recebe um pedido para este ponto final, deve primeiro tentar efetuar a alteração no sistema WFM. Se a alteração for efetuada com êxito, devolve êxito. Caso contrário, devolver a falha.

Os turnos chamam este ponto final para cada alteração (incluindo as alterações iniciadas a partir do conector/sistema WFM). Se o conector enviou uma atualização para os Turnos com API do Graph e adicionou o X-MS-WFMPassthrough: workforceIntegratonId cabeçalho, o pedido que chega a este ponto final terá o mesmo cabeçalho, o que lhe permite identificar e processar estes pedidos adequadamente. Por exemplo, devolve êxito sem fazer a mesma alteração no sistema de WFM que seria redundante e pode fazer com que o conector fique bloqueado num ciclo infinito.

O diagrama seguinte mostra o fluxo de dados.

Diagrama a mostrar o fluxo de atualizações de Turnos para o sistema de WFM.

Observação

Para obter mais informações sobre os modelos de Pedido e Resposta, veja WfiRequest na secção Referência de ponto final deste artigo.

Devolver código de resposta
Qualquer resposta da integração, incluindo um erro, tem de ter um código 200 OKde resposta HTTP. O corpo da resposta tem de ter o status e a mensagem de erro que reflete o estado de erro de subchamada adequado. Qualquer resposta da integração que não 200 OK seja é tratada como um erro e devolvida ao autor da chamada (cliente ou Microsoft Graph).

Se quiser configurar uma sincronização unidirecional, torne os Turnos só de leitura

Para uma sincronização unidirecional, tem de tornar os Turnos só de leitura para que os utilizadores não possam fazer alterações nos Turnos. Para tornar o Turnos só de leitura, devolva uma resposta de falha para todos os pedidos de Turnos.

Por exemplo, para impedir que os utilizadores façam alterações a turnos na agenda, este ponto final tem de devolver uma resposta de falha sempre que receber um pedido relativo a uma shift entidade.

Exemplo

Solicitação
WfiRequestContainer

O exemplo seguinte mostra um pedido de Turnos que pergunta se um turno, cujo ID é SHFT_12345678-1234-1234-1234-1234-1234567890ab e tem as propriedades listadas no corpo, pode ser guardado em Turnos. Este pedido foi acionado quando um utilizador cria uma mudança no Turnos.

{
  "requests": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "method": "POST",
      "url": "/shifts/SHFT_12345678-1234-1234-1234-1234567890ab",
      "headers": {
        "X-MS-Transaction-ID": "1",
        "X-MS-Expires": "2024-10-11T21:27:59.0134605Z"
      },
      "body": {
        "draftShift": {
          "activities": [],
          "isActive": true,
          "startDateTime": "2024-10-12T15:00:00.000Z",
          "endDateTime": "2024-10-12T17:00:00.000Z",
          "theme": "Blue"
        },
        "isStagedForDeletion": false,
        "schedulingGroupId": "TAG_a3e0b3f1-4a5c-4c2e-8eeb-5b8c3d1e3f8b",
        "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "createdDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedBy": {
          "user": {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "displayName": "Adele Vance"
          }
        },
        "id": "SHFT_12345678-1234-1234-1234-1234567890ab"
      }
    }
  ]
}

Response
WfiResponse

Êxito: Devolver HTTP 200 OK

Este exemplo mostra a resposta devolvida se o ponto final tiver aprovado o pedido. Neste cenário, o turno é guardado em Turnos e o utilizador pode ver a mudança na agenda.

{
  "responses": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "status": 200,
      "body": {
        "eTag": "3f4e5d6c-7a8b-9c0d-1e2f-3g4h5i6j7k8l",
        "error": null,
        "data": null
      }
    }
  ]
}

Falha: Devolver HTTP 200 OK

Este exemplo mostra a resposta devolvida se o ponto final tiver negado o pedido. Neste cenário, o utilizador recebe uma mensagem de erro "Não foi possível adicionar o turno" em Turnos.

{
    "responses": [
        {
            "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
            "status": 500,
            "body": {
                "error": {
                    "code": "500",
                    "message": “Could not add the shift”
                },
                "data": null
            }
        }
    ]
}
POST /teams/{teamid}/read

Este ponto final processa pedidos de Turnos para obter motivos de folga elegíveis ou turnos elegíveis para pedidos de troca para um utilizador.

Observação

A partir de outubro de 2024, este ponto final só é suportado na versão beta do Microsoft API do Graph. Também tem de especificar valores para a propriedade eligibilityFilteringEnabledEntities quando registar a integração da força de trabalho.

O diagrama seguinte mostra o fluxo de dados.

Diagrama a mostrar o fluxo para pedidos de filtragem de elegibilidade.

Devolver código de resposta
Qualquer resposta da integração, incluindo um erro, tem de ter um código 200 OKde resposta HTTP. O corpo da resposta tem de incluir o status e a mensagem de erro que reflete o estado de erro de subchamada adequado. Qualquer resposta da integração que não 200 OK seja é tratada como um erro e devolvida ao autor da chamada (cliente ou Microsoft Graph).

Exemplo: TimeOffReason

Solicitação

O exemplo seguinte mostra um pedido de Turnos que pergunta para que motivos de folga um utilizador (ID de utilizador aa162a04-bec6-4b81-ba99-96caa7b2b24d) é elegível. Este pedido foi acionado quando o utilizador pede folgas em Turnos.

 { 
  "requests": [ 
    { 
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
      "method": "GET", 
      "url": "/users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason"
    } 
  ] 
}

Response
Êxito: Devolver HTTP 200 OK

A seguinte resposta mostra que os IDs de motivos de folga elegíveis para o utilizador são "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" e "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". Neste cenário, o utilizador vê os motivos de folga correspondentes para escolher em Turnos.

{
    "responses": [ 
      { 
        "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
        "status": 200, 
        "body": { 
          "data": [ 
            "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc", 
            "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d" 
          ], 
          "error": null 
          } 
        }
    ]
}

Falha: Devolver HTTP 200 OK

Neste exemplo, é devolvida uma resposta de erro porque o conector não conseguiu aceder ao sistema de WFM para obter os motivos de folga para o utilizador.

 {
  "responses": [
    {
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "Could not reach WFM"
        }
      }
    }
  ]
}
Exemplo: SwapRequest

Solicitação

O exemplo seguinte mostra um pedido de Turnos que pergunta que turnos são elegíveis para uma troca com o turno cujo ID é SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 entre 2024-2024 e 2024 10-01T04:00:00.0000000Z e 2024-11-01T03:59:59.9990000Z.

{
  "requests": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "method": "GET",
      "url": "/shifts/SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029/requestableShifts?requestType=SwapRequest&startTime=2024-10-01T04:00:00.0000000Z&endTime=2024-11-01T03:59:59.9990000Z"
    }
  ]
}

Response
Êxito: Devolver HTTP 200 OK

A resposta seguinte mostra que o turno pode ser trocado pelo turno cujo ID é SHFT_98e96e23-966b-43be-b90d-4697037b67af.

{ 
  "responses": [ 
    { 
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029", 
      "status": 200, 
      "body": { 
        "data": ["SHFT_98e96e23-966b-43be-b90d-4697037b67af"],
        "error": null, 
      } 
    }
  ]
}

Falha: Devolver HTTP 200 OK

Neste exemplo, é devolvida uma resposta de erro porque o conector não conseguiu aceder ao sistema WFM para obter turnos elegíveis para um pedido de troca para o utilizador.

{
  "responses": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "could not reach WFM"
        }
      }
    }
  ]
}

Passo 1b: Sincronizar dados do seu sistema de WFM para Turnos

Utilize as APIs de Turnos no Microsoft Graph para ler dados de agendamento do seu sistema de WFM e escrever os dados em Turnos.

Por exemplo, para adicionar uma mudança aos Turnos, utilize a API Criar shift .

Veja a referência do Microsoft API do Graph v1.0 para as APIs shifts, que estão listadas em Gestão de turnos.

Observação

O MS-APP-ACTS-AS cabeçalho é necessário nos pedidos e tem de conter o ID (GUID) do utilizador do qual a sua aplicação está a agir em nome de. Recomendamos que utilize o ID de utilizador de um proprietário de equipa ao atualizar a agenda.

O diagrama seguinte mostra o fluxo de dados.

Diagrama que mostra o fluxo para sincronizar dados do seu sistema de WFM para Shifts.

Sincronização inicial

Para a primeira sincronização, o conector deve ler dados no seu sistema de WFM e escrever os dados em Turnos. Recomendamos que sincronize duas semanas de dados futuros.

Após a sincronização inicial

Após a primeira sincronização, pode optar por:

  • Atualizar síncronamente os Turnos com alterações no seu sistema de WFM: envie uma atualização aos Turnos para cada alteração efetuada no seu sistema de WFM.

  • Atualizar assíncronamente os Turnos com alterações no seu sistema de WFM: efetue uma sincronização periódica ao escrever todas as alterações que ocorreram no seu sistema de WFM dentro de um determinado período de tempo (por exemplo, 10 minutos) em Turnos.

    Todas as operações de escrita em Turnos, incluindo operações de escrita iniciadas pelo conector, acionam uma chamada para o ponto final /update do conector. Recomendamos que inclua o X-MS-WFMPassthrough: workforceIntegratonId cabeçalho em todas as chamadas de escrita para que o conector possa identificá-las e processá-las adequadamente. Por exemplo, se o seu sistema de WFM iniciou a alteração, aprove-a sem aplicar uma atualização ao seu sistema de WFM.

    Observação

    Se estiver a configurar o conector para uma sincronização bidirecional de dados entre o sistema WFM e os Turnos, exclua as alterações iniciadas a partir dos Turnos na sincronização periódica. Estas alterações já estão escritas em Turnos.

Passo 2: registar uma aplicação no centro de administração do Microsoft Entra

Siga estes passos para registar uma aplicação para o conector no plataforma de identidade da Microsoft, configurar permissões para a aplicação aceder ao Microsoft Graph e obter um token de acesso.

  1. Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Administrador de Aplicações na Cloud.

  2. Registre seu aplicativo. Para obter os passos, veja Registar uma aplicação com o plataforma de identidade da Microsoft.

  3. Atribua as permissões de aplicaçãoSchedule.ReadWrite.All à aplicação para acesso apenas à aplicação e obtenha um token de acesso.

    Para obter orientações passo a passo, veja Obter acesso sem um utilizador.

    O token de acesso verifica se a sua aplicação está autorizada a chamar o Microsoft Graph com a sua própria identidade com a permissão Schedule.ReadWrite.All . Tem de ser incluído no cabeçalho Autorização dos pedidos.

Passo 3: criar equipas e agendas para sincronização

Configure as equipas no Teams que pretende sincronizar. Pode utilizar as equipas existentes ou criar novas equipas.

  1. Configure equipas no Teams para corresponderem às equipas e localizações no seu sistema de WFM. Certifique-se de que adiciona as seguintes pessoas a cada equipa:

    • Gestores de primeira linha como proprietários de equipas. Certifique-se de que adiciona o utilizador no MS-APP-ACTS-AS cabeçalho como proprietário da equipa de cada equipa.
    • Trabalhadores de primeira linha como membros da equipa.

  2. Crie uma agenda em Turnos para cada equipa. Para saber mais, consulte Criar ou substituir agendamento.

  3. Adicione grupos de agendamento à agenda de cada equipa. Os grupos de agendamento são utilizados para agrupar funcionários com base em características comuns dentro de uma equipa. Por exemplo, os grupos de agendamento podem ser departamentos ou tipos de trabalho. Para saber mais, veja schedulingGroup resource type (Tipo de recurso schedulingGroup).

  4. Adicionar funcionários a cada grupo de agendamento. Para saber mais, veja Substituir schedulingGroup.

Observação

Também pode utilizar o centro de administração do Teams para configurar as suas equipas e implementar turnos nas equipas. Para saber mais, confira:

Passo 4: Registar e ativar a integração da força de trabalho

Uma integração da força de trabalho define as definições de encriptação para comunicação entre Shifts e o conector, o URL para chamadas de retorno de Turnos e os tipos de entidades a sincronizar.

Para registar e ativar a integração da força de trabalho, conclua os seguintes passos:

Passo 4a: Registar a integração da força de trabalho no seu inquilino

Tem de ser um Administrador Global para efetuar este passo.

Utilize a API Create workforceIntegration para registar a integração da força de trabalho no seu inquilino.

Eis um exemplo de um pedido.

POST https://graph.microsoft.com/v1.0/teamwork/workforceIntegrations/
{ 
  "displayName": "Contoso integration", 
  "apiVersion": 1, 
  "encryption": { 
    "protocol": "sharedSecret", 
    "secret": "secret-value" 
  }, 
  "isActive": true, 
  "url": "https://contosoconnector.com/wfi", 
  "supportedEntities": "Shift,SwapRequest,UserShiftPreferences,Openshift,OpenShiftRequest,OfferShiftRequest”,
}

Consulte a tabela a seguir, para obter os detalhes. Para saber mais, veja workforceIntegration resource type (Tipo de recurso workforceIntegration).

Propriedade Mais informações
apiVersion Versão da API para o URL de chamada de retorno. O URL base é composto pela propriedade url e por esta propriedade.
criptografia Defina o protocolo como sharedSecret. O valor do segredo tem de ter exatamente 64 carateres.

Utilize o segredo para desencriptar os payloads JSON encriptados que são enviados para o ponto final do conector a partir do Shifts. O payload é encriptado com AES-256-CBC-HMAC-SHA256. A sua aplicação deve manter este segredo em segurança. Por exemplo, num cofre de chaves.
supportedEntities Especifique as entidades Shifts que pretende que o conector suporte para sincronização. Os turnos chamam o ponto final /update do conector quando qualquer uma destas entidades é alterada para que possa aprovar ou rejeitar a alteração. Para obter a lista dos valores possíveis, veja workforceIntegration resource type (Tipo de recurso workforceIntegration)

Nota Esta lista é uma enumeração evoluível. Tem de utilizar o cabeçalho do Prefer: include-unknown-enum-members pedido para obter todos os valores.
eligibilityFilteringEnabledEntities Nota: a partir de outubro de 2024, este ponto final só é suportado na versão beta do Microsoft API do Graph.

Especifique as entidades Shifts que pretende que o conector suporte para filtragem de elegibilidade. Os valores possíveis são:
  • none: Lista vazia
  • SwapRequests: Os turnos chamam o ponto final /read do conector para obter uma lista filtrada de turnos que um utilizador pode escolher para um pedido de troca.
  • TimeOffReasons: os turnos chamam o ponto final /read do conector para obter uma lista filtrada de motivos de folga que um utilizador pode escolher quando pede folgas.
Nota Esta lista é uma enumeração evoluível. Tem de utilizar o cabeçalho do Prefer: include-unknown-enum-members pedido para obter todos os valores.
url O URL de integração da força de trabalho para chamadas de retorno de Turnos. O URL base é composto por esta propriedade e a propriedade apiVerson .

Passo 4b: Ativar a integração da força de trabalho para os horários da sua equipa

Ative a integração da força de trabalho nos horários que pretende gerir. Para tal, utilize a API Criar ou substituir agendamento para criar ou atualizar a agenda das suas equipas.

Eis um exemplo de um pedido.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}
  • Especifique o workforceIntegrationId que foi gerado quando registou a integração da força de trabalho.
  • Pode ativar um máximo de uma integração da força de trabalho com base numa agenda. Se incluir mais do que uma workforceIntegrationId no pedido, é utilizado o primeiro.

Solução de problemas

Conector

Quando o conector responde a um pedido do Shifts, o que acontece se devolver um código de resposta diferente de 200? Faz diferença se devolver um status diferente de 200 no corpo da resposta?

Existe uma diferença entre estes dois cenários.

  • Se o conector devolver um código de resposta diferente de 200, o Shifts tenta repetir os pontos finais /read e /update várias vezes. Eventualmente, o Shifts apresenta um "Algo correu mal. A configuração da integração da força de trabalho na sua equipa respondeu com dados inválidos." mensagem de erro.
  • Se o conector devolver um status diferente de 200 no corpo da resposta, Shifts apresenta um "Ocorreu um problema. Pedimos desculpa, mas não foi possível concluir a alteração", mensagem de erro e para de repetir os pontos finais.

O que acontece se o conector devolver dados inválidos no corpo da resposta?

Os turnos tentam repetir os pontos finais /read e /update várias vezes. Eventualmente, o Shifts apresenta um "Algo correu mal. A integração da força de trabalho configurada na sua equipa respondeu com dados inválidos." mensagem de erro.

Como fazer identificar se o pedido foi originalmente feito em Turnos ou no sistema de WFM para evitar um ciclo infinito?

Adicione o X-MS-WFMPassthrough: workforceIntegratonId cabeçalho a todas as chamadas de escrita e atualização para identificar/ignorar as alterações acionadas pelo conector. Este cabeçalho é utilizado para indicar que o pedido foi feito devido a uma chamada anterior efetuada pelo conector para API do Graph para sincronizar dados do seu sistema de WFM para Shifts.

Registo de integração da força de trabalho

Regisci a integração da força de trabalho e especificei "eligibilityFilteringEnabledEntities", incluindo "SwapRequest, OfferShiftRequest e TimeOffReason", mas o corpo da resposta não mostra a lista "eligibilityFilteringEnabledEntities".

A filtragem de elegibilidade é atualmente suportada através do https://graph.microsoft.com/beta ponto final e não do https://graph.microsoft.com/v1 ponto final.

Registei a integração da força de trabalho e adicionei "supportedEntities", mas recebi uma resposta 400 Pedido Inválido e um "Payload inválido: Valor pedido "shift, ....". não foi encontrado." mensagem

Certifique-se de que todas as entidades shifts no corpo do supportedEntities pedido de lista começam com uma letra em maiúscula. Por exemplo, "supportedEntities":"Shift,SwapRequest,OpenShift".

Registei a integração da força de trabalho e implementei os pontos finais /connect, /update e /read, mas o webhook não está a funcionar.

Certifique-se de que a integração da força de trabalho está ativada para o agendamento da sua equipa. Além disso, marcar que as propriedades url e apiVersion estão corretas.

Referência de ponto final

Solicitação

ConnectRequest

Propriedade Tipo Descrição
tenantId String ID do inquilino para a integração da força de trabalho
userId Cadeia de caracteres ID do utilizador para a integração da força de trabalho 
{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Propriedade Tipo Descrição
pedidos Coleção WfiRequest Lista de WfiRequests 
{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

Número de elementos num pedido:

  • Na maioria dos casos, um pedido tem um elemento.
  • Alguns pedidos, como aprovações de pedidos de turno de troca, têm cinco elementos: um pedido de troca PUT, dois turnos DELETE (turnos existentes) e dois turnos POST (novos turnos).

WfiRequest

Propriedade Tipo Descrição
id Cadeia de caracteres ID da entidade
method Cadeia de caracteres O método invocado no item. Por exemplo, POST, PUT, GET, DELETE.
url Cadeia de caracteres Indica o tipo de detalhes da entidade e da operação.
cabeçalhos WfiRequestHeader Cabeçalhos
corpo ShiftsEntity Corpo da entidade relacionada com o pedido.
Para POST /teams/{teamId}/update
Propriedade Tipo Descrição
id Cadeia de caracteres ID da entidade
method Cadeia de caracteres POST para criar uma entidade, PUT para atualizar uma entidade, DELETE para eliminar uma entidade.
url Cadeia de caracteres O formato é /{EntityType}/{EntityId}. Os valores possíveis para {EntityType} são shifts, swapRequests, timeoffReasons, openshifts, openshiftrequests, offershiftrequests, , timesoff. timeOffRequests Por exemplo, /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
cabeçalho WfiRequestHeader Cabeçalho
corpo ShiftsEntity Tem de corresponder {EntityType} na propriedade url . Utilize um de shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Por exemplo, /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
Para POST /teams/{teamsId}/read
Propriedade Tipo Descrição
id Cadeia de caracteres ID da entidade
method Cadeia de caracteres É sempre GET.
url Cadeia de caracteres
  • TimeOffReasons: o formato é /users/{userId}/timeOffReasons?requestType=TimeOffReason. Por exemplo, /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason.
  • SwapRequest: o formato é /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Por exemplo, shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
cabeçalho WfiRequestHeader Cabeçalho
corpo ShiftsEntity É sempre null.

WfiRequestHeader

Propriedade Tipo Descrição
X-MS-Transaction-ID Cadeia de caracteres ID da Transação
X-MS-Expira Cadeia (DateTime) DateTime de expiração da transação

X-MS-WFMPassthrough: workforceIntegratonId não será incluído no WfiRequestHeader. Deve ser extraído do HttpRequest.

Resposta

WfiResponseContainer

Propriedade Tipo Descrição
respostas Coleção WfiResponse Lista de WfiResponses 
{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Propriedade Tipo Descrição
id Cadeia de caracteres ID da entidade
status Cadeia de caracteres Resultado da operação
corpo WfiResponseBody WfiResponseBody

WfiResponseBody

Propriedade Tipo Descrição
eTag String eTag
erro WfiResponseError Detalhes sobre o erro
data Cadeia de caracteres Os dados pedidos (para pedidos de leitura)

WfiResponseError

Propriedade Tipo Descrição
código Cadeia de caracteres Código de erro
mensagem String Mensagem de erro