Creación de una integración personalizada para sincronizar el sistema de administración de los empleados con Turnos

• Se aplica a:

  Microsoft Teams, Microsoft 365 for frontline workers

Información general

Integre Shifts, la aplicación de administración de programación en Microsoft Teams, con el sistema de administración de los empleados (WFM). Esta integración permite a los empleados de primera línea ver y administrar sus programaciones directamente dentro de Turnos.

En este artículo se explica cómo crear un conector mediante microsoft Graph API para facilitar esta integración.

Puede configurar la integración para una sincronización de datos unidireccional o una sincronización de datos bidireccional.

• Sincronización unidireccional (WFM sistema a turnos): en esta configuración, los datos de programación del sistema de WFM se sincronizan con Turnos. El conector lee los datos del sistema de WFM y los escribe en Desplazamientos. Sin embargo, los cambios realizados en Turnos por parte de los usuarios no se reflejan en el sistema de WFM.

• Sincronización bidireccional (sistema de WFM y turnos): esta configuración permite una sincronización bidireccional. Los datos de programación del sistema de WFM se sincronizan con Turnos y los cambios realizados en Turnos por los usuarios se sincronizan de nuevo con el sistema de WFM. El conector valida y aprueba los cambios que realizan los usuarios en Turnos de acuerdo con las reglas de negocio aplicadas por el sistema de WFM antes de que los cambios se escriban en Turnos.

Nota:

Si usa UKG Pro WFM, Blue Yonder WFM o Reflexis WFM, también puede usar un conector administrado para integrar Shifts con el sistema de WFM. Para obtener más información, consulte Shifts connectors (Conectores de turnos).

Terminología usada en este artículo

Término	Descripción
conector	Aplicación que sincroniza los datos de programación entre el sistema de WFM y Turnos.
integración de la fuerza de trabajo	Entidad que define el método de cifrado para la comunicación, la dirección URL de devolución de llamada del conector y las entidades Shifts que se van a sincronizar.

Antes de empezar

Requisitos previos

• Determine qué datos desea sincronizar según sus necesidades empresariales.
• Comprenda los conceptos de autenticación y autorización en el Plataforma de identidad de Microsoft. Consulte Conceptos básicos de autenticación y autorización.
• Administración roles necesarios:
  • Al menos un administrador de aplicaciones en la nube para registrar una aplicación en el Centro de administración Microsoft Entra
  • Administrador global para registrar la integración del personal

Familiarizarse con el proceso de integración

Esta es una introducción a los pasos de integración. Revise esta información para comprender el proceso general, incluido quién realiza cada paso.

Paso	Sincronización unidireccional	Sincronización bidireccional	Quién realiza este paso
1	Cree el conector: Paso 1a: Sincronización de los cambios realizados en Cambios en el sistema de WFM Implementación del punto de conexión /connect Implementación del punto de conexión /update y creación de turnos de solo lectura Paso 1b: Sincronización de datos del sistema de WFM a turnos	Cree el conector: Paso 1a: Sincronización de los cambios realizados en Cambios en el sistema de WFM Implementación del punto de conexión /connect Implementación del punto de conexión /update Paso 1b: Sincronización de datos del sistema de WFM a turnos	Developer
2	Registro de una aplicación en el Centro de administración Microsoft Entra	Registro de una aplicación en el Centro de administración Microsoft Entra	Una cuenta que sea al menos administrador de aplicaciones en la nube
3	Creación de equipos y programaciones para la sincronización	Creación de equipos y programaciones para la sincronización	Desarrollador o administrador de Teams
4	Registrar y habilitar la integración de los empleados: Paso 4a: Registro de la integración del personal en el inquilino Paso 4b: Habilitación de la integración del personal para las programaciones del equipo	Registrar y habilitar la integración de los empleados: Paso 4a: Registro de la integración del personal en el inquilino Paso 4b: Habilitación de la integración del personal para las programaciones del equipo	Paso 4a: Administrador global Paso 4b: Desarrollador

Paso 1: Crear el conector

Para crear el conector, siga estos pasos:

• Paso 1a: Sincronizar los cambios realizados en Cambios en el sistema de WFM
• Paso 1b: Sincronización de datos del sistema de WFM a turnos

Paso 1a: Sincronizar los cambios realizados en Cambios en el sistema de WFM

Para configurar el conector para recibir y procesar solicitudes de Shifts, debe implementar los siguientes puntos de conexión:

• /connect (obligatorio)
• /update (obligatorio)
• /read (opcional)

Determinación de la dirección URL base y las direcciones URL del punto de conexión

La dirección URL base (webhook) es {url}/v{apiVersion}, donde url y apiVersion son las propiedades que se establecen en el objeto workforceIntegration al registrar la integración de workforce.

Las rutas de acceso relativas de las direcciones URL del punto de conexión son las siguientes:

• /conectar: /connect
• /actualizar: /teams/{teamid}/update
• /leer: /teams/{teamid}/read

Por ejemplo, si url es https://contosoconnector.com/wfi y apiVersion es 1:

• La dirección URL base es https://contosoconnector/com/wfi/v1.
• El punto de conexión /connect es https://contosoconnector/wfi/v1/connect.
• El punto de conexión /update es https://contosoconnector/wfi/v1/teams/{teamid}/update.
• El punto de conexión /read es https://contosoconnector/wfi/v1/teams/{teamid}/read.

Cifrado

Todas las solicitudes se cifran mediante AES-256-CBC-HMAC-SHA256. Especifique la clave secreta compartida al registrar la integración del personal. Las respuestas enviadas de vuelta a los turnos no deben cifrarse.

Puntos de conexión

POST /connect

Los turnos llaman a este punto de conexión para probar la conexión al registrar la integración del personal. Solo se devuelve una respuesta correcta si este punto de conexión devuelve una respuesta HTTP 200 OK .

Ejemplo

Solicitud
ConnectRequest

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

Respuesta
Devolver HTTP 200 OK

POST /teams/{teamid}/update

Shifts llama a este punto de conexión para obtener aprobación cuando se realiza un cambio en una entidad Shifts en una programaciónhabilitada para la integración del personal. Si este punto de conexión aprueba la solicitud, el cambio se guarda en Turnos.

Como el sistema de WFM es el sistema de registro, cuando el conector recibe una solicitud a este punto de conexión, primero debe intentar realizar el cambio en el sistema de WFM. Si el cambio se realiza correctamente, devuelve correcto. De lo contrario, devuelve un error.

Shifts llama a este punto de conexión para cada cambio (incluidos los cambios iniciados desde el sistema de WFM o conector). Si el conector envió una actualización a Shifts mediante Graph API y agregó el X-MS-WFMPassthrough: workforceIntegratonId encabezado, la solicitud que llega a este punto de conexión tendrá el mismo encabezado, lo que le permite identificar y controlar estas solicitudes correctamente. Por ejemplo, devolver éxito sin realizar el mismo cambio en el sistema de WFM como sería redundante y puede hacer que el conector se bloquee en un bucle infinito.

En el diagrama siguiente se muestra el flujo de datos.

Nota:

Para obtener más información sobre los modelos de solicitud y respuesta, consulte WfiRequest en la sección Referencia del punto de conexión de este artículo.

Devolver código de respuesta
Cualquier respuesta de la integración, incluido un error, debe tener un código 200 OKde respuesta HTTP . El cuerpo de la respuesta debe tener el estado y el mensaje de error que reflejen el estado de error de subllamada adecuado. Cualquier respuesta de la integración que no 200 OK sea se trata como un error y se devuelve al autor de la llamada (cliente o Microsoft Graph).

Si desea configurar una sincronización unidireccional, haga turnos de solo lectura

Para una sincronización unidireccional, debe realizar turnos de solo lectura para que los usuarios no puedan realizar cambios en Turnos. Para realizar turnos de solo lectura, devuelva una respuesta de error para todas las solicitudes de Turnos.

Por ejemplo, para impedir que los usuarios realicen cambios en los turnos de la programación, este punto de conexión debe devolver una respuesta de error cada vez que recibe una solicitud con respecto a una shift entidad.

Ejemplo

Solicitud
WfiRequestContainer

En el ejemplo siguiente se muestra una solicitud de Shifts que pregunta si un desplazamiento, cuyo identificador es SHFT_12345678-1234-1234-1234-1234567890ab y tiene las propiedades enumeradas en el cuerpo, se puede guardar en Turnos. Esta solicitud se desencadenó cuando un usuario crea un turno en 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"
      }
    }
  ]
}

Respuesta
WfiResponse

Correcto: Devolver HTTP 200 OK

En este ejemplo se muestra la respuesta devuelta si el punto de conexión aprobó la solicitud. En este escenario, el desplazamiento se guarda en Turnos y el usuario puede ver el desplazamiento en la programación.

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

Error: devolver HTTP 200 OK

En este ejemplo se muestra la respuesta devuelta si el punto de conexión denegó la solicitud. En este escenario, el usuario recibe un mensaje de error "No se pudo agregar el desplazamiento" en 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 punto de conexión controla las solicitudes de Turnos para capturar los motivos de tiempo de espera válidos o los turnos aptos para las solicitudes de intercambio de un usuario.

Nota:

A partir de octubre de 2024, este punto de conexión solo se admite en la versión beta de Microsoft Graph API. También debe especificar valores para la propiedad eligibilityFilteringEnabledEntities al registrar la integración del personal.

En el diagrama siguiente se muestra el flujo de datos.

Devolver código de respuesta
Cualquier respuesta de la integración, incluido un error, debe tener un código 200 OKde respuesta HTTP . El cuerpo de la respuesta debe incluir el estado y el mensaje de error que reflejan el estado de error de subllamada adecuado. Cualquier respuesta de la integración que no 200 OK sea se trata como un error y se devuelve al autor de la llamada (cliente o Microsoft Graph).

Ejemplo: TimeOffReason

Solicitud

En el ejemplo siguiente se muestra una solicitud de Shifts que pregunta para qué motivos de tiempo de espera puede optar un usuario (id. de usuario aa162a04-bec6-4b81-ba99-96caa7b2b24d). Esta solicitud se desencadenó cuando el usuario solicita tiempo de expiración en turnos.

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

Respuesta
Correcto: Devolver HTTP 200 OK

La siguiente respuesta muestra que los identificadores de motivo de tiempo de espera válidos para el usuario son "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" y "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d". En este escenario, el usuario ve los motivos de tiempo de expiración correspondientes entre los que elegir en 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 
          } 
        }
    ]
}

Error: devolver HTTP 200 OK

En este ejemplo, se devuelve una respuesta de error porque el conector no pudo llegar al sistema de WFM para recuperar los motivos de tiempo de espera para el usuario.

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

Ejemplo: SwapRequest

Solicitud

En el ejemplo siguiente se muestra una solicitud de Shifts que pregunta qué turnos son aptos para un intercambio con el turno cuyo identificador es SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 entre 2024-2024 10-01T04:00:00.0000000Z y 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"
    }
  ]
}

Respuesta
Correcto: Devolver HTTP 200 OK

La respuesta siguiente muestra que el desplazamiento se puede intercambiar con el turno cuyo identificador es 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, 
      } 
    }
  ]
}

Error: devolver HTTP 200 OK

En este ejemplo, se devuelve una respuesta de error porque el conector no pudo llegar al sistema WFM para recuperar los turnos aptos para una solicitud de intercambio para el usuario.

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

Paso 1b: Sincronización de datos del sistema de WFM a turnos

Use las API shifts de Microsoft Graph para leer los datos de programación del sistema de WFM y escribir los datos en Turnos.

Por ejemplo, para agregar un desplazamiento a Shifts, use la API Create shift .

Consulte la referencia de Microsoft Graph API v1.0 para las API de turnos, que se muestran en Administración de turnos.

Nota:

El MS-APP-ACTS-AS encabezado es necesario en las solicitudes y debe contener el identificador (GUID) del usuario del que actúa la aplicación en nombre de . Se recomienda usar el identificador de usuario de un propietario del equipo al actualizar la programación.

En el diagrama siguiente se muestra el flujo de datos.

Sincronización inicial

Para la primera sincronización, el conector debe leer los datos del sistema de WFM y escribir los datos en Turnos. Se recomienda sincronizar dos semanas de datos futuros.

Después de la sincronización inicial

Después de la primera sincronización, puede elegir:

• Actualizar sincrónicamente Turnos con cambios en el sistema de WFM: envíe una actualización a Turnos para cada cambio realizado en el sistema de WFM.

• Actualización asincrónica de Turnos con cambios en el sistema de WFM: realice una sincronización periódica escribiendo todos los cambios que se produjeron en el sistema de WFM en un período de tiempo determinado (por ejemplo, 10 minutos) en Turnos.

  Todas las operaciones de escritura en Shifts, incluidas las operaciones de escritura iniciadas por el conector, desencadenan una llamada al punto de conexión /update del conector. Se recomienda incluir el X-MS-WFMPassthrough: workforceIntegratonId encabezado en todas las llamadas de escritura para que el conector pueda identificarlas y controlarlas correctamente. Por ejemplo, si el sistema de WFM inició el cambio, aprobándolo sin aplicar una actualización al sistema de WFM.

  Nota:

  Si va a configurar el conector para una sincronización bidireccional de datos entre el sistema de WFM y Shifts, excluya los cambios iniciados desde Turnos en la sincronización periódica. Estos cambios ya están escritos en Turnos.

Paso 2: Registro de una aplicación en el Centro de administración Microsoft Entra

Siga estos pasos para registrar una aplicación para el conector en el Plataforma de identidad de Microsoft, configurar permisos para que la aplicación acceda a Microsoft Graph y obtener un token de acceso.

1. Inicie sesión en el Centro de administración Microsoft Entra como al menos un administrador de aplicaciones en la nube.

2. Registrar la aplicación. Para ver los pasos, consulte Registro de una aplicación con el Plataforma de identidad de Microsoft.

3. Asigne los permisos de aplicaciónSchedule.ReadWrite.All a la aplicación para el acceso solo a la aplicación y obtenga un token de acceso.

   Para obtener instrucciones paso a paso, consulte Obtención de acceso sin un usuario.

   El token de acceso comprueba que la aplicación está autorizada para llamar a Microsoft Graph mediante su propia identidad mediante el permiso Schedule.ReadWrite.All . Debe incluirse en el encabezado de autorización de las solicitudes.

Paso 3: Crear equipos y programaciones para la sincronización

Configure los equipos de Teams que desea sincronizar. Puede usar los equipos existentes o crear nuevos equipos.

1. Configure equipos en Teams para que se correspondan con los equipos y las ubicaciones del sistema de WFM. Asegúrese de agregar las siguientes personas a cada equipo:

   • Administradores de primera línea como propietarios del equipo. Asegúrese de agregar el usuario en el MS-APP-ACTS-AS encabezado como propietario del equipo de cada equipo respectivo.
   • Trabajadores de primera línea como miembros del equipo.

2. Cree una programación en Turnos para cada equipo. Para obtener más información, consulte Crear o reemplazar programación.

3. Agregue grupos de programación a la programación de cada equipo. Los grupos de programación se usan para agrupar empleados en función de las características comunes dentro de un equipo. Por ejemplo, los grupos de programación pueden ser departamentos o tipos de trabajo. Para obtener más información, consulte Tipo de recurso schedulingGroup.

4. Agregue empleados a cada grupo de programación. Para obtener más información, consulte Reemplazar schedulingGroup.

Nota:

También puede usar el Centro de administración de Teams para configurar los equipos e implementar turnos en los equipos. Para más información, vea:

• Implementación de equipos dinámicos de primera línea a escala
• Implementar turnos en los equipos de primera línea a escala

Paso 4: Registro y habilitación de la integración del personal

Una integración del personal define la configuración de cifrado para la comunicación entre los turnos y el conector, la dirección URL de las devoluciones de llamada de los turnos y los tipos de entidades que se van a sincronizar.

Para registrar y habilitar la integración del personal, siga estos pasos:

• Paso 4a: Registro de la integración del personal
• Paso 4b: Habilitación de la integración del personal para las programaciones del equipo

Paso 4a: Registro de la integración del personal en el inquilino

Debe ser administrador global para realizar este paso.

Use create workforceIntegration API para registrar la integración de los empleados en el inquilino.

Este es un ejemplo de una solicitud.

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 la tabla siguiente para obtener más información. Para obtener más información, consulte tipo de recurso workforceIntegration.

Propiedad	Más información
apiVersion	Versión de API para la dirección URL de devolución de llamada. La dirección URL base se compone de la propiedad url y esta propiedad.
cifrado	Establezca el protocolo en sharedSecret. El valor del secreto debe tener exactamente 64 caracteres. Use el secreto para descifrar las cargas JSON cifradas que se envían al punto de conexión del conector desde Turnos. La carga se cifra mediante AES-256-CBC-HMAC-SHA256. La aplicación debe conservar este secreto de forma segura. Por ejemplo, en un almacén de claves.
supportedEntities	Especifique las entidades Shifts que desea que el conector admita para la sincronización. Shifts llama al punto de conexión /update del conector cuando cualquiera de estas entidades cambia para que pueda aprobar o rechazar el cambio. Para obtener la lista de los valores posibles, consulte workforceIntegration resource type (Tipo de recurso workforceIntegration) Nota Esta lista es una enumeración evolvable. Debe usar el encabezado de Prefer: include-unknown-enum-members solicitud para obtener todos los valores.
eligibilityFilteringEnabledEntities	Nota: A partir de octubre de 2024, este punto de conexión solo se admite en la versión beta de Microsoft Graph API. Especifique las entidades Shifts que desea admitir para el filtrado de idoneidad. Los posibles valores son: none: lista vacía SwapRequests: Shifts llama al punto de conexión /read del conector para obtener una lista filtrada de turnos entre los que un usuario puede elegir para una solicitud de intercambio. TimeOffReasons: shifts llama al punto de conexión /read del conector para obtener una lista filtrada de los motivos por los que un usuario puede elegir cuando solicita el tiempo de expiración. Nota Esta lista es una enumeración evolvable. Debe usar el encabezado de Prefer: include-unknown-enum-members solicitud para obtener todos los valores.
url	Dirección URL de integración del personal para las devoluciones de llamada de Shifts. La dirección URL base está formada por esta propiedad y la propiedad apiVerson .

Paso 4b: Habilitación de la integración del personal para las programaciones del equipo

Habilite la integración de los empleados en las programaciones que desea administrar. Para ello, use la API Crear o reemplazar programación para crear o actualizar la programación de los equipos.

Este es un ejemplo de una solicitud.

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}

• Especifique el valor de workforceIntegrationId que se generó al registrar la integración del personal.
• Puede habilitar un máximo de una integración del personal según una programación. Si incluye más de un elemento workforceIntegrationId en la solicitud, se usa el primero.

Solución de problemas

Connector

Cuando el conector responde a una solicitud de Shifts, ¿qué ocurre si devuelve un código de respuesta distinto de 200? ¿Hace una diferencia si devuelve un estado distinto de 200 en el cuerpo de la respuesta?

Hay una diferencia entre estos dos escenarios.

• Si el conector devuelve un código de respuesta distinto de 200, Shifts intenta reintentar los puntos de conexión /read y /update varias veces. Con el tiempo, Shifts muestra un mensaje "Algo salió mal. La configuración de integración del personal en el equipo ha respondido con datos no válidos." mensaje de error.
• Si el conector devuelve un estado distinto de 200 en el cuerpo de la respuesta, Shifts muestra un mensaje "Algo salió mal. Lo sentimos, no se pudo completar el cambio", mensaje de error y deja de reintentar los puntos de conexión.

¿Qué ocurre si el conector devuelve datos no válidos en el cuerpo de la respuesta?

Los turnos intentan reintentar los puntos de conexión /read y /update varias veces. Con el tiempo, Shifts muestra un mensaje "Algo salió mal. La integración del personal configurada en el equipo ha respondido con datos no válidos".

Cómo identificar si la solicitud se realizó originalmente en Shifts o en el sistema WFM para evitar un bucle infinito?

Agregue el X-MS-WFMPassthrough: workforceIntegratonId encabezado a todas las llamadas de escritura y actualización para identificar o omitir los cambios desencadenados por el conector. Este encabezado se usa para indicar que la solicitud se realiza debido a una llamada anterior realizada por el conector para Graph API sincronizar los datos del sistema de WFM con Shifts.

Registro de integración de workforce

Registré la integración del personal y especificé "eligibilityFilteringEnabledEntities" incluyendo "SwapRequest, OfferShiftRequest y TimeOffReason", pero el cuerpo de la respuesta no muestra la lista "eligibilityFilteringEnabledEntities".

Actualmente, el filtrado de idoneidad se admite a través del https://graph.microsoft.com/beta punto de conexión, no del punto de https://graph.microsoft.com/v1 conexión.

He registrado la integración de la fuerza de trabajo y he agregado "supportedEntities", pero recibo una respuesta de solicitud incorrecta 400 y una "Carga no válida: valor solicitado 'shift, ....' no se encontró".

Asegúrese de que cada entidad Shifts del cuerpo de la supportedEntities solicitud de lista comienza con una letra mayúscula. Por ejemplo, "supportedEntities":"Shift,SwapRequest,OpenShift".

Registré la integración del personal e implementé los puntos de conexión /connect, /update y /read, pero el webhook no funciona.

Asegúrese de que la integración de los empleados está habilitada para la programación del equipo. Además, compruebe que las propiedades url y apiVersion son correctas.

Referencia de punto de conexión

Solicitud

ConnectRequest

Propiedad	Tipo	Descripción
tenantId	Cadena	Identificador del inquilino para la integración del personal
userId	Cadena	Identificador del usuario para la integración del personal

{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

Propiedad	Tipo	Descripción
Solicitudes	Colección 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 de una solicitud:

• En la mayoría de los casos, una solicitud tiene un elemento.
• Algunas solicitudes, como las aprobaciones de solicitudes de cambio de turno, tienen cinco elementos: una solicitud de intercambio PUT, dos turnos DELETE (turnos existentes) y dos turnos POST (nuevos turnos).

WfiRequest

Propiedad	Tipo	Descripción
id	Cadena	Identificador de la entidad
método	Cadena	Método invocado en el elemento. Por ejemplo, POST, PUT, GET, DELETE.
URL	Cadena	Indica el tipo de entidad y los detalles de la operación.
encabezados	WfiRequestHeader	Encabezados
body	ShiftsEntity	Cuerpo de la entidad relacionada con la solicitud.

Para POST /teams/{teamId}/update

Propiedad	Tipo	Descripción
id	Cadena	Identificador de la entidad
método	Cadena	POST para crear una entidad, PUT para actualizar una entidad, DELETE para eliminar una entidad.
URL	Cadena	El formato es /{EntityType}/{EntityId}. Los valores posibles para {EntityType} son shifts, swapRequests, timeoffReasons, openshifts, openshiftrequests, offershiftrequests, , timesofftimeOffRequests. Por ejemplo, /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.
encabezado	WfiRequestHeader	Encabezado
body	ShiftsEntity	Debe coincidir {EntityType} en la propiedad url . Use uno de shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest. Por ejemplo, /shifts/SHFT_12345678-1234-1234-1234-1234567890ab.

Para POST /teams/{teamsId}/read

Propiedad	Tipo	Descripción
id	Cadena	Identificador de la entidad
método	Cadena	Siempre es GET.
URL	Cadena	TimeOffReasons: el formato es /users/{userId}/timeOffReasons?requestType=TimeOffReason. Por ejemplo, /users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason. SwapRequest: el formato es /shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}. Por ejemplo, shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z.
encabezado	WfiRequestHeader	Encabezado
body	ShiftsEntity	Siempre es null.

WfiRequestHeader

Propiedad	Tipo	Descripción
X-MS-Transaction-ID	Cadena	Identificador de transacción
X-MS-Expires	String (DateTime)	Fecha y hora de expiración de la transacción

X-MS-WFMPassthrough: workforceIntegratonId no se incluirá en WfiRequestHeader. Debe extraerse de HttpRequest.

Respuesta

WfiResponseContainer

Propiedad	Tipo	Descripción
Respuestas	Colección WfiResponse	Lista de WfiResponses

{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

Propiedad	Tipo	Descripción
id	Cadena	Identificador de la entidad
status	Cadena	Resultado de la operación
body	WfiResponseBody	WfiResponseBody

WfiResponseBody

Propiedad	Tipo	Descripción
eTag	String	eTag
error	WfiResponseError	Detalles sobre el error
data	Cadena	Los datos solicitados (para solicitudes de lectura)

WfiResponseError

Propiedad	Tipo	Descripción
código	Cadena	Código de error
message	String	Mensaje de error

Artículos relacionados

• Turnos para la organización de primera línea
• Conectores de Turnos