Configuration de l’ingestion de données pour vos données ServiceNow®¶

Enregistrements archivés¶

Le connecteur ne reflète pas activement les enregistrements archivés dans ServiceNow côté Snowflake pour les tables ingérées. Si vous archivez des enregistrements inactifs antérieurs à une certaine date, les règles suivantes s’appliquent :

• Aucun enregistrement archivé avant son ingestion par le connecteur (par exemple, avant le chargement initial de la table) ne sera présent dans la table côté Snowflake.

• Tout enregistrement archivé après avoir été ingéré par le connecteur reste côté Snowflake sans aucune indication de l’action d’archivage.

• Aucun enregistrement archivé restauré pour une table qui fonctionne déjà en mode de mises à jour incrémentielles ne sera ingéré côté Snowflake, sauf si cet enregistrement est également modifié par la suite (avec sa valeur sys_updated_on mise à jour à l’heure actuelle).

• Un enregistrement archivé restauré lors du chargement initial de la table peut être ingéré côté Snowflake suivant son ID dans la colonne sys_id.

Si vous souhaitez mettre à jour la table avec une règle d’archivage active, vous pouvez recharger la table entière, mais tout enregistrement archivé ou restauré après le rechargement suivra les mêmes principes que ceux énumérés ci-dessus.

Les tables d’archivage ServiceNow ar_[table_name] peuvent être activées à des fins de synchronisation. Toutefois, la première mise à jour incrémentielle qui suit le chargement initial de cette table fait l’objet de recherches pour trouver les enregistrements créés/mis à jour après la date de début du chargement initial de la table d’archivage. Comme ni sys_updated_on, ni sys_created_on ne sont modifiés lorsque l’enregistrement est archivé, les enregistrements archivés après le chargement initial de la table d’archivage jusqu’à un moment donné n’y figurent pas côté Snowflake. Par exemple, si vous archivez des enregistrements datant de plus d’un an, aucun enregistrement archivé pendant un an après le chargement initial de la table d’archivage n’est ingéré dans la table d’archivage côté Snowflake. Les enregistrements archivés qui ont été restaurés ou supprimés par une règle de destruction à la suite du chargement initial d’une table d’archivage ne sont jamais supprimés de celle-ci côté Snowflake.

Modification de l’ingestion de données à l’aide de Snowsight¶

Pour modifier les tables ServiceNow® à ingérer ou la planification de synchronisation des tables, procédez comme suit :

1. Connectez-vous à Snowsight en tant qu’utilisateur ayant le rôle ACCOUNTADMIN.

2. Dans le menu de navigation, sélectionnez Data Products » Apps.

3. Recherchez l’application Snowflake Connector for ServiceNow® V2, puis sélectionnez la vignette du connecteur.

4. Dans la page Snowflake Connector for ServiceNow®V2, sélectionnez Data Sync.

5. Sélectionnez le bouton Edit tables pour passer en mode d’édition.

6. Modifiez les tables que vous souhaitez ingérer :

   1. Recherchez la table que vous souhaitez ingérer.

   2. Cochez la case de la colonne Status à gauche de la table que vous souhaitez sélectionner ou désélectionner.

   3. Sous Sync Schedule, sélectionnez la fréquence de synchronisation de la table entre Snowflake et ServiceNow®.

7. Sélectionnez Update data sync.

Activation ou désactivation de la synchronisation des tables¶

Cette section explique comment activer ou désactiver la synchronisation d’une table dans ServiceNow®. L’activation de la synchronisation peut être effectuée avec une configuration par défaut et une configuration personnalisée.

CALL ENABLE_TABLES(<tables_to_enable>);

CALL ENABLE_TABLES(['table1', 'table2', 'table3']);

CALL DISABLE_TABLES(<tables_to_disable>);

CALL DISABLE_TABLES(['table1', 'table2']);

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('u_table', { 'include_columns': ['sys_id', 'sys_updated_on'] });

CALL ENABLE_TABLE('u_table', { 'exclude_columns': ['col_1'] });

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('sys_audit', {
  'row_filter': 'tablename = "incident" AND fieldname = "cause" AND newvalue LIKE "privacy"'
});

CALL ENABLE_TABLE('incident', {
  'row_filter': 'active = "true" AND sys_created_by STARTSWITH "support" OR sys_created_by ENDSWITH "admin" AND category IN ("Network", "Cloud Management")'
});

CALL ENABLE_TABLE('incident', {
  'row_filter': 'incident_state IN ("1", "2", "3")', -- "New", "In Progress", "On Hold"
  'include_columns': ['incident_state', 'description']
});

Spécification du calendrier de synchronisation¶

Snowflake Connector for ServiceNow®V2 synchronise les données de toutes les tables ServiceNow® avec Snowflake selon une planification spécifiée. Par défaut, toutes les tables sont synchronisées une fois par heure (1h).

Pour modifier le calendrier de synchronisation par défaut pour toutes les tables, appelez la procédure stockée CONFIGURE_DATA_INGESTION_SCHEDULE avec les arguments suivants :

CALL CONFIGURE_DATA_INGESTION_SCHEDULE(<schedule>);

Où :

schedule

Spécifie la fréquence de la synchronisation. Vous pouvez spécifier l’une des valeurs JSON suivantes :

• { 'type': 'interval', 'value': '<valeur_intervalle>' }, où interval_value est l’une des valeurs de chaîne suivantes :

  • '30m'

  • '1h'

  • '3h'

  • '6h'

  • '12h'

  • '1d'

• { 'type': 'custom', 'value': { 'hour': <heure>, 'day_of_week': '<jour_de_la_semaine>' } }, où hour spécifie l’heure dans le fuseau horaire UTC à laquelle l’ingestion doit commencer, et day_of_week spécifie le jour de la semaine où l’ingestion doit être effectuée. Il est possible d’utiliser des expressions spéciales comme jours de la semaine :

  • '*' pour exécuter l’intégration tous les jours.

  • '1-3' pour exécuter l’intégration du lundi au mercredi.

  • '0,5,6' pour exécuter l’intégration le vendredi, le samedi et le dimanche.

  Les valeurs possibles pouvant être utilisées dans l’expression pour la configuration day_of_week sont :

  • '0' - Dimanche

  • '1' - Lundi

  • '2' - Mardi

  • '3' - Mercredi

  • '4' - Jeudi

  • '5' - Vendredi

  • '6' - Samedi

  Les autres valeurs non numériques telles que '5L' indiquant le dernier vendredi d’un mois ou 'FRI-SUN' indiquant la plage du vendredi au dimanche ne sont pas prises en charge.

Il est possible de configurer la planification d’ingestion d’une table spécifique lors de son activation. Pour activer une seule table et définir sa planification d’ingestion, appelez la procédure stockée ENABLE_TABLE avec les arguments suivants :

CALL ENABLE_TABLE('<table_name>', <table_config>);

Où :

table_name

Spécifie un nom de table ServiceNow® à activer.

table_config

Objet incluant la propriété schedule, qui spécifie la configuration de la synchronisation de la table. Pour des informations détaillées, voir schedule de la procédure stockée CONFIGURE_DATA_INGESTION_SCHEDULE.

Par exemple, pour activer l’ingestion de la table table_1 et synchroniser les données toutes les 3 heures, appelez la procédure stockée suivante :

CALL ENABLE_TABLE('table_1', { 'schedule': { 'type': 'interval', 'value': '3h' } });

Le connecteur vous permet également de spécifier un calendrier différent pour chaque table dont la synchronisation est activée. Pour modifier le calendrier de synchronisation pour un ensemble sélectionné de tables, appelez la procédure stockée CONFIGURE_TABLES_SCHEDULE avec les arguments suivants :

CALL CONFIGURE_TABLES_SCHEDULE(<table_names>, <schedule>);

Où :

table_names

Spécifie un tableau de noms de tables pour lesquelles vous souhaitez configurer le calendrier de synchronisation.

schedule

Spécifie la fréquence de la synchronisation. Pour des informations détaillées, voir schedule de la procédure stockée CONFIGURE_DATA_INGESTION_SCHEDULE.

Par exemple, pour ingérer les tables table_1 et table_2 chaque samedi et dimanche à 11:00 PM UTC, appelez la procédure stockée suivante :

CALL CONFIGURE_TABLES_SCHEDULE(['table_1', 'table_2'], { 'type': 'custom', 'value': { 'hour': 23, 'day_of_week': '0,6' } });

Par défaut, le connecteur tente de démarrer l’ingestion dans une fenêtre temporelle de trois heures à partir de l’heure de démarrage planifiée. S’il n’est pas possible de démarrer l’ingestion dans ce délai, par exemple lorsque le connecteur ingère d’autres tables, l’exécution planifiée actuelle n’est pas exécutée. Le connecteur tente d’exécuter l’ingestion à la prochaine période planifiée. Il est possible de modifier la durée de la période en appelant la procédure stockée CONFIGURE_CUSTOM_SCHEDULE_START_INGESTION_WINDOW :

CALL CONFIGURE_CUSTOM_SCHEDULE_START_INGESTION_WINDOW(<window_length>);

où window_length est la durée de la fenêtre au format de durée ISO 8601. La durée doit être arrondie à l’heure entière suivante et doit être d’au moins une heure. Par exemple, la valeur 'PT12H' indique une fenêtre qui dure 12 heures, et 'P2D' indique une fenêtre qui dure deux jours.

Si vous n’activez que des tables avec des planifications personnalisées, cette configuration n’affecte que le temps nécessaire à la création et à l’actualisation des vues aplaties pour les tables configurées. Les vues aplaties sont créées lors du premier cycle d’ingestion lorsque les conditions suivantes sont remplies :

• L’ingestion des tables de métadonnées est terminée

• L’ingestion de la table configurée a commencé.

Si les alertes par e-mail sont activées, Snowflake recommande de remplacer la fréquence des alertes par Once per day lors de l’utilisation de la planification personnalisée.

Spécification des heures de début des plages de données¶

Par défaut, Snowflake Connector for ServiceNow®V2 synchronise tous les enregistrements des tables ServiceNow® correspondantes. Pour les tables comportant des colonnes sys_updated_on ou sys_created_on (désormais appelées colonnes de temps), il est possible de restreindre la plage de données synchronisées en définissant une heure de début de la plage de données, c’est-à-dire une limite inférieure pour la valeur de la colonne de temps correspondante des enregistrements.

Avec une telle configuration, les enregistrements dont la valeur de la colonne d’heure correspondante est antérieure à l”horodatage de début de la plage de données ne sont pas ingérés. La colonne de temps correspondante utilisée par cette procédure est déterminée de la même manière que pour les mises à jour incrémentales.

Pour modifier la valeur de l’heure de début de la plage de données, appelez la procédure stockée CONFIGURE_TABLES_RANGE_START avec les arguments suivants :

CALL CONFIGURE_TABLES_RANGE_START(<table_names>, <range_start>);

Copy

Où :

table_names

Spécifie un tableau de noms de tables pour lesquelles vous souhaitez configurer l’heure de début de la plage de données.

range_start

Horodatage spécifiant l”heure de début de la plage de données au format TIMESTAMP_TZ ou NULL pour annuler la valeur actuelle.

• Si l’ingestion de la table n’a pas encore commencé, la valeur de l’heure de début de la plage de données est prise en compte lors de la première ingestion.

• Si l’ingestion de la table a déjà commencé (par exemple, un rechargement est en cours), la valeur de l’heure de début de la plage de données est ignorée et un (autre) rechargement de la (des) table(s) est nécessaire pour filtrer les enregistrements dont la valeur de la colonne de temps correspondante est trop ancienne.

Il est donc recommandé de définir l’heure de début de la plage de données avant de commencer la première ingestion d’une table (et donc aussi avant de l’activer).

Par exemple, si les tables table1 et table2 ont les colonnes d’heure requises, pour définir l”heure de début de la plage de données à 2022-11-23 07:00:00 UTC pour ces deux tables, exécutez la commande suivante :

CALL CONFIGURE_TABLES_RANGE_START(['table1', 'table2'], TO_TIMESTAMP_TZ('2022-11-23 07:00:00 +00:00'));

Copy

Ensuite :

• Pour la table table1, par exemple, si son ingestion n’a pas encore été lancée, tous les enregistrements dont la valeur de la colonne de temps est antérieure à 2022-11-23 07:00:00 ne sont pas ingérés.

• Pour la table table2, par exemple, si son ingestion a déjà commencé, la valeur de l”heure de début de la plage de données est ignorée dans toutes les synchronisations de données jusqu’au rechargement de cette table. Lors du rechargement, tous les enregistrements dont la valeur de la colonne de temps est antérieure à 2022-11-23 07:00:00 ne sont pas ingérés.

Il est également possible de désactiver l”heure de début de la plage de données. Par exemple, pour la désactiver pour la table table1, exécutez la commande suivante :

CALL CONFIGURE_TABLES_RANGE_START(['table1'], NULL);

Copy

Là encore, si une ingestion de la table table1 a déjà été lancée, le rechargement de cette table est nécessaire pour ingérer tous les enregistrements provenant de ServiceNow®.

Rechargement de données dans une table¶

Pour recharger les données d’une table particulière, appelez la procédure stockée RELOAD_TABLE :

CALL RELOAD_TABLE('<table_name>');

Où :

table_name

Spécifie le nom de la table à recharger.

Lorsque vous appelez la procédure stockée RELOAD_TABLE, le connecteur exécute l’exemple suivant :

1. Le connecteur suspend temporairement la table d’origine pour l’ingestion.

   Note

   Pendant que la table est rechargée, vous ne pouvez pas réactiver la table pour l’ingestion.

2. Le connecteur crée une table temporaire distincte pour l’ingestion.

3. Le connecteur ingère les données dans cette nouvelle table temporaire. Cette table est visible dans la vue CONNECTOR_STATS sous la forme d’une table nommée avec un suffixe __tmp.

   Note

   Chaque rechargement prend en compte la valeur de l’heure de début de la plage de données , ce qui peut restreindre les enregistrements ingérés.

4. Une fois les données ingérées, le connecteur remplace les données de la table d’origine par les données de la table temporaire.

5. Le connecteur supprime la table temporaire.

6. Le connecteur réactive la table d’origine pour l’ingestion.

Pendant ce processus, vous pouvez continuer à interroger les données existantes dans la table d’origine. Cependant, les modifications apportées aux données de la table ServiceNow® ne seront pas répercutées dans la table Snowflake tant que le processus d’ingestion ne sera pas terminé.

Pour éviter de surcharger votre instance ServiceNow®, ne rechargez qu’une seule table à la fois.

Annulation du rechargement de la table¶

Pour annuler le processus de rechargement des données d’une table, utilisez la procédure stockée CANCEL_RELOAD_TABLE comme indiqué dans l’exemple suivant :

CALL CANCEL_RELOAD_TABLE('<table_name>');

Où :

table_name

Spécifie le nom de la table dont vous souhaitez annuler le rechargement.

Lorsque vous annulez le rechargement, le connecteur supprime tous les objets temporaires créés pendant le rechargement. La table est alors disponible pour l’ingestion dans le cadre du programme de synchronisation normal.

Configuration de la taille d’une recherche de page unique pour une table¶

Le connecteur récupère les données d’une table en les divisant en morceaux plus petits appelés pages. Chaque requête d’API auprès de ServiceNow® permet de récupérer une page.

Pour en tenir compte, le connecteur limite le nombre de lignes extraites au cours d’une seule requête API. Cette limite correspond à la taille de la page.

Le connecteur utilise le processus suivant pour déterminer la taille de la page :

1. Initialement, la taille de page par défaut est fixée à 10 000 lignes.

2. Si la demande d’extraction échoue pendant l’ingestion parce que la taille de la réponse est dépassée, la taille de la page est progressivement réduite de 1 000, 100, 10 et 1 jusqu’à ce que la demande aboutisse ou que la taille finale de la page soit définie sur 1.

3. La taille de page obtenue est enregistrée dans l’état du connecteur et cette valeur est utilisée par les demandes suivantes.

La taille de page actuelle d’une table est disponible dans la vue TABLES_STATE. Pour connaître la taille de la page, exécutez la commande suivante :

SELECT PAGE_SIZE FROM TABLES_STATE WHERE TABLE_NAME = '<table_name>';

Où :

table_name

Spécifie le nom de la table ServiceNow® en cours d’ingestion.

Le processus utilisé par le connecteur pour déterminer la taille de la page peut être source d’inefficacité. Ce processus ne fait que réduire la taille de la page. Il n’augmente pas la taille de la page. Cela peut se produire lorsqu’une table comporte une seule ligne importante qui entraîne la définition d’une valeur inférieure pour la taille de la page.

Pour éviter cette situation, vous pouvez définir manuellement la taille de la page en appelant la procédure stockée RESET_PAGE_SIZE comme le montre l’exemple suivant :

CALL RESET_PAGE_SIZE('<table_name>');

Où :

table_name

Spécifie le nom de la table ServiceNow® en cours d’ingestion.

Cycle d’ingestion¶

Les cycles d’ingestion pour une table donnée sont déclenchés selon le calendrier configuré. Un cycle télécharge en boucle toutes les lignes pertinentes divisées en pages mentionnées dans le paragraphe précédent à partir de la table source.

Chargement initial et mises à jour

Dès qu’une page de données est récupérée, elle est insérée dans la table correspondante du journal des événements. À ce stade, les modifications récemment récupérées ne sont pas encore disponibles dans la table de synchronisation ou dans les vues aplaties. Lorsque c’est fait, la demande suivante avec des critères mis à jour est émise tant que des données sont renvoyées. Lorsque le cycle d’ingestion est terminé et qu’il n’y a plus de données à récupérer dans la table source, une tâche de fusion asynchrone est déclenchée, qui prend toutes les modifications du journal des événements insérées depuis la dernière fusion et les applique à la table de synchronisation. Une fois terminé, les données sont disponibles sous forme de tables de synchronisation et de vues aplaties.

Tronquer et charger

En mode Tronquer et charger, une table temporaire est créée pour chaque cycle d’ingestion. Chaque page de lignes récupérée est d’abord insérée dans cette table temporaire (cette table existe dans le schéma interne du connecteur et n’est pas accessible aux utilisateurs du connecteur). À ce stade, les modifications récemment récupérées ne sont pas encore disponibles dans la table de synchronisation ou dans les vues aplaties ; elles affichent toujours les données récupérées lors de l’exécution précédente. Lorsque le cycle d’ingestion est terminé et qu’il n’y a plus de données disponibles dans la table source, les données de la table temporaire remplacent les données existantes dans la table de synchronisation. Toutes les lignes extraites sont également ajoutées au journal des événements. À la fin, la table temporaire est supprimée.

Suivi des progrès

Pour vérifier le statut d’un cycle d’ingestion en cours ou passé, vous pouvez effectuer une requête dans la vue CONNECTOR_STATS. Elle est visible dans la colonne STATUS. La valeur DONE n’est attribuée que si les données ont été récupérées avec succès et que toutes les modifications ont été appliquées à la table de synchronisation. Lorsque l’ingestion est en cours ou que la fusion vers la table de synchronisation/le remplacement des lignes dans la table de synchronisation n’est pas encore terminé, le statut est RUNNING.