helpers - UI Builder

helpers API にはページスクリプト全体に共通する一般的な機能があるため、モーダルのオープンやクローズといった簡単な機能のスクリプトを記述する必要はありません。

この API はページスクリプトでのみ使用できます。次のような他の UI Builder スクリプトでは使用できません。

• コンポーネントプロパティ値スクリプト
• コンポーネント可視化スクリプト
• イベントペイロードスクリプト
• UX クライアントスクリプトインクルード

helpers - helpers.modal.close(文字列 modalId)

現在のページの指定されたモーダルを閉じます。

表 : 1. パラメーター

名前	タイプ	説明
modalId	文字列	閉じるモーダルのモーダルコンポーネント ID。コンポーネントが UI ビルダー ステージにドラッグアンドドロップされると、コンポーネント ID が自動的に生成されます。その ID はプロパティページで見つけることができます。

表 : 2. 返される内容

タイプ	説明
なし

この例は、alert-modalで終わるコンポーネント ID のモーダルを閉じる様子を示しています。

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

helpers - helpers.modal.open(文字列 modalId, オブジェクト options)

現在のページの指定されたモーダルを開きます。

1 ページ内で一度に表示できるモーダルは 1 つだけです。モーダルが現在開いているときにこのメソッドを呼び出すと、既存のモーダルは非表示になり、新しいモーダルが表示されます。

表 : 3. パラメーター

名前	タイプ	説明
modalId	文字列	開くモーダルのコンポーネント ID。コンポーネントが UI ビルダー ステージにドラッグアンドドロップされると、コンポーネント ID が自動的に生成されます。その ID はプロパティページで見つけることができます。
オプション	オブジェクト	オプション。 "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
options.content	文字列	モーダルのテキストコンテンツ。
options.contentFullWidth	ブーリアン	幅の広いコンテンツに合わせてモーダルの本文周囲の水平方向のパディングを削除するかどうかを示すフラグ。 有効な値： true：パディングを削除します。 false：パディングを削除しません。 デフォルト値：false
options.headerLabel	文字列	モーダルヘッダーのテキストコンテンツ。
options.size	文字列	モーダルコンテナのサイズ。画面サイズが小さい場合、ほとんどのサイズはビューポート全体に自動的に拡大されます。 有効な値： SM md lg fullscreen デフォルト：sm

表 : 4. 返される内容

タイプ	説明
なし

この例は、alert-modalで終わるコンポーネント ID のモーダルを開く様子を示しています。

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

helpers - helpers.navigate.setRouteParams(オブジェクト params)

指定されたパラメーターを同じページ上の他のコンポーネントに渡します。

このメソッドは、URL にパラメーターを追加する任意のページコンポーネントで使用します。あるパラメーターが変更されたときに別のコンポーネントがそのパラメーターの現在の値を知る必要がある場合は、URL にパラメーターを追加すると、それに反応して動作します。例として、このメソッドを使用してタブコンポーネントの selectedIndex を渡し、URL に反映させてそのタブにフォーカスを移動します。

表 : 5. パラメーター

名前	タイプ	説明
params	オブジェクト	他のコンポーネントに渡すオプションのパラメーターのキーと値のペア。 これは、プリミティブ値のみを持つ単純でフラットなオブジェクトである必要があります。アレイやオブジェクト参照は無視され、URL に追加されません。指定されたすべてのキーがルート構成のオプションのパラメーターの一部である必要があります。そうでない場合、キーは無視されます。オプションのパラメーターの詳細については、「UI Builder でページを作成する」を参照してください。

表 : 6. 戻り値

タイプ	説明
なし

このコード例は、params/selected-tab-index/2 という URL を追加する方法を示しています。実際の URL のパラメーターがキャメルケースからスネークケースに変更されるため、selectedTabIndex は selected-tab-index になります。

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

helpers - helpers.navigate.to(文字列 route, オブジェクト fields, オブジェクト params, ブーリアン redirect, ブーリアン passiveNavigation, 文字列 targetRoute)

指定されたルートとフィールドの情報に基づいて、ある画面から別の画面に移動します。URL が変わり、それぞれの画面のロードが観察されます。

表 : 7. パラメーター

名前	タイプ	説明
route	文字列	ルートの名前。UX アプリルート (sys_ux_app_route.list) からの有効なエントリである必要があります。この値は URL に反映され、 route、fields、および optionalParams 列の値に基づいて次のように URL が作成されます。/<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2> 例：/record/incident/12345/params/selectedTabIndex/4
フィールド	オブジェクト	オプション。必須パラメーターのキーと値のペア。例：'fields' : {'table': 'incident', 'sysId': '12345'}
params	オブジェクト	オプション。オプションのパラメーターのキーと値のペア。例：'params' : {'selectedTabIndex': 4}
redirect	ブーリアン	ブラウザー履歴から最新の履歴エントリーを削除するかどうかを示すフラグ。たとえば、サイト A、B、C の順に移動すると、C に移動するときに redirect が true に設定され、B の履歴エントリーが削除されます。ブラウザー履歴には A と C のみが表示されます。 有効な値： true：最新の履歴エントリーを削除し、最新の URL にリダイレクトします。 false：履歴エントリーを削除しません。 デフォルト値：false
passiveNavigation	ブーリアン	バックグラウンドナビゲーションを実行するかどうかを示すフラグ。バックグラウンドナビゲーションは、ページが開いているがアクティブになっていない、または表示されていない場合に実行されます。たとえば、ページの非アクティブなタブを開いても、ページは表示されずにバックグラウンドでロードされます。 有効な値： true：バックグラウンドナビゲーションを実行します。 false：バックグラウンドナビゲーションを実行しません。 デフォルト値：false
targetRoute	文字列またはオブジェクト	ドリルダウン、ディープリンク、またはサブタブへのサブナビゲーション。current に設定すると、現在のルートが現在の 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' などの文字列の場合と、navigation NAV_ITEM_SELECTED payload などのオブジェクトの場合があります。

表 : 8. 返される内容

タイプ	説明
なし

この例は、route パラメーターのみを渡してページに移動する方法を示しています。

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

この例は、route と fields パラメーターを渡してページに移動する方法を示しています。

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

この例は、route、fields および params パラメーターを渡してページに移動する方法を示しています。

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-canvaas-screen 内の画面 Macroponent のプロパティとして screenKey があります。 status：(文字列) このアクションのステータス操作。この値は、inserted、deleted、saved、closed のいずれかである必要があります。 title：(文字列) 更新された表示タイトルや新規表示タイトル。 tooltipPreview：(JSON) 更新されたツールチップや新しいツールチップ。例：tooltipPreview : { primaryTitle, secondaryContent: {} }

表 : 10. 返される内容

タイプ	説明
なし

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

helpers - helpers.snHttp(文字列 url, オブジェクト options)

ServiceNow インスタンスへの HTTP 要求を行い、結果を含む 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" }
options.batch	ブーリアン	オプション。この 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 PUT デフォルト：GET

表 : 12. 返される内容

タイプ	説明
error	REST API によって返された任意のエラーを説明するオブジェクト。 データタイプ：オブジェクト "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
error.data	HTTP API から返された応答。 データタイプ：REST API によって定義
error.message	HTTP 要求を処理しようとしたときに発生したエラーを記述するメッセージ。 注: このパラメーターは常に返されるわけではありません。 データタイプ：文字列
error.options	元の HTTP 要求を記述します。 データタイプ：オブジェクト "options": { "headers": {Object}, "responseHeader": {Object} }
error.options.headers	要求で送信されたすべての要求ヘッダーのリストを含むオブジェクト。 データタイプ：オブジェクト
error.options.responseHeader	要求で送信されたすべての応答ヘッダーのリストを含むオブジェクト。 データタイプ：オブジェクト
error.status	返された HTTP エラーステータスコード (400、405、500 など)。 データタイプ：数値
error.statusText	返された HTTP ステータスメッセージ (Bad Request など)。 データタイプ：文字列
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 - helpers.timing.clearInterval(数字 timeoutId)

以前の setInterval() 呼び出しを通じてスケジュールされた関数の実行をキャンセルします。

表 : 13. パラメーター

名前	タイプ	説明
timeoutId	数字	クリアするスケジュール設定済み機能の一意の識別子。この値は、対応する setInterval() 呼び出しによって返されます。

表 : 14. 返される内容

タイプ	説明
なし

この例では、setInterval() メソッドを使用して以前に設定されたタイミング操作を、clearInterval() を使用してキャンセルする様子を示します。この機能は、ユーザーがページの [自動リフレッシュの無効化 (Disable Auto-refresh)] ボタンをクリックすることで呼び出される可能性があります。

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

helpers - helpers.timing.clearTimeout(数字 timeoutId)

以前の setTimeout() 呼び出しを通じてスケジュールされた関数の実行をキャンセルします。

表 : 15. パラメーター

名前	タイプ	説明
timeoutId	数字	クリアするスケジュール設定済み機能の一意の識別子。この値は、対応する setTimeout() 呼び出しによって返されます。

表 : 16. 返される内容

タイプ	説明
なし

このコード例は、指定された timeoutId を使用してタイマーを終了する方法を示しています。

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

helpers - helpers.timing.setInterval(関数 fn, 数字 delay)

指定された遅延値を関数呼び出しの間隔に使用して、指定された関数を繰り返し実行します。

ネイティブの JavaScript の setInterval() メソッドとは異なり、このメソッドでは評価するコード文字列を最初の引数として渡すことはできません。追加の引数は関数自体に渡されます。

表 : 17. パラメーター

名前	タイプ	説明
fn	関数	繰り返し実行する関数。
遅延	数字	各関数の実行間隔の長さ。 単位：ミリ秒

表 : 18. 返される内容

タイプ	説明
数字	関数実行操作の一意の識別子。この操作をキャンセルする必要がある場合は、helpers - helpers.timing.clearInterval(数字 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, 数字 delay)

指定された遅延の後に、指定された関数を実行します。

ネイティブの JavaScript の setTimeout() メソッドとは異なり、このメソッドでは評価するコード文字列を最初の引数として渡すことはできません。追加の引数は関数自体に渡されます。

表 : 19. パラメーター

名前	タイプ	説明
fn	関数	実行する関数。
遅延	数字	指定された関数を呼び出す前に待機する時間の長さ。 単位：ミリ秒

表 : 20. 返される内容

タイプ	説明
数字	関数実行操作の一意の識別子。この操作をキャンセルする必要がある場合は、helpers - helpers.timing.clearTimeout(数字 timeoutId) メソッドでこの値を使用します。

このコード例は、20 分のタイマーを設定する方法を示しています。この機能は [20 分後に通知 (Remind me in 20 minutes)] ボタンに関連付けることができます。

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(文字列 message, 文字列 tokens)

現在のユーザーのセッション言語に基づいて、指定されたメッセージを非同期に取得して翻訳します。

このメソッドを api - setState(文字列 stateParam, 任意 value) とともに使用して、変換された値をページ上の他のフィールドにバインドできます。

注:

このメソッドは、promise または async と await を使用して呼び出すことができます。以下のコード例は、両方を実装する場合を示しています。

表 : 21. パラメーター

名前	タイプ	説明
message	文字列	翻訳するメッセージ。
トークン	文字列	オプション。文字列変数を置き換えるために使用するパラメーターのカンマ区切りリスト。 例： 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);
}