도우미 - UI 빌더

도우미 API는 페이지 스크립트 전반에 공통적인 일반적인 기능을 제공하므로 모달 열기 및 닫기와 같은 간단한 기능을 위해 스크립트를 작성할 필요가 없습니다.

이 API는 페이지 스크립트에만 사용할 수 있으며 다음을 포함한 다른 UI Builder 스크립트에서는 사용할 수 없습니다.

• 구성요소 속성 값 스크립트
• 구성요소 가시성 스크립트
• 이벤트 페이로드 스크립트
• UX 클라이언트 스크립트 포함

helpers - helpers.modal.close(String modalId)

현재 페이지에서 지정된 모달을 닫습니다.

표 1. 매개변수

이름	유형	설명
modalId	문자열	종결할 모달의 모달 구성요소 ID입니다. 구성요소 ID는 스테이지에서 UI 빌더 구성요소를 끌어서 놓을 때 자동으로 생성됩니다. 속성 페이지에서 ID를 찾을 수 있습니다.

표 2. 반환

유형	설명
없음

이 예제에서는 alert-modal로 끝나는 구성요소 ID로 모달을 닫는 방법을 보여줍니다.

function handler({api, event, imports, helpers}) {
  helpers.modal.close("[component-id$='alert_modal']")
}

helpers - helpers.modal.open(String modalId, Object options)

현재 페이지에서 지정된 모달을 엽니다.

페이지 내에서 한 번에 하나의 모달만 표시할 수 있습니다. 모달이 현재 열려 있는 경우 이 메서드를 호출하면 기존 모달이 숨겨지고 새 모달이 나타납니다.

표 3. 매개변수

이름	유형	설명
modalId	문자열	열 모달의 구성요소 ID입니다. 구성요소 ID는 스테이지에서 UI 빌더 구성요소를 끌어서 놓을 때 자동으로 생성됩니다. 속성 페이지에서 ID를 찾을 수 있습니다.
옵션	객체	옵션입니다. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
옵션.콘텐츠	문자열	모달에 대한 텍스트 컨텐츠입니다.
옵션.contentFullWidth	부울	더 넓은 컨텐츠를 맞추기 위해 모달 본문 주위의 가로 패딩을 제거할지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 패딩을 제거합니다. false: 패딩을 제거하지 않습니다. 기본값: false
options.headerLabel	문자열	모달 헤더의 텍스트 콘텐츠입니다.
options.size	문자열	모달 컨테이너의 크기입니다. 대부분의 크기는 화면 크기가 작을 때 자동으로 확장되어 뷰포트를 채웁니다. 유효한 값은 다음과 같습니다. sm MD Lg 전체 화면 기본값: sm

표 4. 반환

유형	설명
없음

이 예제에서는 alert-modal로 끝나는 ca omponent ID가 있는 모달을 여는 방법을 보여 줍니다.

function handler({api, event, imports, helpers}) {
  helpers.modal.open("[component-id$='alert_modal']")
}

도우미 - helpers.navigate.setRouteParams(객체 params)

지정된 매개변수를 같은 페이지의 다른 구성요소에 전달합니다.

URL에 매개 변수를 추가하려는 모든 페이지 구성 요소에서 이 메서드를 사용합니다. 다른 구성 요소가 변경될 때 해당 매개 변수의 현재 값을 알아야 응답할 수 있도록 URL에 매개 변수를 추가할 수 있습니다. 예를 들어, 이 메서드를 사용하여 탭 구성 요소의 selectedIndex 를 전달하여 URL에 반영되어 해당 탭에 포커스를 부여할 수 있습니다.

표 5. 매개변수

이름	유형	설명
매개변수	객체	다른 구성요소에 전달할 선택적 매개변수의 키-값 쌍입니다. 이 개체는 기본 값만 있는 평범하고 평평한 개체여야 합니다. 배열 또는 개체 참조는 무시되고 URL에 추가되지 않습니다. 지정된 모든 키는 경로 구성에서 선택적 매개 변수의 일부여야 하며, 그렇지 않으면 무시됩니다. 선택적 매개변수에 대한 자세한 내용은 UI Builder에서 페이지 생성을 참조하십시오.

표 6. 반환

유형	설명
없음

이 코드 예제에서는 URL params/selected-tab-index/2를 추가하는 방법을 보여 줍니다. 실제 URL의 매개 변수는 카멜 대/소문자에서 뱀 대/소문자로 변경되므로 selectedTabIndex 는 selected-tab-index가 됩니다.

function handler({api, event, helpers, imports}) {  
  helpers.navigate.setRouteParams({'params': {'selectedTabIndex':  2}});  
} 

도우미 - helpers.navigate.to(문자열 경로, 객체 필드, 객체 매개변수, 부울 리디렉션, 부울 passiveNavigation, 문자열 targetRoute)

지정된 경로 및 필드 정보를 기반으로 한 화면에서 다른 화면으로 이동합니다. URL 변경 및 각 화면 로드가 관찰됩니다.

표 7. 매개변수

이름	유형	설명
route	문자열	경로의 이름입니다. UX 앱 경로(sys_ux_app_route.list)의 유효한 항목이어야 합니다. 이 값은 URL에 반영되며, fieldsURL은 /optionalParams<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2 열 값을 기반으로 route 만들어집니다> 예: / record/incident/12345/params/selectedTabIndex/4
필드	객체	옵션입니다. 필수 매개변수의 키-값 쌍입니다. 예: 'fields' : {'table': ' incident', 'sysId': '12345'}.
매개변수	객체	옵션입니다. 선택적 매개변수의 키-값 쌍입니다. 예: ' params' : {'selectedTabIndex': 4}.
redirect	부울	브라우저 기록에서 최신 기록 항목을 제거할지 여부를 나타내는 플래그입니다. 예를 들어 사이트 A, B, C로 차례로 이동하는 경우입니다. redirect C로 이동하는 동안 가 true 로 설정되면 B에 대한 이력 항목이 제거됩니다. 브라우저 기록에는 A와 C만 표시됩니다. 유효한 값은 다음과 같습니다. true: 최신 기록 항목을 제거하고 최신 URL로 리디렉션합니다. false: 이력 항목을 제거하지 않습니다. 기본값: false
passiveNavigation	부울	백그라운드 탐색을 수행할지 여부를 나타내는 플래그입니다. 백그라운드 탐색은 페이지가 열려 있지만 활성화되지 않거나 표시되지 않는 경우입니다. 예를 들어 페이지의 비활성 탭을 열지만 보이지 않지만 백그라운드에서 로드됩니다. 유효한 값은 다음과 같습니다. true: 백그라운드 탐색을 수행합니다. false: 백그라운드 탐색을 수행하지 않습니다. 기본값: false
targetRoute	문자열 또는 객체	드릴다운, 딥 링크 또는 하위 탭으로 이동하는 하위 탐색. current로 설정하면 현재 경로가 현재 URL 아래의 하위 탐색을 수행합니다. 예를 들어 / record/incident/123 이 현재 URL이고 다음 호출이 수행되는 경우: helper.navigate.to('기록', {'테이블': '문제', 'sysId': '567'}, {}, 거짓, 거짓, '현재'); 다음 URL이 생성됩니다. /record/ incident/123/sub/record/problem/567 주: targetRoute"현재"와 같은 문자열 또는 탐색 NAV_ITEM_SELECTED 페이로드와 같은 객체일 수 있습니다.

표 8. 반환

유형	설명
없음

이 예제에서는 매개 변수만 route 전달하는 페이지로 이동하는 방법을 보여 줍니다.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test');
}

이 예제에서는 and fields 매개 변수를 전달하는 route 페이지로 이동하는 방법을 보여 줍니다.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test', {'key': 'value'});
}

이 예제에서는 , , fields및 params 매개 변수를 전달하는 route페이지로 이동하는 방법을 보여 줍니다.

function handler({api, event, helpers, imports}) {
  helpers.navigate.to('test', {'key': 'value'}, {'first': 'FirstName', 'last': 'Last Name'});
}

도우미 - helpers.screen.updateStatus(statusObj 객체)

페이지에서 제목, 아이콘, 더티 상태, 메시지 및 오류 변경과 같은 상태 업데이트를 보고할 수 있도록 합니다.

상태 업데이트는 외부 레이어가 무엇이든 호스트 역할을 하는 WorkspaceChrome 또는 AppShell에 보고됩니다.

표 9. 매개변수

이름	유형	설명
statusObj	객체	컨텐츠가 업데이트되었음을 보고하기 위해 현재 페이지로 보낼 페이로드입니다. 유효한 값은 다음과 같습니다. dirtyModalId: (문자열) 변경된 모달의 ID입니다. hasError: (부울) 페이지에 오류가 있음을 나타내는 플래그입니다. hasUpdate: (부울) 페이지에 업데이트가 있었음을 나타내는 플래그입니다. icon: (문자열) 업데이트된 아이콘이나 새 아이콘의 이름입니다. isDirty: (부울) 페이지가 더티(값이 변경됨)인지 여부를 나타내는 플래그입니다. message: (문자열) 업데이트된/새 메시지입니다. screenKey: (문자열) 변경이 발생한 화면의 ID입니다. 모든 화면에는 screenKey sn-canvas-screen 내부의 화면 macroponent에 속성이 있습니다. status: (문자열) 이 작업에 대한 상태 작업입니다. 이 값은 삽입, 삭제, 저장 또는 종결 중 하나여야 합니다. title: (문자열) 업데이트된/새 표시 제목입니다. tooltipPreview: (JSON) 업데이트 또는 새 도구 설명입니다. 예를 들어 tooltipPreview : { primaryTitle, secondaryContent: {} }입니다.

표 10. 반환

유형	설명
없음

screen.updateStatus({'dirtyModalId': 'customModalId', 'isDirty': true});

helpers - helpers.snHttp(String url, Object options)

인스턴스에 HTTP 요청을 ServiceNow 만들고 결과와 함께 promise를 반환합니다.

주:

명명된 options 객체가 HTTP 응답에서 생략되는 알려진 문제가 있습니다.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

표 11. 매개변수

이름	유형	설명
URL	문자열	인스턴스 URL을 기준으로 한 HTTP 엔드포인트입니다. 예: /api/now/table/incident 또는 /api/now/table/incident/a83820b58f723300e7e16c7827bdeed.
옵션	객체	HTTP 요청의 내용을 설명합니다. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }
옵션.배치	부울	옵션입니다. 이 HTTP 요청을 인스턴스에 대한 다른 HTTP 요청과 함께 일괄 처리해야 하는지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 배치 요청의 일부로 요청을 수행합니다. false: 전용 요청을 만듭니다. 기본값: true
options.body	객체	옵션입니다. 요청 본문으로 보낼 데이터입니다. 요청 메서드 PUT, POST 및 PATCH에만 적용할 수 있습니다. 개체의 요소는 HTTP 메서드의 유형에 따라 달라집니다. 자세한 내용은 아래 코드 예제를 참조하십시오. 기본값: {}
options.headers	객체	옵션입니다. 추가 HTTP 요청 헤더입니다. 예: headers: { "Content-Type": "application/json", "Accept": "application/xml" }
options.method	문자열	옵션입니다. HTTP 메서드입니다. 유효한 값은 다음과 같습니다. 삭제 임포트 패치 게시 넣기 기본값: GET

표 12. 반환

유형	설명
오류	REST API에서 반환되는 오류를 설명하는 객체입니다. 데이터 유형: 객체 "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
오류.데이터	HTTP API에서 반환된 응답입니다. 데이터 유형: REST API에 의해 정의됨
error.message	HTTP 요청을 처리하는 동안 발생한 오류를 설명하는 메시지입니다. 주: 이 매개 변수가 항상 반환되는 것은 아닙니다. 데이터 유형: 문자열
오류.옵션	원래 HTTP 요청에 대해 설명합니다. 데이터 유형: 객체 "options": { "headers": {Object}, "responseHeader": {Object} }
error.options.headers	요청에서 전송된 모든 요청 헤더의 목록을 포함하는 객체입니다. 데이터 유형: 객체
error.options.responseHeaders	요청에서 전송된 모든 응답 헤더의 목록이 포함된 객체입니다. 데이터 유형: 객체
error.status	400, 405 또는 500과 같은 HTTP 오류 상태 코드를 반환했습니다. 데이터 유형: 숫자
error.statusText	잘못된 요청과 같은 HTTP 상태 메시지를 반환했습니다. 데이터 유형: 문자열
response	HTTP 요청이 성공할 경우 반환됩니다. HTTP 요청에 대한 응답입니다. 데이터 유형: 모두

다음 예제에서는 promise를 반환하는 snHttp() 를 호출하는 방법을 보여 줍니다.

function handler({api, event, helpers, imports}) {
  helpers.snHttp('/api/now/table/u_movie', {method: 'GET'})
    .then(({response}) => {
      // do something with the table data
    })
    .catch(({error}) => {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
    });
  });
}

다음 예제에서는 async 및 await를 사용하여 snHttp()를 호출하는 방법을 보여 줍니다.

async function handler({helpers}) {
  try {
    const result = await helpers.snHttp('/api/now/table/u_movie', {method: 'GET'});
  } catch ({error}) {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
      });
  }
}

다음 예제에서는 POST 요청을 설정하는 방법을 보여 줍니다.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident", {
      method: "POST",
      body: {
        description: "Sample description",
        close_notes: "Sample close notes",
        order: "-1"
      }
    })
    .then(({ response }) => {
      // handle POST request response
    })
    .catch(({ error }) => {
      // handle POST request errors
    });
}

다음 예제에서는 PUT 요청을 설정하는 방법을 보여 줍니다.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident/a83820b58f723300e7e16c7827bdeed2", {
      method: "PUT",
      body: {
        activity_due: "1970-04-02 18:26:17"
      },
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/xml"
      }
    })
    .then(({ response }) => {
      // handle PUT request response
    })
    .catch(({ error }) => {
      // handle PUT request errors
    });
}

도우미 - helpers.timing.clearInterval(Number timeoutId)

이전 setInterval() 호출을 통해 예약된 함수의 실행을 취소합니다.

표 13. 매개변수

이름	유형	설명
시간 초과 ID	번호	지울 예약된 기능의 고유 식별자입니다. 이 값은 해당 setInterval() 호출에 의해 반환됩니다.

표 14. 반환

유형	설명
없음

이 예제에서는 clearInterval()을 사용하여 setInterval() 메서드를 사용하여 이전에 설정된 타이밍 작업을 취소하는 방법을 보여 줍니다. 이 함수는 페이지에서 자동 새로 고침 사용 안 함 단추를 클릭하는 사용자가 호출할 수 있습니다.

function handler({api, helpers}) {
  api.setState('intervalId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearInterval(currentValue);
    }
    return -1;
  });
}

도우미 - helpers.timing.clearTimeout(Number timeoutId)

이전 setTimeout() 호출을 통해 예약된 함수의 실행을 취소합니다.

표 15. 매개변수

이름	유형	설명
시간 초과 ID	번호	지울 예약된 기능의 고유 식별자입니다. 이 값은 해당 setTimeout() 호출에 의해 반환됩니다.

표 16. 반환

유형	설명
없음

이 코드 예제에서는 지정된 timeoutId를 사용하여 타이머를 종료하는 방법을 보여 줍니다.

function handler({api, helpers}) {
  api.setState('timeoutId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearTimeout(currentValue);
    }
    return -1;
  });
}

helpers - helpers.timing.setInterval(Function fn, Number delay)

지정된 지연 값을 함수 호출 사이의 간격으로 사용하여 지정된 함수를 반복적으로 실행합니다.

네이티브 JavaScript setInterval() 메서드와 달리 이 메서드는 첫 번째 인수로 평가할 코드 문자열 전달을 지원하지 않습니다. 추가 인수는 함수 자체에 전달됩니다.

표 17. 매개변수

이름	유형	설명
Fn	함수	반복적으로 실행하는 기능입니다.
지연	번호	각 기능 실행 사이의 시간 간격 길이입니다. 단위: 밀리초

표 18. 반환

유형	설명
번호	기능 실행 운영의 고유 식별자입니다. 이 작업을 취소해야 하는 경우 메서드에서 도우미 - helpers.timing.clearInterval(Number timeoutId) 이 값을 사용합니다.

이 코드 예제에서는 매초 페이지의 타임스탬프를 새로 고치는 방법을 보여 줍니다. 이 함수는 페이지에서 자동 새로 고침 사용 단추를 클릭하는 사용자가 호출할 수 있습니다.

function handler({api, helpers}) {
  // Every one second, refresh the value of current timestamp client state parameter
  const intervalId = helpers.timing.setInterval(() => {
    api.setState('currentTimestamp', new Date().toString())
  }, 1000);

  // The interval ID is kept in state to use when calling the helpers.timing.clearInterval() method at a later point
  api.setState('intervalId', intervalId);
}

helpers - helpers.timing.setTimeout(함수 fn, Number delay)

지정된 지연 시간 후에 지정된 함수를 실행합니다.

기본 JavaScript setTimeout() 메서드와 달리 이 메서드는 첫 번째 인수로 평가할 코드 문자열 전달을 지원하지 않습니다. 추가 인수는 함수 자체에 전달됩니다.

표 19. 매개변수

이름	유형	설명
Fn	함수	실행할 함수입니다.
지연	번호	지정된 함수를 호출하기 전에 대기할 시간의 길이입니다. 단위: 밀리초

표 20. 반환

유형	설명
번호	기능 실행 운영의 고유 식별자입니다. 이 작업을 취소해야 하는 경우 메서드에서 도우미 - helpers.timing.clearTimeout(Number timeoutId) 이 값을 사용합니다.

이 코드 예제에서는 20분 타이머를 설정하는 방법을 보여 줍니다. 이 기능을 버튼과 연결할 수 있습니다 20 분 후에 알림.

function handler({api, helpers}) {
  const timeoutId = helpers.timing.setTimeout(() => {
    api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
      id: 'alert5',
      status: 'high',
      icon: 'info-circle-outline',
      content: 'Try to look away at something that is 20 feet away from you for a total of 20 minutes.',
      action: { type: 'dismiss' }
    });
  }, 20 * 60 * 1000);

  // The timeout ID is kept in state to use when calling the helpers.timing.clearTimeout() method at a later point
  api.setState('timeoutId', timeoutId);
}

helpers - helpers.translate(문자열 메시지, 문자열 토큰)

현재 사용자의 세션 언어에 따라 지정된 메시지를 비동기적으로 검색하고 번역합니다.

와 함께 api - setState(문자열, stateParam, 임의의 값) 이 메서드를 사용하여 변환된 값을 페이지의 다른 필드에 바인딩할 수 있습니다.

주:

promise 또는 async 및 await 를 사용하여 이 메서드를 호출할 수 있습니다. 아래 코드 예제에서는 두 구현을 모두 보여 줍니다.

표 21. 매개변수

이름	유형	설명
메시지	문자열	번역할 메시지입니다.
토큰	문자열	옵션입니다. 문자열 변수를 대체하는 데 사용할 매개변수의 쉼표로 구분된 목록입니다. 예: helpers.translate('Text {0} {1}', 'to', 'translate');

표 22. 반환

유형	설명
문자열	번역된 텍스트 문자열입니다.

다음 예제에서는 promise를 사용하여 문자열의 해당 변수에 포함할 테이블 필드 참조를 전달하는 방법을 보여 줍니다.

function handler ({api, helpers}) {
  helpers.translate('Welcome {0} {1}!', user.firstName, user.lastName)
    .then((translatedText) => {
      api.setState('greeting', translatedText);
    });
}

다음 예제에서는 함수에서 promise 대신 async 및 await 를 사용하는 방법을 보여 줍니다.

async function handler ({api, helpers}) {
  const translatedText = await helpers.translate('Welcome to {0}', 'ServiceNow');
    api.setState('greeting', translatedText);
}