openFrameAPI - クライアント

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む17読むのに数分

    • OpenFrame は、コミュニケーションパートナーがシステムを ServiceNow プラットフォームに統合するために使用できる、非常に一般的なフレームです。

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

    OpenFrame には 2 つの重要な部分があります。その 1 つが ServiceNow アプリケーション内にあるもの (TopFrame という) で、この API はパートナーアプリケーションから供給されます。この API には、TopFrame と通信して OpenFrame のビジュアル機能をコントロールするために必要なメソッドがあります。
    注:
    OpenFrame ライブラリへの参照を最新に保つには、https://[servicenow instance]/scripts/openframe/latest/openFrameAPI.min.js のリソース URI を使用します。

    openFrameAPI - hide()

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

    表 : 1. パラメーター
    名前 タイプ 説明
    なし
    表 : 2. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.hide()

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

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

    このメソッドは、TopFrame への通信を初期化し、設定パラメーターで渡された視覚的要素を初期化します。

    表 : 3. パラメーター
    名前 タイプ 説明
    config オブジェクト キーと値のペアのオブジェクト。可能なキーは、height、width、title、subTitle、および titleIcon です。すべてのキーはオプションです。
    successCallback 関数 init メソッドが成功した場合に使用されるコールバック関数。システムに保存されている OpenFrame 構成が、パラメーターとしてコールバック関数に渡されます。
    failureCallback 関数 init メソッドが失敗した場合に使用されるコールバック関数。
    表 : 4. 返される内容
    タイプ 説明
    なし 
    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 に表示されるかどうかを確認します。

    表 : 5. パラメーター
    名前 タイプ 説明
    callback 関数 true または false の値を持つパラメーターがコールバック関数に返されます。OpenFrame が表示される場合は true、表示されない場合は false です。
    表 : 6. 返される内容
    タイプ 説明
    なし 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(文字列 details)

    TopFrame でカスタム URL を開きます。

    表 : 7. パラメーター
    名前 タイプ 説明
    Url 文字列 2083 文字以下の文字列。
    表 : 8. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.openCustomURL('10_cool_things.do');

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

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

    エージェントが着信コールを受信すると、OpenFrame ウィンドウにアカウント、連絡先、コンシューマーなどの情報が表示されます。OpenFrame ウィンドウのリンクをクリックすると、対応するレコードが表示されます。
    • プラットフォームインターフェイスの場合、この API では TopFrame にフォーム URL が開きます。
    • エージェントワークスペース の場合、この API はインタラクションタブの管理をサポートします。エージェントワークスペース では、インタラクションレコードが親タブに開き、指定されたエンティティレコードがインタラクションタブの下の子タブで開きます。
    表 : 9. パラメーター
    名前 タイプ 説明
    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>'
    表 : 10. 返される内容
    タイプ 説明
    なし

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

    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 インターフェイスで呼び出された場合はエンティティを開きます。

    表 : 11. パラメーター
    名前 タイプ 説明
    開く ServiceNowFormwithChildTab オブジェクト ワークスペースで呼び出された場合、API が子タブを含むフォームを開くか、UI16 インターフェイスで呼び出された場合にエンティティを開く ServiceNow かを定義します。
    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。
    表 : 12. 返される内容
    タイプ 説明
    なし

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

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

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

    TopFrame でリストの URL を開きます。

    表 : 13. パラメーター
    名前 タイプ 説明
    details オブジェクト キーと値のペアのオブジェクト。可能なキーは以下のとおりです。
    • エンティティ、テーブル名
    • クエリー、エンコードされたクエリー文字列
    表 : 14. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

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

    この API で渡されるモードには次のような機能があります。
    • ヘッダーに適切なアイコン (折りたたみまたは展開) を設定する
    • CTI に対して以下の関連イベントを発生させる
      • openFrameAPI.EVENTS.COLLAPSE
      • openFrameAPI.EVENTS.EXPAND
    表 : 15. パラメーター
    名前 タイプ 説明
    モード 文字列 OpenFrame のモードを設定します。オプションは以下のとおりです。
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    表 : 16. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    OpenFrame の高さを設定します。

    表 : 17. パラメーター
    名前 タイプ 説明
    Height 数字 高さ (ピクセル)
    表 : 18. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.setHeight(100);

    openFrameAPI - setIcons(アレイ icons)

    OpenFrame ヘッダーでは、閉じるアイコンの横に配置するアイコンを含めることができます。

    表 : 19. パラメーター
    名前 タイプ 説明
    icons アレイ アイコン構成のリスト。それぞれのアイコン構成が、キー値 imageURL、imageTitle、およびその他の必要なコンテキストを持つオブジェクトになります。
    表 : 20. 返される内容
    タイプ 説明
    なし 
    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 構成の作成」を参照してください

    表 : 21. パラメーター
    名前 タイプ 説明
    state 文字列 エージェントの在席ステータス。

    デフォルトのステータス：

    • 連絡可能
    • 離席中
    • オフライン

    カスタムのステータスも指定できます。
    色 文字列 Workspace のプレゼンスインジケーターの色。

    サポートされている色：

    • 赤
    • オレンジ
    • グレイ
    • 緑
    表 : 22. 返される内容
    タイプ 説明
    なし 
    openframeAPI.setPresenceIndicator('Available', 'green');

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

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

    表 : 23. パラメーター
    名前 タイプ 説明
    width 数字 ゼロより大きくする必要があります。
    height 数字 ゼロより大きくする必要があります。
    表 : 24. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.setSize(300, 370);

    openFrameAPI - setSubtitle(文字列 subTitle)

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

    表 : 25. パラメーター
    名前 タイプ 説明
    subTitle 文字列 256 文字以下の文字列。
    表 : 26. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI - setTitle(文字列 title)

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

    表 : 27. パラメーター
    名前 タイプ 説明
    title 文字列 256 文字以下の文字列。
    表 : 28. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.setTitle('Incoming Call');

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

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

    表 : 29. パラメーター
    名前 タイプ 説明
    icon オブジェクト キーと値のペアのオブジェクト。キーには、imageURL、imageTitle、その他必要なコンテキストなどがあります。
    表 : 30. 返される内容
    タイプ 説明
    なし 
    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 の幅を設定します。

    表 : 31. パラメーター
    名前 タイプ 説明
    Width 数字 幅 (ピクセル)
    表 : 32. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.setWidth(100);

    openFrameAPI - show()

    TopFrame で OpenFrame を表示します。

    表 : 33. パラメーター
    名前 タイプ 説明
    なし
    表 : 34. 返される内容
    タイプ 説明
    なし 
    openFrameAPI.show()

    openFrameAPI - subscribe(openFrameAPIEVENT event, 関数 eventCallback)

    イベントに登録します。

    表 : 35. パラメーター
    名前 タイプ 説明
    イベント 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 関数 指定されたイベントが発生したときに呼び出される関数。
    表 : 36. 返される内容
    タイプ 説明
    特に記載がない限りはなし。 ほとんどのイベントサブスクリプションには戻り値はありませんが、次の例外があります。
    AWA では、openframe_awa_agent_presence イベントが以下のプレゼンスオブジェクトを返します。
    • presence：エージェントの現在の在席状況とチャネルに関する情報。 出力例を下に示します。
    • presence.name：エージェントの在席状況の名前。
    • presents.sys_id：在席状況の sys_id。在席状況 [awa_presence_state] テーブルにあります。
    • presence.available：エージェントが利用可能かどうかを示すフラグ。
    • presence.channels：エージェントとの利用可能な通信チャネルを説明するオブジェクトのリスト。
    • presence.channels.name：チャネル名 (チャットや電話など)。
    • presence.channels.available：チャネルが利用可能かどうかを示すフラグ。
    • presents.channels.sys_id：チャネルの sys_id。サービスチャネル [awa_service_channel] テーブルにあります。
    • presents.channels.restrict_update：ユーザーが更新を制限できるかどうかを示すフラグ。

    例

    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":"<SysID>",
         "available":true,
         "channels":[
            {
               "name":"Chat",
               "available":true,
               "sys_id":"<SysID>",
               "restrict_update":false
            },
            {
               "name":"Phone",
               "available":true,
               "sys_id":"<SysID>",
               "restrict_update":false
            }
         ]
      }
   }
}

    openFrameAPI - version()

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

    表 : 37. パラメーター
    名前 タイプ 説明
    なし
    表 : 38. 返される内容
    タイプ 説明
    文字列 OpenFrame API のバージョン 
    var version = openFrameAPI.version();

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