Importación de datos de la organización mediante la importación basada en API (primera importación) (versión preliminar)

Los datos de la organización pueden aparecer en la aplicación web Viva Insights de una de estas tres maneras: a través de Microsoft Entra ID, que es el origen predeterminado; a través de archivos de .csv individuales que el administrador de Insights carga directamente en Viva Insights, o a través de una importación de datos basada en API que usted, el administrador del sistema de origen y la configuración del administrador de TI de Microsoft 365.

En este artículo se habla de la tercera opción, importar datos.

Con una importación, puede traer datos del sistema de origen a la API de entrada de datos de RR. HH. de Viva Insights a través de un archivo ZIP. Puede:

• Cree una aplicación personalizada para exportar datos del sistema de origen a un archivo ZIP. A continuación, con la misma aplicación, importe esos datos mediante la información de API siguiente.
• Cree una aplicación personalizada para exportar datos del sistema de origen a un archivo ZIP. A continuación, ejecute una aplicación de consola de C# que hemos creado para importar datos a Viva Insights.
• Cree una aplicación personalizada para exportar datos del sistema de origen a un archivo ZIP. A continuación, ejecute un script de PowerShell que hemos creado para importar datos a Viva Insights.
• Use nuestra plantilla de Azure Data Factory (ADF) para enviar datos a nuestra importación basada en API.

Sin embargo, antes de poder ejecutar la aplicación y empezar a transferir datos a Viva Insights, debe coordinar algunas tareas entre el administrador de Microsoft 365 y el administrador de Insights (administrador de Insights). Consulte Flujo de trabajo para obtener información general sobre los pasos necesarios.

Flujo de trabajo

1. Configuración:

   1. El administrador del origen de datos genera un certificado de seguridad y lo proporciona al administrador de Microsoft 365.
   2. Con el certificado de seguridad, el administrador de Microsoft 365 registra una nueva aplicación en Azure.
   3. Con los identificadores del registro de la aplicación, el administrador de Insights configura la importación.
   4. El administrador del origen de datos prepara sus datos y:
      1. Lo exporta desde su sistema de origen mediante una aplicación personalizada basada en nuestra API y, a continuación, con la misma aplicación, importa los datos a Viva Insights.
      2. Lo exporta desde su sistema de origen mediante una aplicación personalizada basada en nuestra API y, a continuación, con nuestra solución de C# o script de PowerShell, importa los datos a Viva Insights.

   

2. Validación: Viva Insights valida los datos. (Si la validación no se realiza correctamente, puede elegir entre algunas opciones descritas en Error de validación).

3. Procesamiento: Viva Insights procesa los datos. (Si el procesamiento no se realiza correctamente, puede elegir entre algunas opciones descritas en Error de procesamiento).

Una vez que los datos se validan y procesan correctamente, se completa la tarea de importación de datos general.

Instalación

Generación del certificado de seguridad

Se aplica a: administrador del origen de datos

Para empezar a obtener datos del archivo de origen en Viva Insights, el administrador de Microsoft 365 debe crear y registrar una aplicación en Azure. Como administrador del origen de datos, debe ayudar al administrador de Microsoft 365 a registrar su aplicación proporcionándole un certificado de seguridad.

Esto es lo que debe hacer:

1. Cree un certificado siguiendo las instrucciones de este artículo: Creación de un certificado público autofirmado para autenticar la aplicación
2. Envíe el certificado generado al administrador de Microsoft 365.

Eso es todo por ahora. Si desea obtener una ventaja en los pasos siguientes, siga los pasos descritos en Exportación de los datos con una frecuencia establecida.

Registro de una nueva aplicación en Azure

Se aplica a: Administrador de Microsoft 365

1. En el carril izquierdo del Centro de administración de Microsoft, seleccione Todos los centros de administración. Esta opción aparece como la última de la lista.

   

2. Seleccione Microsoft Entra ID.

3. Cree un nuevo registro de aplicación:

   1. En la barra de herramientas superior, seleccione Agregar > registro de aplicación.

      

   2. En la pantalla resultante:

      1. Asigne un nombre a la aplicación.
      2. En Tipos de cuenta admitidos, deje la primera opción, Solo cuentas en este directorio organizativo ([Solo su organización] - Inquilino único) seleccionada.
      3. Seleccione el botón Registrar en la parte inferior de la pantalla.

      

   3. Cuando vuelva a la pantalla Información general, copie el identificador de aplicación (cliente) y el identificador de directorio (inquilino).

      

      Importante

      Mantenga estos identificadores a mano. Tendrá que proporcionarlos más adelante.

4. Agregar un certificado:

   1. Seleccione Agregar un certificado o secreto.

      

   2. Seleccione Cargar certificado.

      

   3. Cargue el certificado que le proporcionó el administrador del origen de datos y agregue una descripción. Seleccione el botón Agregar.

      

5. Quitar permisos de API:

   1. Seleccione Permisos de API en el carril izquierdo.

   2. Para cada nombre de API o permisos enumerado, seleccione los puntos suspensivos (...) a la derecha de la API, por ejemplo, Microsoft Graph.

   3. Seleccione Quitar permiso.

      

   4. Confirme la eliminación.

   Al quitar permisos para estos elementos, se asegura de que la aplicación solo tenga permisos para lo que necesita.

6. Comparta los identificadores que anotó en el paso 3c:

   1. Asigne al administrador de Insights el identificador de la aplicación.
   2. Asigne al administrador del origen de datos el identificador de la aplicación y el identificador de inquilino.

Configuración de la importación en Viva Insights

Se aplica a: Administrador de Insights

1. Inicie la importación desde uno de los dos lugares: la página Centro de datos o la página Datos de la organización , en Conexiones de datos.

   1. Desde el centro de datos:

      1. En la sección Origen de datos , busque la opción de importación basada en API . Haga clic en el botón Inicio.

   2. Desde Conexiones de datos:

      1. Junto a Origen actual, seleccione el botón Orígenes de datos .

      2. Aparece una ventana Cambiar a: importación basada en API . Seleccione Inicio.

2. En la página de importación de datos de la organización basada en API :

   1. Asigne un nombre a la conexión.

   2. Escriba el identificador de aplicación que le proporcionó el administrador de Microsoft 365.

   3. Guardar.

3. Seleccione la conexión que anominó en el paso 3a como nuevo origen de datos.

4. Póngase en contacto con el administrador del origen de datos y solicite que envíe datos de la organización a Viva Insights.

Preparación, exportación e importación de datos de la organización

Sugerencias para preparar los datos

• Para los nuevos datos, incluya datos históricos completos para todos los empleados.
• Importe los datos de la organización para todos los empleados de la empresa, incluidos los empleados con licencia y sin licencia.
• Consulte la plantilla de .csv de ejemplo para obtener instrucciones y estructura de datos para evitar problemas comunes, como demasiados o demasiados valores únicos, campos redundantes, formatos de datos no válidos, etc.

Exportación de los datos con una frecuencia establecida

Con la frecuencia que decidas (una vez al mes, una vez a la semana, etc.) hacer que la aplicación personalizada exporte los datos de la organización desde el sistema de origen como una carpeta zip y guárdalos en los archivos. Base esta carpeta zip en la que se encuentra aquí. La carpeta zip debe contener un archivo data.csv y un archivo metadata.json.

Estos son algunos detalles más sobre estos archivos y lo que deben contener:

data.csv

Agregue todos los campos que desea importar en este archivo. Asegúrese de darle formato de acuerdo con nuestras directrices en Preparación de datos de la organización.

metadata.json

Indique el tipo de actualización que está realizando y cómo debe asignar Los campos a Viva Insights:

• "DatasetType": "HR" (línea 2). Déjelo tal como está.
• "IsBootstrap": (línea 3). Use "true" para indicar una actualización completa e "false" indicar una actualización incremental.
• "ColumnMap":. Si usa nombres distintos de los que usa Viva Insights, cambie cada nombre de encabezado de columna para que coincida con lo que usa en el sistema de origen.

Ejemplo de asignación

En el ejemplo siguiente se representa un campo en el archivo metadata.json:

"PersonId": {
    "name": "PersonId",
    "type": "EmailType"

• "PersonId": { corresponde al nombre de la columna de origen.
• “name” : “PersonId”, corresponde al nombre del campo Viva Insights.
• "type": "EmailType" corresponde al tipo de datos del campo.

Supongamos que en lugar de , el sistema de PersonIdorigen usa Employee para este encabezado de campo. Para asegurarse de que los campos están asignados correctamente, edite la primera línea siguiente para que tenga este aspecto:

      "Employee": {
        "name": "PersonId",
        "type": "EmailType"

Al cargar los datos, el Employee campo se convierte PersonId en Viva Insights.

Importación de los datos

Para importar los datos a Viva Insights, puede elegir entre cuatro opciones:

• Use nuestra API para crear una aplicación personalizada que exporte e importe los datos con la frecuencia que elija. Más información.
• Ejecute nuestra solución de C# en la consola, que se basa en nuestra API. Más información.
• Ejecute el script de PowerShell, que también se basa en nuestra API. Más información.
• Use nuestra plantilla de Azure Data Factory (ADF) para enviar datos a nuestra importación basada en API. Más información.

Antes de trabajar con cualquiera de las opciones siguientes, asegúrese de que tiene esta información:

• Identificador de aplicación (cliente). Busque este identificador en la información de la aplicación registrada en la Azure Portal en Id. de aplicación (cliente).
• Secreto de cliente: se trata de una cadena secreta que la aplicación usa para demostrar su identidad al solicitar un token. También se conoce como contraseña de aplicación. Este secreto solo se muestra por primera vez cuando se crea el secreto de cliente. Para crear un nuevo secreto de cliente, consulte Creación de una aplicación Microsoft Entra y una entidad de servicio en el portal.
• Nombre del certificado. Este nombre se configura en la aplicación registrada. Después de cargar el certificado, el nombre del certificado aparece en Descripción en Azure Portal. Puede usar el nombre del certificado como alternativa al secreto de cliente.
• El archivo zip y la ruta de acceso al archivo zip. No cambie los nombres de archivo data.csv y metadata.json.
• Microsoft Entra identificador de inquilino. Busque también este identificador en la página de información general de la aplicación en Id. de directorio (inquilino).
• Unidad de escalado: la unidad de escalado que se le proporciona para el inquilino, por ejemplo, novaprdwus2-01.

Acerca de la API de entrada de datos de RR. HH. de Viva Insights

Vea los siguientes comandos:

[Encabezados de solicitud]

Estos dos encabezados de solicitud son necesarios para todas las API mencionadas a continuación

x-nova-scaleunit: <ScaleUnit obtained from Insights setup connection page>

Authentication: Bearer <Oauth token from AAD>

Obtención de un conector o ping para comprobar si el conector está establecido para un inquilino

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/HR

[ResponseBody]

Si se establece el conector y se concede autorización a la aplicación de llamador (id):

200:  

{ 
       “ConnectorId”: “Connector-id-guid” 

}

Si el administrador de Insights ha quitado el conector o, el administrador de Insights aún no ha establecido el conector:

403: Forbidden.

Insertar datos

Aplicación de encuesta 1P/3P para llamar a Viva Insights API para insertar contenido

[POST] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/HR/ingestions/fileIngestion

[Cuerpo] contenido del archivo como multipart/form-data

Tipo: Archivo zip

Contenido que se va a archivar:

Metadata.json

Data.csv

[Cuerpo de la solicitud]

Body: 

{ 

   "$content-type": "multipart/form-data", 

   "$multipart":  

    [ 

        { 

            "headers":  

                { 

                    "Content-Disposition": "form-data; name=\"file\"; filename=info" 

                   }, 

            "body": @{body('Get_blob_content_(V2)')} 

         } 

    ] 

} 

[Cuerpo de la respuesta]

200:  
{ 

  "FriendlyName": "Data ingress", 

  "Id": "<ingestion Id>", 

  "ConnectorId": "<connector Id>", 

  "Submitter": "System", 

  "StartDate": "2023-05-08T19:07:07.4994043Z", 

  "Status": "NotStarted", 

  "ErrorDetail": null, 

  "EndDate": null, 

  "Type": "FileIngestion" 

} 

En caso de que no se establezca el conector:

403: Forbidden

Si el conector está establecido pero la ingesta anterior aún no está completa:

400: Bad request: Previous ingestion is not complete.

Estado de sondeo

API para sondear el estado de la ingesta, ya que la ingesta de datos es una operación de larga duración.

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/Hr/ingestions/fileIngestion/{ingestionId:guid}

[Respuesta]

200: 
{ 

            "FriendlyName": "Data ingress", 

            "Id": "<ingestion Id>", 

            "ConnectorId": "<connector Id>", 

            "Submitter": "System", 

            "StartDate": "2023-05-08T19:05:44.2171692Z", 

            		  "Status": "NotStarted/ExtractionComplete/ValidationFailed 

/Completed/", 

            "ErrorDetail": null, 

            "EndDate": "2023-05-08T20:09:18.7301504Z", 

            "Type": "FileIngestion" 

}, 

Descargar la secuencia de errores si se produce un error en la validación (problema en los datos)

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>//Hr/ingestions/{ingestionId}/errors

[Respuesta]

200: File stream with errors, if any.

Opción 1: Usar la API de entrada de datos de RR. HH. de Viva Insights para crear una aplicación personalizada de importación y exportación

Puede usar la API de entrada de datos de RR. HH. de Viva Insights para crear una aplicación personalizada que exporte automáticamente los datos del sistema de origen y, a continuación, los importe a Viva Insights.

La aplicación puede tomar cualquier forma(por ejemplo, un script de PowerShell), pero debe exportar los datos de origen como una carpeta zip con la frecuencia que elija, almacenar la carpeta en los archivos e importar esa carpeta en Viva Insights.

Opción 2: Importar datos a través de nuestra solución de C# después de exportar datos a través de la aplicación personalizada

Después de exportar los datos de origen como una carpeta zip con la frecuencia que elija y almacenar esa carpeta en los archivos, puede ejecutar la solución DescriptiveDataUploadApp C# en la consola. A continuación, la solución DescriptDataUploadApp C# lleva los datos almacenados localmente a Viva Insights. Obtenga más información en GitHub.

Para ejecutar la solución:

1. Clone esta aplicación en el equipo ejecutando el siguiente comando en la línea de comandos:

   git clone https://github.com/microsoft/vivainsights_ingressupload.git.

2. Incluya los siguientes valores de consola. Consulte Preparación, exportación e importación de datos de la organización para obtener descripciones.

   • AppID/ClientID
   • Ruta de acceso absoluta al archivo comprimido. Dé formato a la ruta de acceso de la siguiente manera: C:\\Users\\JaneDoe\\OneDrive - Microsoft\\Desktop\\info.zip
   • Microsoft Entra identificador de inquilino
   • Nombre del certificado

Opción 3: Ejecutar la solución de PowerShell DescriptiveDataUpload después de exportar datos a través de la aplicación personalizada

De forma similar a la opción 2, después de exportar los datos de origen como una carpeta zip con la frecuencia que elija y almacenar esa carpeta en los archivos, puede ejecutar la solución de PowerShell DescriptiveDataUpload en la consola. A continuación, la solución de PowerShell DescriptiveDataUpload lleva los datos almacenados localmente a Viva Insights. Obtenga más información en GitHub.

1. Clone el código fuente en la máquina mediante la ejecución de este comando en la línea de comandos:

   git clone https://github.com/microsoft/vivainsights_ingressupload.git

2. Abra una nueva ventana de PowerShell como administrador.

3. En la ventana de PowerShell, ejecute el siguiente comando:

   Install-Module -Name MSAL.PS

   O bien, vaya a este vínculo de la galería de PowerShell para obtener instrucciones sobre la instalación.

4. Establecer parámetros. Consulte Preparación, exportación e importación de datos de la organización para obtener descripciones.

   • ClientID
   • pathToZippedFile
   • TenantId
   • novaScaleUnit
   • ingressDataType: HR
   • ClientSecret o certificateName

Opción 4: Usar nuestra plantilla de Azure Data Factory (ADF) para enviar datos a nuestra importación basada en API

1. Crear Azure Data Factory

1. Inicie sesión en https://adf.azure.com/en/datafactories.

2. Cree una nueva factoría de datos o use una factoría de datos existente. Complete los campos y, a continuación, seleccione Crear.

   

2. Creación de una nueva canalización y actividad

1. Cree una nueva canalización y escriba un nombre para la canalización.

   

2. En Actividades, agregue Copiar datos.

   

3. Configuración de la actividad de copia de datos: General

Seleccione la actividad Copiar datos y, a continuación, seleccione General para completar cada campo siguiendo las instrucciones que se indican a continuación.

• Nombre: escriba un nombre para la actividad.
• Descripción: escriba una descripción para la actividad.
• Estado de la actividad: seleccione Activado. O bien, seleccione Desactivado para excluir la actividad de la ejecución y validación de la canalización.
• Tiempo de espera: es la cantidad máxima de tiempo que se puede ejecutar una actividad. El valor predeterminado es 12 horas, el mínimo es de 10 minutos y la cantidad máxima de tiempo permitido es de siete días. El formato está en D.HH:MM:SS.
• Reintento: número máximo de reintentos. Esto puede dejarse como 0.
• Intervalo de reintentos (seg.): el número máximo de reintentos. Esto puede dejarse en 30 si los reintentos se establecen en 0.
• Salida segura: cuando se selecciona, la salida de la actividad no se captura en el registro. Puedes dejar esto despejado.
• Entrada segura: cuando se selecciona, la entrada de la actividad no se captura en el registro. Puedes dejar esto despejado.

4. Copiar la configuración de la actividad de datos: Origen

1. Seleccione Origen.

2. Seleccione un conjunto de datos de origen existente o +Nuevo para crear un nuevo conjunto de datos de origen. Por ejemplo, en Nuevo conjunto de datos, seleccione Azure Blob Storage y, a continuación, seleccione el tipo de formato de los datos.

   

3. Establezca las propiedades del archivo .csv. Escriba un nombre y, en Servicio vinculado, seleccione una ubicación existente o seleccione +Nuevo.

   

4. Si seleccionó +Nuevo, escriba los detalles del nuevo servicio vinculado siguiendo las instrucciones siguientes.

   

5. Junto a Conjunto de datos de origen, seleccione Abrir.

   

6. Seleccione Primera fila como encabezado.

   

5. Configuración de la actividad de copia de datos: Receptor

1. Seleccione Receptor.

2. Seleccione +Nuevo para configurar un nuevo recurso rest para conectarse a la API de importación de Viva Insights. Busque "Rest" y seleccione Continuar.

   

3. Asigne al servicio el nombre . En Servicio vinculado , seleccione +Nuevo.

   

4. Busque "Rest" y selecciónelo.

   

5. Escriba los campos siguiendo las instrucciones que se indican a continuación.

   

• Nombre: escriba un nombre para el nuevo servicio vinculado.
• Descripción: escriba una descripción en el nuevo servicio vinculado.
• Conectarse a través de Integration Runtime: escriba el método preferido.
• Dirección URL base: use la dirección URL siguiente y reemplace <TENANT_ID> por el identificador de inquilino: https://api.orginsights.viva.office.com/v1.0/scopes/<TENANT_ID>/ingress/connectors/HR/ingestions/fileIngestion
• Tipo de autenticación: seleccione el tipo de autenticación como Entidad de servicio o Certificado. Ejemplo de entidad de servicio:
  • En línea: selecciónela.
  • Identificador de entidad de servicio: escriba el identificador.
  • Clave de entidad de servicio: escriba la clave.
  • Inquilino: escriba el identificador de inquilino.
  • Microsoft Entra ID recurso:https://api.orginsights.viva.office.com
  • Azure tipo de nube: seleccione el tipo de nube Azure.
  • Validación de certificados de servidor: seleccione Habilitado.

6. Escriba la configuración del receptor siguiendo las instrucciones que se indican a continuación.

   

• Conjunto de datos receptor: seleccione el conjunto de datos existente o recién creado.
• Método de solicitud: seleccione POST.
• Tiempo de espera de la solicitud: cinco minutos es el valor predeterminado.
• Intervalo de solicitud (ms):10 es el valor predeterminado.
• Tamaño del lote de escritura: el tamaño del lote debe ser mayor que el número máximo de líneas del archivo.
• Tipo de compresión HTTP: Ninguno es el valor predeterminado. O puede usar GZip.
• Encabezados adicionales: seleccione +Nuevo.
  • Cuadro 1: x-nova-scaleunit
  • Valor: el valor se puede recuperar de Workplace Analytics; para ello, vaya a la pestaña Datos> de la organización:> seleccione Administrar orígenes de datos:> seleccione Importación basada en API.

6. Copiar la configuración de la actividad de datos: Asignación

1. Seleccione Asignación.

2. Para la carga de arranque, asegúrese de incluir PersonId, ManagerId y Organization en la asignación (nombre de destino). Para la carga incremental, compruebe que los nombres de destino son coherentes con los de la carga anterior, junto con PersonId. No puede realizar cargas incrementales con nuevas columnas y PersonId es necesario en todas las cargas.

   

7. Configuración de la actividad de copia de datos: configuración y propiedades de usuario

No se requieren otras personalizaciones para la configuración o las propiedades de usuario. Puede editar esta configuración caso por caso si es necesario.

8. Actividad de copia de datos: Configuración del desencadenador (Automatización)

Para agregar un desencadenador a la configuración de automatización, seleccione Agregar desencadenador. La automatización recomendada es semanal. También puede personalizar la frecuencia.

Validation

Una vez que el administrador del origen de datos envía datos, la aplicación comienza a validarse.

Una vez completada esta fase, la validación se ha realizado correctamente o ha producido un error. En función del resultado, recibirá una notificación de éxito o una notificación de error en la esquina superior derecha de la pantalla Conexiones de datos .

Para obtener información sobre lo que sucede a continuación, vaya a la sección correspondiente:

La validación se realiza correctamente

Error en la validación

La validación se realiza correctamente

Después de una validación correcta, Viva Insights comienza a procesar los nuevos datos. El procesamiento puede tardar entre unas horas y un día aproximadamente. Durante el procesamiento, aparece un estado "Procesamiento" en la tabla Historial de importación .

Una vez completado el procesamiento, se realiza correctamente o se produce un error. En función del resultado, encontrará un estado "Correcto" o "Erróneo" en la tabla Historial de importación .

El procesamiento se realiza correctamente

Cuando encuentre el estado "Correcto" en la tabla Historial de importación , el proceso de carga se completa.

Después de recibir el estado "Correcto", puede hacer lo siguiente:

• Seleccione el icono de vista (ojo) para ver un resumen de los resultados de validación.
• Seleccione el icono de asignación para ver la configuración de asignación del flujo de trabajo.

Error en el procesamiento

Si se produce un error en el procesamiento, aparece un estado "Error de procesamiento" en la tabla Historial de importación . Para que el procesamiento se realice correctamente, el administrador del origen de datos debe corregir errores e insertar los datos en Viva Insights de nuevo.

Error en la validación

Si se produce un error en la validación de datos, aparece un estado "Error de validación" en la tabla Historial de importación . Para que la validación se realice correctamente, el administrador del origen de datos debe corregir errores e insertar los datos en Viva Insights de nuevo. En Acciones, seleccione el icono de descarga para descargar un registro de errores. Envíe este registro al administrador del origen de datos para que sepa qué corregir antes de volver a enviar los datos.

El administrador del origen de datos podría encontrar la siguiente sección útil para corregir errores de datos en su archivo de exportación.

Acerca de los errores en los datos

Se aplica a: administrador del origen de datos

Cuando cualquier fila o columna de datos tiene un valor no válido para cualquier atributo, se produce un error en toda la importación hasta que el administrador del origen de datos corrige los datos de origen.

Consulte Preparación de datos organizativos para reglas de formato específicas que podrían ayudar a resolver los errores que se producen.

Obtenga más información sobre los errores de validación y las advertencias.

Temas relacionados

Preparar los datos de la organización

Importar datos de la organización (importación posterior)