Ensembles de données à importer API : ServiceNow Fluent
L’API Ensembles de données à importer définit des cartes de transformation [sys_transform_map] qui spécifient comment transformer et mapper les données de la table intermédiaire du jeu d’importation vers les tables cibles.
Chaque opération d’importation vers une table de production nécessite au moins une carte de transformation associée à un jeu d’importation. La carte de transformation spécifie les relations de données entre le jeu d’importation et la table cible.
Pour créer un jeu d’importation dans ServiceNow Fluent le code, vous devez définir les métadonnées requises dans l’ordre suivant :
- Définissez la table intermédiaire [sys_db_object] à l’aide de l’API Table. La table doit étendre la table Ligne de jeu d’importation [sys_import_set_row]. Pour plus d'informations, consultez API de table : ServiceNow Fluent.
La table intermédiaire définit toutes les colonnes qui reçoivent des données importées.
- Définissez la source de données [sys_data_source] à l’aide de l’API d’enregistrement. La source de données doit référencer la table intermédiaire à partir de sa propriété import_set_table_name . Pour plus d'informations, consultez API d’enregistrement : ServiceNow Fluent.
La source de données définit la connexion à des systèmes externes (fichiers, bases de données, API) et la façon de charger les données dans des tables intermédiaires d’importation. Pour plus d'informations, consultez Data sources.
- Définissez la carte de transformation [sys_transform_map] à l’aide de l’API Import Sets. La carte de transformation doit référencer la table intermédiaire à partir de sa propriété sourceTable .
Important :
La chaîne
NULL est un mot réservé. Elle ne doit pas être utilisée comme valeur de champ dans les jeux d’importation, les cartes de transformation ou ailleurs dans les champs Prénom ou Nom de famille . Le mot réservé est NULL en majuscules. Un champ avec la valeur Null ou null, par exemple, est acceptable. NULL ne doit être utilisé que pour effacer un champ particulier.Pour des informations générales sur les jeux d’importation, reportez-vous à la section Import sets.
Objet ImportSet
Créez une carte de transformation [sys_transform_map] pour définir les relations entre les champs d’une table de jeux d’importation et les champs d’une table existante.
Pour en savoir plus sur la création de cartes de transformation, reportez-vous à la section Create a transform map.
| Nom | Type | Description |
|---|---|---|
| $id | Chaîne ou numéro | Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques. Format : |
| nom | Chaîne | Requis. Nom interne de la carte de transformation. |
| targetTable | Chaîne | Requis. Nom de la table dans laquelle vous souhaitez insérer les données transformées. Vous pouvez spécifier uniquement des tables dans le périmètre de l’application ou le périmètre global, ou des tables qui accordent un accès en écriture à d’autres applications. |
| sourceTable | Chaîne | Requis. Nom de la table contenant les données brutes du jeu d’importation à transformer. Une table d’importation est une table qui étend la table Ligne de jeu d’importation [sys_import_set_row]. Vous pouvez spécifier uniquement des tables dans le périmètre de l’application. Remarque : La valeur de cette propriété doit correspondre à la valeur de la propriété name dans la définition de table intermédiaire et à la propriété import_set_table_name dans la définition de source de données. |
| order | Numéro | Ordre d’exécution auquel appliquer les cartes de transformation si plusieurs cartes correspondent aux conditions. Par défaut : 100 |
| actif | Booléen | Marqueur indiquant si la carte de transformation est active. Valeur par défaut : false |
| runBusinessRules | Booléen | Marqueur indiquant s’il convient d’exécuter des règles métier, des workflows, des moteurs d’approbation, des audits et la normalisation de champ pendant que la transformation insère ou met à jour les données dans la table cible. Si la valeur est faux, GlideRecord.setWorkflow() s’exécute avec la valeur faux. Par défaut : true |
| enforceMandatoryFields | Chaîne | Option permettant d’appliquer des champs obligatoires sur la table cible. Valeurs valides :
Par défaut : non |
| copyEmptyFields | Booléen | Marqueur indiquant s’il faut copier les champs vides à partir de la source et remplacer les valeurs de champ cible existantes. Valeur par défaut : false |
| createOnEmptyCoalesce | Booléen | Marqueur qui indique s’il faut créer un enregistrement lorsque les champs de fusion sont vides, au lieu d’ignorer l’enregistrement ou d’en écraser un existant. Si createOnEmptyCoalesce est vrai pour un champ de l’enregistrement, l’enregistrement est fusionné. Valeur par défaut : false |
| exécuter le script | Booléen | Marqueur indiquant s’il faut exécuter le script de carte de transformation. Le système exécute le script de carte de transformation en plus des cartes de champs. Valeur par défaut : false |
| script | Script | Script qui transforme les valeurs de champ de la table source en table cible. Cette propriété prend en charge une fonction d’un module JavaScript, une référence à un autre fichier dans l’application qui contient un script ou JavaScript en ligne. Attend une fonction de type (source, target, map, log, isUpdate) => void.Format :
|
| champs | Objet | Paires clé/valeur des mappages de champs où la clé est le nom du champ cible et la valeur est le nom de champ source ou l’objet fields. Chaque nom de champ cible (clé) doit être unique dans l’objet fields pour éviter les conflits de mappage. Format :
|
| scripts | Tableau | Une liste de scripts de transformation pour un traitement supplémentaire. Pour plus d'informations, consultez Tableau de scripts. |
import '@servicenow/sdk/global'
import { Table, Record, ImportSet } from '@servicenow/sdk/core'
// STEP 1: Create Staging Table Definition (REQUIRED - MUST BE FIRST)
// This creates the actual table structure to hold imported data
export const userStagingTable = Table({
$id: Now.ID['user-staging-table'],
name: 'u_user_import_staging',
label: 'User Import Staging',
extends: 'sys_import_set_row', // All staging tables extend this
columns: [
{
name: 'u_email_address',
type: 'email',
max_length: 100,
label: 'Email Address'
},
{
name: 'u_full_name',
type: 'string',
max_length: 100,
label: 'Full Name'
},
{
name: 'u_username',
type: 'string',
max_length: 40,
label: 'Username'
},
]
})
// STEP 2: Create Data Source (REQUIRED - MUST BE SECOND)
// The data source defines HOW to get data from external systems
export const userDataSource = Record({
$id: Now.ID['user-csv-datasource'],
table: 'sys_data_source',
data: {
name: 'User CSV Data Source',
type: 'File',
format: 'CSV',
file_retrieval_method: 'Attachment',
csv_delimiter: ',',
header_row: 1,
// CRITICAL: This must match the table name from STEP 1
import_set_table_name: 'u_user_import_staging',
import_set_table_label: 'User Import Staging',
batch_size: 500,
active: true,
},
})
// STEP 3: Create Import Set (Transform Map) (REQUIRED - MUST BE THIRD)
// The import set defines HOW to transform data from staging to target table
export const userImportSet = ImportSet({
$id: Now.ID['user-import-transform'],
name: 'User Import Transform',
targetTable: 'sys_user',
// CRITICAL: This must match import_set_table_name in Data Source
sourceTable: 'u_user_import_staging',
active: true,
runBusinessRules: true,
fields: {
email: {
sourceField: 'u_email_address',
coalesce: true,
},
name: 'u_full_name',
user_name: 'u_username',
}
})Objet de champs
Définissez des mappages de champs [sys_transform_entry] à partir des champs sources d’un jeu d’importation vers les champs de la table cible.
Utilisez l’objet fields dans l’objet ImportSet . Dans l’objet fields , chaque clé du nom de champ cible doit être unique pour éviter les conflits de mappage.
Pour des informations générales sur la création de cartes de champs, reportez-vous à la section Create a field map.
| Nom | Type | Description |
|---|---|---|
| sourceField | Chaîne | Nom du champ source de la table d’importation à transformer. Cette propriété est obligatoire sauf si vous utilisez la propriété sourceScript ou une configuration de fusion uniquement. Champ de la table source à transformer. Si la table source ne contient que des données brutes, la valeur peut être vide. |
| choiceAction | Chaîne | Action à effectuer si le jeu d’importation contient une valeur de référence ou de choix autre que celles disponibles. Cette propriété s’applique si le champ cible est une liste de choix ou un champ de référence. Valeurs valides :
|
| Script source | Script | Script qui transforme les valeurs de champ de la table source en table cible. Cette propriété prend en charge une fonction d’un module JavaScript, une référence à un autre fichier dans l’application qui contient un script ou JavaScript en ligne. Attend une fonction de type (source) => n’importe lequel.Format :
|
| useSourceScript | Booléen | Marqueur indiquant s’il faut utiliser le script source au lieu du champ source. Valeur par défaut : false |
| format de date | Chaîne | Format des transformations lorsque le champ cible est un champ Date ou un champ Date/Heure. Remarque : Pour en savoir plus sur les formats de date autorisés, voir Format du champ de date et d’heure global. Format : |
| referenceValueField | Chaîne | Champ de valeur de référence lorsque le champ cible est un champ de référence. La carte de transformation a besoin d’un moyen de faire correspondre les valeurs sources entrantes aux enregistrements existants dans la table source du champ de référence. Étant donné que la plupart des importations ne fournissent pas de valeur sys_id de 32 caractères, vous devez spécifier une colonne de la table source du champ de référence qui contient des valeurs qui correspondent aux valeurs sources entrantes. Pour plus d'informations, consultez Create a field map. |
| Fusionner | Booléen | Marqueur indiquant si le champ est utilisé pour la correspondance d’enregistrement. La configuration de la fusion d’un champ cible entraîne le traitement du champ par l’ensemble de données à importer comme une clé unique. Pour plus d'informations, consultez Create a field map. Valeur par défaut : false |
| coalesceCaseSensitive | Booléen | Marqueur indiquant s’il faut faire en sorte que des valeurs de fusion sensibles à la casse entraînent la création de nouveaux enregistrements. Par défaut, les champs de fusion sont utilisés dans une recherche qui n’est pas sensible à la casse pour les enregistrements existants. Les enregistrements non sensibles à la casse mettent à jour uniquement les enregistrements existants et n’entraînent pas la création de nouveaux enregistrements. Valeur par défaut : false |
| coalesceEmptyFields | Booléen | Marqueur indiquant s’il faut faire correspondre une valeur de champ source vide à une valeur de champ cible vide. La propriété de fusion doit être définie sur vrai pour que cette propriété s’applique. Par exemple, la carte de transformation de l’utilisateur fusionne dans le champ d’e-mail. Si cette propriété est définie sur vrai, un enregistrement source contenant une adresse e-mail vide fusionne en un enregistrement cible contenant une adresse e-mail vide. Valeur par défaut : false |
fields: {
email: {
sourceField: 'email_address',
coalesce: true,
useSourceScript: true,
sourceScript: `answer = (function transformEntry(source) {
return source.email_address.toLowerCase().trim();
})(source);`
},
department: {
sourceField: 'dept_code',
choiceAction: 'create'
}
}Tableau de scripts
Définissez les scripts de transformation [sys_transform_script] qui s’exécutent à différentes étapes du processus d’importation.
| Nom | Type | Description |
|---|---|---|
| $id | Chaîne ou numéro | Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques. Format : |
| actif | Booléen | Marqueur indiquant si le script est actif et s’exécute. Par défaut : true |
| order | Numéro | Ordre d’exécution dans lequel les scripts s’exécutent si plusieurs scripts correspondent aux conditions. Par défaut : 100 |
| quand | Chaîne | Étape du processus d’importation dans laquelle exécuter le script. Pour plus d'informations, consultez Map with transformation event scripts. Valeurs valides : onBefore, onAfter, onReject, onStart, onForeignInsert, onComplete, onChoiceCreate Par défaut : onAfter |
| script | Script | Script qui modifie le comportement de transformation à l’étape spécifiée avec la propriété quand . Cette propriété prend en charge une fonction d’un module JavaScript, une référence à un autre fichier dans l’application qui contient un script ou JavaScript en ligne. Attend une fonction de type (source, carte, journal, cible) => void.Format :
|
scripts: [
{
$id: Now.ID['validate-email'],
active: true,
order: 100,
when: 'onBefore',
script: `(function runTransformScript(source, map, log, target) {
if (!source.email_address || source.email_address.indexOf('@') === -1) {
log.error('Invalid email address: ' + source.email_address);
return;
}
})(source, map, log, target);`
},
{
$id: Now.ID['validate-user-script'],
active: true,
order: 100,
when: 'onBefore',
// Using imported function for lifecycle script
script: validateUserData
}
]