UI 작업 API - ServiceNow Fluent

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 16분

    • UI 작업 API는 양식 및 목록의 단추, 링크, 컨텍스트 메뉴 항목과 같은 사용자 지정 UI(사용자 인터페이스) 작업[sys_ui_action]을 정의합니다.

    UI 작업에 대한 일반적인 정보는 다음 문서를 참조하십시오 Create a UI action.

    UiAction 객체

    UI 작업 [sys_ui_action]을 만들어 양식에 표시합니다.

    표 1. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    테이블 문자열 필수 UI 작업을 사용할 수 있는 테이블의 이름입니다.

    기본적으로 UI 작업은 선택한 테이블을 확장하는 테이블에도 나타납니다. 예를 들어 인시던트 테이블에 작업 동작이 표시됩니다. 모든 테이블에서 작업을 사용할 수 있도록 값을 전역 으로 설정합니다.
    이름 문자열 필수 버튼, 링크 또는 컨텍스트 메뉴 항목에 표시되는 텍스트입니다. 이름은 지정된 테이블 내에서 고유해야 합니다.
    actionName 문자열 스크립트에서 UI 작업을 참조할 때 사용할 고유한 이름입니다.
    활성 부울 UI 작업을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: UI 작업이 나타나고 실행됩니다.
    • false: UI 동작이 숨겨져 있습니다.

    기본값: true
    양식 객체 UI 작업이 양식에 표시되는 방식에 대한 옵션입니다. 자세한 내용은 양식 객체 문서를 참조하십시오.
    목록 객체 UI 작업이 목록 뷰에 표시되는 방식에 대한 옵션입니다. 자세한 내용은 목록 객체 문서를 참조하십시오.
    클라이언트 객체 브라우저에서 스크립트를 실행하는 옵션입니다. 자세한 내용은 클라이언트 객체 문서를 참조하십시오.
    작업 공간 객체 UI 작업이 작업 공간에 작동하고 표시되는 방식에 대한 옵션입니다. 자세한 내용은 작업 공간 객체 문서를 참조하십시오.
    재정의 문자열 또는 참조 UI 작업이 재정의하는 다른 UI 작업의 이름 또는 변수 식별자입니다.
    표시삽입 부울 새 기록을 삽입하기 전에 버튼을 표시할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 버튼이 삽입되기 전에 기록에 나타납니다.
    • false: 삽입되지 않은 기록에는 버튼이 나타나지 않습니다.

    기본값: false
    showUpdate 부울 기존 기록에 버튼을 표시할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 기존 기록에 버튼이 나타납니다.
    • false: 기존 기록에 버튼이 나타나지 않습니다.

    기본값: true
    showQuery 부울 필터 쿼리가 적용될 때 UI 작업이 목록에 표시되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 필터 쿼리가 적용되면 UI 작업이 나타납니다.
    • false: UI 작업이 표시되지 않습니다. 필터 쿼리가 적용되었습니다.

    기본값: false
    showMultipleUpdate 부울 여러 기록을 선택할 때 버튼을 표시할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 여러 기록을 선택하면 버튼이 나타납니다.
    • false: 여러 기록을 선택하면 버튼이 나타나지 않습니다.

    기본값: false
    조건 문자열 스크립트를 실행하기 위해 예여야 하는 필드와 값을 지정하는 JavaScript 조건문입니다.
    주:
    • script 속성과 함께 조건문을 포함하는 경우에는 이 속성을 사용하지 마십시오.
    • 현재 객체는 목록 컨텍스트 메뉴의 조건에 사용할 수 없습니다. 목록의 showContextMenu 속성이 예이면 이러한 작업에서 current 를 사용하는 것이 무시됩니다.
    • 관련 목록 버튼에서 UI 작업 조건에 대한 상위 기록을 참조할 수 있습니다. 예를 들어, 종결된 변경에 대한 영향을 받는 CI 관련 목록에서 새로 만들기 및 편집 버튼을 비활성화하려면 전역 m2m UI 작업을 task_ci 테이블에 복사하고 조건을 parent.active추가합니다.
    • 조건문에 지정한 필드 중 하나를 비워 두면 해당 조건은 기본적으로 true로 설정됩니다.
    체재:
    • 다른 파일의 텍스트 컨텐츠를 사용하려면 Now.include('path/to/file') 형식을 사용하여 애플리케이션의 파일을 참조하십시오. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    스크립트 스크립트 UI 작업이 실행될 때 실행되는 클라이언트 측 또는 서버 측 스크립트입니다. 함수 이름은 고유해야 합니다. 이 속성은 인라인 JavaScript 또는 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 컨텐츠를 사용하려면 Now.include('path/to/file') 형식을 사용하여 애플리케이션의 파일을 참조하십시오. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    댓글 문자열 UI 작업에 대한 내부 메모입니다.
    메시지 문자열 UI 작업이 메시지 [sys_ui_message] 테이블에서 지역화된 메시지 대안을 조회하기 위한 키로 사용할 수 있는 텍스트 문자열입니다. 각 메시지 키는 메시지 필드의 별도 줄에 있습니다.

    인스턴스는 UI 작업이 메시지 문자열이 메시지 필드의 키와 일치하는 getmessage('[message]') 호출을 수행할 때마다 현지화된 메시지 문자열을 찾습니다. 자세한 내용은 클라이언트 스크립트 메시지 번역을 참조하세요.
    힌트 문자열 마우스로 가리킬 때 도구 설명으로 표시되는 UI 작업에 대한 짧은 설명입니다.
    순서 번호 UI 작업이 나타나는 순서입니다. 이 순서는 왼쪽에서 오른쪽으로, 메뉴 작업은 위에서 아래로 적용됩니다.

    기본값: 100
    isolateScript 부울 스크립트가 직접 DOM, jQuery, 프로토타입 및 창 객체에 대한 접근이 꺼진 엄격 모드에서 실행되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 스크립트를 격리하고 엄격 모드에서 실행하지 마십시오.
    • false: 스크립트를 엄격 모드로 실행합니다.

    기본값: false
    역할 배열 UI 작업을 적용하는 데 필요한 역할 객체 또는 역할 의 변수 식별자 목록입니다. 자세한 내용은 역할 API - ServiceNow Fluent 문서를 참조하십시오.
    includeInViews 배열 UI 작업이 포함된 뷰의 이름 목록입니다.
    excludeFromViews 배열 UI 작업이 제외되는 뷰의 이름 목록입니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    import { UiAction } from '@servicenow/sdk/core'
        
UiAction({
    $id: Now.ID['car_info'],
    table: 'x_snc_ts_custom_cars',
    actionName: 'Car Information',
    name: 'View car info',
    active: true,
    showInsert: true,
    showUpdate: true,
    hint: 'View car info',
    condition: "current.type == 'SUV'",
    form: {
        showButton: true,
        showLink: true,
        showContextMenu: false,
        style: 'destructive',
    },
    list: {
        showLink: true,
        style: 'primary',
        showButton: true,
        showContextMenu: false,
        showListChoice: false,
        showBannerButton: true,
        showSaveWithFormButton: true,
    },
    workspace: {
        isConfigurableWorkspace: true,
        showFormButtonV2: true,
        showFormMenuButtonV2: true,
        clientScriptV2: `function onClick(g_form) {
                        }`,
    },
    script: `current.name =  "updated by script";
                current.update();`,
    roles: ['u_requestor'],
    client: {
        isClient: true,
        isUi11Compatible: true,
        isUi16Compatible: true,
        },
    order: 100,
    showQuery: false,
    showMultipleUpdate: false,
    isolateScript: false,
    includeInViews: ['specialView'],
    excludeFromViews: [],
})

    양식 객체

    UI 작업이 양식에 표시되는 방법을 구성합니다.

    양식 객체는 UiAction 객체 내의 속성입니다.

    표 2. 속성
    이름 유형 설명
    버튼 표시 부울 양식에 버튼을 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 양식에 버튼이 나타납니다.
    • false: 양식에 버튼이 표시되지 않습니다.

    기본값: false
    링크 표시 부울 양식의 관련 링크 섹션에 링크를 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 관련 링크 섹션에 링크가 나타납니다.
    • false: 관련 링크 섹션에 링크가 나타나지 않습니다.

    기본값: false
    show컨텍스트메뉴 부울 양식의 상황에 맞는 메뉴에 항목을 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 컨텍스트 메뉴에 항목이 나타납니다.
    • false: 컨텍스트 메뉴에 항목이 표시되지 않습니다.

    기본값: false
    스타일 문자열 UI 작업 버튼이 양식에 표시되는 방식을 정의하는 스타일입니다.
    유효한 값은 다음과 같습니다.
    • primary: UI 작업을 파란색으로 바꿉니다.
    • destructive: UI 작업을 빨간색으로 바꿉니다.
    • unstyled: UI 작업에 스타일이 지정되지 않습니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    form: {
  showButton: true,
  showLink: true,
  showContextMenu: false,
  style: 'destructive',
}

    목록 객체

    목록 뷰에 UI 작업이 표시되는 방법을 구성합니다.

    목록 객체는 UiAction 객체 내의 속성입니다.

    표 3. 속성
    이름 유형 설명
    버튼 표시 부울 목록 하단에 버튼을 포함할지 여부를 나타내는 플래그입니다.
    주:
    목록 하단에 있는 버튼은 조건에 관계 없이 나타나며 실행 시 기록별로 평가됩니다.
    유효한 값은 다음과 같습니다.
    • true: 목록 하단에 버튼이 나타납니다.
    • false: 목록 하단에 버튼이 나타나지 않습니다.

    기본값: false
    링크 표시 부울 목록의 관련 링크 섹션에 링크를 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 관련 링크 섹션에 링크가 나타납니다.
    • false: 관련 링크 섹션에 링크가 나타나지 않습니다.

    기본값: false
    show컨텍스트메뉴 부울 목록의 컨텍스트 메뉴에 항목을 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 컨텍스트 메뉴에 항목이 나타납니다.
    • false: 컨텍스트 메뉴에 항목이 표시되지 않습니다.

    기본값: false
    스타일 문자열 UI 작업 버튼이 목록 뷰에 표시되는 방식을 정의하는 스타일입니다.
    유효한 값은 다음과 같습니다.
    • primary: UI 작업을 파란색으로 바꿉니다.
    • destructive: UI 작업을 빨간색으로 바꿉니다.
    • unstyled: UI 작업에 스타일이 지정되지 않습니다.
    showListChoice 부울 목록의 작업 목록에 선택 항목을 포함할지 여부를 나타내는 플래그입니다.
    주:
    작업 목록의 선택 항목은 조건에 관계없이 나타나며 실행 시 기록별로 평가됩니다.
    유효한 값은 다음과 같습니다.
    • true: 선택 항목이 작업 목록에 나타납니다.
    • false: 선택 항목이 작업 목록에 나타나지 않습니다.

    기본값: false
    showBannerButton 부울 목록의 배너에 버튼을 포함할지 여부를 나타내는 플래그입니다.
    주:
    목록의 배너에 있는 버튼은 기록별 조건을 지원하기 위한 것이 아닙니다. 목록에 버튼이 표시되는지 여부를 결정하기 위해 조건을 평가할 때는 첫 번째 행만 고려됩니다. current.getValue('state') === 'closed'와 같은 기록별 조건은 사용하지 마십시오.
    유효한 값은 다음과 같습니다.
    • true: 목록 배너에 버튼이 나타납니다.
    • false: 목록 배너에 버튼이 나타나지 않습니다.

    기본값: false
    showSaveWithFormButton 부울 UI 작업 버튼을 실행하기 전에 목록에서 액세스할 때 양식이 저장되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: UI 작업을 실행하기 전에 양식을 저장해야 합니다.
    • false: UI 작업을 실행하기 전에 양식을 저장할 필요가 없습니다.

    기본값: false
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    list: {
  showButton: true,
  showLink: true,
  showContextMenu: false,
  style: 'primary',
  showListChoice: false,
  showBannerButton: true,
  showSaveWithFormButton: true,
}

    클라이언트 객체

    브라우저에서 UI 작업 스크립트를 실행하는 옵션을 구성합니다.

    클라이언트 객체는 UiAction 객체 내의 속성입니다.

    표 4. 속성
    이름 유형 설명
    isClient 부울 UI 작업 스크립트가 실행되는 위치를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 스크립트가 클라이언트(사용자의 브라우저)에서 실행됩니다.
    • false: 스크립트가 서버에서 실행됩니다.

    기본값: false
    isUi11호환 부울 레거시 UI 11에서 UI 작업이 지원되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: UI 작업은 레거시 UI 11에서 지원됩니다.
    • false: UI 작업이 레거시 UI 11에서 지원되지 않습니다.

    기본값: false
    isUi16호환 부울 코어 UI에서 UI 작업이 지원되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 코어 UI에서 UI 작업이 지원됩니다.
    • false: 코어 UI에서 UI 작업이 지원되지 않습니다.

    기본값: false
    onClick 문자열 UI 작업이 실행될 때 실행할 JavaScript 함수의 이름입니다. 함수는 스크립트 속성으로 정의됩니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    client: {
  isClient: true,
  isUi11Compatible: true,
  isUi16Compatible: true,
  onClick: 'reopenIncident()'
}

    작업 공간 객체

    UI 작업이 작업 공간에서 작동하고 나타나는 방식을 구성합니다.

    작업 공간 객체는 UiAction 객체 내의 속성입니다.

    표 5. 속성
    이름 유형 설명
    isConfigurableWorkspace 부울 UI 작업이 적용되는 작업 공간의 유형을 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: UI 작업이 구성 가능한 작업 공간에 적용됩니다.
    • false: UI 작업이 레거시 작업 공간에 적용됩니다.

    기본값: false
    showFormButtonV2 부울 작업 공간의 양식에 버튼을 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 양식에 버튼이 나타납니다.
    • false: 양식에 버튼이 표시되지 않습니다.

    기본값: false
    showFormMenuButtonV2 부울 작업 공간의 추가 작업 메뉴에 항목을 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 추가 작업 메뉴에 항목이 나타납니다.
    • false: 추가 작업 메뉴에 항목이 나타나지 않습니다.

    기본값: false
    클라이언트스크립트V2 문자열 작업 공간에서 UI 작업이 실행될 때 실행되는 스크립트입니다. 이 속성은 인라인 JavaScript 또는 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 컨텐츠를 사용하려면 Now.include('path/to/file') 형식을 사용하여 애플리케이션의 파일을 참조하십시오. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    workspace: {
  isConfigurableWorkspace: true,
  showFormButtonV2: true,
  showFormMenuButtonV2: true,
  clientScriptV2: `function onClick(g_form) {
  }`,
}