Importsätze API – ServiceNow Fluent
Die Importsätze API definiert Transformationszuordnungen [ sys_transform_Map ] Die angeben, wie Daten aus der Bereitstellungstabelle des Importsatzes transformiert und den Zieltabellen zugeordnet werden.
Jeder Importvorgang in eine Produktionstabelle erfordert mindestens eine Transformationszuordnung, die einem Importsatz zugeordnet ist. Die Transformationszuordnung gibt die Datenbeziehungen zwischen dem Importsatz und der Zieltabelle an.
Zum Erstellen eines Importsatzes in ServiceNow FluentCode, Sie müssen die erforderlichen Metadaten in der folgenden Reihenfolge definieren:
- Definieren Sie die Bereitstellungstabelle [sys_DB_object] mithilfe der Tabellen-API. Die Tabelle muss die Tabelle „Importsatzzeile“ [sys_Import_Set_row] erweitern. Weitere Informationen finden Sie unter Tabellen-API – ServiceNow Fluent.
Die Bereitstellungstabelle definiert alle Spalten, die importierte Daten empfangen.
- Definieren Sie die Datenquelle [sys_Data_Source] mithilfe der Datensatz-API. Die Datenquelle muss auf die Bereitstellungstabelle aus verweisen Import_Set_table_Name Eigenschaft. Weitere Informationen finden Sie unter Datensatz-API – ServiceNow Fluent.
Die Datenquelle definiert die Verbindung zu externen Systemen (Dateien, Datenbanken, APIs) und wie Daten in Importbereitstellungstabellen geladen werden. Weitere Informationen finden Sie unter Data sources.
- Definieren Sie die Transformationszuordnung [sys_transform_Map] mithilfe der API „Importsätze“. Die Transformationszuordnung muss auf die Bereitstellungstabelle aus verweisen Quelltabelle Eigenschaft.
Wichtig:
Die Zeichenfolge
NULL Ist ein reserviertes Wort. Es darf nicht als Feldwert in Transformationszuordnungen des Importsatzes oder an einer beliebigen Stelle in verwendet werden Vorname Oder Nachname Felder. Das reservierte Wort ist NULL In allen Großbuchstaben. Ein Feld mit dem Wert Null oder null ist also beispielsweise zulässig. NULL Sollte nur verwendet werden, um ein bestimmtes Feld zu löschen.Allgemeine Informationen zu Importsätzen finden Sie unter Import sets.
ImportSet-Objekt
Erstellen Sie eine Transformationszuordnung [sys_transform_Map], um die Beziehungen zwischen Feldern in einer Importsatztabelle und Feldern in einer vorhandenen Tabelle zu definieren.
Allgemeine Informationen zum Erstellen von Transformationszuordnungen finden Sie unter Create a transform map.
| Name | Typ | Beschreibung |
|---|---|---|
| $ID | Zeichenfolge oder Zahl | Erforderlich. Eine eindeutige ID für das Metadatenobjekt. Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Format: |
| Name | Zeichenfolge | Erforderlich. Ein interner Name für die Transformationszuordnung. |
| targetTable | Zeichenfolge | Erforderlich. Der Name der Tabelle, in die die transformierten Daten eingefügt werden sollen. Sie können nur Tabellen innerhalb des Anwendungsbereichs oder des globalen Bereichs oder Tabellen angeben, die Schreibzugriff auf andere Anwendungen gewähren. |
| sourceTable | Zeichenfolge | Erforderlich. Der Name der Tabelle, die die zu transformierenden Rohimportsatzdaten enthält. Eine Importtabelle ist eine beliebige Tabelle, die die Tabelle „Importsatzzeile“ [sys_Import_Set_row] erweitert. Sie können nur Tabellen innerhalb des Anwendungsbereichs angeben. Hinweis: Der Wert dieser Eigenschaft muss mit dem Wert von übereinstimmen Name Eigenschaft in der Bereitstellungstabellendefinition und in Import_Set_table_Name Eigenschaft in der Datenquellendefinition. |
| Reihenfolge | Nummer | Die Ausführungsreihenfolge, in der Transformationszuordnungen angewendet werden, wenn mehr als eine Zuordnung den Bedingungen entspricht. Standard: 100 |
| aktiv | Boolean | Kennzeichnung, die angibt, ob die Transformationszuordnung aktiv ist. Standardwert: false |
| RunBusinessRules | Boolean | Kennzeichnung, die angibt, ob Business-Regeln, Workflows, Genehmigungsmodule, Auditing und Feldnormalisierung ausgeführt werden sollen, während die Transformation Daten in die Zieltabelle einfügt oder aktualisiert. Wenn „falsch“, GlideRecord.setWorkflow() Wird mit dem Wert „falsch“ ausgeführt. Standardwert: wahr |
| DurchsetzenPflichtfelder | Zeichenfolge | Eine Option zum Erzwingen von Pflichtfeldern in der Zieltabelle. Gültige Werte:
Standard: Nein |
| CopyEmptyFields | Boolean | Kennzeichnung, die angibt, ob leere Felder aus der Quelle kopiert und vorhandene Zielfeldwerte überschrieben werden sollen. Standardwert: false |
| CreateOnEmptyCoalesce | Boolean | Kennzeichnung, die angibt, ob ein Datensatz erstellt werden soll, wenn Zusammenfügungsfelder leer sind, anstatt den Datensatz zu ignorieren oder einen vorhandenen Datensatz zu überschreiben. Wenn CreateOnEmptyCoalesce Ist für ein beliebiges Feld im Datensatz „wahr“, der Datensatz wird zusammengefügt. Standardwert: false |
| Skript ausführen | Boolean | Kennzeichnung, die angibt, ob das Transformationszuordnungsskript ausgeführt werden soll. Das System führt das Transformationszuordnungsskript zusätzlich zu allen Feldzuordnungen aus. Standardwert: false |
| Skript | Skript | Ein Skript, das Feldwerte in der Quelltabelle in die Zieltabelle umwandelt. Diese Eigenschaft unterstützt eine Funktion aus einem JavaScript-Modul, einen Verweis auf eine andere Datei in der Anwendung, die ein Skript enthält, oder Inline-JavaScript.Erwartet eine Funktion vom Typ (Quelle, Ziel, Karte, Protokoll, isUpdate) => ungültig .Format:
|
| Felder | Objekt | Schlüssel- und Wertpaare von Feldzuordnungen, bei denen der Schlüssel der Zielfeldname ist und der Wert der Quellfeldname oder das Feldobjekt ist. Jeder Zielfeldname (Schlüssel) muss innerhalb des Feldobjekts eindeutig sein, um Zuordnungskonflikte zu vermeiden. Format:
|
| Skripts | Array | Eine Liste von Transformationsskripts für zusätzliche Verarbeitung. Weitere Informationen finden Sie unter Skripts-Array. |
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',
}
})Feldobjekt
Definieren Sie Feldzuordnungen [sys_transform_entry] aus den Quellfeldern eines Importsatzes zu den Feldern der Zieltabelle.
Verwenden Sie Felder Objekt innerhalb von Importsatz Objekt. In Felder Objekt, jeder Schlüssel für den Zielfeldnamen muss eindeutig sein, um Zuordnungskonflikte zu vermeiden.
Allgemeine Informationen zum Erstellen von Feldzuordnungen finden Sie unter Create a field map.
| Name | Typ | Beschreibung |
|---|---|---|
| sourceField | Zeichenfolge | Der Name des Quellfelds aus der zu transformierenden Importtabelle. Diese Eigenschaft ist erforderlich, es sei denn, Sie verwenden Quellskript Eigenschaft oder eine reine Zusammenfügungskonfiguration. Feld in der zu transformierenden Quelltabelle. Wenn Quelltabelle Enthält nur Rohdaten, der Wert kann leer sein. |
| Auswahlaktion | Zeichenfolge | Die auszuführende Aktion, wenn der Importsatz einen anderen Referenz- oder Auswahlwert als die verfügbaren enthält. Diese Eigenschaft gilt, wenn das Zielfeld eine Auswahlliste oder ein Referenzfeld ist. Gültige Werte:
|
| Quellskript | Skript | Ein Skript, das Feldwerte in der Quelltabelle in die Zieltabelle umwandelt. Diese Eigenschaft unterstützt eine Funktion aus einem JavaScript-Modul, einen Verweis auf eine andere Datei in der Anwendung, die ein Skript enthält, oder Inline-JavaScript.Erwartet eine Funktion vom Typ (Quelle) => beliebig .Format:
|
| UseSourceScript | Boolean | Kennzeichnung, die angibt, ob das Quellskript anstelle des Quellfelds verwendet werden soll. Standardwert: false |
| DATEFORMAT | Zeichenfolge | Das Format für Transformationen, wenn das Zielfeld ein Datums- oder Datums-/Uhrzeitfeld ist. Hinweis: Weitere Informationen zu zulässigen Datumsformaten finden Sie unter Globales Datums- und Uhrzeitfeldformat . Format: |
| ReferenceWertFeld | Zeichenfolge | Das Referenzwertfeld, wenn das Zielfeld ein Referenzfeld ist. Die Transformationszuordnung benötigt eine Möglichkeit, eingehende Quellwerte mit vorhandenen Datensätzen in der Quelltabelle des Referenzfelds abzugleichen. Da die meisten Importe keinen 32-stelligen sys_ID-Wert bereitstellen, müssen Sie eine Spalte aus der Quelltabelle des Referenzfelds angeben, die Werte enthält, die den eingehenden Quellwerten entsprechen. Weitere Informationen finden Sie unter Create a field map. |
| Zusammenfügen | Boolean | Kennzeichnung, die angibt, ob das Feld für den Datensatzabgleich verwendet wird. Wenn Sie ein Zielfeld zum Zusammenfügen konfigurieren, behandelt der Importsatz das Feld als eindeutigen Schlüssel. Weitere Informationen finden Sie unter Create a field map. Standardwert: false |
| ZusammenfügungFallsensitiv | Boolean | Kennzeichnung, die angibt, ob Zusammenfügungswerte, bei denen die Groß-/Kleinschreibung beachtet wird, zur Erstellung neuer Datensätze führen sollen. Standardmäßig werden Zusammenfügungsfelder in einer Suche ohne Berücksichtigung der Groß-/Kleinschreibung für vorhandene Datensätze verwendet. Datensätze ohne Berücksichtigung der Groß-/Kleinschreibung aktualisieren nur vorhandene Datensätze und verursachen nicht die Erstellung neuer Datensätze. Standardwert: false |
| ZusammenfügungEmptyFields | Boolean | Kennzeichnung, die angibt, ob ein leerer Quellfeldwert mit einem leeren Zielfeldwert abgeglichen werden soll. Die Zusammenfügen Die Eigenschaft muss auf „wahr“ festgelegt sein, damit diese Eigenschaft angewendet wird. Beispielsweise fügt sich die Anwendertransformationszuordnung im E-Mail-Feld zusammen. Wenn diese Eigenschaft auf „wahr“ festgelegt ist, wird ein Quelldatensatz, der eine leere E-Mail-Adresse enthält, zu einem Zieldatensatz zusammengefügt, der eine leere E-Mail-Adresse enthält. Standardwert: 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'
}
}Skripts-Array
Definieren Sie Transformationsskripts [sys_transform_script], die in verschiedenen Phasen des Importprozesses ausgeführt werden.
| Name | Typ | Beschreibung |
|---|---|---|
| $ID | Zeichenfolge oder Zahl | Erforderlich. Eine eindeutige ID für das Metadatenobjekt. Wenn Sie die Anwendung erstellen, wird diese ID in eine eindeutige sys_ID gehasht Weitere Informationen finden Sie unter ServiceNow Fluent Sprachkonstrukte. Format: |
| active | Boolean | Kennzeichnung, die angibt, ob das Skript aktiv ist und ausgeführt wird. Standardwert: wahr |
| Reihenfolge | Nummer | Die Ausführungsreihenfolge, in der Skripts ausgeführt werden, wenn mehr als ein Skript den Bedingungen entspricht. Standard: 100 |
| when | Zeichenfolge | Die Phase des Importprozesses, in der das Skript ausgeführt werden soll. Weitere Informationen finden Sie unter Map with transformation event scripts. Gültige Werte: OnBefore, onAfter, onReject, onStart, onForeignInsert, OnComplete, onChoiceErstellen Standard: OnAfter |
| Skript | Skript | Ein Skript, das das Transformationsverhalten in der mit angegebenen Phase ändert Wann Eigenschaft. Diese Eigenschaft unterstützt eine Funktion aus einem JavaScript-Modul, einen Verweis auf eine andere Datei in der Anwendung, die ein Skript enthält, oder Inline-JavaScript.Erwartet eine Funktion vom Typ (Quelle, Zuordnung, Protokoll, Ziel) => ungültig .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
}
]