openFrameAPI - Client

  • Release version: Xanadu
  • Updated August 1, 2024
  • 12 minutes to read

    • The openFrameAPI provides methods that interact with OpenFrame. OpenFrame is an omni-present frame that communication partners can use to integrate their systems into the ServiceNow platform.

    One of the core requirements is the ability to connect and serve code from different domains that can connect seamlessly with partner subsystems. This cross domain connection is required to keep connections and callbacks registered into communication systems without any cross domain issues.

    OpenFrame has two significant parts: one that lives in the ServiceNow application (referred to as TopFrame) and this API that is sourced from the partner application. This API has the necessary methods to communicate with TopFrame and control the visual features of the OpenFrame.
    Note:
    To stay current with reference to the OpenFrame library, use the following resource URI: https://[servicenow instance]/scripts/openframe/latest/openFrameAPI.min.js.

    openFrameAPI - getAWAAgentPresence(String success, String failure)

    Returns the logged in agent’s current presence state.

    Table 1. Parameters
    Name Type Description
    success String If the method is successful, name of the callback function to invoke.
    failure String If the method fails, name of the callback function to invoke.
    Table 2. Returns
    Type Description
    presence Results passed to the success callback function by the openFrame infrastructure.

    Data type: Object

    "presence": {  
  "available": Boolean, 
  "channels": [Array],
  "name": "String", 
  "sys_id": "String"
}
    presence.available Flag that indicates whether the associated agent is available.
    Valid values:
    • true: Agent is available.
    • false: Agent isn't available.

    Data type: Boolean
    presence.channels List of available channels of communication with the agent.

    Data type: Array of Objects

    "channels": [
  { 
    "available": Boolean,
    "name": "String",
    "restrict_update": Boolean,
    "service_channel_type": "String",
    "sys_id": "String"
  }
]
    presence.channels.available Flag that indicates whether the channel is available.
    Valid values:
    • true: Channel is available.
    • false: Channel isn't available.

    Data type Boolean
    presence.channels.name Name of the channel, such as Chat or Phone.

    Data type: String
    presence.channels.restrict_update Flag that indicates whether the user can restrict updates to the channel.
    Valid values:
    • true: User can restrict updates to the channel.
    • false: User can't restrict updates to the channel.

    Data type Boolean
    presence.channels.service_channel_type Type of the service channel.

    Data type: String
    presence.channels.sys_id Sys_id of the channel record. Located in the Service Channels [awa_service_channel] table.

    Data type: String
    presence.name Name of the agent's presence state.

    Data type: String
    presence.sys_id Sys_id of the presence state record. Located in the Presence States [awa_presence_state] table.

    Data type: String

    The following code exapmle shows how to call this method.

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

    Response to success callback function:

    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()

    Hides the OpenFrame in the TopFrame.

    Table 3. Parameters
    Name Type Description
    None
    Table 4. Returns
    Type Description
    void 
    openFrameAPI.hide()

    openFrameAPI - init(Object config, function successCallback, function failureCallback)

    Initializes OpenFrame. This must be the first method that you call.

    This method initializes communication to TopFrame and initializes any visual elements passed in the config parameter.

    Table 5. Parameters
    Name Type Description
    config Object Name-value pairs to use during the initialization process.
    Possible keys:
    • height
    • subTitle
    • title
    • titleIcon
    • width
    All keys are optional. Pass an empty object if you don't want to set these key-value pairs.
    successCallback function Name of the callback function to use if the init method succeeds. The OpenFrame configuration stored in the system is passed as a parameter to the callback function.
    failureCallback function Name of the callback function to use if the init method fails.
    Table 6. Returns
    Type Description
    void 
    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(function callback)

    Checks to see if the OpenFrame is visible in the TopFrame.

    Table 7. Parameters
    Name Type Description
    callback function The callback function receives a parameter with a value of true or false. True if OpenFrame is visible and false if not visible.
    Table 8. Returns
    Type Description
    void 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(String details)

    Opens a custom URL in the UI16 interface.

    Table 9. Parameters
    Name Type Description
    Url String Text of the custom URL.

    Maximum size: 2083 characters
    Table 10. Returns
    Type Description
    void 
    openFrameAPI.openCustomURL('10_cool_things.do');

    openFrameAPI - openServiceNowForm(Object details)

    Opens a form URL.

    When an agent receives an incoming call, the OpenFrame window displays information such as the account, contact, or consumer. Clicking a link in the OpenFrame window displays the corresponding record.
    • In the platform interface, this API opens a form URL in TopFrame.
    • For Agent Workspace, this API supports interaction tab management. In Agent Workspace, an interaction record opens in a parent tab and the specified entity record opens in a child tab under the interaction tab.
    Table 11. Parameters
    Name Type Description
    details Object Key-value pairs that identify the form URL to open. 
    "details": {
  "entity": "String";
  "interaction_sys_id": "String";
  "query": "String"
}
    details.entity String Table or entity name.
    details.interaction_sys_id String Optional. Sys_id of the interaction record to open as parent tab in Agent Workspace.
    Note:
    In the platform interface the interaction_sys_id is ignored.
    details.query String Query to identify the record to open, such as: query:'sys_id=<record_sys_id>'.
    Table 12. Returns
    Type Description
    void

    The following example shows basic usage in platform:

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

    The following example shows how to use the query parameter to create a new record with data provided in the form by using sysparm_query and an encoded query to populate the first and last name fields in Workspace:

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

    openFrameAPI - openServiceNowFormwithChildTab()

    Opens a ServiceNow form with a child tab if invoked in a workspace or opens an entity if invoked in the UI16 interface.

    Table 13. Parameters
    Name Type Description
    openServiceNowFormwithChildTab Object Defines if the API opens a ServiceNow form with a child tab if invoked in a workspace or opens an entity if invoked in the UI16 interface.
    openFrameAPI.openServiceNowFormwithChildTab({
  entity: "String",
  sys_id: String", 	
  parent_entity: "String",	
  parent_entity_sys_id: "String"
})
    openServiceNowFormwithChildTab.entity String Name of the table that contains the record to open.
    openServiceNowFormwithChildTab.sys_id String Sys_id of the record to open.
    openServiceNowFormwithChildTab.parent_entity String Name of the table to open as a parent tab.
    openServiceNowFormwithChildTab.parent_entity_sys_id String Sys_id of the parent record to open.
    Table 14. Returns
    Type Description
    None

    The following example opens the parent entity as a parent tab on a configured workspace, or opens just the entity if invoked in UI16.

    openFrameAPI.openServiceNowFormwithChildTab({
  entity: "customer_account", 
  sys_id: "447832786f0331003b3c498f5d3ee452", 	
  parent_entity: "interaction", 
  parent_entity_sys_id: "3be092313b711300758ce9b534efc4dd"
});

    openFrameAPI - openServiceNowList(Object details)

    Opens a list URL in the UI16 interface.

    Table 15. Parameters
    Name Type Description
    details Object Key value pairs that describe the content to use when opening the list URL.

    Valid values:
    Table 16. Returns
    Type Description
    void 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

    Sets the OpenFrame mode.

    The mode passed in this API:
    • Sets the appropriate icon in the header: collapse or expand
    • Raises the relevant event for CTI:
      • openFrameAPI.EVENTS.COLLAPSE
      • openFrameAPI.EVENTS.EXPAND
    Table 17. Parameters
    Name Type Description
    Mode String Set OpenFrame Mode. Enumerated options:
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    Table 18. Returns
    Type Description
    void 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    Sets the OpenFrame height.

    Table 19. Parameters
    Name Type Description
    Height Number Height in pixels
    Table 20. Returns
    Type Description
    void 
    openFrameAPI.setHeight(100);

    openFrameAPI - setIcons(Array icons)

    Defines icons in the OpenFrame header that are placed next to the close icon.

    Table 21. Parameters
    Name Type Description
    icons Array of objects A list of icon configurations, where each icon configuration is an object with key values imageURL, imageTitle, and any other needed context.

    Maximum size: Icons can be a maximum of 16x16 pixels. Larger images are automatically adjusted to this maximum.
    Table 22. Returns
    Type Description
    void 
    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)

    Sets the presence indicator to display agent availability in a workspace.

    For more information on configuring OpenFrame, refer to Create an OpenFrame configuration

    Table 23. Parameters
    Name Type Description
    state String Presence state of the agent.

    Default states:

    • Available
    • Away
    • Offline

    You can also specify custom states.
    color String Presence indicator color on workspace.

    Supported colors:

    • red
    • orange
    • grey
    • green
    Table 24. Returns
    Type Description
    void 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI - setSize(Number width, Number height)

    Sets the OpenFrame size.

    Table 25. Parameters
    Name Type Description
    width Number Should be greater than zero.
    height Number Should be greater than zero.
    Table 26. Returns
    Type Description
    void 
    openFrameAPI.setSize(300, 370);

    openFrameAPI - setSubtitle(String subTitle)

    Sets the OpenFrame subtitle.

    Table 27. Parameters
    Name Type Description
    subTitle String A string of 256 or fewer characters.
    Table 28. Returns
    Type Description
    void 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI - setTitle(String title)

    Sets the OpenFrame title.

    Table 29. Parameters
    Name Type Description
    title String A string of 256 or fewer characters.
    Table 30. Returns
    Type Description
    void 
    openFrameAPI.setTitle('Incoming Call');

    openFrameAPI - setTitleIcon(Object icon)

    Sets the OpenFrame's title icon.

    Table 31. Parameters
    Name Type Description
    icon Object Object of key value pairs. Keys include imageURL, imageTitle, and any other context needed.

    Maximum size: Icons can be a maximum of 16x16 pixels. Larger images are automatically adjusted to this maximum.
    Table 32. Returns
    Type Description
    void 
    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)

    Sets the OpenFrame width.

    Table 33. Parameters
    Name Type Description
    Width Number Width in pixels
    Table 34. Returns
    Type Description
    void 
    openFrameAPI.setWidth(100);

    openFrameAPI - show()

    Makes the OpenFrame visible in the TopFrame.

    Table 35. Parameters
    Name Type Description
    None
    Table 36. Returns
    Type Description
    void 
    openFrameAPI.show()

    openFrameAPI - subscribe(openFrameAPIEVENT event, function eventCallback)

    Subscribes to a specified event.

    Table 37. Parameters
    Name Type Description
    event openFrameAPIEVENT The event to subscribe to:
    • openframe_agent_off_interaction: Indicates the presence of an agent on chat as off or available.
    • openframe_awa_agent_presence: In Advanced Work Assignment (AWA), this event occurs when there's any change in the agent presence state. Computer Telephony Integration (CTI) developers can subscribe to this event to receive presence state changes.
    • openframe_awa_workitem_accepted: Occurs when a work item is accepted by an agent.
    • openframe_awa_workitem_offered: Occurs when a work item is offered to an agent.
    • openframe_awa_workitem_rejected: Occurs when a work item is rejected by an agent.
    • openframe_before_destroy: Occurs before the TopFrame is unloaded.
    • openframe_collapse: Occurs when the collapse icon is selected on the OpenFrame header.
    • openframe_communication: Application-specific and can be customized.
    • openframe_communication_failure: Occurs when communication to TopFrame fails.
    • openframe_expand: Occurs when the expand icon is selected on the OpenFrame header.
    • openframe_header_icon_clicked: Deprecated. Use openframe_icon_clicked or openframe_title_icon_clicked instead.
    • openframe_hidden: Occurs when the OpenFrame is hidden.
    • openframe_icon_clicked: Occurs when any icon other than the close icon is selected on the OpenFrame footer. The callback receives the icon object as a parameter.
    • openframe_shown: Occurs when the OpenFrame is shown.
    • openframe_title_icon_clicked: Occurs when the title icon is selected on the OpenFrame. The callback receives the titleIcon object as a parameter.
    eventCallback function Function to call when the specified event occurs.
    Table 38. Returns
    Type Description
    results Most event subscriptions have no return values. The event subscriptions that do return values are described in the following table entries.
    openframe_awa_agent_presence In AWA, the openframe_awa_agent_presence event returns the presence object:
    "presence":{
  "available": Boolean,
  "channels":[
    {
      "available": Boolean,
      "name": "String",
      "restrict_update": Boolean,
      "sys_id": "String"
    }
  ],
  "name": "String",
  "sys_id": "String"
}
    presence: Information about an agent's current presence state and channel.
    • presence.available: Flag that indicates whether the agent is available.
    • presence.channels: List of objects that describe the available channels of communication with the agent.
      • presence.channels.available: Flag that indicates whether the channel is available.
      • presence.channels.name: Channel name, such as Chat or Phone.
      • presence.channels.restrict_update: Flag that indicates whether the user can restrict updates.
      • presence.channels.sys_id: Channel sys_id.
    • presence.name: Name of the agent's presence state.
    • presence.sys_id: Presence state sys_id.
    openframe_awa_workitem_accepted and openframe_awa_workitem_offered In AWA, the openframe_awa_workitem_accepted and openframe_awa_workitem_offered events return the workItem object:
    "workItem": {
  "document": {
    "sys_id": "String",
    "table": "String"
  },
  "isAutoAccepted": Boolean,
  "isQueueTransferred": Boolean,
  "previousWorkItem": "String",
  "serviceChannel": {
    "name": "String",
    "sys_id": "String"
  },
  "size": Number,
  "sys_id": "String"
}

    workItem: Information about the work item that is associated with the event.

    • workItem.document: List of documents associated with the work item task.
      • workItem.document.sys_id: Sys_id of the document assigned to the work item task.
      • workItem.document.table: Name of the document table assigned to the task.
    • workItem.isAutoAccepted: Flag that indicates whether the work item was automatically accepted by the system. Set to true if the work item was auto-accepted.
    • workItem.isQueueTransferred: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't. For more information on queue transfers, see Transfer a chat to another queue.
    • workItem.previousWorkItem: Sys_id of the previous work item for the same document ID. For the non-transfer work items this value is empty.
    • workItem.serviceChannel: List of service channels associated with the work item task.
      • workItem.serviceChannel.name: Name of the service channel, such as Chat or Phone.
      • workItem.serviceChannel.sys_id: Sys_id of the service channel.
    • workItem.size: Agent's capacity used when this work item is assigned to the agent.
    • workItem.sys_id: Sys_id of the work item that was accepted or offered.
    openframe_awa_workitem_rejected In AWA, the openframe_awa_workitem_rejected event returns the workItem object:
    "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: Information about the work item that is associated with the event.

    • workItem.document: List of documents associated with the work item task.
      • workItem.document.sys_id: Sys_id of the document assigned to the work item task.
      • workItem.document.table: Name of the document table assigned to the task.
    • workItem.isQueueTransferred: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't. For more information on queue transfers, see Transfer a chat to another queue.
    • workItem.previousWorkItem: Sys_id of the previous work item for the same document ID. For the non-transfer work items this value is empty.
    • workItem.rejection: List of reasons for the rejection of the work item.
      • workItem.rejection.reason: Name of the reason for rejecting the work items.
      • workItem.rejection.sys_id: Sys_id of the rejection reason.

        Table: Reject Reasons [awa_reject_reason]

    • workItem.serviceChannel: List of service channels associated with the work item task.
      • workItem.serviceChannel.name: Name of the service channel, such as Chat or Phone.
      • workItem.serviceChannel.sys_id: Sys_id of the service channel.
    • workItem.size: Agent's capacity used when this work item is assigned to the agent.
    • workItem.sys_id: Sys_id of the work item that was accepted or offered.

    The following code example shows how to call this method for an openframe_awa_agent_presence event.

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

    Output:

    // 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
        }
      ]
    }
  }
}

    The following code example shows how to call this method for an openframe_awa_workitem_accepted event.

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

    Output:

    // 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,
      "isAutoAccepted": true
    }
  }
}

    The following code example shows how to call this method for an openframe_awa_workitem_rejected event.

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

    Output:

    // 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()

    Returns the OpenFrame API version.

    Table 39. Parameters
    Name Type Description
    None
    Table 40. Returns
    Type Description
    String The OpenFrame API version 
    var version = openFrameAPI.version();

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