openFrameAPI - クライアント

Xanadu API リファレンス

Release

xanadu

ft:locale

ja-JP

ft:publication_title

Xanadu API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

openFrameAPI - クライアント

リリースバージョン: Xanadu

更新日 2024年08月01日

所要時間：28分

openFrameAPI は、OpenFrame とやり取りするメソッドを提供します。OpenFrame は、コミュニケーションパートナーがシステムを ServiceNow プラットフォームに統合するために使用できる、非常に一般的なフレームです。

コア要件の 1 つが、パートナーサブシステムとシームレスに接続できるさまざまなドメインから取得したコードをつないで提供する機能です。このクロスドメイン接続は、クロスドメインの問題を発生させることなく接続とコールバックを通信システムに登録するために必要です。

OpenFrame には 2 つの重要な部分があります。その 1 つが ServiceNow アプリケーション内にあるもの (TopFrame という) で、この API はパートナーアプリケーションから供給されます。この API には、TopFrame と通信して OpenFrame のビジュアル機能をコントロールするために必要なメソッドがあります。

注:

OpenFrame ライブラリへの参照を最新に保つには、https://[servicenow instance]/scripts/openframe/latest/openFrameAPI.min.js のリソース URI を使用します。

openFrameAPI - getAWAAgentPresence(文字列 success, 文字列 failure)

ログインしているエージェントの現在の在席状況を返します。

表 : 1. パラメーター
名前	タイプ	説明
正常終了	文字列	メソッドが成功した場合、呼び出すコールバック関数の名前。
失敗	文字列	メソッドが失敗した場合に呼び出すコールバック関数の名前。

表 : 2. 返される内容
タイプ	説明
presence	OpenFrame インフラストラクチャによって成功コールバック関数に渡される結果。データタイプ: オブジェクト `"presence": { "available": Boolean, "channels": [Array], "name": "String", "sys_id": "String" }`
presence.available	関連付けられたエージェントが利用可能かどうかを示すフラグ。有効な値： true：エージェントは利用可能です。 false:エージェントは利用できません。データタイプ：ブーリアン
presence.channels	エージェントとの利用可能なコミュニケーションチャネルのリスト。データタイプ：オブジェクトのアレイ `"channels": [ { "available": Boolean, "name": "String", "restrict_update": Boolean, "service_channel_type": "String", "sys_id": "String" } ]`
presence.channels.available	チャネルが利用可能かどうかを示すフラグ。有効な値： true：チャネルは利用可能です。 false:チャネルは利用できません。データタイプ:ブーリアン
presence.channels.name	チャットや電話などのチャネルの名前。データタイプ：文字列
presence.channels.restrict_update	ユーザーがチャネルの更新を制限できるかどうかを示すフラグ。有効な値： true:ユーザーはチャネルの更新を制限できます。 false:ユーザーはチャネルの更新を制限できません。データタイプ:ブーリアン
presence.channels.service_channel_type	サービスチャネルのタイプ。データタイプ：文字列
presence.channels.sys_id	チャネルレコードのSys_id。サービスチャネル [awa_service_channel] テーブルにあります。データタイプ：文字列
presence.name	エージェントの在席状況の名前。データタイプ：文字列
presents.sys_id	在席状況レコードのSys_id。在席状況 [awa_presence_state] テーブルにあります。データタイプ：文字列

次のコード例は、このメソッドを呼び出す方法を示しています。

function failure(data)
{
  console.log("failure: " + JSON.stringify(data));
}
 
function success(data)
{
  console.log("success: " + JSON.stringify(data));
}
 
openFrameAPI.getAWAAgentPresence(success, failure)

成功コールバック関数への応答:

success: { 
  "presence": { 
    "name": "Available", 
    "sys_id": "0b10223c57a313005baaaa65ef94f970", 
    "available": true, 
    "channels": [ 
      { 
        "name": "Chat", 
        "available": true, 
        "sys_id": "27f675e3739713004a905ee515f6a7c3", 
        "restrict_update": false, 
        "service_channel_type": "chat" 
      } 
    ] 
  } 
}

openFrameAPI - hide()

TopFrame で OpenFrame を非表示にします。

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

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

openFrameAPI.hide()

openFrameAPI - init(オブジェクト config, 関数 successCallback, 関数 failureCallback)

OpenFrame を初期化します。これは、呼び出す最初のメソッドである必要があります。

このメソッドは、TopFrame への通信を初期化し、 config パラメーターで渡されたすべてのビジュアル要素を初期化します。

表 : 5. パラメーター
名前	タイプ	説明
config	オブジェクト	初期化プロセス中に使用する名前と値のペア。可能なキー: 高さ subTitle タイトルタイトルアイコン幅すべてのキーはオプションです。これらのキーと値のペアを設定しない場合は、空のオブジェクトを渡します。
successCallback	関数	init メソッドが成功した場合に使用するコールバック関数の名前。システムに保存されている OpenFrame 構成は、パラメーターとしてコールバック関数に渡されます。
failureCallback	関数	init メソッドが失敗した場合に使用するコールバック関数の名前。

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

var config = {
height: 300,
width: 200
}
function handleCommunicationEvent(context) {
console.log("Communication from Topframe", context);
}
function initSuccess(snConfig) {
console.log("openframe configuration", snConfig);
//register for communication event from TopFrame
openFrameAPI.subscribe(openFrameAPI.EVENTS.COMMUNICATION_EVENT,
handleCommunicationEvent);
}
function initFailure(error) {
console.log("OpenFrame init failed...", error);
}
openFrameAPI.init(config, initSuccess, initFailure);

openFrameAPI - isVisible(関数 callback)

OpenFrame が TopFrame に表示されるかどうかを確認します。

表 : 7. パラメーター
名前	タイプ	説明
callback	関数	true または false の値を持つパラメーターがコールバック関数に返されます。OpenFrame が表示される場合は true、表示されない場合は false です。

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

function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

openFrameAPI - openCustomURL(文字列 details)

UI16 インターフェイスでカスタム URL を開きます。

表 : 9. パラメーター
名前	タイプ	説明
Url	文字列	カスタム URL のテキスト。最大サイズ:2083 文字

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

openFrameAPI.openCustomURL('10_cool_things.do');

openFrameAPI - openServiceNowForm(オブジェクト details)

フォームの URL を開きます。

エージェントが着信コールを受信すると、OpenFrame ウィンドウにアカウント、連絡先、コンシューマーなどの情報が表示されます。OpenFrame ウィンドウのリンクをクリックすると、対応するレコードが表示されます。

プラットフォームインターフェイスの場合、この API では TopFrame にフォーム URL が開きます。
エージェントワークスペースの場合、この API はインタラクションタブの管理をサポートします。エージェントワークスペースでは、インタラクションレコードが親タブに開き、指定されたエンティティレコードがインタラクションタブの下の子タブで開きます。

表 : 11. パラメーター
名前	タイプ	説明
details	オブジェクト	開くフォームの URL を特定するキーと値のペア。 `"details": { "entity": "String"; "interaction_sys_id": "String"; "query": "String" }`
details.entity	文字列	テーブルまたはエンティティの名前。
details.interaction_sys_id	文字列	オプション。エージェントワークスペースで親タブとして開くインタラクションレコードの sys_id。注: プラットフォームインターフェイスでは、interaction_sys_id は無視されます。
details.query	文字列	開くレコードを特定するクエリー。例：`query:'sys_id=<record_sys_id>'`

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

次の例は、プラットフォームでの基本的な使い方を示しています。

openFrameAPI.openServiceNowForm({entity:'customer_account', 
query:'sys_id=447832786f0331003b3c498f5d3ee452', 'interaction_sys_id':'3be092313b711300758ce9b534efc4dd'});

次の例は、query パラメーターを使用して、フォームで提供されたデータを使って sysparm_query とエンコードされたクエリーで新しいレコードを作成し、Workspace の姓と名のフィールドに入力する方法を示しています。

openFrameAPI.openServiceNowForm({ entity: 'sys_user',
query: 'sys_id=-1&sysparm_query=first_name=Ivan^last_name=Greggor' });

openFrameAPI:openServiceNowFormwithChildTabIf()

ワークスペースで呼び出された場合は子タブを含む ServiceNow フォームを開き、UI16 インターフェイスで呼び出された場合はエンティティを開きます。

表 : 13. パラメーター
名前	タイプ	説明
OpenServiceNowFormwithChildTab	オブジェクト	ワークスペースで呼び出された場合に API が子タブを含む ServiceNow フォームを開くか、UI16 インターフェイスで呼び出された場合にエンティティを開くかを定義します。 `openFrameAPI.openServiceNowFormwithChildTablf({ entity: “String”, sys_id: “String”, parent_entity: “String”, parent_entity_sys_id: “String”,`
openServiceNowFormwithChildTab.entity	文字列	テーブルの名前です。
openServiceNowFormwithChildTab.sys_id	文字列	開くレコードの sys_id。
openServiceNowFormwithChildTab.parent_entity	文字列	親タブとして開くテーブルの名前。
openServiceNowFormwithChildTab.parent_entity_sys_id	文字列	開く親レコードのSys_id。

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

次の例では、構成されたワークスペースで親エンティティを親タブとして開くか、UI16 で呼び出された場合はエンティティのみを開きます。

openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “customer_account”, 
	sys_id: “447832786f0331003b3c498f5d3ee452”, 	
	parent_entity: “interaction”, 
	parent_entity_sys_id: “3be092313b711300758ce9b534efc4dd”
});

openFrameAPI - openServiceNowList(オブジェクト details)

UI16 インターフェイスでリスト URL を開きます。

表 : 15. パラメーター
名前	タイプ	説明
details	オブジェクト	リスト URL を開くときに使用するコンテンツを説明するキーと値のペア。有効な値： entity:テーブル名 query: エンコードされたクエリ文字列

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

openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

openFrameAPI - setFrameMode(mode)

OpenFrame のモードを設定します。

この API で渡されるモードには次のような機能があります。

ヘッダーに適切なアイコン (折りたたみまたは展開) を設定する
CTI に対して以下の関連イベントを発生させる
- openFrameAPI.EVENTS.COLLAPSE
- openFrameAPI.EVENTS.EXPAND

表 : 17. パラメーター
名前	タイプ	説明
モード	文字列	OpenFrame のモードを設定します。オプションは以下のとおりです。 openFrameAPI.FRAME_MODE.COLLAPSE openFrameAPI.FRAME_MODE.EXPAND

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

openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

openFrameAPI - setHeight(height)

OpenFrame の高さを設定します。

表 : 19. パラメーター
名前	タイプ	説明
Height	数字	高さ (ピクセル)

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

openFrameAPI.setHeight(100);

openFrameAPI - setIcons(アレイ icons)

閉じるアイコンの横に配置される OpenFrame ヘッダーのアイコンを定義します。

表 : 21. パラメーター
名前	タイプ	説明
アイコン	オブジェクトのアレイ	アイコン構成のリスト。各アイコン構成は、キー値 imageURL、 imageTitle、およびその他の必要なコンテキストを持つオブジェクトです。最大サイズ:アイコンのサイズは最大 16 x 16 ピクセルです。大きな画像は、この最大値に自動的に調整されます。

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

openFrameAPI.setIcons([{imageURL:'https://mydomian.com/image/mute.png',
imageTitle:'mute', id:101}, {imageURL:'https://mydomian.com/image/hold.png',
imageTitle:'hold', id:102}]);

openFrameAPI - setPresenceIndicator(presence)

エージェントの空き状況を表示するプレゼンスインジケーターを Workspace に設定します。

OpenFrame の構成の詳細については、「OpenFrame 構成の作成」を参照してください

表 : 23. パラメーター
名前	タイプ	説明
state	文字列	エージェントの在席ステータス。デフォルトのステータス：連絡可能離席中オフラインカスタムのステータスも指定できます。
色	文字列	Workspace のプレゼンスインジケーターの色。サポートされている色：赤オレンジグレイ緑

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

openframeAPI.setPresenceIndicator('Available', 'green');

openFrameAPI - setSize(数字 width, 数字 height)

OpenFrame のサイズを設定します。

表 : 25. パラメーター
名前	タイプ	説明
width	数字	ゼロより大きくする必要があります。
height	数字	ゼロより大きくする必要があります。

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

openFrameAPI.setSize(300, 370);

openFrameAPI - setSubtitle(文字列 subTitle)

OpenFrame のサブタイトルを設定します。

表 : 27. パラメーター
名前	タイプ	説明
subTitle	文字列	256 文字以下の文字列。

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

openFrameAPI.setSubtitle('+18888888888');

openFrameAPI - setTitle(文字列 title)

OpenFrame のタイトルを設定します。

表 : 29. パラメーター
名前	タイプ	説明
title	文字列	256 文字以下の文字列。

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

openFrameAPI.setTitle('Incoming Call');

openFrameAPI - setTitleIcon(オブジェクト icon)

OpenFrame のタイトルアイコンを設定します。

表 : 31. パラメーター
名前	タイプ	説明
icon	オブジェクト	キーと値のペアのオブジェクト。キーには、 imageURL、 imageTitle、および必要なその他のコンテキストが含まれます。最大サイズ:アイコンのサイズは最大 16 x 16 ピクセルです。大きな画像は、この最大値に自動的に調整されます。

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

openFrameAPI.setTitleIcon({imageURL:'/my/image/path.png', imageTitle:'mute', id:101});

openFrameAPI.setTitleIcon({imageURL:'https://mydomian.com/image/path.png',
imageTitle:'mute', id:101});

openFrameAPI - setwidth(width)

OpenFrame の幅を設定します。

表 : 33. パラメーター
名前	タイプ	説明
Width	数字	幅 (ピクセル)

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

openFrameAPI.setWidth(100);

openFrameAPI - show()

TopFrame で OpenFrame を表示します。

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

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

openFrameAPI.show()

openFrameAPI - subscribe(openFrameAPIEVENT event, 関数 eventCallback)

指定されたイベントに登録します。

表 : 37. パラメーター
名前	タイプ	説明
イベント	openFrameAPIEVENT	登録するイベント: openframe_agent_off_interaction：チャット中のエージェントの在席状況をオフまたは対応可能として示します。 openframe_awa_agent_presence: 高度な作業アサイン (AWA) では、エージェントの在席状況が変更されると、このイベントが発生します。コンピューター電話統合 (CTI) の開発者は、このイベントに登録して、在席状況の変更を受け取ることができます。 openframe_awa_workitem_accepted：作業アイテムがエージェントによって承認されると発生します。 openframe_awa_workitem_offered：作業アイテムがエージェントにオファーされると発生します。 openframe_awa_workitem_rejected：作業アイテムがエージェントによって拒否されると発生します。 openframe_before_destroy：TopFrame がアンロードされる前に発生します。 openframe_collapse:OpenFrame ヘッダーで折りたたみアイコンが選択されている場合に発生します。 openframe_communication：アプリケーション固有であり、カスタマイズ可能です。 openframe_communication_failure：TopFrame への通信に失敗すると発生します。 openframe_expand:OpenFrame ヘッダーで展開アイコンが選択されたときに発生します。 openframe_header_icon_clicked：廃止されました。代わりに openframe_icon_clicked または openframe_title_icon_clicked を使用してください。 openframe_hidden：OpenFrame が非表示の場合に発生します。 openframe_icon_clicked:OpenFrame フッターで閉じるアイコン以外のアイコンが選択されたときに発生します。コールバックは、アイコンオブジェクトをパラメーターとして受け取ります。 openframe_shown：OpenFrame が表示されている場合に発生します。 openframe_title_icon_clicked:OpenFrame でタイトルアイコンが選択されたときに発生します。コールバックは titleIcon オブジェクトをパラメーターとして受け取ります。
eventCallback	関数	指定されたイベントが発生したときに呼び出す関数。

表 : 38. 返される内容
タイプ	説明
結果	ほとんどのイベントサブスクリプションには戻り値がありません。値を返すイベントサブスクリプションについては、次の表のエントリで説明されています。
openframe_awa_agent_presence	AWA、openframe_awa_agent_presence イベントは`プレゼンス` オブジェクトを返します。 `"presence":{ "available": Boolean, "channels":[ { "available": Boolean, "name": "String", "restrict_update": Boolean, "sys_id": "String" } ], "name": "String", "sys_id": "String" }` presence：エージェントの現在の在席状況とチャネルに関する情報。 presence.available：エージェントが利用可能かどうかを示すフラグ。 presence.channels：エージェントとの利用可能な通信チャネルを説明するオブジェクトのリスト。 presence.channels.available：チャネルが利用可能かどうかを示すフラグ。 presence.channels.name：チャネル名 (チャットや電話など)。 presence.channels.restrict_update：ユーザーが更新を制限できるかどうかを示すフラグ。 presence.channels.sys_id：チャネルの sys_id。サービスチャネル [awa_service_channel] テーブルにあります。 presence.name：エージェントの在席状況の名前。 presence.sys_id：在席状況の sys_id。在席状況 [awa_presence_state] テーブルにあります。
openframe_awa_workitem_acceptedとopenframe_awa_workitem_offered	AWA、openframe_awa_workitem_accepted イベントと openframe_awa_workitem_offered イベントは `workItem` オブジェクトを返します。 `"workItem": { "document": { "sys_id": "String", "table": "String" }, "isQueueTransferred": Boolean, "previousWorkItem": "String", "serviceChannel": { "name": "String", "sys_id": "String" }, "size": Number, "sys_id": "String" }` workItem:イベントに関連付けられている作業アイテムに関する情報。 workItem.document:作業アイテムタスクに関連付けられたドキュメントのリスト。 workItem.document.sys_id:作業アイテムタスクにアサインされたドキュメントのSys_id。 workItem.document.table:タスクに割り当てられたドキュメントテーブルの名前。 workItem.isQueueTransferred:作業アイテムがキュー転送されているかどうかを示します。作業アイテムがキュー転送される場合は true に設定され、そうでない場合は false に設定されます。キュー転送の詳細については、「 Transfer a chat to another queue」を参照してください。 workItem.previousWorkItem:同じドキュメント ID の以前の作業アイテムのSys_id。非転送作業アイテムの場合、この値は空です。 workItem.serviceChannel:作業アイテムタスクに関連付けられたサービスチャネルのリスト。 workItem.serviceChannel.name:チャットや電話などのサービスチャネルの名前。 workItem.serviceChannel.sys_id:サービスチャネルのSys_id。 workItem.size:この作業アイテムがエージェントにアサインされたときに使用されるエージェントのキャパシティ。 workItem.sys_id:承認または提供された作業アイテムのSys_id。
openframe_awa_workitem_rejected	AWA、openframe_awa_workitem_rejected イベントは `workItem` オブジェクトを返します。 `"workItem": { "document": { "sys_id": "String", "table": "String" }, "isQueueTransferred": Boolean, "previousWorkItem": "String", "rejection": { "reason": "String", "sys_id": "String" }, "serviceChannel": { "name": "String", "sys_id": "String" }, "size": Number, "sys_id": "String" }` workItem:イベントに関連付けられている作業アイテムに関する情報。 workItem.document:作業アイテムタスクに関連付けられたドキュメントのリスト。 workItem.document.sys_id:作業アイテムタスクにアサインされたドキュメントのSys_id。 workItem.document.table:タスクに割り当てられたドキュメントテーブルの名前。 workItem.isQueueTransferred:作業アイテムがキュー転送されているかどうかを示します。作業アイテムがキュー転送される場合は true に設定され、そうでない場合は false に設定されます。キュー転送の詳細については、「 Transfer a chat to another queue」を参照してください。 workItem.previousWorkItem:同じドキュメント ID の以前の作業アイテムのSys_id。非転送作業アイテムの場合、この値は空です。 workItem.rejection:作業アイテムが却下された理由のリスト。 workItem.rejection.reason:作業アイテムを却下する理由の名前。 workItem.rejection.sys_id:却下理由のSys_id。却下理由 [awa_reject_reason] テーブルにあります。 workItem.serviceChannel:作業アイテムタスクに関連付けられたサービスチャネルのリスト。 workItem.serviceChannel.name:チャットや電話などのサービスチャネルの名前。 workItem.serviceChannel.sys_id:サービスチャネルのSys_id。 workItem.size:この作業アイテムがエージェントにアサインされたときに使用されるエージェントのキャパシティ。 workItem.sys_id:承認または提供された作業アイテムのSys_id。

次のコード例は、 openframe_awa_agent_presence イベントに対してこのメソッドを呼び出す方法を示しています。

function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_agent_presence, handleIconClick);

出力:

// Sample presence object output
// openframe_awa_agent_presence event only

{
  "result":{
    "presence":{
      "name":"Available",
      "sys_id":"27f675e3739713004a905ee515f6a7c3",
      "available":true,
      "channels":[
        {
          "name":"Chat",
          "available":true,
          "sys_id":"36f675e4239713124a905fe515f6a832",
          "restrict_update":false
        },
        {
          "name":"Phone",
          "available":true,
          "sys_id":"9378a530a1820610f809018efd9bc01e",
          "restrict_update":false
        }
      ]
    }
  }
}

次のコード例は、 openframe_awa_workitem_accepted イベントに対してこのメソッドを呼び出す方法を示しています。

function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_workitem_accepted, handleIconClick);

出力:

// Sample workItem object output
// openframe_awa_workitem_accepted event only
{
  "result": {
    "workItem": {
      "sys_id": "14c86c40a1650610f87701807d9bc0be",
      "size": 1,
      "serviceChannel": {
        "name": "Chat",
        "sys_id": "27f675e3739713004a905ee515f6a7c3"
      },
      "document": {
        "sys_id": "aa582040a1650610f87701807d9bc076",
        "table": "interaction"
      },
      "previousWorkItem": "7c78a440a1650610f87701807d9bc02b",
      "isQueueTransferred": true
    }
  }
}

次のコード例は、 openframe_awa_workitem_rejected イベントに対してこのメソッドを呼び出す方法を示しています。

function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_workitem_rejected, handleIconClick);

出力:

// Sample workItem object output
// openframe_awa_workitem_rejected event only
{
  "payload": {
    "workItem": {
      "sys_id": "2c3bdc4824250610f8775e73b116f8de",
      "size": "1",
      "serviceChannel": {
        "name": "Chat",
        "sysID": "27f675e3739713004a905ee515f6a7c3"
      },
      "document": {
        "sys_id": "cf0a180824250610f8775e73b116f80c",
        "table": "interaction"
      },
      "rejection": {
        "reason": "Busy",
        "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
      },
      "previousWorkItem": "831b9c4824250610f8775e73b116f841",
      "isQueueTransferred": true
    }
  }
}

openFrameAPI - version()

OpenFrame API のバージョンを返します。

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

表 : 40. 返される内容
タイプ	説明
文字列	OpenFrame API のバージョン

var version = openFrameAPI.version();

console.log("API version " + version);