Comando IMPORT GRCRESULTS

Concept Information

Importar dados do Resultados do Diligent One

Cria uma tabela do Analytics importando uma tabela ou interpretação do Resultados do Diligent One.

Sintaxe

IMPORT GRCRESULTS TO tabela nome_arquivo_importação PASSWORD número FROM caminho_recursos_resultados <FIELD nome AS nome_exibição <...n>> <CHARMAX tamanho_máximo_campo>

Parâmetros

Nome Descrição
TO tabela

O nome da tabela do Analytics na qual os dados serão importados.

Nota

Os nomes de tabela são limitados a 64 caracteres alfanuméricos. O nome pode incluir o caractere de sublinhado ( _ ) mas nenhum outro caractere especial e nenhum espaço. O nome não pode começar com um número.

nomearquivo_importação

O nome do arquivo de dados do Analytics a ser criado.

Especifique nome_arquivo_importação como uma cadeia entre aspas com uma extensão de arquivo .FIL. Por exemplo, "Faturas.FIL".

Por padrão, o arquivo de dados (.FIL) é salvo na pasta que contém o projeto do Analytics.

Use um caminho de arquivo absoluto ou relativo para salvar o arquivo de dados em uma pasta diferente já existente:

  • "C:\dados\Faturas.FIL"
  • "dados\Faturas.FIL"
PASSWORD num

A definição de senha a ser usada.

PASSWORD num não é usado para solicitar ou especificar uma senha real. A definição de senha faz referência a uma senha previamente fornecida ou definida com o comando PASSWORD, o comando SET PASSWORD ou a tag de análise PASSWORD.

num é o número da definição de senha. Por exemplo, se as duas senhas foram previamente fornecidas ou definidas em um script, ou no agendamento de um script de análise, PASSWORD 2 especifica o uso da senha nº 2.

Para obter mais informações sobre o fornecimento ou a definição de senhas, consulte:

O valor de senha obrigatório é um token de acesso do HighBond. Para obter mais informações, consulte Criação de uma definição de senha e especificação do valor da senha.

PASSWORD número pode ou não ser obrigatória, dependendo do ambiente em que o script é executado.

Ambiente onde o script é executado PASSWORD número é obrigatória
Analytics

(ativação on-line)

PASSWORD número não é obrigatória.

O token de acesso do HighBond do usuário atual, armazenado no registro do Windows, é usado automaticamente.
Analytics

(ativação off-line)

PASSWORD número é obrigatória.
Robôs

FROM Caminho_recursos_Results

O caminho até os dados que estão sendo importados.

O formato do caminho varia dependendo dos dados importados. Para obter detalhes sobre o formato do caminho, consulte Caminho de Resultados.

Nota

O formato do caminho de Resultados é fornecido por uma API e está sujeito à alteração. A forma mais fácil e confiável de obter a sintaxe correta e atual do caminho e executar uma importação manual dos dados de destino e copiar o caminho do log de comandos.
FIELD nome AS nome_exibicao <...n>

opcional

Campos individuais nos dados de origem a serem importados. Especifique o nome.

Se você omitir FIELD, todos os campos serão importados.

Nome

nome deve corresponder exatamente ao nome do campo físico na tabela Resultados, inclusive maiúsculas e minúsculas. Para exibir o nome físico do campo, realize uma das ações a seguir:

  • No Resultados, clique em um cabeçalho de coluna na Exibição de tabela. O nome do campo físico é exibido após Nome do campo.
  • No Analytics, quando você importa uma tabela do aplicativo Resultados, o nome de campo físico aparece entre parênteses após o nome de exibição na caixa de diálogo que permite selecionar campos.

Nota

O nome do campo físico do Resultados não é o nome de exibição usado para cabeçalhos de coluna na Exibição de tabela.

Consulte também Considerações sobre nomes de campos para importação e exportação de dados do Resultados.

Nome de exibição

nome_exibicao (título alternativo da coluna) é o nome do campo na exibição na nova tabela do Analytics. Você deve especificar um nome de exibição para cada FIELD nome. Especifique nome_exibicao como uma cadeia entre aspas.

Utilize um ponto e vírgula (;) entre palavras se quiser uma quebra de linha no título da coluna.

Ao contrário de alguns comandos IMPORT no Analytics, não é possível especificar nome_exibicao em branco como forma de usar o nome de FIELD como nome de exibição.
CHARMAX tamanho_máximo_do_campo

opcional

O tamanho máximo em caracteres de qualquer campo na tabela do Analytics originada como dados de caracteres na tabela de Resultados ou interpretação.

Dados na tabela de Resultados ou interpretação que excedam o tamanho máximo do campo ficam truncados quando importados para o Analytics.

A habilidade de truncar campos evita que valores ocasionalmente longos expandam o tamanho geral do registro além do que é suportado pelo processo de importação:

  • 32.767 caracteres (Analytics versão não Unicode)

  • 16.383 caracteres (Analytics versão Unicode)

Exemplos

Importação dos campos especificados de uma tabela do Resultados

Importe os campos especificados de uma tabela do Resultados para uma tabela do Analytics chamada Exceções T e E:

IMPORT GRCRESULTS TO Exceções_T_e_E "C:\Análise Secundária\Exceções_T_e_E.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" FIELD "metadata.status" AS "Status" FIELD "NumFunc" AS "Número Funcionário" FIELD "DATA" AS "Data" FIELD "NUMCARTAO" AS "Número do cartão" FIELD "CODIGOS" AS "Códigos MC" FIELD "VALOR" AS "Valor" FIELD "DESCRICAO" AS "Descrição"

Importação de todos os campos de uma tabela do Resultados

Importe todos os campos de uma tabela do Resultados para uma tabela do Analytics chamada Exceções T e E:

IMPORT GRCRESULTS TO Exceções_T_e_E "C:\Análise Secundária\Exceções_T_e_E.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions"

Tamanho limite do campo ao importar uma tabela do Resultados

Importe todos os campos de uma tabela do Resultados para uma tabela do Analytics chamada Exceções T e E. Use o parâmetro CHARMAX para limitar o tamanho dos campos.

IMPORT GRCRESULTS TO Exceções_T_e_E "C:\Análise Secundária\Exceções_T_e_E.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" CHARMAX 200

Na tabela de resultados do Analytics, todos os campos originados como dados de caracteres no Resultados são limitados ao tamanho especificado de 200 caracteres. Valores de campos que excederem o limite ficarão truncados a 200 caracteres.

Importação de dados de uma interpretação no Resultados

Importe uma interpretação no Resultados para uma tabela do Analytics chamada Exceções T e E filtradas:

IMPORT GRCRESULTS TO Exceções_T_e_E_filtradas "C:\Análise Secundária\Exceções_T_e_E_filtradas.fil" FROM "results/api/orgs/11594/control_tests/185699/interpretations/22699/exceptions"

Observações

Para obter mais informações sobre o funcionamento desse comando, consulte Importar dados do Resultados do Diligent One.

Preservação de critério de ordenação e filtros

Quando você importa dados do Resultados, todas as personalizações de dados, como ordenação e filtragem, são preservadas ou ignoradas na tabela resultante do Analytics, dependendo da forma como os dados são importados:

  • importar uma tabela a personalização de dados é ignorada. Todos os dados da tabela são importados, exceto os campos que você preferir omitir.
  • importar uma interpretação a personalização de dados preservada

Caminho de Resultados

Nota

O formato do caminho de Resultados é fornecido por uma API e está sujeito à alteração. A forma mais fácil e confiável de obter a sintaxe correta e atual do caminho e executar uma importação manual dos dados de destino e copiar o caminho do log de comandos.

O caminho de Resultados no parâmetro FROM tem o seguinte formato geral:

FROM "results<-código da região>/api/orgs/<ID da organização>/testes_controle/<ID do teste de controle>/exceções

Por exemplo:

FROM "results/api/orgs/11594/control_tests/4356/exceptions"

O ID da organização é exibido na barra de endereço do navegador quando você faz login no Launchpad. O ID do teste de controle e o ID da interpretação são exibidos na barra de endereço quando você exibe essas tabelas no aplicativo Resultados.

A tabela a seguir oferece as variações do caminho de Resultados.

Para importar: Use este formato do caminho de Resultados:
Teste de controle de dados (tabela) 
FROM "results/api/orgs/11594/control_tests/4356/exceptions"
Teste de controle de trilha de auditoria (tabela) 
FROM "results/api/orgs/11594/control_tests/4356/audit_trail"
Teste de controle de comentários (tabela) 
FROM "results/api/orgs/11594/control_tests/4356/comments"
Interpretação 
FROM "results/api/orgs/11594/control_tests/4356/interpretations/1192/exceptions"
Dados de uma região do Diligent One diferente da região padrão - América do Norte (EUA)
  • África (África do Sul)
    FROM "results-af/api/orgs/11594/control_tests/4356/exceptions"
  • Ásia-Pacífico (Austrália)
    FROM "results-au/api/orgs/11594/control_tests/4356/exceptions"
  • Ásia-Pacífico (Singapura)
    FROM "results-ap/api/orgs/11594/control_tests/4356/exceptions"
  • Ásia-Pacífico (Tóquio)
    FROM "results-jp/api/orgs/11594/control_tests/4356/exceptions"
  • Europa (Alemanha)
    FROM "results-eu/api/orgs/11594/control_tests/4356/exceptions"
  • América do Norte (Canadá)
    FROM "results-ca/api/orgs/11594/control_tests/4356/exceptions"
  • América do Sul (Brasil)
    FROM "results-sa/api/orgs/11594/control_tests/4356/exceptions"

Colunas de informações geradas pelo sistema

Quando você importa dados do aplicativo Resultados, pode também importar uma ou mais das colunas de informações geradas pelo sistema listadas a seguir.

As colunas geradas pelo sistema se dividem em dois tipos:

  • parte das tabelas do aplicativo Resultados, com informações de processamento relacionadas a registros individuais
  • informações adicionais: nome da coleção nome da tabela ou número do ID do registro

Você deve especificar os nomes de campo das colunas geradas pelo sistema exatamente da forma como aparecem a seguir. Os nomes de exibição padrão se aplicam na importação do aplicativo Resultados por meio da interface do usuário do Analytics. É possível alterar os nomes de exibição se você codificar o processo de importação em scripts.

Nome do campo

Nome de exibição padrão

metadata.priority

Prioridade

metadata.status

Status

metadata.publish_date

Publicação

metadata.publisher

Nome do Editor

metadata.assignee

Atribuído(a) a
metadata.group Grupo
metadata.updated_at Atualizado(a)
metadata.closed_at Fechado(a)
extras.collection Coleção
extras.results_table Tabela de Resultados
extras.record_id ID do registro

Considerações sobre nomes de campos para importação e exportação de dados do Resultados

Se você está executando um processo de ida e volta de dados entre o Resultados e o Analytics, precisa garantir que todos os nomes de campos da tabela do Resultados cumpram os requisitos mais rigorosos de nomenclatura de campos do Analytics. Caso contrário, os dados do Analytics e do Resultados poderão ficar desalinhados.

Por exemplo, todos os caracteres especiais dos nomes de campos do Resultados são convertidos automaticamente em sublinhados quando importados para o Analytics, o que significa que os nomes de campos deixam de corresponder aos nomes originais do Resultados. Se em seguida você exportar os dados do Analytics de volta para a tabela original no Resultados, os campos não corresponderão corretamente.

Para evitar esse problema em processos de ida e volta de dados, antes de carregar dados de arquivos CSV ou Excel para o Resultados, verifique se os requisitos de nomenclatura de campos do Analytics a seguir são cumpridos:

  • sem caracteres especiais ou espaços
  • não começa com um número
  • contém apenas caracteres alfanuméricos ou o caractere sublinhado ( _ )

Criação de uma definição de senha e especificação do valor da senha

Ao executar um script no Robôs que importa uma tabela do Resultados ou interpretação do Diligent One, você deverá incluir uma definição de senha com o comando IMPORT GRCRESULTS. A mesma exigência se aplica a scripts executados no Analytics se você usou a ativação off-line.

Independentemente do método usado para criar a definição de senha, o valor de senha obrigatório é um token de acesso do HighBond, que você pode gerar no Launchpad. Para obter mais informações, consulte Adquira um token de acesso do HighBond.

Métodos para definição de senha

Método Descrição

Tag de análise PASSWORD

(para scripts executados no Robôs)

Se você usar a tag de análise PASSWORD para criar a definição de senha numerada para conexão ao Diligent One, nenhum valor de senha será especificado no script. Quando você cria uma tarefa para ser executada no script no Robôs, um campo de entrada no Designer de tarefa permite que você ou outro usuário especifique a senha real.

Para obter mais informações, consulte Tag de análise PASSWORD.

Comando PASSWORD

(para scripts executados no Analytics com ativação off-line)

Se você usar o comando PASSWORD para criar a definição de senha numerada para conexão ao Diligent One, nenhum valor de senha será especificado no script. Um prompt de senha será exibido quando o script tentar se conectar.

Para obter mais informações, consulte Comando PASSWORD.

Comando SET PASSWORD

(para scripts executados no Analytics com ativação off-line)

Se você usar o comando PASSWORD para criar a definição da senha numerada para conexão com o Diligent One, um valor de senha será especificado no script, portanto, nenhum prompt de senha será exibido. Essa abordagem é apropriada para scripts criados para execução não assistida, mas ela expõe a senha real em texto não criptografado no script, o que pode não ser adequado para a sua situação.

Para obter mais informações, consulte Comando SET PASSWORD.

Adquira um token de acesso do HighBond

Cuidado

O token de acesso gerado corresponde à conta usada para fazer login no Diligent One. Como um autor de scripts, pode não ser apropriado especificar seu próprio token de acesso em um script se ele for usado por outras pessoas.

Proteja os tokens de acesso como qualquer senha de conta.

Use um token existente, a menos que você tenha um motivo para criar um novo. Se o token existente não funcionar, crie um novo. O uso de um token existente reduz o número de tokens que você precisa gerenciar.

  1. Execute uma das seguintes ações:

    • No menu principal do Analytics, selecione Ferramentas > Token de Acesso do HighBond.

    • No Editor de script, clique com o botão direito e selecione Inserir > Token do HighBond.

    A página Gerenciar tokens da API abre no navegador. Pode ser necessário primeiro fazer o login no Diligent One.

    O acesso à página Gerenciar Tokens da API por meio do Analytics é um recurso de conveniência. Você também pode fazer login no Diligent One e acessar a página por meio do seu perfil de usuário sem usar o Analytics.

  2. Execute uma das seguintes ações:

    • Usar um token existente

      1. Na coluna Token, clique no token parcialmente mascarado que deseja usar.

      2. Digite a senha da conta do Diligent One e clique em Confirmar.

        O token não mascarado é exibido.

      3. Clique em Copiar para copiar o token.

        Dica

        Não feche a caixa de diálogo que contém o token até colar corretamente o token.

    • Criar um novo token

      1. Clique em Adicionar token > Analytics.

      2. No painel lateral Novo token do Analytics, especifique estas informações:

        Campo ou opção Descrição
        Descrição

        Insira uma descrição que forneça informações úteis, como:

        • O propósito do token
        • Onde o token é usado – por exemplo, o nome e a localização do script do Analytics, ou o nome e a localização da tarefa do robô
        Expiração do token
        • Habilitada o token expira após um número de dias especificado
        • Desabilitada o token nunca expira

        Nota

        Sua organização pode ter uma política de segurança que exige a expiração de tokens após um determinado período. É recomendado criar tokens com expiração. O Diligent One enviará uma notificação automática por e-mail antes da data de expiração.
        Expiração em Especifique o número de dias até a expiração do token (1 a 365).
        Senha Digite a senha da conta do Diligent One.

      3. Clique em Gerar token.

      4. Clique em Copiar para copiar o token.

        Dica

        Não feche o painel lateral que contém o token até colar corretamente o token.

  3. Dependendo do método de definição de senha que você está usando, faça uma das seguintes opções:

    • Tag de análise PASSWORD No Designer de Tarefa em um robô ACL, cole o token copiado em um campo de parâmetro de senha.

    • Comando PASSWORD No Analytics, cole o token copiado em um prompt de senha exibido durante a execução de scripts.

    • Comando SET PASSWORD No Analytics, cole o token no ponto apropriado na sintaxe do comando SET PASSWORD em um script.

  4. No Launchpad, feche a caixa de diálogo ou o painel lateral que contém o token.

    Se tiver criado um novo token, uma versão parcialmente mascarada do token é adicionada ao início da lista de tokens.

    Para obter mais informações, consulte Criando e gerenciando tokens de acesso do HighBond.

Recurso para depuração de importações

Existe um recurso de depuração simples para importações do Diligent One.

Os dados importados são armazenados temporariamente em um arquivo JSON intermediário na pasta que contém o projeto de destino do Analytics. Em qualquer pasta que contém um projeto do Analytics, você pode criar um arquivo de texto para que o arquivo JSON seja retido, em vez de ser excluído, após a importação dos dados para o Analytics.

  • Arquivo JSON presente Se a importação do Diligent One falhar, mas o arquivo JSON estiver presente no computador, você saberá que o problema está no Analytics e não no Diligent One.
  • Arquivo JSON ausente Se a importação do Diligent One falhar, mas o arquivo JSON não estiver presente no computador, você saberá que o problema está no Diligent One.

Essa informação pode ser útil para solucionar o problema.

Configurar retenção do arquivo JSON intermediário

Na pasta que contém o projeto do Analytics de destino, crie um arquivo de texto vazio com o nome exatamente igual a _grc_import_debug.txt

Quando você realizar uma importação do Resultados ou do Projetos no Diligent One, o arquivo JSON intermediário será retido com o nome results.json. O arquivo será sobrescrito a cada importação subsequente do Diligent One.

Importação de grandes tabelas

A importação de tabelas com um grande número de campos usando um único comando IMPORT GRCRESULTS pode falhar. Se você precisar trabalhar com uma única tabela que contém um grande número de campos fora do Resultados, use uma das seguintes abordagens:

  • Divida a tabela use dois ou mais comandos IMPORT GRCRESULTS para importar um subconjunto dos campos e associe as tabelas resultantes no Analytics usando o comando JOIN
  • Exporte a tabela para um arquivo use o formato de exportação para CSV e importe o arquivo resultante para o Analytics usando o comando IMPORT DELIMITED