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

Enregistrements archivés¶

The connector does not actively reflect the records archived in ServiceNow on the Snowflake side for the ingested tables. Assuming that you archive inactive records older than a certain date, the following apply:

• Any record archived before the connector ingested it (for example, before the initial load of the table) will not be present in the table on the Snowflake side at all.

• 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).

• An archived record restored during the initial load of the table may be ingested on the Snowflake side depending on its ID in the sys_id column.

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.

Modify data ingestion using 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 Catalog » Apps.

3. Recherchez l’appli Snowflake Connector for ServiceNow®, puis sélectionnez la vignette correspondant au connecteur.

4. Dans la page Snowflake Connector for ServiceNow®, 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.

Enable or disable the table synchronization¶

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']);

Enable a single table by using column filtering¶

If you don’t need all columns from a ServiceNow® table in Snowflake, the connector can ignore them. For example, skip columns if a single row exceeds the maximum row size of 128 MB.

Pour activer l’ingestion de tables avec les colonnes spécifiées, exécutez la commande suivante :

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

Où :

table_to_enable

Spécifie un nom de table ServiceNow®.

table_config

Objet comprenant la propriété include_columns ou exclude_columns avec une liste de noms de colonne. Si sys_id, sys_created_on et sys_updated_on existent, ils sont toujours inclus. Vous n’avez pas besoin de les ajouter au tableau included_columns et vous ne pouvez pas les exclure via excluded_columns, car le connecteur les utilise dans le processus d’ingestion.

Par exemple, avec une table ServiceNow® nommée u_table avec les colonnes sys_id, sys_updated_on, col_1 et col_2 et exécutant :

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

n’ingérera que les colonnes sys_id et sys_updated_on pour la table donnée, mais l’appel à :

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

ingérera sys_id, sys_updated_on et aussi col_2.

The connector validates the provided columns and rejects the enablement request if any of the columns are not available in ServiceNow®. ServiceNow® API supports only include mode. As a result the connector transforms provided column arrays into included columns list and sends them with each request to ServiceNow®. The URL with included columns could possibly be too long to be handled by ServiceNow®. The connector validates this limitation when the ENABLE_TABLE is invoked.

La configuration des colonnes pour chaque table se trouve dans la colonne INCLUDED_COLUMNS de la vue CONFIGURED_TABLES. Pour modifier la liste des colonnes ingérées, vous devez d’abord désactiver la table concernée. Si le filtrage des colonnes est configuré pour une table, vous pouvez activer la table uniquement à l’aide de la procédure ENABLE_TABLE. Vous ne pouvez pas utiliser ENABLE_TABLES, qui accepte une liste de tables comme argument.

Les vues aplaties ne comprennent que les colonnes spécifiées lors de l’activation de la table. Elles sont mises à jour chaque fois que la liste des colonnes incluses est modifiée. Si le filtrage de colonnes n’est pas configuré, les vues contiennent toutes les colonnes disponibles.

Enable a single table by using row filtering¶

Vous pouvez exclure l’ingestion de données pour certaines lignes d’une table ServiceNow® en spécifiant une condition de filtre. Par exemple, pour exclure les lignes qui incluent des données sensibles que vous ne souhaitez pas dans Snowflake ou pour exclure les lignes qui incluent des données inutiles afin de réduire les coûts.

Pour activer l’ingestion de tables avec le filtre de lignes spécifié, exécutez la commande suivante :

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

Où :

table_to_enable

Spécifie un nom de table ServiceNow®.

table_config

Objet comprenant la propriété row_filter avec une expression de filtre, qui est une chaîne valide.

Les opérateurs de filtre actuellement pris en charge sont les suivants :

Opérateur	Description	Exemple
AND	Opérateur logique permettant de joindre des conditions, où les deux conditions doivent être remplies.	active = "true" AND impact = "2"
OR	Opérateur logique permettant de joindre des conditions, où au moins l’une des conditions doit être remplie. Important A priorité sur l’opérateur AND. Voir les exemples ci-dessous.	tablename = "incident" OR tablename = "problem"
=	Renvoie true si les valeurs sont égales.	priority = "1"
!=	Renvoie true si les valeurs ne sont pas égales.	state != "7"
LIKE	Renvoie true si la valeur contient la séquence de caractères spécifiée. [1]	newvalue LIKE "privacy"
NOT LIKE	Renvoie true si la valeur ne contient pas de séquence de caractères spécifiée. [1]	description NOT LIKE "test"
STARTSWITH	Renvoie true si la valeur commence par la séquence de caractères spécifiée. [1]	description STARTSWITH "important"
ENDSWITH	Renvoie true si la valeur se termine par la séquence de caractères spécifiée. [1]	description ENDSWITH "important"
IN	Renvoie true si la valeur est égale à l’une des listes de valeurs. [2]	tablename IN ("incident", "task", "cmdb_ci")
NOT IN	Renvoie true si la valeur n’est égale à aucune des valeurs de la liste. [2]	status NOT IN ("in progress", "on hold", "cancelled")

_[1] - les champs doivent posséder le type de données string.

_[2] - les champs de sélection doivent contenir des chaînes.

Règles et limitations des expressions de filtre :

• deux expressions de filtre, quelles qu’elles soient, doivent être jointes à l’aide de l’opérateur AND ou OR.

• Les opérateurs doivent être séparés par un espace et en majuscules.

• Les expressions de valeur doivent être placées entre guillemets doubles.

• Les expressions sont sensibles à la casse.

• L’expression ne peut pas fonctionner sur une colonne sys_id, sys_updated_on ou sys_created_on.

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']
});

Specify the synchronization schedule¶

Snowflake Connector for ServiceNow® 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': 'continuous' }, qui est une planification d’ingestion en quasi-temps réel. Une table avec ce calendrier de synchronisation utilise un travail dédié pour ingérer des données et ne compte pas dans le nombre maximum de tables pouvant être synchronisées en parallèle. Pour plus d’informations, voir Adaptation de la taille du connecteur. Vous pouvez configurer jusqu’à 20 tables avec une planification continue.

  Avertissement

  Les tables avec une planification continue provoquent une charge accrue sur une instance ServiceNow®. En outre, l’entrepôt du connecteur est constamment utilisé, ce qui augmente la consommation de crédit de l’entrepôt. Snowflake recommande d’utiliser les planifications continues avec précaution et uniquement pour les tables qui nécessitent des données en temps quasi réel dans Snowflake. Pour éviter la surcharge d’une instance ServiceNow®, le connecteur met en œuvre un mécanisme de détection capable de désactiver automatiquement les tables qui échouent avec une planification continue. Pour plus d’informations, voir Table avec planification continue désactivée par le connecteur.

• { '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': '<day_of_week>' } } 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.

Specify whether deletions should be synchronized¶

Vous pouvez spécifier si le connecteur doit synchroniser les suppressions de ServiceNow® vers Snowflake. Par défaut, le connecteur synchronise les suppressions si une table de journal est configurée. Cependant, vous pouvez souhaiter désactiver la synchronisation des suppressions d’une table spécifique et ne pas modifier la configuration globale.

Pour activer l’ingestion de tables avec les paramètres de synchronisation des suppressions spécifiés, exécutez la commande suivante :

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

Où :

table_to_enable

Spécifie un nom de table ServiceNow®.

table_config

Objet comprenant la propriété booléenne sync_deletions. Si la valeur est définie sur true, le connecteur synchronise les suppressions pour la table ; si la valeur est définie sur false, le connecteur ne synchronise pas les suppressions pour la table.

Par exemple, pour activer l’ingestion de la table incident mais ne pas synchroniser les suppressions, exécutez la commande suivante :

CALL ENABLE_TABLE('incident', { 'sync_deletions': false });

Specify whether display values should be fetched¶

Le connecteur peut extraire les valeurs d’affichage pour tous les types de champs pris en charge dans ServiceNow®. Les valeurs d’affichage sont des valeurs lisibles qui correspondent aux valeurs réelles stockées dans la base de données. Par exemple, un champ dont la valeur est 1 peut avoir une valeur d’affichage High. Pour en savoir plus sur les valeurs d’affichage, consultez la documentation ServiceNow®.

La valeur résolue est affichée dans une vue aplatie dans une colonne séparée avec le suffixe __DISPLAY_VALUE. Le connecteur crée des colonnes de texte et booléennes avec les types Snowflake, mais pour d’autres types, par exemple différents formats possibles de valeurs de nombres ou de dates, les valeurs d’affichage sont stockées en tant que variantes.

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

CALL ENABLE_TABLE('incident', { 'fetch_display_values': true });

CALL CONFIGURE_DISPLAY_VALUE_FETCHING(<fetch_display_values>);

CALL CONFIGURE_DISPLAY_VALUE_FETCHING(true);

Specify the data range start time¶

Par défaut, Snowflake Connector for ServiceNow® 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.

With such a configuration, records with the corresponding time column value older than the data range start timestamp are not ingested. The corresponding time column used by this procedure is determined in the same way as for the incremental updates .

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 :

• for table table1, for example, if its ingestion has not started yet, all records with a corresponding time column value before 2022-11-23 07:00:00 are not ingested.

• for table table2, for example, if its ingestion has already started, the data range time start value is ignored in all data synchronizations until reloading this table. During the reload, all records with a corresponding time column value before 2022-11-23 07:00:00 are not ingested.

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®.

Full reload¶

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 ce qui suit :

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.

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é.

Rechargement filtré¶

Pour ne recharger qu’une partie des données d’une table particulière, appelez la procédure stockée RELOAD_TABLE avec un paramètre d’objet de configuration :

CALL RELOAD_TABLE('<table_name>', <config>);

Où :

table_name

Spécifie le nom de la table à recharger.

config

Spécifie la configuration du rechargement. L’objet de configuration peut inclure les propriétés suivantes :

• sys_ids : Un tableau d’identificateurs d’enregistrements ServiceNow® (sys_id) à recharger.

• data_reload_range_start_time et data_reload_range_end_time : Valeurs d’horodatage spécifiant la plage de données au format TIMESTAMP_TZ. Selon le type d’ingestion de table donné, uniquement les enregistrements avec sys_updated_on ou sys_created_on dans la période spécifiée sont rechargés.

• conditions : Une expression de chaîne qui spécifie les conditions sur les champs d’une table ServiceNow®. Seuls les enregistrements qui remplissent les conditions sont rechargés.

  La syntaxe de l’expression est la même que pour le filtrage des lignes. Si le filtrage des lignes est configuré sur la table ordinaire, il est également appliqué aux conditions.

Contrairement au rechargement complet, le rechargement filtré ne remplace pas les données de la table d’origine, mais modifie uniquement les enregistrements sélectionnés.

Par exemple, pour recharger uniquement les enregistrements avec les valeurs sys_id de 1, 2 et 3 dans la table incident, exécutez la commande suivante :

CALL RELOAD_TABLE('incident', { 'sys_ids': ['1', '2', '3'] });

Pour recharger uniquement les enregistrements avec les valeurs sys_updated_on comprises entre 2022-11-23 07:00:00 et 2022-11-23 08:00:00 UTCet qui sont toujours actives dans la table incident, exécutez la commande suivante :

CALL RELOAD_TABLE('incident', {
  'data_reload_range_start_time': TO_TIMESTAMP_TZ('2022-11-23 07:00:00 +00:00'),
  'data_reload_range_end_time': TO_TIMESTAMP_TZ('2022-11-23 08:00:00 +00:00'),
  'conditions': 'active = "true"'
});

Cancel table reload¶

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.