ヘルパー:UI ビルダー

ヘルパー API は、ページスクリプト間で共通する一般的な機能を提供するため、モーダルのオープンやクローズなどの単純な機能用のスクリプトを記述する必要がなくなります。

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

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

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

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

表 : 1. パラメーター

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

表 : 2. 返される内容

タイプ	説明
なし

この例は、 アラートモーダルで終わるコンポーネント ID を持つモーダルを閉じることを示しています。

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

helpers - helpers.modal.open(文字列 modalId, オブジェクトオプション)

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

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 で終わる 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. パラメーター

名前	タイプ	説明
params	オブジェクト	他のコンポーネントに渡すオプションのパラメーターのキーと値のペア。 これは、プリミティブ値のみを持つプレーンでフラットなオブジェクトである必要があります。アレイまたはオブジェクト参照は無視され、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(String route, Object fields, Object params, Boolean redirect, Boolean passiveNavigation, String 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}。
リダイレクト	ブーリアン	ブラウザー履歴から最新の履歴エントリを削除するかどうかを示すフラグ。たとえば、サイト 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」 などの文字列または ナビゲーションNAV_ITEM_SELECTEDペイロードなどのオブジェクトのいずれかにすることができます。

表 : 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.screen.updateStatus(Object statusObj)

ページがタイトル、アイコン、ダーティステータス、メッセージ、エラーの変更などのステータスの更新を報告できるようにします。

ステータスの更新は、WorkspaceChrome または AppShell のいずれかの外部レイヤーに報告され、ホストとして機能します。

表 : 9. パラメーター

名前	タイプ	説明
ステータスオブジェクト	オブジェクト	コンテンツが更新されたことを報告するために現在のページに送信するペイロード。 有効な値： dirtyModalId:(文字列) 変更されたモーダルの ID。 hasError:(ブーリアン) ページにエラーがあることを示すフラグ。 hasUpdate:(ブーリアン) ページの更新があったことを示すフラグ。 icon:(文字列) 更新されたアイコンまたは新しいアイコンの名前。 isDirty:(ブーリアン) ページがダーティかどうかを示すフラグ (値が変更されています)。 message:(文字列) 更新済み/新規メッセージ。 screenKey:(文字列) 変更が発生した画面の ID。すべての画面には、sn-canvas-screen 内の画面 macroponent のプロパティとして screenKey があります。 status:(文字列) このアクションのステータス操作。この値は、[挿入済み]、[削除済み]、[保存済み]、または [クローズ済み] のいずれかである必要があります。 title:(文字列) 更新された/新しい表示タイトル。 tooltipPreview:(JSON) 更新された、または新しいツールヒント。例: tooltipPreview : { primaryTitle, secondaryContent: {} }

表 : 10. 返される内容

タイプ	説明
なし

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

helpers - helpers.snHttp(文字列 url, オブジェクトオプション)

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.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. パラメーター

名前	タイプ	説明
timeoutId	番号	クリアするスケジュール済み機能の一意の識別子。この値は、対応する 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. パラメーター

名前	タイプ	説明
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(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, 数値遅延)

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

ネイティブの 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(String message, String tokens)

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

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

注:

このメソッドは、promise または async and 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);
}