インポートセット API - ServiceNow Fluent
インポートセット API は、インポートセットステージングテーブルからターゲットテーブルにデータを変換してマッピングする方法を指定する変換マップ [sys_transform_map] を定義します。
本番テーブルへのすべてのインポート操作には、インポートセットに関連付けられた変換マップが少なくとも 1 つ必要です。変換マップは、インポートセットとターゲットテーブルの間のデータ関係を指定します。
ServiceNow Fluentコードでインポートセットを作成するには、必要なメタデータを次の順序で定義する必要があります。
- テーブル API を使用してステージングテーブル [sys_db_object] を定義します。このテーブルは、インポートセット行 [sys_import_set_row] テーブルを拡張する必要があります。詳細については、「テーブル API - ServiceNow Fluent」を参照してください。
ステージングテーブルは、インポートされたデータを受信するすべての列を定義します。
- レコード API を使用してデータソース [sys_data_source] を定義します。データソースは、 そのimport_set_table_name プロパティからステージングテーブルを参照する必要があります。詳細については、「レコード API - ServiceNow Fluent」を参照してください。
データソースは、外部システム (ファイル、データベース、API) への接続と、インポートステージングテーブルにデータをロードする方法を定義します。詳細については、「Data sources」を参照してください。
- インポートセット API を使用して変換マップ [sys_transform_map] を定義します。変換マップは、 sourceTable プロパティからステージングテーブルを参照する必要があります。
重要:
文字列
NULL は予約語です。インポートセット変換マップや、[ 名 ] フィールドや [姓] フィールドのフィールド値として使用しないでください。予約語はすべて大文字の NULL です。Null や null などの値を持つフィールドは受け入れ可能です。NULL は、特定のフィールドをクリアするためにのみ使用する必要があります。インポートセットに関する一般的な情報については、「 Import sets」を参照してください。
ImportSet オブジェクト
変換マップ [sys_transform_map] を作成して、インポートセットテーブルのフィールドと既存のテーブルのフィールドの間の関係を定義します。
変換マップの作成に関する一般的な情報については、「 Create a transform map」を参照してください。
| 名前 | タイプ | 説明 |
|---|---|---|
| $id | 文字列または数値 | 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。 形式: |
| name | 文字列 | 必須。変換マップの内部名。 |
| targetTable | 文字列 | 必須。変換されたデータを挿入するテーブルの名前。 アプリケーションスコープまたはグローバルスコープ内のテーブル、または他のアプリケーションへの書き込みアクセスを許可するテーブルのみを指定できます。 |
| sourceTable | 文字列 | 必須。変換する生のインポートセットデータを含むテーブルの名前。インポートテーブルは、インポートセット行 [sys_import_set_row] テーブルを拡張するテーブルです。指定できるのは、アプリケーションスコープ内のテーブルのみです。 注: このプロパティの値は、ステージングテーブル定義の name プロパティの値とデータソース定義の import_set_table_name プロパティの値と一致する必要があります。 |
| 順序 | 番号 | 複数のマップが条件に適合する場合に変換マップを適用する実行順序。 デフォルト：100 |
| アクティブ | ブール | 変換マップがアクティブかどうかを示すフラグ。 デフォルト値：false |
| runBusinessRules | ブール | ターゲットテーブルへのデータの変換挿入または更新中に、ビジネスルール、ワークフロー、承認エンジン、監査、およびフィールド正規化を実行するかどうかを示すフラグ。false の場合、 GlideRecord.setWorkflow() は false の値で実行されます。 デフォルト：true |
| enforceMandatoryFields | 文字列 | ターゲットテーブルの必須フィールドを強制するオプション。 有効な値：
デフォルト:いいえ |
| copyEmptyFields | ブール | ソースから空のフィールドをコピーし、既存のターゲットフィールド値を上書きするかどうかを示すフラグ。 デフォルト値：false |
| createOnEmptyCoalesce | ブール | レコードを無視したり既存のレコードを上書きしたりするのではなく、結合フィールドが空のときにレコードを作成するかどうかを示すフラグ。 レコード内のいずれかのフィールドで createOnEmptyCoalesce が true の場合、レコードは結合されます。 デフォルト値：false |
| runScript | ブール | 変換マップスクリプトを実行するかどうかを示すフラグ。システムは、フィールドマップに加えて変換マップスクリプトを実行します。 デフォルト値：false |
| script | スクリプト | ソーステーブルのフィールド値をターゲットテーブルに変換するスクリプト。このプロパティは、JavaScript モジュールからの関数、スクリプトを含むアプリケーション内の別のファイルへの参照、またはインライン JavaScript をサポートします。 タイプ (source、target、map、log、isUpdate) => void の関数が必要です。Format (形式)：
|
| フィールド | オブジェクト | キーがターゲットフィールド名で、値がソースフィールド名またはフィールドオブジェクトであるフィールドマッピングのキーと値のペア。マッピングの競合を避けるために、各ターゲットフィールド名 (キー) はフィールドオブジェクト内で一意である必要があります。 Format (形式)：
|
| スクリプト | アレイ | 追加処理のための変換スクリプトのリスト。詳細については、「スクリプトアレイ」を参照してください。 |
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',
}
})fields オブジェクト
インポートセットのソースフィールドからターゲットテーブルのフィールドへのフィールドマッピング [sys_transform_entry] を定義します。
ImportSet オブジェクト内の fields オブジェクトを使用します。フィールドオブジェクトでは、マッピングの競合を避けるために、ターゲットフィールド名の各キーが一意である必要があります。
フィールドマップの作成に関する一般的な情報については、「 Create a field map」を参照してください。
| 名前 | タイプ | 説明 |
|---|---|---|
| sourceField | 文字列 | 変換するインポートテーブルのソースフィールドの名前。sourceScript プロパティまたは結合のみの構成を使用し |
| choiceAction | 文字列 | インポートセットに利用可能な値以外の参照値または選択値が含まれている場合に実行するアクション。このプロパティは、ターゲットフィールドが選択リストまたは参照フィールドの場合に適用されます。 有効な値：
|
| ソーススクリプト | スクリプト | ソーステーブルのフィールド値をターゲットテーブルに変換するスクリプト。このプロパティは、JavaScript モジュールからの関数、スクリプトを含むアプリケーション内の別のファイルへの参照、またはインライン JavaScript をサポートします。 型 (source) => any の関数が必要です。Format (形式)：
|
| useSourceScript | ブール | ソースフィールドの代わりにソーススクリプトを使用するかどうかを示すフラグ。 デフォルト値：false |
| 日付形式 | 文字列 | ターゲットフィールドが日付または日付/時刻フィールドである場合の変換の形式。 注: 許可されている日付形式の詳細については、「グローバル日付/時刻フィールド形式」を参照してください。 形式:「 |
| 参照値フィールド | 文字列 | ターゲットフィールドが参照フィールドである場合の参照値フィールド。変換マップには、受信ソース値を参照フィールドのソーステーブルの既存のレコードと照合する方法が必要です。ほとんどのインポートでは 32 文字のsys_id値が提供されないため、受信ソース値と一致する値を含む参照フィールドのソーステーブルの列を指定する必要があります。詳細については、「Create a field map」を参照してください。 |
| coalesce | ブール | フィールドがレコードの照合に使用されるかどうかを示すフラグ。ターゲットフィールドを結合するように構成すると、インポートセットはフィールドを一意のキーとして扱います。詳細については、「Create a field map」を参照してください。 デフォルト値：false |
| 結合ケース依存 | ブール | 大文字と小文字を区別する結合値で新しいレコードを作成するかどうかを示すフラグ。 デフォルトでは、結合フィールドは、既存のレコードの大文字と小文字を区別しないルックアップで使用されます。大文字と小文字を区別しないレコードは既存のレコードのみを更新し、新しいレコードの作成は発生しません。 デフォルト値：false |
| coalesceEmptyFields | ブール | 空のソースフィールド値を空のターゲットフィールド値と照合するかどうかを示すフラグ。このプロパティを適用するには、 結合 プロパティを true に設定する必要があります。 たとえば、ユーザー変換マップをメールフィールドで結合させます。このプロパティが true に設定されている場合、空のメールアドレスを含むソースレコードは、空のメールアドレスを含むターゲットレコードに結合します。 デフォルト値：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'
}
}スクリプトアレイ
インポートプロセスのさまざまなステージで実行する変換スクリプト [sys_transform_script] を定義します。
| 名前 | タイプ | 説明 |
|---|---|---|
| $id | 文字列または数値 | 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。 形式: |
| active | ブール | スクリプトがアクティブで実行されているかどうかを示すフラグ。 デフォルト：true |
| 順序 | 番号 | 複数のスクリプトが条件に適合する場合にスクリプトが実行される実行順序。 デフォルト：100 |
| when | 文字列 | スクリプトを実行するインポートプロセスのステージ。詳細については、「Map with transformation event scripts」を参照してください。 有効な値:onBefore、onAfter、onReject、onStart、onForeignInsert、onComplete、onChoiceCreate デフォルト:onAfter |
| スクリプト | スクリプト | when プロパティで指定されたステージの変換動作を変更するスクリプト。このプロパティは、JavaScript モジュールからの関数、スクリプトを含むアプリケーション内の別のファイルへの参照、またはインライン JavaScript をサポートします。 タイプ (source、map、log、target) => 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
}
]