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.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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:
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.
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
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.
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.
Planeje e projete sua metodologia de projeto para implementar com êxito aplicativos de finanças e operações com serviços do Microsoft FastTrack, gerenciamento de dados e muito mais.
Saiba mais sobre os requisitos, os pré-requisitos e a configuração do ambiente de que precisa antes de utilizar o assistente do conector Shifts ou o PowerShell para integrar turnos no Teams com o UKG Pro Workforce Management.
Saiba como configurar turnos abertos entre localizações para a sua linha de frente em Turnos. Com esta funcionalidade, os gestores de primeira linha podem oferecer turnos abertos em vários locais para os trabalhadores de primeira linha pedirem, e os trabalhadores podem ver e pedir turnos abertos noutros locais.