Accès aux données ServiceNow® dans Snowflake

Le connecteur Snowflake pour ServiceNow® est soumis aux conditions de connecteur.

Cette rubrique décrit comment accéder aux données ServiceNow à partir de votre compte Snowflake.

Dans ce chapitre :

Pour chaque table de ServiceNow configurée pour la synchronisation, le connecteur crée la table et les vues suivantes :

  • Une table portant le même nom qui contient les données sous forme brute, où chaque enregistrement est contenu dans une seule colonne VARIANT.

  • Une table nommée table_name__event_log qui contient l’historique des modifications apportées aux enregistrements ServiceNow.

  • Une vue nommée table_name__view qui contient les données sous forme aplatie, la vue contenant une colonne pour chaque colonne de la table d’origine et une ligne pour chaque enregistrement présent dans la table d’origine.

  • Une vue nommée table_name__view_with_deleted qui contient les mêmes données que table_name__view ainsi que les lignes des enregistrements qui ont été supprimées dans ServiceNow.

Note

Après le démarrage du connecteur, la création des vues peut prendre un certain temps.

La création d’une vue dépend des données contenues dans les tables ServiceNow sys_db_object, sys_dictionary et sys_glide_object. Le connecteur charge les métadonnées de ces tables une fois qu’une table commerciale est activée à des fins de synchronisation. Lorsque les tables de métadonnées sont ingérées, une tâche d’arrière-plan crée des vues aplaties des tables activées. La tâche est exécutée aussi souvent que la programmation de l’ingestion de table la plus fréquente. Après la synchronisation des tables de métadonnées, la tâche capture également toutes les modifications de schéma de table et met à jour les vues déjà créées en conséquence (uniquement les vues avec les suffixes __view et __view_with_deleted, mais pas avec __view_with_display_values).

Comme il ne s’agit pas d’un processus immédiat, le statut du processus de création de vue est disponible sous la vue ENABLED_TABLES. Si la création de vue prend trop de temps, la vue CONNECTOR_ERRORS peut également être vérifiée pour détecter d’éventuelles erreurs associées.

Les sections suivantes expliquent comment accorder les privilèges d’accès à ces données et comment accéder aux données de ces tables et vues.

Octroi de privilèges pour l’accès aux données ServiceNow dans Snowflake

Une fois que le Snowflake Connector for ServiceNow® a synchronisé les données avec Snowflake, tout rôle disposant des privilèges suivants peut accéder aux données ServiceNow :

  • Le privilège USAGE sur la base de données et le schéma qui contiennent les données ServiceNow dans Snowflake et

  • Le privilège SELECT sur les tables ou les vues de ce schéma

Snowflake recommande de créer un rôle dédié avec ces privilèges qui peuvent être accordés aux utilisateurs qui ont besoin d’accéder aux données ServiceNow ingérées.

Par exemple, si vous avez configuré le connecteur pour stocker les données ServiceNow dans la base de données dest_db et le schéma dest_schema , vous pouvez créer un rôle nommé servicenow_data_reader_role et lui accorder les privilèges d’accès aux données.

L’exemple suivant montre comment accorder ces privilèges :

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

Note

  • N’exécutez pas GRANT OWNERSHIP ON FUTURE TABLES IN SCHEMA sur le schéma qui contient les données ServiceNow dans Snowflake. Ne modifiez pas non plus la propriété des tables déjà créées par le connecteur. La modification de la propriété empêche le connecteur d’intégrer les données dans la table.

  • Ne modifiez pas la propriété des vues dans le schéma qui contient les données ServiceNow dans Snowflake. La modification de la propriété empêche le connecteur de mettre à jour les vues lorsque des modifications sont apportées au schéma de table ServiceNow.

Accès aux données brutes

Pour chaque table ServiceNow que vous synchronisez, le Snowflake Connector for ServiceNow® crée une nouvelle table portant le même nom dans la base de données et le schéma pour les données ServiceNow dans Snowflake.

Par exemple, si vous avez configuré le connecteur pour stocker les données ServiceNow dans la base de données dest_db et le schéma dest_schema , et si vous avez configuré le connecteur pour synchroniser la table incident dans ServiceNow, le connecteur crée la table nommée dest_db.dest_schema.incident.

Cette table contient des données brutes ingérées depuis ServiceNow. Cette table contient les colonnes suivantes :

Colonne

Type de données

Description

sys_id

VARCHAR

Valeur de sys_id de l’enregistrement dans ServiceNow.

raw

VARIANT

Données de l’enregistrement sous forme brute.

is_deleted

BOOLEAN

Indique si l’enregistrement a été supprimé ou non dans ServiceNow.

last_update_date

TIMESTAMP_NTZ

Dernière mise à jour de l’enregistrement dans Snowflake. Notez que l’horodatage affiché est fourni dans le fuseau horaire UTC sans décalage, ce qui peut différer du fuseau horaire des dates affichées dans l’instance ServiceNow.

Voici un exemple de la sortie d’une instruction SELECT qui récupère les données de la table 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

Accès aux données aplaties

Pour chaque table contenant des données, le connecteur crée deux vues aplaties sur les données brutes. Les noms des vues sont les noms des tables avec les suffixes __view et __view_with_deleted. Par exemple, pour la table ServiceNow nommée incident, le connecteur crée les vues suivantes :

  • dest_db.dest_schema.incident__view

  • dest_db.dest_schema.incident__view_with_deleted

La vue avec le suffixe __view contient les enregistrements qui se trouvent dans la table ServiceNow. La vue avec le suffixe __view_with_deleted comprend ces mêmes enregistrements ainsi que les enregistrements qui ont été supprimés de la table ServiceNow.

Remarques :

  • Les noms des colonnes de ces vues sont en majuscules. Vous ne pouvez pas utiliser de noms en minuscules pour accéder à ces colonnes.

  • Les colonnes contenant l’heure et les horodatages sont toujours enregistrées en utilisant le fuseau horaire UTC, quel que soit le fuseau horaire défini dans l’instance ServiceNow. En conséquence, selon la configuration de l’instance ServiceNow, leurs valeurs affichées peuvent différer des valeurs affichées dans l’instance ServiceNow. La différence ne concerne que les valeurs affichées, les horodatages dans ServiceNow et Snowflake se réfèrent au même point dans le temps.

  • Il n’y a pas de vues pour les tables vides. Une fois que les données apparaissent dans la table ServiceNow, la vue est créée.

  • Bien que le connecteur gère les modifications du schéma, il ne recharge pas les données.

    Par conséquent, en cas de modification du schéma, les enregistrements de l’ancien schéma ne sont pas mis à jour.

Voici un exemple de la sortie d’une instruction SELECT qui récupère les données de la vue dest_db.dest_schema.incident_view. Dans cet exemple, la table incident dans ServiceNow comporte des colonnes nommées ACTIVE, APPROVAL, CATEGORY, et 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

Visualisation des journaux d’événements d’une table

Le Snowflake Connector for ServiceNow® peut suivre les modifications apportées aux enregistrements dans ServiceNow. Ces informations de suivi sont stockées dans des tables appelées journaux d’événements.

Pour chaque table ServiceNow pour lesquelles la synchronisation est activée, le connecteur crée une table de journal d’événements dans Snowflake nommée <destination_db>.<destination_schema>.<table_name>__event_log.

Chaque table du journal d’événements comporte les colonnes suivantes :

Colonne

Type de données

Description

sys_id

VARCHAR

Valeur de sys_id de l’enregistrement dans ServiceNow.

sys_updated_on

VARCHAR

Date de la dernière mise à jour de l’enregistrement dans ServiceNow. S’il n’y a pas de champ sys_updated_on dans la table ServiceNow, cette colonne contient des valeurs nulles. Notez que l’horodatage affiché est fourni dans le fuseau horaire UTC sans décalage, ce qui peut différer du fuseau horaire des dates affichées dans l’instance ServiceNow.

event_date

TIMESTAMP_NTZ

Date à laquelle l’événement a été inséré dans le journal des événements. Notez que l’horodatage affiché est fourni dans le fuseau horaire UTC sans décalage, ce qui peut différer du fuseau horaire des dates affichées dans l’instance ServiceNow.

raw

VARIANT

Données actuelles de l’événement d’enregistrement. Pour les événements DELETE, il s’agit des données de l’enregistrement au moment de la suppression.

event_type

VARCHAR

Indique si l’enregistrement a été inséré, mis à jour ou supprimé de ServiceNow.

Le journal des événements reflète l’historique des changements de données dans la table ServiceNow correspondante. Par exemple, si un nouvel enregistrement est inséré dans la table u_ip_port dans ServiceNow, un enregistrement dont le type d’événement event_type est défini sur INSERT est ajouté à la table dest_db.dest_schema.u_ip_port__event_log dans Snowflake.

De même, si un enregistrement est mis à jour ou supprimé dans une table dans ServiceNow, un enregistrement dont event_type est défini comme UPDATE ou DELETE est ajouté à la table dest_db.dest_schema.u_ip_port__event_log.

Les tables dans Snowflake qui contiennent les données brutes (dest_db.dest_schema.table_name) sont dérivées des tables correspondantes du journal des événements (dest_db.dest_schema.table_name__event_log). Par exemple :

  • Si un enregistrement pour un événement INSERT est ajouté à table_name__event_log, le connecteur ajoute un enregistrement correspondant à la table table_name.

  • Si un événement UPDATE pour le sys_id donné est ajouté à la table du journal d’événements, le connecteur met à jour l’enregistrement correspondant avec le sys_id dans la table table_name avec de nouvelles données.

  • Si un événement DELETE se produit, l’indicateur is_deleted de l’enregistrement correspondant dans table_name est défini sur true.

Obtention de la valeur d’affichage d’un champ de référence

Dans les tables ServiceNow, certains champs sont des champs de référence, qui contiennent des références à des enregistrements d’autres tables.

Dans l’exemple ci-dessous, le champ opened_by de la table incident est un champ de référence qui contient une référence à l’enregistrement avec le sys_id <sys_id> dans une autre table (sys_user) :

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

Pour afficher les champs de référence dans la table, appelez la procédure stockée SHOW_REFERENCES_OF_TABLE avec l’argument suivant :

CALL SHOW_REFERENCES_OF_TABLE('<table_name>');
Copy

Où :

table_name

Indique le nom de la table pour laquelle vous souhaitez afficher les champs de référence.

Cette procédure stockée inspecte le schéma de la table et renvoie une liste d’objets JSON contenant les propriétés suivantes :

Propriété

Description

columnName

Nom du champ de référence.

referencedColumnName

Nom du champ sur lequel porte la référence.

referencedTableName

Nom de la table référencée.

Note

Pour utiliser cette procédure, le connecteur doit utiliser l’utilisateur ServiceNow auquel a été attribué le rôle ServiceNow admin. Sans ce rôle, la procédure renverra une erreur d’autorisation. Pour plus d’informations, voir Préparation de votre instance ServiceNow.

Activation de la synchronisation des données pour les tables de référence

Si une table contient des références à d’autres tables, vous pouvez activer la synchronisation des données des tables de référence. Pour synchroniser les données des tables de référence, appelez la procédure stockée ENABLE_REFERENCED_TABLES avec l’argument suivant :

CALL ENABLE_REFERENCED_TABLES('<table_name>');
Copy

Où :

table_name

Spécifie le nom de la table (avec les champs de référence de la table) pour laquelle vous souhaitez activer la synchronisation des données.

Note

Pour utiliser cette procédure, le connecteur doit utiliser l’utilisateur ServiceNow auquel a été attribué le rôle ServiceNow admin. Sans ce rôle, la procédure renverra une erreur d’autorisation. Pour plus d’informations, voir Préparation de votre instance ServiceNow.

Création d’une vue contenant des champs de référence

Si la table contenant les champs de référence et si les tables référencées par ces champs ont été traitées, vous pouvez créer une vue qui remplace les références par des valeurs d’affichage.

Pour créer cette vue, appelez la procédure stockée CREATE_VIEW_WITH_DISPLAY_VALUES.

CALL CREATE_VIEW_WITH_DISPLAY_VALUES('<table_name>');
Copy

Où :

table_name

Spécifie le nom de la table contenant les champs de référence de la table pour lesquels vous souhaitez créer une vue avec valeur d’affichage.

Note

Seuls les champs de référence avec la clé de référence sys_id comme sont pris en charge.

Note

Pour utiliser cette procédure, le connecteur doit utiliser l’utilisateur ServiceNow auquel a été attribué le rôle ServiceNow admin. Sans ce rôle, la procédure renverra une erreur d’autorisation. Pour plus d’informations, voir Préparation de votre instance ServiceNow.

Une fois la vue créée avec succès, la procédure stockée renvoie le nom de la vue nouvellement créée. Le nom de la vue est le nom de la table auquel a été ajouté le suffixe __view_with_references. Par exemple, pour une table ServiceNow nommée incident, la procédure stockée crée la vue incident__view_with_references. Les champs de référence sont remplacés par des valeurs d’affichage et une nouvelle colonne de métadonnées est ajoutée pour chaque champ de référence.

La colonne de la valeur d’affichage porte le même nom que la colonne de référence remplacée et peut être nulle si la valeur d’affichage est nulle ou si la référence n’est pas résolue. Le nom de la colonne de métadonnées est le nom de la colonne de référence avec le suffixe __metadata. Par exemple, pour une colonne de référence nommée user, la procédure crée une colonne nommée user__metadata. Le contenu de cette colonne est un objet JSON avec un champ nommé reference_field avec les propriétés suivantes :

Propriété

Description

key

sys_id de la ligne de référence. Si la colonne de référence ou le champ de colonne de référence value est nul, cette propriété est également nulle.

reference_table

Nom de la table référencée. Si la référence n’est pas résolue, cette propriété est nulle.

link

Lien ServiceNow vers la ligne de référence. Si la colonne de référence ou le champ de colonne de référence link est nul, cette propriété est également nulle.

display_value

Valeur d’affichage. Si la référence n’est pas résolue, cette propriété est nulle.

resolved

true si la valeur d’affichage est résolue. false lorsque le connecteur ne peut pas résoudre la référence.

reason

Raison pour laquelle la référence n’a pas été résolue. Par exemple, Display value is not ingested yet. Si la référence est résolue, cette propriété n’est pas affichée.

L’exemple suivant montre à quoi ressemble une paire de colonnes de valeurs d’affichage et de métadonnées dans une vue créée par la procédure stockée CREATE_VIEW_WITH_DISPLAY_VALUES. La table d’exemple incident possède une colonne opened_by qui fait référence (par sys_id comme clé de référence) à la table sys_user.

La vue incident__view_with_references créée par la procédure stockée résout la référence, de sorte que les valeurs affichées peuvent être obtenues par une simple SELECT.

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

Cette commande permet d’afficher des informations dans le format suivant :

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