Acesso aos dados do ServiceNow no Snowflake

Este tópico descreve como acessar os dados do ServiceNow de sua conta Snowflake.

Neste tópico:

Para cada tabela no ServiceNow que esteja configurada para sincronização, o conector cria as seguintes tabelas e exibições:

  • Uma tabela com o mesmo nome que contém os dados bruto, onde cada registro está contido em uma única coluna VARIANT.

  • Uma tabela chamada table_name__event_log que contém o histórico das alterações feitas nos registros do ServiceNow.

  • Uma exibição chamada table_name__view que contém os dados em forma nivelada, em que a exibição contém uma coluna para cada coluna na tabela original e uma linha para cada registro que está presente na tabela original.

  • Uma exibição chamada table_name__view_with_deleted que contém os mesmos dados que table_name__view assim como linhas para registros que foram apagados no ServiceNow.

Nota

Depois de iniciar o conector, pode levar algum tempo até que as exibições sejam criadas.

A criação da exibição depende dos dados nas tabelas ServiceNow sys_db_object, sys_dictionary e sys_glide_object. O conector carrega metadados destas tabelas do ServiceNow depois que você habilita uma tabela para sincronização. Pode levar algum tempo até que o conector carregue esses metadados.

As seções seguintes explicam como conceder os privilégios de acesso a esses dados e como acessar os dados dessas tabelas e exibições.

Concessão de privilégios para acessar os dados do ServiceNow no Snowflake

Depois que o conector Snowflake ServiceNow sincronizar os dados com o Snowflake, qualquer função com os seguintes privilégios pode acessar os dados do ServiceNow:

  • Privilégio USAGE no banco de dados e esquema que contém os dados do ServiceNow no Snowflake, e

  • Privilégio SELECT em tabelas ou exibições dentro deste esquema

Snowflake recomenda a criação de uma função dedicada com estes privilégios que podem ser concedidos aos usuários que precisam ter acesso aos dados ingeridos do ServiceNow.

Por exemplo, se você tiver configurado o conector para armazenar os dados do ServiceNow no banco de dados dest_db e o esquema dest_schema, você pode criar uma função chamada servicenow_data_reader_role e conceder os privilégios de acesso aos dados para essa função.

O exemplo a seguir mostra como conceder esses privilégios:

CREATE ROLE servicenow_data_reader_role;
GRANT USAGE ON DATABASE dest_db TO ROLE servicenow_data_reader_role;
GRANT USAGE ON SCHEMA dest_db.dest_schema TO ROLE servicenow_data_reader_role;
GRANT SELECT ON FUTURE TABLES IN SCHEMA dest_db.dest_schema TO ROLE servicenow_data_reader_role;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA dest_db.dest_schema TO ROLE servicenow_data_reader_role;
GRANT SELECT ON ALL TABLES IN SCHEMA dest_db.dest_schema TO ROLE servicenow_data_reader_role;
GRANT SELECT ON ALL VIEWS IN SCHEMA dest_db.dest_schema TO ROLE servicenow_data_reader_role;
Copy

Nota

  • Não execute GRANT OWNERSHIP ON FUTURE TABLES IN SCHEMA no esquema que contém os dados do ServiceNow no Snowflake. Além disso, não altere a propriedade das tabelas que já foram criadas pelo conector. A alteração da propriedade impede que o conector ingira os dados na tabela.

  • Não altere a propriedade das exibições no esquema que contém os dados do ServiceNow no Snowflake. A alteração da propriedade impede que o conector atualize as exibições quando ocorrem mudanças no esquema da tabela do ServiceNow.

Acesso aos dados brutos

Para cada tabela do ServiceNow que você sincroniza, o conector Snowflake para ServiceNow cria uma nova tabela com o mesmo nome no banco de dados e esquema para os dados do ServiceNow no Snowflake.

Por exemplo, se você tiver configurado o conector para armazenar os dados do ServiceNow no banco de dados dest_db e esquema dest_schema, e se você tiver configurado o conector para sincronizar a tabela incident no ServiceNow, o conector criará a tabela chamada dest_db.dest_schema.incident.

Esta tabela contém dados brutos ingeridos do ServiceNow. Esta tabela contém as seguintes colunas:

Coluna

Tipo de dados

Descrição

sys_id

VARCHAR

O valor do sys_id do registro no ServiceNow.

raw

VARIANT

Os dados para o registro na forma bruta.

is_deleted

BOOLEAN

Especifica se o registro foi ou não excluído no ServiceNow.

last_update_date

TIMESTAMP_NTZ

A última vez que o registro foi atualizado no Snowflake.

O seguinte é um exemplo da saída para uma instrução SELECT que recupera os dados para a tabela dest_db.dest_schema.incident:

SELECT * FROM DEST_DB.DEST_SCHEMA.INCIDENT LIMIT 5;

+----------------------------------+-------------------------+-------------+--------------------------+
| SYS_ID                           | RAW:ACTIVE              |  IS_DELETED | LAST_UPDATE_DATE         |
+----------------------------------+-------------------------+-------------+--------------------------+
| caa04d36db8ba0106e9643c81396197b | {"active": "true", ...} |  FALSE      |  2021-08-24 12:59:23.932 |
| cea045be1b03e010eac562c4bd4bcbb2 | {"active": "true", ...} |  FALSE      |  2021-08-24 12:59:23.932 |
| caa0c9bedb8be010f9f19c41ba961934 | {"active": "true", ...} |  FALSE      |  2021-08-24 12:59:23.932 |
| caa0c9bedb8be010f9f19c41ba961969 | {"active": "true", ...} |  FALSE      |  2021-08-24 12:59:23.932 |
| b9a0c53adb436410d6fa2b691396190a | {"active": "true", ...} |  FALSE      |  2021-08-24 12:59:23.932 |
+----------------------------------+-------------------------+-------------+--------------------------+
Copy

Acesso aos dados nivelados

Para cada tabela que contém dados, o conector cria duas exibições niveladas sobre os dados brutos. Os nomes das exibições são os nomes da tabela com os sufixos __view e __view_with_deleted. Por exemplo, para a tabela ServiceNow chamada incident, o conector cria as seguintes exibições:

  • dest_db.dest_schema.incident__view

  • dest_db.dest_schema.incident__view_with_deleted

A exibição com o sufixo __view contém os registros que estão na tabela ServiceNow. A exibição com o sufixo __view_with_deleted inclui esses mesmos registros, assim como os registros que foram excluídos da tabela ServiceNow.

Observe o seguinte:

  • Os nomes das colunas nestas exibições estão em maiúsculas. Você não pode usar nomes em minúsculas para acessar estas colunas.

  • Não há exibições para tabelas vazias. Depois que os dados aparecem na tabela no ServiceNow, a exibição é criada.

  • Embora o conector trate de alterações no esquema, o conector não recarrega os dados.

    Como resultado, no caso de alterações de esquema, os registros do esquema antigo não são atualizados.

O seguinte é um exemplo da saída para uma instrução SELECT que recupera os dados da exibição dest_db.dest_schema.incident_view. Neste exemplo, a tabela incident no ServiceNow tem colunas chamadas ACTIVE, APPROVAL, CATEGORY e ESCALATION.

SELECT ACTIVE, APPROVAL, CATEGORY, ESCALATION
FROM DEST_DB.DEST_SCHEMA.INCIDENT__VIEW LIMIT 5;

+--------+----------------+------------------+------------+
| ACTIVE | APPROVAL       | CATEGORY         | ESCALATION |
+--------+----------------+------------------+------------+
| TRUE   | not requested  | software         | 0          |
| TRUE   | not requested  | Cloud Management | 0          |
| TRUE   | not requested  | software         | 0          |
| TRUE   | not requested  | network          | 0          |
| TRUE   | not requested  | database         | 0          |
+--------+----------------+------------------+------------+
Copy

Visualização dos logs de eventos de uma tabela

O conector Snowflake para ServiceNow pode rastrear as alterações feitas nos registros no ServiceNow. Estas informações de rastreamento são armazenadas em tabelas chamadas logs de eventos.

Para cada tabela do ServiceNow habilitada para sincronização, o conector cria uma tabela de log de eventos dentro do Snowflake chamada <destination_db>.<destination_schema>.<table_name>__event_log.

Cada tabela de log de eventos tem as seguintes colunas:

Coluna

Tipo de dados

Descrição

sys_id

VARCHAR

O valor do sys_id do registro no ServiceNow.

sys_updated_on

VARCHAR

A data em que o registro foi atualizado pela última vez em ServiceNow. Se não houver campo sys_updated_on na tabela ServiceNow, esta coluna terá valores nulos.

event_date

TIMESTAMP_NTZ

A data em que o evento foi inserido no log de eventos.

raw

VARIANT

Os dados atuais do evento de registro. Para eventos DELETE, estes são os dados do registro no momento da exclusão.

event_type

VARCHAR

Especifica se o registro foi inserido, atualizado ou excluído do ServiceNow.

O log de eventos reflete o histórico de alterações de dados na tabela correspondente do ServiceNow. Por exemplo, se um novo registro for inserido na tabela u_ip_port no ServiceNow, um registro com event_type definido como tipo de evento INSERT é adicionado à tabela dest_db.dest_schema.u_ip_port__event_log no Snowflake.

Da mesma forma, se um registro for atualizado ou excluído em uma tabela no ServiceNow, um registro com event_type definido como UPDATE ou DELETE é adicionado à tabela de dest_db.dest_schema.u_ip_port__event_log.

As tabelas no Snowflake que contêm os dados brutos (dest_db.dest_schema.table_name) são derivadas das tabelas de log de eventos correspondentes (dest_db.dest_schema.table_name__event_log). Por exemplo:

  • Se um registro para um evento INSERT for adicionado ao table_name__event_log, o conector adiciona um registro correspondente à tabela table_name.

  • Se um evento UPDATE para o sys_id dado for adicionado à tabela de registro de eventos, o conector atualiza o registro correspondente com o sys_id na tabela table_name com novos dados.

  • Se um evento DELETE ocorrer, o sinalizador is_deleted do registro correspondente em table_name é definido como true.

Como obter o valor de exibição de um campo de referência

Nas tabelas do ServiceNow, alguns campos são campos de referência, que contêm referências a registros em outras tabelas.

No exemplo abaixo, o campo opened_by na tabela incident é um campo de referência que contém uma referência ao registro com o sys_id <sys_id> em outra tabela (sys_user):

{
  "link": "https://testingatt1.service-now.com/api/now/table/sys_user/<sys_id>",
  "value": "<sys_id>"
}
Copy

Para mostrar os campos de referência na tabela, chame o procedimento armazenado SHOW_REFERENCES_OF_TABLE com o seguinte argumento:

CALL SHOW_REFERENCES_OF_TABLE('<table_name>');
Copy

Onde:

table_name

Especifica o nome da tabela para a qual você deseja mostrar os campos de referência.

Este procedimento armazenado inspeciona o esquema da tabela e retorna uma lista de objetos JSON contendo as seguintes propriedades:

Propriedade

Descrição

columnName

Nome do campo de referência.

referencedColumnName

Nome do campo para o qual a referência aponta.

referencedTableName

Nome da tabela referenciada.

Nota

Para usar este procedimento, o conector deve usar o usuário ServiceNow atribuído à função ServiceNow admin. Sem esta função, o procedimento retornará um erro de autorização. Para obter mais informações, consulte Como preparar sua instância do ServiceNow.

Ativação da sincronização de dados para tabelas referidas

Se uma tabela contiver referências a outras tabelas, você poderá habilitar a sincronização de dados das tabelas referidas. Para sincronizar dados para tabelas referidas, chame o procedimento armazenado ENABLE_REFERENCED_TABLES com o seguinte argumento:

CALL ENABLE_REFERENCED_TABLES('<table_name>');
Copy

Onde:

table_name

Especifica o nome da tabela (com os campos de referência da tabela) para a qual você deseja ativar a sincronização de dados.

Nota

Para usar este procedimento, o conector deve usar o usuário ServiceNow atribuído à função ServiceNow admin. Sem esta função, o procedimento retornará um erro de autorização. Para obter mais informações, consulte Como preparar sua instância do ServiceNow.

Criação de uma exibição contendo campos de referência

Se a tabela que contém os campos de referência e as tabelas referenciadas por esses campos tiverem sido processadas, você poderá criar uma exibição que substitua as referências por valores de exibição.

Para criar esta exibição, chame o procedimento armazenado CREATE_VIEW_WITH_DISPLAY_VALUES.

CALL CREATE_VIEW_WITH_DISPLAY_VALUES('<table_name>');
Copy

Onde:

table_name

Especifica o nome da tabela que contém os campos de referência da tabela para os quais você deseja criar uma exibição com valor de exibição.

Nota

Somente campos de referência com sys_id como chave de referência são suportados.

Nota

Para usar este procedimento, o conector deve usar o usuário ServiceNow atribuído à função ServiceNow admin. Sem esta função, o procedimento retornará um erro de autorização. Para obter mais informações, consulte Como preparar sua instância do ServiceNow.

Depois que a exibição for criada com êxito, o procedimento armazenado retornará o nome da exibição recém-criada. O nome da exibição é o nome da tabela com o sufixo __view_with_references adicionado. Por exemplo, para uma tabela do ServiceNow chamada incident, o procedimento armazenado cria a exibição incident__view_with_references. Os campos de referência são substituídos por valores de exibição e uma nova coluna de metadados é adicionada para cada campo de referência.

A coluna do valor de exibição tem o mesmo nome da coluna de referência que está sendo substituída e pode ser nula quando o valor de exibição for nulo ou a referência não for resolvida. O nome da coluna de metadados é o nome da coluna de referência com o sufixo __metadata. Por exemplo, para uma coluna de referência denominada user, o procedimento cria uma coluna denominada user__metadata. O conteúdo desta coluna é um objeto JSON com um campo denominado reference_field com as seguintes propriedades:

Propriedade

Descrição

key

sys_id da referida linha. Se a coluna de referência ou o campo da coluna de referência value for nulo, esta propriedade também será nula.

reference_table

Nome da tabela referenciada. Se a referência não for resolvida, esta propriedade será nula.

link

Link do ServiceNow para a linha referida. Se a coluna de referência ou o campo da coluna de referência link for nulo, esta propriedade também será nula.

display_value

Valor de exibição. Se a referência não for resolvida, esta propriedade será nula.

resolved

true se o valor de exibição for resolvido. false quando o conector não consegue resolver a referência.

reason

Motivo pelo qual a referência não foi resolvida. Por exemplo Display value is not ingested yet. Se a referência for resolvida, esta propriedade não será exibida.

O exemplo a seguir mostra a aparência de um par de colunas de valor de exibição e metadados em uma exibição criada pelo procedimento armazenado CREATE_VIEW_WITH_DISPLAY_VALUES. A tabela de exemplo incident possui a coluna opened_by que faz referência (por sys_id como chave de referência) à tabela sys_user.

A exibição incident__view_with_references criada pelo procedimento armazenado resolve a referência, portanto os valores exibidos podem ser obtidos com um simples SELECT.

SELECT OPENED_BY, OPENED_BY__METADATA
  FROM DEST_DB.DEST_SCHEMA.INCIDENT__VIEW_WITH_REFERENCES;
Copy

Este comando exibe informações no seguinte formato:

+-----------+------------------------------------+
| OPENED_BY | OPENED_BY__METADATA                |
+-----------+------------------------------------+
| "JOHN"    | {                                  |
|           |   "reference_field": {             |
|           |     "display_value": "JOHN",       |
|           |     "key": "b177...",              |
|           |     "link": "https://...",         |
|           |     "reference_table": "sys_user", |
|           |     "resolved": true               |
|           |   }                                |
|           | }                                  |
+-----------+------------------------------------+