도우미 - UI 빌더

도우미 - 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.modal.open(String modalId, Object options)

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

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

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

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

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

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

표 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. 매개변수
이름	유형	설명
경로	문자열	경로의 이름입니다. UX 앱 경로(sys_ux_app_route.list)의 유효한 항목이어야 합니다. 이 값은 URL에 반영되며 , 열 값(`/<route>/field1Value/<>{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2>` 및 열 값을 기반으로 routefieldsoptionalParams URL이 생성됩니다 예: `/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	문자열 또는 객체	드릴다운, 딥 링크 또는 하위 탭으로 하위 탐색. `현재`로 설정된 경우 현재 경로는 현재 URL에서 하위 탐색을 수행합니다. 예를 들어, `/record/incident/123` 이 현재 URL이고 다음 호출이 수행되는 경우: `helper.navigate.to('record', {'table': 'problem', 'sysId': '567'}, {}, false, false, 'current');` 다음 URL이 생성됩니다. `/record/incident/123/sub/record/problem/567` 주: targetRoute`'current'`와 같은 문자열 또는 `탐색 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 - helpers.screen.updateStatus(객체 statusObj)

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

상태 업데이트는 외부 레이어가 있는 WorkspaceChrome 또는 AppShell에 보고되며 호스트 역할을 합니다.

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

표 10. 반환
유형	설명
안 함

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

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

인스턴스에 HTTP 요청을 ServiceNow 하고 결과와 함께 약속을 반환합니다.

주:

HTTP 응답에서 이름이 지정된 options 개체가 생략되는 알려진 문제가 있습니다.

{
  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 PATCH POST 넣기 기본값: GET

표 12. 반환
유형	설명
오류	REST API에서 반환하는 오류를 설명하는 객체입니다. 데이터 유형: 객체 `"error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }`
오류.데이터	HTTP API에서 반환된 응답입니다. 데이터 유형: REST API에 의해 정의됨
오류.메시지	HTTP 요청을 처리하려고 할 때 발생한 오류를 설명하는 메시지입니다. 주: 이 매개변수가 항상 반환되는 것은 아닙니다. 데이터 유형: 문자열
오류.옵션	원래 HTTP 요청을 설명합니다. 데이터 유형: 객체 `"options": { "headers": {Object}, "responseHeader": {Object} }`
error.options.headers	요청에서 보낸 모든 요청 헤더의 목록을 포함하는 객체입니다. 데이터 유형: 객체
error.options.responseHeaders	요청에서 보낸 모든 응답 헤더의 목록을 포함하는 객체입니다. 데이터 유형: 객체
오류.상태	반환된 HTTP 오류 상태 코드(예: 400, 405 또는 500). 데이터 유형: 숫자
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.timing.setInterval(Function fn, Number delay)

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

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

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

표 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(Function fn, Number delay)

지정된 지연 후 지정된 기능을 실행합니다.

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

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

표 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(String message, String tokens)

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

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

주:

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);
}