임포트 세트 API - ServiceNow Fluent
임포트 세트 API는 임포트 세트 스테이징 테이블에서 대상 테이블로 데이터를 변환하고 매핑하는 방법을 지정하는 변환 맵[sys_transform_map]을 정의합니다.
프로덕션 테이블에 대한 모든 임포트 작업에는 임포트 세트와 연결된 변환 맵이 하나 이상 필요합니다. 변환 맵은 임포트 세트와 대상 테이블 간의 데이터 관계를 지정합니다.
코드에서 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 언어 구성 문서를 참조하십시오. 형식: |
| 이름 | 문자열 | 필수 변환 맵의 내부 이름입니다. |
| targetTable | 문자열 | 필수 변환된 데이터를 삽입할 테이블의 이름입니다. 애플리케이션 범위 또는 전역 범위 내의 테이블이나 다른 애플리케이션에 대한 쓰기 접근 권한을 부여하는 테이블만 지정할 수 있습니다. |
| sourceTable | 문자열 | 필수 변환할 원시 임포트 세트 데이터가 포함된 테이블의 이름입니다. 임포트 테이블은 임포트 세트 행 [sys_import_set_row] 테이블을 확장하는 모든 테이블입니다. 애플리케이션 범위 내의 테이블만 지정할 수 있습니다. 주: 이 속성의 값은 준비 테이블 정의의 이름 속성 값 및 데이터 소스 정의의 import_set_table_name 속성과 일치해야 합니다. |
| 순서 | 번호 | 둘 이상의 맵이 조건을 충족하는 경우 변환 맵을 적용할 실행 순서입니다. 기본값: 100 |
| 활성 | 부울 | 변환 맵이 활성 상태인지 여부를 나타내는 플래그입니다. 기본값: false |
| runBusinessRules | 부울 | 변환을 통해 대상 테이블에 데이터를 삽입하거나 업데이트하는 동안 비즈니스 규칙, 워크플로우, 승인 엔진, 감사 및 필드 정규화를 실행할지 여부를 나타내는 플래그입니다. false인 경우 GlideRecord.setWorkflow()가 false 값으로 실행됩니다. 기본값: true |
| enforceMandatoryFields | 문자열 | 대상 테이블에 필수 필드를 적용하는 옵션입니다. 유효한 값은 다음과 같습니다.
기본값: 아니오 |
| copyEmptyFields | 부울 | 소스에서 빈 필드를 복사하고 기존 대상 필드 값을 재정의할지 여부를 나타내는 플래그입니다. 기본값: false |
| createOnEmptyCoalesce | 부울 | 병합 필드가 비어 있을 때 기록을 무시하거나 기존 기록을 덮어쓰는 대신 기록을 생성할지 여부를 나타내는 플래그입니다. 기록의 필드에 대해 createOnEmptyCoalesce 가 true이면 기록이 병합됩니다. 기본값: false |
| runScript | 부울 | 변환 맵 스크립트를 실행할지 여부를 나타내는 플래그입니다. 시스템은 필드 맵뿐만 아니라 변환 맵 스크립트도 실행합니다. 기본값: false |
| 스크립트 | 스크립트 | 소스 테이블의 필드 값을 대상 테이블로 변환하는 스크립트입니다. 이 속성은 JavaScript 모듈의 함수, 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조 또는 인라인 JavaScript를 지원합니다. 유형 (소스, 대상, 맵, 로그, isUpdate) = > void의 함수가 필요합니다.체재:
|
| 필드 | 객체 | 키가 대상 필드 이름이고 값이 소스 필드 이름 또는 필드 객체인 필드 매핑의 키 및 값 쌍입니다. 매핑 충돌을 방지하려면 각 대상 필드 이름(키)이 fields 객체 내에서 고유해야 합니다. 체재:
|
| 스크립트 | 배열 | 추가 처리를 위한 변환 스크립트 목록입니다. 자세한 내용은 스크립트 배열 문서를 참조하십시오. |
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',
}
})필드 객체
임포트 세트의 소스 필드에서 대상 테이블의 필드로 필드 매핑 [sys_transform_entry]을 정의합니다.
ImportSet 객체 내에서 fields 객체를 사용합니다. fields 객체에서 매핑 충돌을 피하려면 대상 필드 이름의 각 키가 고유해야 합니다.
필드 맵 생성에 대한 일반적인 정보는 다음 문서를 참조하십시오 Create a field map.
| 이름 | 유형 | 설명 |
|---|---|---|
| sourceField | 문자열 | 변환할 임포트 테이블의 소스 필드 이름입니다. sourceScript 속성이나 병합 전용 구성을 사용하지 않는 한 이 속성은 필수입니다. 변환할 소스 테이블의 필드입니다. sourceTable에 원시 데이터만 포함되어 있으면 값이 비어 있을 수 있습니다. |
| choiceAction | 문자열 | 임포트 세트에 사용 가능한 값 이외의 참조 또는 선택 값이 포함되어 있을 경우 수행할 작업입니다. 이 속성은 대상 필드가 선택 목록 또는 참조 필드인 경우에 적용됩니다. 유효한 값은 다음과 같습니다.
|
| 소스 스크립트 | 스크립트 | 소스 테이블의 필드 값을 대상 테이블로 변환하는 스크립트입니다. 이 속성은 JavaScript 모듈의 함수, 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조 또는 인라인 JavaScript를 지원합니다. ( source) = > any의 함수가 필요합니다.체재:
|
| useSourceScript | 부울 | 소스 필드 대신 소스 스크립트를 사용할지 여부를 나타내는 플래그입니다. 기본값: false |
| 날짜 형식 | 문자열 | 대상 필드가 날짜 또는 날짜/시간 필드인 경우 변환의 형식입니다. 주: 허용되는 날짜 형식에 대한 자세한 내용은 전역 날짜 및 시간 필드 형식을 참조하세요. 형식: |
| referenceValueField | 문자열 | 대상 필드가 참조 필드일 경우의 참조 값 필드입니다. 변환 맵에는 들어오는 소스 값을 참조 필드의 소스 테이블에 있는 기존 기록과 일치시키는 방법이 필요합니다. 대부분의 임포트는 32자의 sys_id 값을 제공하지 않으므로 수신 소스 값과 일치하는 값이 포함된 참조 필드의 소스 테이블에서 열을 지정해야 합니다. 자세한 내용은 Create a field map 문서를 참조하십시오. |
| 병합 | 부울 | 필드가 기록 일치에 사용되는지 여부를 나타내는 플래그입니다. 병합할 대상 필드를 구성하면 임포트 세트는 해당 필드를 고유 키로 취급합니다. 자세한 내용은 Create a field map 문서를 참조하십시오. 기본값: false |
| coalesceCaseSensitive | 부울 | 대/소문자를 구분하는 병합 값으로 새 기록을 생성할지 여부를 나타내는 플래그입니다. 기본적으로 병합 필드는 기존 기록에 대한 대/소문자를 구분하지 않는 조회에 사용됩니다. 대/소문자를 구분하지 않는 기록은 기존 기록만 업데이트하며 새 기록은 생성되지 않습니다. 기본값: false |
| 병합 빈 필드 | 부울 | 빈 소스 필드 값을 빈 대상 필드 값과 일치시킬지 여부를 나타내는 플래그입니다. 이 속성을 적용하려면 병합 속성을 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 언어 구성 문서를 참조하십시오. 형식: |
| 활성 | 부울 | 스크립트가 활성 상태이고 실행되는지 여부를 나타내는 플래그입니다. 기본값: true |
| 순서 | 번호 | 둘 이상의 스크립트가 조건을 충족하는 경우 스크립트가 실행되는 실행 순서입니다. 기본값: 100 |
| 시기 | 문자열 | 스크립트를 실행할 임포트 프로세스의 스테이지입니다. 자세한 내용은 Map with transformation event scripts 문서를 참조하십시오. 유효한 값: onBefore, onAfter, onReject, onStart, onForeignInsert, onComplete, onChoiceCreate 기본값: onAfter |
| 스크립트 | 스크립트 | when 속성으로 지정된 스테이지에서 변환 동작을 수정하는 스크립트입니다. 이 속성은 JavaScript 모듈의 함수, 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조 또는 인라인 JavaScript를 지원합니다. 유형 (소스, 맵, 로그, 대상) = > void 함수가 필요합니다.체재:
|
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
}
]