서비스 포털 API - ServiceNow Fluent

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 20분

    • API는 서비스 포털 포털 페이지에 대한 사용자 지정 위젯 [sp_widget]을 정의합니다.

    주:
    최신 ServiceNow Fluent API 설명서 및 예제는 ServiceNow Fluent API 참조 및 ServiceNow SDK 예제 리포지토리 는 의 위치에 있습니다 GitHub.

    포털에 대한 일반적인 정보는 다음 문서를 참조하십시오 Service Portal.

    SPWidget 객체

    포털 페이지에 포함할 사용자 지정 위젯 [sp_widget]을 생성합니다.

    사용자 지정 위젯 생성에 대한 일반적인 정보는 다음 문서를 참조하십시오 Developing custom widgets.

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

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 위젯의 이름입니다.
    범주 문자열 위젯의 유형입니다.
    유효한 값은 다음과 같습니다.
    • 표준
    • otherApplications
    • 사용자 지정
    • 샘플
    • 지식베이스
    • 서비스 포털
    • 서비스 카탈로그

    기본값: 사용자 지정
    클라이언트 스크립트 스크립트 AngularJS 컨트롤러를 정의하는 클라이언트 측 스크립트입니다. 이 속성은 인라인 JavaScript 또는 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    기본값: 
    api.controller=function() { /* widget controller */ var c = this;};
    serverScript 스크립트 초기 위젯 상태를 설정하거나, 데이터 객체를 사용하여 위젯의 클라이언트 스크립트로 데이터를 전송하거나, 서버 측 쿼리를 실행하는 서버 측 스크립트입니다. 이 속성은 인라인 JavaScript 또는 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    기본값:
    (function () { /* populate the 'data' object */ /* e.g., data.table = $sp.getValue('table'); */ })();
    컨트롤러로서 문자열 지침 범위 내에서 컨트롤러에 대한 참조에 대한 변수입니다. 클라이언트 스크립트는 기본적으로 c.data 변수를 사용하여 서버 데이터 객체에 액세스합니다.

    기본값: c
    html템플릿 문자열 페이지가 표시될 때 렌더링되는 내용을 정의하는 본문 HTML 코드입니다. 여기에는 정적 XHTML, Jelly로 정의된 동적으로 생성된 콘텐츠 또는 호출 스크립트 포함 및 UI 매크로가 포함될 수 있습니다. 이 속성은 HTML 또는 인라인 HTML이 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 HTML을 제공하려면 여러 줄의 코드에 대해 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'HTML' 또는 'HTML').
    기본값:
    <div><!-- your widget template --></div>
    customCss 문자열 위젯 스타일을 정의하는 CSS 또는 SCSS입니다. 이 속성은 CSS 또는 인라인 CSS가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 CSS를 제공하려면 여러 줄의 코드에 대해 문자열 리터럴 또는 템플릿 리터럴을 사용합니다 ('CSS' 또는 'CSS').
    데이터 테이블 문자열 위젯 인스턴스 옵션을 저장할 테이블입니다. 사용자 지정 옵션 스키마를 정의하려면 위젯 인스턴스 [sp_instance] 테이블을 확장하는 테이블에 필드를 추가하고 확장 테이블을 데이터 소스로 사용하도록 위젯을 설정할 수 있습니다. 자세한 내용은 Store instance options in a table 문서를 참조하십시오.

    기본값: sp_instance
    demoData 문자열 또는 객체 위젯 기능을 보여주는 데이터입니다. 이 속성은 인라인 문자열, JSON이 포함된 애플리케이션의 다른 파일에 대한 참조 또는 인라인 JSON 직렬화 가능 객체를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 JSON을 제공하려면 키와 값 쌍이 있는 객체 { key: value }를 사용합니다.
    설명 문자열 위젯 및 용도에 대한 설명입니다.
    문서 참조 위젯 및 위젯의 용도에 대한 추가 정보를 제공하는 설명서 [sp_documentation]의 서비스 포털 변수 식별자입니다.

    설명서를 정의 서비스 포털 하려면 다음 문서를 참조하십시오 기록 API - ServiceNow Fluent.
    필드 배열 위젯 옵션 스키마에 사용할 데이터 테이블의 열 이름 목록입니다.
    has미리 보기 부울 위젯 편집기에서 위젯을 미리 볼 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 위젯 편집기에서 위젯을 미리 볼 수 있습니다.
    • false: 위젯 편집기에서 위젯을 미리 볼 수 없습니다.

    기본값: false
    ID 문자열 위젯의 고유 ID입니다. ID에는 공백을 포함할 수 없습니다.
    링크스크립트 스크립트 AngularJS를 사용하여 DOM을 직접 조작하는 링크 함수입니다. 이 속성은 인라인 JavaScript 또는 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    기본값: 
    function link(scope, element, attrs, controller) { }
    역할 배열 역할 개체의 변수 식별자 목록 또는 에 액세스할 수 있는 역할 이름입니다. 위젯. 자세한 내용은 역할 API - ServiceNow Fluent 문서를 참조하십시오.
    옵션스키마 배열 관리자(sp_admin)가 서비스 포털 위젯 인스턴스에 대해 구성할 수 있는 매개변수 목록입니다. 위젯 옵션 스키마는 위젯 재사용과 여러 페이지에서 위젯 인스턴스를 고유하게 구성할 수 있도록 지원합니다. 자세한 내용은 Widget option schema 문서를 참조하십시오.
    optionSchema: [
  {
    name: 'String',
    label: 'String',
    section: 'String',
    type: 'String',
    defaultValue: 'String',
    hint: 'String'
  },
...
]
    • 이름: 필수. 매개변수의 이름입니다.
    • 레이블: 필수입니다. 위젯 인스턴스 옵션에 나타나는 매개변수의 레이블입니다.
    • 섹션: 필수입니다. 매개변수가 표시되는 위젯 인스턴스 옵션의 섹션입니다.
      유효한 값은 다음과 같습니다.
      • 데이터
      • 동작
      • 설명서
      • 프레젠테이션
      • 기타
    • 유형: 필수입니다. 매개변수의 데이터 형식입니다.
      유효한 값은 다음과 같습니다.
      • 문자열
      • 부울
      • 정수
      • 참조
      • 선택
      • 필드목록
      • fieldName
      • 글라이드 목록
      • 글리프 아이콘
    • defaultValue: 매개변수의 기본값입니다.
    • 힌트: 매개변수 위에 마우스를 올렸을 때 도구 설명으로 표시되는 매개변수에 대한 짧은 설명입니다.
    공개 부울 인증되지 않은 사용자가 위젯을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 인증되지 않은 사용자가 위젯에 액세스할 수 있습니다.
    • false: 인증된 사용자만 위젯에 접근할 수 있습니다.

    기본값: false
    의존성 배열 SPWidgetDependency 개체의 변수 식별자 목록이거나 위젯에 대한 종속성 이름 또는 sys_ids입니다. 자세한 내용은 SPWidgetDependency 객체 문서를 참조하십시오.
    AngularProvider 배열 SPAngularProvider 개체의 변수 식별자 목록이거나 위젯에 대한 Angular 공급자의 이름 또는 sys_ids입니다. 자세한 내용은 SPAngularProvider 객체 문서를 참조하십시오.
    템플릿 배열 위젯과 연결할 Angular ng-templates [sp_ng_template] 목록입니다. Angular ng-templates에는 렌더링하도록 지시할 때만 렌더링되는 콘텐츠가 포함되어 있습니다.
    templates: [
  {
    $id: Now.ID['String' or Number]
    id: 'String'
    htmlTemplate: 'HTML' or `HTML` 
  },
  ...
]
    • $id: 필수입니다. 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다.

      형식: Now.ID['문자열' 또는 숫자]

    • id: 필수입니다. Angular ng-template의 ID입니다.
    • htmlTemplate: 필수입니다. HTML 템플릿 내용입니다. 이 속성은 HTML 또는 인라인 HTML이 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    import { SPWidget } from '@servicenow/sdk/core'

SPWidget({
    $id: 'my_simple_widget',
    name: 'My Simple Widget',
    category: 'knowledgeBase',
    clientScript: Now.include('./client.js'),
    serverScript: Now.include('./server.js'),
    controllerAs: '$ctrl',
    customCss: Now.include('./custom_css.css'),
    dataTable: 'sp_instance',
    demoData: { message: 'Hello, World!' },
    description: 'This is a test widget',
    docs: widgetDoc,
    htmlTemplate: Now.include('./template.html'),
    fields: ['color', 'class_name'],
    hasPreview: true,
    id: 'my-simple-widget',
    linkScript: Now.include('./link.client.js'),
    optionSchema: [
        {
            name: 'my_option',
            label: 'My Option',
            type: 'string',
            section: 'behavior'
        }
    ],
    roles: [manager, 'admin'],
})

    SPAngularProvider 객체

    여러 위젯에서 구성요소를 재사용하고 포털 성능을 개선하는 Angular 제공자 [sp_angular_provider]를 생성합니다.

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

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 Angular 제공자의 이름입니다.
    클라이언트 스크립트 스크립트 위젯에서 재사용할 클라이언트 측 스크립트입니다.이 속성은 인라인 JavaScript 또는 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조를 지원합니다.
    체재:
    • 다른 파일의 텍스트 콘텐츠를 사용하려면 Now.include('경로/대상/파일') 형식을 사용하여 애플리케이션에서 파일을 참조합니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    유형 문자열 Angular 제공자의 유형입니다.
    유효한 값은 다음과 같습니다.
    • 지시문
    • 공장
    • 서비스

    기본값: 지시문
    필요 배열 다른 SPAngularProvider 개체의 변수 식별자 목록이나 Angular 공급자의 이름 또는 sys_ids입니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    import { SPAngularProvider } from '@servicenow/sdk/core'
const OTHER_ANGULAR_PROVIDER = 'd11f285fe069e1f119b44bd05c0770aa'

SPAngularProvider({
    $id: 'my_angular_provider',
    name: 'my_angular_provider',
    clientScript: Now.include('my_angular_provider.client.js'),
    type: 'directive',
    requires: [OTHER_ANGULAR_PROVIDER]
})

    SPWidgetDependency 객체

    JavaScript 및 CSS 파일을 위젯에 연결하고 타사 라이브러리, 외부 스타일시트 또는 Angular 모듈을 사용하는 위젯 종속성 [sp_dependency]을 생성합니다.

    의존성은 필요할 때 서버에서 비동기식으로 로드됩니다. 위젯에는 필요한 만큼 의존성이 있을 수 있습니다. 그러나 더 많이 추가할수록 위젯이 페이지에서 렌더링하기 위해 다운로드해야 하는 컨텐츠가 더 많아집니다. 보다 효율적인 로드 시간을 위해 종속성을 가능한 한 작게 유지하십시오. 자세한 내용은 Create a widget dependency 문서를 참조하십시오.

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

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 위젯 의존성의 이름입니다.
    angularModuleName 문자열 JS 포함이 Angular 모듈인 경우 로드할 Angular 모듈의 이름입니다.
    includeOnPageLoad 부울 페이지에서 종속성이 로드되는 시기를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 초기 페이지 로드와 함께 의존성이 로드됩니다.
    • false: 연결된 위젯이 페이지에 로드될 때만 의존성이 로드됩니다.

    기본값: false
    css포함 배열 CssInclude 객체의 변수 식별자 목록 또는 CSS 포함 sys_ids 및 순서입니다. 자세한 내용은 CssInclude 객체 문서를 참조하십시오.
    cssIncludes: [
  {
    order: Number,
    include: 'String' or Reference,
  },
  ...
]
    jsIncludes 배열 JsInclude 객체의 목록 변수 식별자 또는 JS 포함 sys_ids 및 해당 순서입니다. 자세한 내용은 JsInclude 객체 문서를 참조하십시오.
    jsIncludes: [
  {
    order: Number,
    include: 'String' or Reference,
  },
  ...
]
    portalsForPageLoad 배열 위젯 의존성을 로드하는 포털 [sp_portal] sys_ids 목록입니다. 비어 있으면 종속성이 모든 포털의 페이지 로드에 포함됩니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    import { SPWidgetDependency } from '@servicenow/sdk/core'

SPWidgetDependency({
    $id: 'samplejs',
    name: 'Sample',
    angularModuleName: 'samplejs',
    includeOnPageLoad: true,
    portalsForPageLoad: ['b4572a48262a16df3032b48cef75a853', 'fe12dbbed14bd3f712f0787141c2f656'],
    cssIncludes: [
        {
            order: 100,
            include: localCss,
        },
        {
            order: 200,
            include: '94112ccb0fb3c2ed072b01d3cb401196',
        },
    ],
    jsIncludes: [
        {
            order: 100,
            include: localJs,
        },
        {
            order: 200,
            include: 'f8af18a5e6c71a3702c4f2038b43cf62',
        },
    ],
})

    CssInclude 객체

    위젯 의존성에서 스타일시트 또는 외부 CSS를 참조하는 CSS 포함 [sp_css_include]을 만듭니다.

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

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 CSS 포함의 이름입니다.
    URL 문자열 외부 CSS 파일의 URL입니다. 스타일시트가 spCss 속성과 함께 제공되지 않는 경우 이 속성이 필요합니다.
    spCss 문자열 스타일시트 [sp_css]의 sys_id입니다. 외부 CSS 파일이 url 속성과 함께 제공되지 않은 경우 이 속성이 필요합니다.
    rtlCssUrl 문자열 세션 언어가 히브리어와 같은 오른쪽에서 왼쪽으로 쓰는 언어일 때 위젯의 방향을 미러링하기 위한 외부 오른쪽에서 왼쪽(RTL) CSS 파일의 URL입니다. 자세한 내용은 Styling for right-to-left languages in portals 문서를 참조하십시오.
    지연 로드 부울 CSS 포함을 로드하는 방법을 나타내는 플래그입니다. 이 속성은 spCSS 속성을 사용하여 스타일시트를 지정하는 경우에만 적용됩니다.
    유효한 값은 다음과 같습니다.
    • true: CSS 포함을 비동기식으로 로드하여 페이지 로드 시간을 개선합니다.
    • false: CSS 포함이 비동기적으로 로드되지 않습니다.

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

const localCss = CssInclude({
    $id: '22bcf16da81e2bc0340c53d50d531adf',
    name: 'Sample Styles',
    spCss: '50e3e32aa321b1c7d1945c5f423228bd',
})

    JsInclude 객체

    위젯 의존성에서 UI 스크립트 또는 외부 JavaScript 코드를 참조하는 JS 포함 [sp_js_include]을 만듭니다.

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

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 JS 포함의 이름입니다.
    URL 문자열 외부 JavaScript 파일의 URL입니다. URL은 절대 경로여야 합니다. UI 스크립트가 sysUiScript 속성과 함께 제공되지 않은 경우 이 속성이 필요합니다.
    sysUiScript 문자열 UI 스크립트 [sys_ui_script]의 sys_id입니다. 외부 JavaScript 파일이 url 속성과 함께 제공되지 않은 경우 이 속성이 필요합니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    import { JsInclude } from '@servicenow/sdk/core'

const localJs = JsInclude({
    $id: '98239e4eadfac88b01cce7daa23b6fc3',
    name: 'Sample Framework',
    sysUiScript: 'b67af05645f738df1f286bb3e9ecd55f',
})