Importar dados organizacionais usando a importação baseada em API (primeira importação) (visualização)

Seus dados organizacionais podem aparecer no aplicativo Web Viva Insights de uma das três maneiras: por meio do Microsoft Entra ID, que é a fonte padrão; por meio de arquivos .csv individuais que você, como administrador do Insights, carrega diretamente no Viva Insights; ou por meio de uma importação de dados baseada em API que você, seu administrador do sistema de origem e seu administrador de TI do Microsoft 365 configurar.

Este artigo fala sobre a terceira opção, a importação de dados.

Com uma importação, você traz dados do seu sistema de origem para a API de entrada de dados de RH do Viva Insights por meio de um arquivo zip. Você pode:

• Crie um aplicativo personalizado para exportar dados do sistema de origem para um arquivo zip. Em seguida, usando o mesmo aplicativo, importe esses dados usando as informações da API abaixo.
• Crie um aplicativo personalizado para exportar dados do sistema de origem para um arquivo zip. Em seguida, execute um aplicativo de console C# que criamos para importar dados para o Viva Insights.
• Crie um aplicativo personalizado para exportar dados do sistema de origem para um arquivo zip. Em seguida, execute um script do PowerShell que criamos para importar dados para o Viva Insights.
• Use nosso modelo do ADF (Azure Data Factory) para enviar dados para nossa importação baseada em API.

No entanto, antes de executar seu aplicativo e começar a transferir dados para o Viva Insights, você precisa coordenar algumas tarefas entre o administrador do Microsoft 365 e o Administrador do Insights (administrador do Insights). Consulte Fluxo de trabalho para obter uma visão geral das etapas necessárias.

Fluxo de trabalho

1. Configuração:

   1. O administrador da fonte de dados gera um certificado de segurança e o fornece ao administrador do Microsoft 365.
   2. Usando o certificado de segurança, o administrador do Microsoft 365 registra um novo aplicativo no Azure.
   3. Usando IDs do registro do aplicativo, o administrador do Insights configura a importação.
   4. O administrador da fonte de dados prepara os dados e:
      1. Exporta-os do sistema de origem usando um aplicativo personalizado baseado em nossa API e, em seguida, usando o mesmo aplicativo, importa os dados para o Viva Insights.
      2. Exporta-os do sistema de origem usando um aplicativo personalizado baseado em nossa API e, em seguida, usando nossa solução C# ou script do PowerShell, importa os dados para o Viva Insights.

   

2. Validação: o Viva Insights valida seus dados. (Se a validação não for bem-sucedida, você poderá escolher entre algumas opções descritas em Falha na validação.)

3. Processando: o Viva Insights processa seus dados. (Se o processamento não for bem-sucedido, você poderá escolher entre algumas opções descritas em Falha no processamento.)

Depois que os dados forem validados e processados com êxito, a tarefa geral de importação de dados será concluída.

Configurar

Gerar o certificado de segurança

Aplica-se a: administrador da fonte de dados

Para começar a obter dados do arquivo de origem no Viva Insights, o administrador do Microsoft 365 precisa criar e registrar um aplicativo no Azure. Como administrador da fonte de dados, você precisa ajudar o administrador do Microsoft 365 a registrar o aplicativo fornecendo a ele um certificado de segurança.

Veja o que fazer:

1. Crie um certificado seguindo as instruções neste artigo: Crie um certificado público autoassinado para autenticar seu aplicativo
2. Envie o certificado gerado para o administrador do Microsoft 365.

Por enquanto é isso. Se você quiser sair na frente nas próximas etapas, siga as etapas em Exportar seus dados em uma frequência definida.

Registrar um novo aplicativo no Azure

Aplica-se a: Administrador do Microsoft 365

1. No painel esquerdo do centro de administração da Microsoft, selecione Todos os centros de administração. Essa opção aparece como a última da lista.

   

2. Selecione o Microsoft Entra ID.

3. Criar um novo registro de aplicativo:

   1. Na barra de ferramentas superior, selecione Adicionar > registro de aplicativo.

      

   2. Na tela resultante:

      1. Dê um nome ao seu aplicativo.
      2. Em Tipos de conta com suporte, deixe a primeira opção, Somente contas neste diretório organizacional (somente [Sua organização] - locatário único),selecionada.
      3. Selecione o botão Registrar na parte inferior da tela.

      

   3. Quando você voltar à tela Visão geral , copie a ID do aplicativo (cliente) e a ID do diretório (locatário).

      

      Importante

      Mantenha essas IDs à mão. Você precisará fornecê-las mais tarde.

4. Adicione um certificado:

   1. Selecione Adicionar um certificado ou segredo.

      

   2. Selecione Carregar certificado.

      

   3. Carregue o certificado fornecido pelo administrador da fonte de dados e adicione uma Descrição. Selecione o botão Adicionar.

      

5. Remover permissões de API:

   1. Selecione as permissões de API no painel esquerdo.

   2. Para cada nome de API/Permissões listado, selecione as reticências (...) à direita da API, por exemplo, Microsoft Graph.

   3. Selecione Remover permissão.

      

   4. Confirmar remoção.

   Ao remover permissões para esses itens, você está certificando-se de que o aplicativo tenha apenas permissões para o que precisa.

6. Compartilhe as IDs anotadas na etapa 3c:

   1. Forneça ao administrador do Insights a ID do aplicativo.
   2. Forneça ao administrador da fonte de dados a ID do aplicativo e a ID do locatário.

Configurar a importação no Viva Insights

Aplica-se a: Administrador do Insights

1. Inicie a importação de um dos dois locais: a página Hub de dados ou a página Dados organizacionais , em Conexões de dados.

   1. Do Hub de dados:

      1. Na seção Fonte de dados , localize a opção de importação baseada em API . Selecione o botão Iniciar.

   2. Das conexões de dados:

      1. Ao lado de Fonte atual, selecione o botão fontes de dados .

      2. É exibida uma janela Alternar para: importação baseada em API . Selecione Iniciar.

2. Na página de importação de dados organizacionais baseada em API :

   1. Dê um nome à sua conexão.

   2. Insira a ID do aplicativo fornecida pelo administrador do Microsoft 365.

   3. Salvar.

3. Selecione a conexão nomeada na etapa 3a como a nova fonte de dados.

4. Entre em contato com o administrador da fonte de dados e solicite que ele envie dados da organização para o Viva Insights.

Preparar, exportar e importar dados organizacionais

Dicas para preparar seus dados

• Para novos dados, inclua dados históricos completos de todos os funcionários.
• Importe dados organizacionais de todos os funcionários da empresa, incluindo funcionários licenciados e não licenciados.
• Consulte o modelo de .csv de exemplo para estrutura de dados e diretrizes para evitar problemas comuns, como muitos ou poucos valores exclusivos, campos redundantes, formatos de dados inválidos e muito mais.

Exporte seus dados com uma frequência definida

Na frequência que você decidir (uma vez por mês, uma vez por semana etc.), faça com que seu aplicativo personalizado exporte dados organizacionais do sistema de origem como uma pasta zip e armazene-os em seus arquivos. Baseie esta pasta zip na pasta aqui. Sua pasta zip precisa conter um arquivo data.csv e um arquivo metadata.json.

Aqui estão mais alguns detalhes sobre esses arquivos e o que eles precisam conter:

data.csv

Adicione todos os campos que deseja importar neste arquivo. Certifique-se de formatá-lo de acordo com nossas diretrizes em Preparar dados organizacionais.

metadata.json

Indique o tipo de atualização que você está executando e como o Viva Insights deve mapear seus campos:

• "DatasetType": "HR" (linha 2). Deixe isso como está.
• "IsBootstrap": (linha 3). Use "true" para indicar uma atualização completa e "false" uma atualização incremental.
• "ColumnMap":. Se você usar nomes diferentes dos que o Viva Insights usa, altere o nome de cada cabeçalho de coluna para corresponder ao que você usa em seu sistema de origem.

Exemplo de mapeamento

O exemplo a seguir representa um campo no arquivo metadata.json:

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

• "PersonId": { corresponde ao nome da coluna de origem.
• “name” : “PersonId”, corresponde ao nome do campo do Viva Insights.
• "type": "EmailType" corresponde ao tipo de dados do campo.

Digamos que, em vez de , seu sistema de origem use Employee esse cabeçalho de PersonIdcampo. Para garantir que seus campos sejam mapeados corretamente, edite a primeira linha abaixo, para que fique assim:

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

Quando você carrega seus dados, seu Employee campo se torna PersonId no Viva Insights.

Importar seus dados

Para importar seus dados para o Viva Insights, você pode escolher entre quatro opções:

• Use nossa API para criar um aplicativo personalizado que exporta e importa seus dados na frequência que você escolher. Saiba mais.
• Execute nossa solução C# em seu console, que é baseada em nossa API. Saiba mais.
• Execute nosso script do PowerShell, que também é baseado em nossa API. Saiba mais.
• Use nosso modelo do ADF (Azure Data Factory) para enviar dados para nossa importação baseada em API. Saiba mais.

Antes de trabalhar com qualquer uma das opções abaixo, verifique se você tem essas informações:

• ID do aplicativo (cliente). Encontre essa ID nas informações do aplicativo registrado no portal do Azure em ID do aplicativo (cliente).
• Segredo do cliente: essa é uma cadeia de caracteres secreta que o aplicativo usa para provar sua identidade ao solicitar um token. Ela também é conhecida como senha do aplicativo. Esse segredo só é mostrado pela primeira vez quando o segredo do cliente é criado. Para criar um novo segredo do cliente, consulte Criar um aplicativo e entidade de serviço do Microsoft Entra no portal.
• Nome do certificado. Esse nome é configurado no seu aplicativo registrado. Depois de carregar o certificado, o nome do certificado aparece em Descrição no Portal do Azure. Você pode usar o nome do certificado como uma alternativa ao segredo do cliente.
• O arquivo zip e o caminho para o arquivo zip. Não altere os nomes de arquivo data.csv e metadata.json.
• ID do locatário do Microsoft Entra. Encontre também essa ID na página de visão geral do aplicativo em ID do diretório (locatário).
• Unidade de escala: a unidade de escala fornecida a você para seu locatário, por exemplo, novaprdwus2-01.

Sobre a API de entrada de dados de RH do Viva Insights

Visualize os seguintes comandos:

[Cabeçalhos da solicitação]

Esses dois cabeçalhos de solicitação são necessários para todas as APIs mencionadas abaixo

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

Authentication: Bearer <Oauth token from AAD>

Obter conector/ping para marcar se o conector está definido para um locatário

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

[ResponseBody]

Se o conector estiver definido e o aplicativo chamador (id) tiver autorização concedida:

200:  

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

}

Se o Administrador do Insights tiver removido o conector ou o conector ainda não tiver sido definido pelo Administrador do Insights:

403: Forbidden.

Enviar dados por push

Aplicativo para chamar a API do Viva Insights para enviar conteúdo por push

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

[Corpo] conteúdo do arquivo como dados de várias partes/formulário

Tipo: arquivo Zip

Conteúdo a ser arquivado:

Metadata.json

Data.csv

[Corpo da Solicitação]

Body: 

{ 

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

   "$multipart":  

    [ 

        { 

            "headers":  

                { 

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

                   }, 

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

         } 

    ] 

} 

[corpo da resposta]

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" 

} 

Caso o conector não esteja definido:

403: Forbidden

Se o conector estiver definido, mas a ingestão anterior ainda não estiver concluída:

400: Bad request: Previous ingestion is not complete.

Status da votação

API para pesquisar o status da ingestão, pois a ingestão de dados é uma operação de execução prolongada.

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

[Resposta]

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" 

}, 

Baixar fluxo de erros se a validação falhar (problema nos dados)

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

[Resposta]

200: File stream with errors, if any.

Opção 1: usar a API de entrada de dados de RH do Viva Insights para criar um aplicativo de importação/exportação personalizado

Você pode usar a API de entrada de dados de RH do Viva Insights para criar um aplicativo personalizado que exporta automaticamente dados do seu sistema de origem e, em seguida, os importa para o Viva Insights.

Seu aplicativo pode assumir qualquer forma, por exemplo, um script do PowerShell, mas precisa exportar seus dados de origem como uma pasta zip na frequência escolhida, armazenar a pasta em seus arquivos e importar essa pasta para o Viva Insights.

Opção 2: Importar os dados por meio de nossa solução C# após exportar os dados por meio de seu aplicativo personalizado

Depois de exportar os dados de origem como uma pasta zip na frequência escolhida e armazenar essa pasta em seus arquivos, você poderá executar a solução C# DescriptiveDataUploadApp no console. A solução DescriptiveDataUploadApp C# traz seus dados armazenados localmente para o Viva Insights. Saiba mais no GitHub.

Para executar a solução:

1. Clone este aplicativo em seu computador executando o seguinte comando na linha de comando:

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

2. Inclua os seguintes valores de console. Consulte Preparar, exportar e importar dados organizacionais para obter descrições.

   • AppID/ClientID
   • Caminho absoluto para o arquivo compactado. Formate o caminho desta forma: C:\\Users\\JaneDoe\\OneDrive - Microsoft\\Desktop\\info.zip
   • ID do locatário do Microsoft Entra
   • Nome do certificado

Opção 3: execute a solução DescriptiveDataUpload do PowerShell depois de exportar os dados por meio do seu aplicativo personalizado

Semelhante à opção 2, depois de exportar os dados de origem como uma pasta zip na frequência escolhida e armazenar essa pasta em seus arquivos, você pode executar a solução DescriptiveDataUpload PowerShell no console. A solução DescriptiveDataUpload do PowerShell traz seus dados armazenados localmente para o Viva Insights. Saiba mais no GitHub.

1. Clone o código-fonte em seu computador executando este comando na linha de comando:

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

2. Abra uma nova janela do PowerShell como administrador.

3. Na janela do PowerShell, execute o seguinte comando:

   Install-Module -Name MSAL.PS

   Ou acesse o link da galeria do PowerShell para obter instruções sobre a instalação.

4. Defina parâmetros. Consulte Preparar, exportar e importar dados organizacionais para obter descrições.

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

Opção 4: Usar nosso modelo do ADF (Azure Data Factory) para enviar dados para nossa importação baseada em API

1. Criar o novo Azure Data Factory

1. Entre no https://adf.azure.com/en/datafactories.

2. Crie um novo data factory ou use um data factory existente. Preencha os campos e selecione Criar.

   

2. Criar um novo pipeline e atividade

1. Crie um novo pipeline e insira um nome para o pipeline.

   

2. Em Atividades, adicione Copiar dados.

   

3. Copiar configurações de atividade de dados: Geral

Selecione sua atividade Copiar dados e, em seguida, selecione Geral para concluir cada campo usando as orientações abaixo.

• Nome: Insira um nome para sua atividade.
• Descrição: insira uma descrição para sua atividade.
• Estado da atividade: selecione Ativado. Ou selecione Desativado para excluir a atividade da execução e validação do pipeline.
• Tempo limite: é a quantidade máxima de tempo que uma atividade pode executar. O padrão é de 12 horas, o mínimo é de 10 minutos e o máximo de tempo permitido é de sete dias. O formato está em D.HH:MM:SS.
• Tentar novamente: o número máximo de tentativas de repetição. Pode ser deixado como 0.
• Intervalo de repetição (s): o número máximo de tentativas de repetição. Isso poderá ser deixado como 30 se as tentativas de repetição forem definidas como 0.
• Saída segura: quando selecionada, a saída da atividade não é capturada no registro em log. Você pode deixar isso limpo.
• Entrada segura: quando selecionada, a entrada da atividade não é capturada no registro em log. Você pode deixar isso limpo.

4. Copiar configurações de atividade de dados: Fonte

1. Selecionar origem.

2. Selecione um conjunto de dados de origem existente ou selecione +Novo para criar um novo conjunto de dados de origem. Por exemplo, em Novo conjunto de dados, selecione o Armazenamento de Blobs do Azure e, em seguida, selecione o tipo de formato dos seus dados.

   

3. Defina as propriedades do arquivo .csv. Insira um Nome e, em Serviço vinculado, selecione um local existente ou selecione +Novo.

   

4. Se você selecionou +Novo, insira os detalhes do novo serviço vinculado usando as orientações abaixo.

   

5. Ao lado do conjunto de dados de origem, selecione Abrir.

   

6. Selecione Primeira linha como cabeçalho.

   

5. Copiar configurações de atividade de dados: Coletor

1. Selecione Coletor.

2. Selecione +Novo para configurar um novo recurso rest para se conectar à API de importação do Viva Insights. Pesquise por "Descansar" e selecione Continuar.

   

3. Nomeie o serviço. Em Serviço vinculado , selecione +Novo.

   

4. Pesquise por "Rest" e selecione-o.

   

5. Insira os campos usando as orientações abaixo.

   

• Nome: insira um nome para seu novo serviço vinculado.
• Descrição: insira uma descrição para o novo serviço vinculado.
• Conectar-se por meio do runtime de integração: Insira o método preferencial.
• URL base: use a URL abaixo e substitua < TENANT_ID pela ID do> locatário: https://api.orginsights.viva.office.com/v1.0/tenants/{tenantid}/modis/connectors/HR/ingestions/fileIngestion<TENANT_ID>/ingress/connectors/HR/ingestions/fileIngestion
• Tipo de autenticação: selecione o tipo de autenticação como Entidade de Serviço e selecione Segredo ou Certificado. Exemplo da entidade de serviço:

  • Embutido: Selecione-o.

  • ID da entidade de serviço: insira a ID do aplicativo autorizada para o conector de API.

  • Chave da entidade de serviço: insira a chave.

    

  • Locatário: insira a ID do locatário.

  • Recurso do Microsoft Entra ID:https://api.orginsights.viva.office.com

  • Tipo de nuvem do Azure: selecione seu tipo de nuvem do Azure.

  • Validação de certificado do servidor: Selecione Habilitado.

6. Insira as configurações do coletor usando as orientações abaixo.

   

• Conjunto de dados do coletor: selecione o conjunto de dados existente ou recém-criado.
• Método de solicitação: Selecione POST.
• Tempo limite da solicitação: cinco minutos é o padrão.
• Intervalo de solicitação (ms): 10 é o padrão.
• Gravar tamanho do lote: o tamanho do lote deve ser maior que o número máximo de linhas em seu arquivo.
• Tipo de compactação Http: Nenhum é o padrão. Ou você pode usar GZip.
• Cabeçalhos adicionais: Selecione +Novo.
  • Caixa 1: unidade de escala x-nova
  • Valor: o valor pode ser recuperado do Workplace Analytics navegando até ->Guia Dados da organização -> Selecione Gerenciar fontes de dados -> Selecione Importação baseada em API.

6. Copiar configurações de atividade de dados: Mapeamento

1. Selecione Mapeamento.

2. Para o upload de bootstrap, inclua PersonId, ManagerId e Organization no mapeamento (nome de destino). Para o upload incremental, verifique se os nomes de destino são consistentes com os do upload anterior, juntamente com PersonId. Você não pode executar uploads incrementais com novas colunas, e PersonId é necessário em todos os uploads.

   

7. Copiar configurações de atividade de dados: Configurações e propriedades do usuário

Nenhuma outra personalização é necessária para Configurações ou Propriedades do Usuário. Você pode editar essas configurações caso a caso, se precisar.

8. Copiar atividade de dados: Configuração do gatilho (automação)

Para adicionar um gatilho à configuração de automação, selecione Adicionar gatilho. A automação recomendada é semanal. Você também pode personalizar a frequência.

Validação

Depois que o administrador da fonte de dados enviar dados, o aplicativo começará a validar.

Após a conclusão dessa fase, a validação foi bem-sucedida ou falhou. Dependendo do resultado, você receberá uma notificação de sucesso ou falha no canto superior direito da tela Conexões de dados .

Para obter informações sobre o que acontece a seguir, vá para a seção apropriada:

Validação bem-sucedida

Falha na validação

Validação bem-sucedida

Após a validação, o Viva Insights começará a processar seus novos dados. O processamento pode levar entre algumas horas e um dia ou mais. Durante o processamento, um status "Processando" aparece na tabela Histórico de importação.

Após a conclusão do processamento, ele foi bem-sucedido ou falhou. Dependendo do resultado, você encontrará um status "Êxito" ou "Com falha" na tabela Histórico de importação.

O processamento foi bem-sucedido

Quando você encontrar o status "Bem-sucedido" na tabela Histórico de importação, o processo de upload estará concluído.

Depois de receber o status "Êxito", você poderá:

• Selecione o ícone de exibição (olho) para ver um resumo dos resultados da validação.
• Selecione o ícone de mapeamento para ver as configurações de mapeamento do fluxo de trabalho.

Falha no processamento

Se o processamento falhar, um status "Falha no processamento" será exibido na tabela Histórico de importação. Para que o processamento seja bem-sucedido, o administrador da fonte de dados precisa corrigir os erros e enviar os dados por push para o Viva Insights novamente.

Falha na validação

Se a validação de dados falhar, um status "Falha na validação" será exibido na tabela Histórico de importação. Para que a validação seja bem-sucedida, o administrador da fonte de dados precisa corrigir os erros e enviar os dados para o Viva Insights novamente. Em Ações, selecione o ícone de download para baixar um log de erros. Envie o log para o administrador da fonte de dados para que ele saiba o que corrigir antes de enviar os dados novamente.

O administrador da fonte de dados pode achar a seção a seguir útil para corrigir erros de dados no arquivo de exportação.

Sobre erros nos dados

Aplica-se a: administrador da fonte de dados

Quando qualquer linha ou coluna de dados tem um valor inválido para qualquer atributo, toda a importação falha até que o administrador da fonte de dados corrija os dados de origem.

Consulte Preparar dados organizacionais para regras de formatação específicas que podem ajudar a resolver erros encontrados.

Saiba mais sobre erros e avisos de validação.

Tópicos relacionados

Prepare os dados organizacionais

Importar dados organizacionais (importação subsequente)