spUtil - クライアント

Zurich API リファレンス

Release

zurich

ft:locale

ja-JP

ft:publication_title

Zurich API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

spUtil - クライアント

リリースバージョン: Zurich

更新日 2025年07月31日

所要時間：12分

spUtil API は、サービスポータルウィジェットクライアントスクリプトで一般的な機能を実行するためのユーティリティメソッドを提供します。

これらの機能は次のとおりです。

通知エラーメッセージを表示します。 spUtil - addErrorMessage(文字列 message)
通知情報メッセージを表示します。 spUtil - addInfoMessage(文字列 message)
簡単な通知メッセージを表示します。 spUtil - addTrivialMessage(文字列 message)
一意の識別子を作成します。 spUtil - createUid()
変数を使用して文字列をフォーマットします。 spUtil - format(文字列 template, オブジェクト data)
ウィジェットクライアントスクリプトにウィジェットモデルを埋め込みます。 spUtil - get(文字列 widgetId オブジェクト data)
API 呼び出しに使用するすべてのヘッダーを取得します。 spUtil - getHeaders()
完全なホストドメインを返します。 spUtil - getHost()
設定名を渡して、ユーザー設定応答でコールバックを実行します。 spUtil - getPreference(文字列 preference, 関数 callback)
現在のサービスポータル URL 情報を返します。 spUtil - getURL()
現在のクライアントがモバイルデバイスであるかどうかを確認します。 spUtil - isMobile()
指定された文字列内のカンマ区切りの属性を解析します。 spUtil - parseAttributes(文字列 attributes)
テーブルまたはフィルターの更新を監視し、コールバック関数から値を返します。 spUtil - recordWatch(オブジェクト $scope, 文字列 table, 文字列 filter, 関数 callback)
サーバーを呼び出し、現在のオプションとデータをサーバーの応答に置き換えます。 spUtil - refresh(オブジェクト $scope)
指定した期間にわたって、指定したセレクターを持つ要素にスクロールします。 spUtil - scrollTo(文字列 selector, 数字 time)
ヘッダーのブレッドクラムを更新します。 spUtil - setBreadCrumb(オブジェクト$scope、アレイブレッドクラム)
ユーザー初期設定を設定します。 spUtil - setPreference(文字列設定, 文字列値)
検索ページを更新します。 spUtil - setSearchPage(文字列 searchPage)
指定されたスコープ内のサーバー上のデータオブジェクトを更新します。 spUtil - update(オブジェクト $scope)

ウィジェットの詳細については、「サービスポータルウィジェット」を参照してください。

spUtil - addErrorMessage(文字列 message)

通知エラーメッセージを表示します。

表 : 1. パラメーター
名前	タイプ	説明
message	文字列	表示するエラーメッセージ。

表 : 2. 返される内容
タイプ	説明
なし

spUtil.addErrorMessage("There has been an error processing your request")

spUtil - addInfoMessage(文字列 message)

通知情報メッセージを表示します。

表 : 3. パラメーター
名前	タイプ	説明
message	文字列	表示するメッセージ。

表 : 4. 返される内容
タイプ	説明
なし

spUtil.addInfoMessage("Your order has been placed")

spUtil - addTrivialMessage(文字列 message)

些細な通知メッセージを表示します。

些細なメッセージはしばらくすると消えます。

表 : 5. パラメーター
名前	タイプ	説明
message	文字列	表示するメッセージ。

表 : 6. 返される内容
タイプ	説明
なし

spUtil.addTrivialMessage("Thanks for your order")

spUtil - createUid()

一意の識別子を作成します。

表 : 7. パラメーター
名前	タイプ	説明
なし

表 : 8. 返される内容
タイプ	説明
文字列	一意の 32 文字の ID。

spUtil - get(文字列 widgetId オブジェクト data)

ウィジェットクライアントスクリプトにウィジェットモデルを埋め込みます。

コールバック関数が完全なウィジェットモデルを返します。ウィジェットの詳細については、「サービスポータルウィジェット」を参照してください。

表 : 9. パラメーター
名前	タイプ	説明
widgetId	文字列	埋め込むウィジェットのウィジェット ID または sys_id。
data	オブジェクト	オプション。ウィジェットモデルに渡すパラメーターの名前/値のペア。

表 : 10. 戻り値
タイプ	説明
オブジェクト	埋め込みウィジェットのモデル。

データが渡されませんでした。

spUtil.get("widget-cool-clock").then(function(response) {
  c.coolClock = response;
});

データが渡されました。

spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
  table: 'resource_allocation', 
  queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
  view: 'resource_portal_allocations' }).then(function(response) {
    var formModal = response;
    c.allocationListModal = response;
  });

spUtil - getHeaders()

API 呼び出しに使用するすべてのヘッダーを取得します。

表 : 11. パラメーター
名前	タイプ	説明
なし

表 : 12. 返される内容
タイプ	説明
オブジェクト	API 呼び出しに使用するすべてのヘッダー。

spUtil - getHost()

完全なホストドメインを返します。

表 : 13. パラメーター
名前	タイプ	説明
なし

表 : 14. 返される内容
タイプ	説明
文字列	完全なホストのドメイン (例：`hi.servicenow.com`)

spUtil - getPreference(文字列 preference, 関数 callback)

設定名を渡して、ユーザー設定応答でコールバックを実行します。

表 : 15. パラメーター
名前	タイプ	説明
preference	文字列	初期設定の名前。
コールバック	関数	コールバック関数を定義します。

表 : 16. 返される内容
タイプ	説明
なし

spUtil - getURL()

現在のサービスポータル URL 情報を返します。

表 : 17. パラメーター
名前	タイプ	説明
なし

表 : 18. 返される内容
タイプ	説明
文字列	現在のサービスポータル URL。

spUtil - format(文字列 template, オブジェクト data)

変数を含む文字列をフォーマットします。

このメソッドは、文字列連結の代わりに使用します。

表 : 19. パラメーター
名前	タイプ	説明
template	文字列	変数代替の値を含む文字列テンプレート。
データ	オブジェクト	テンプレート文字列で定義された変数の値を含むオブジェクト。

表 : 20. 戻り値
タイプ	説明
文字列	変数の命名法の代わりに変数値を含む文字列。

spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

出力:

'An error occurred: 404 when loading sp-widget'

spUtil - isMobile()

現在のクライアントがモバイルデバイスかどうかを確認します。

表 : 21. パラメーター
名前	タイプ	説明
なし

表 : 22. 返される内容
タイプ	説明
ブール	現在のクライアントがモバイルデバイスかどうかを示すフラグ。有効な値： true:現在のクライアントはモバイルデバイスです。 false:現在のクライアントはモバイルデバイスではありません。

spUtil - parseAttributes(文字列 attributes)

指定された文字列内のカンマ区切り属性を解析します。

表 : 23. パラメーター
名前	タイプ	説明
attributes	文字列	辞書レコードの [属性] フィールドなど、カンマ区切りの属性を含む文字列。

表 : 24. 返される内容
タイプ	説明
アレイ	解析済みの属性を含むオブジェクトのアレイ。

function getRefQualElements() {
  var refQualElements = [];
  if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
    var attributes = spUtil.parseAttributes(field.attributes);
    refQualElements = attributes['ref_qual_elements'].split(';');
  }
  return refQualElements;
}

spUtil - recordWatch(オブジェクト $scope, 文字列 table, 文字列 filter, 関数 callback)

テーブルまたはフィルターの更新を監視し、コールバック関数から値を返します。

ウィジェット開発者がリアルタイムでテーブルの更新に応答できるようになります。例えば、recordWatch() を使用すると、簡易リストウィジェットでデータテーブルの変更をリスンできます。レコードが追加、削除、または更新されると、ウィジェットが自動的に更新されます。

注:

$scope 引数を recordWatch() 関数に渡すときに、クライアントスクリプト関数のパラメーターに $scope を挿入します。

表 : 25. パラメーター
名前	タイプ	説明
$scope	オブジェクト	コールバック関数によって更新されたデータオブジェクトのスコープ。
table	文字列	監視対象テーブル。
filter	文字列	監視対象フィールドのフィルター。
callback	関数	オプション。コールバック関数を定義するパラメーター。

表 : 26. 返される内容
タイプ	説明
Promise	コールバック関数の戻り値。

//A simple recordWatch function.
spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

//In a widget client script
function(spUtil, $scope) {
  /* widget controller */
  var c =this;

  // Registers a listener on the incident table with the filter active=true, 
  // meaning that whenever something changes on that table with that filter, 
  // the callback function is executed.    
  // The callback function takes a single parameter 'response', which contains 
  // the property 'data'. The 'data' property contains information about the changed record. 
  spUtil.recordWatch($scope, "incident", "active=true", function(response) {
        
    // Returns the data inserted or updated on the table 
    console.log(response.data);   
    
    });
}

spUtil - refresh(オブジェクト $scope)

サーバーを呼び出し、サーバーの応答から取得された現在のオプションとデータを置き換えます。

spUtil.refresh() の呼び出しは server.refresh() の呼び出しに類似しています。ただし、spUtil.refresh()を呼び出すと、$scope オブジェクトを定義できます。

表 : 27. パラメーター
名前	タイプ	説明
$scope	オブジェクト	更新に対して定義されたスコープ。

表 : 28. 戻り値
タイプ	説明
オブジェクト	更新されたオプションとデータオブジェクト。

spUtil - scrollTo(文字列 selector, 数字 time)

指定された期間にわたって、指定されたセレクターを持つ要素までスクロールします。

表 : 29. パラメーター
名前	タイプ	説明
selector	文字列	スクロール先のセレクター。
時間	番号	指定したセレクターにスクロールするのにかかった時間。単位：ミリ秒

表 : 30. 返される内容
タイプ	説明
なし

spUtil - setBreadCrumb(オブジェクト$scope、アレイブレッドクラム)

ヘッダーのブレッドクラムを更新します。

表 : 31. パラメーター
名前	タイプ	説明
$scope	オブジェクト	テーブルに定義されたスコープ。
ブレッドクラム	アレイ	ブレッドクラムフィルターの作成に使用される条件。

表 : 32. 戻り値
タイプ	説明
なし

spUtil - setPreference(文字列設定, 文字列値)

ユーザー設定を行います。

表 : 33. パラメーター
名前	タイプ	説明
県	文字列	初期設定名
値	文字列	設定値

表 : 34. 戻り値
タイプ	説明
なし

spUtil - setSearchPage(文字列 searchPage)

検索ページを更新します。

表 : 35. パラメーター
名前	タイプ	説明
searchPage	文字列	検索ページの名前。

表 : 36. 戻り値
タイプ	説明
なし

spUtil - update(オブジェクト $scope)

指定されたスコープ内にあるサーバー上のデータオブジェクトを更新します。

このメソッドは server.update() に似ていますが、渡すスコープを定義する $scope パラメーターが含まれています。

表 : 37. パラメーター
名前	タイプ	説明
$scope	オブジェクト	更新に対して定義されたスコープ。

表 : 38. 戻り値
タイプ	説明
オブジェクト	更新されたデータオブジェクト。

次の例には、ステータスフィールドの変更を監視する P1 ウィジェットが含まれています。フィルターを使用してすべてのアクティブな P1 を監視して、データを更新するかどうかの判断をコールバック関数に許可します。data.changes プロパティには更新されたフィールドのアレイが入っています。フィールドのステータスが変更されると、ウィジェット内のデータが更新されます。

var q = "priority=1^active=true^EQ";
spUtil.recordWatch($scope, "incident", q, function(event, data) {
   if (data.changes.includes("state")) { // only update if state was updated.
      spUtil.update($scope);
   }
});