openFrameAPI - Client

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 7 minutes to read

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

    Hides the OpenFrame in the TopFrame.

    Table 1. Parameters
    Name Type Description
    None
    Table 2. Returns
    Type Description
    void 
    openFrameAPI.hide()

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

    Initialize OpenFrame, must be the first method called.

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

    Table 3. Parameters
    Name Type Description
    config Object An object of key value pairs. The possible keys are height, width, title, subTitle, and titleIcon. All keys are optional.
    successCallback function The callback function used if the init method succeeds. The openframe configuration stored in the system is passed as a parameter to the callback function.
    failureCallback function The callback function used if the init method fails.
    Table 4. 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 5. 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 6. 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 7. Parameters
    Name Type Description
    Url String Text of the custom URL.

    Maximum size: 2083 characters
    Table 8. 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 9. 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 10. 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 11. 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 12. 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 13. Parameters
    Name Type Description
    details Object Key value pairs that describe the content to use when opening the list URL.

    Valid values:
    Table 14. 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 15. Parameters
    Name Type Description
    Mode String Set OpenFrame Mode. Enumerated options:
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    Table 16. Returns
    Type Description
    void 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    Sets the OpenFrame height.

    Table 17. Parameters
    Name Type Description
    Height Number Height in pixels
    Table 18. 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 19. 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 20. 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 21. 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 22. Returns
    Type Description
    void 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI - setSize(Number width, Number height)

    Sets the OpenFrame size.

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

    openFrameAPI - setSubtitle(String subTitle)

    Sets the OpenFrame subtitle.

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

    openFrameAPI - setTitle(String title)

    Sets the OpenFrame title.

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

    openFrameAPI - setTitleIcon(Object icon)

    Sets the OpenFrame's title icon.

    Table 29. 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 30. 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 31. Parameters
    Name Type Description
    Width Number Width in pixels
    Table 32. Returns
    Type Description
    void 
    openFrameAPI.setWidth(100);

    openFrameAPI - show()

    Makes the OpenFrame visible in the TopFrame.

    Table 33. Parameters
    Name Type Description
    None
    Table 34. Returns
    Type Description
    void 
    openFrameAPI.show()

    openFrameAPI - subscribe(openFrameAPIEVENT event, function eventCallback)

    Subscribes to the event.

    Table 35. Parameters
    Name Type Description
    event openFrameAPIEVENT One of the following events:
    • 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 is any change in the agent presence state. Computer Telephony Integration (CTI) developers can subscribe to the 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 clicked 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 clicked 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 clicked 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 clicked on the OpenFrame. The callback receives the titleIcon object as a parameter.
    eventCallback function Function called when the specified event occurs.
    Table 36. Returns
    Type Description
    None unless described otherwise. Most event subscriptions have no return values, with the following exception(s):
    In AWA, the openframe_awa_agent_presence event returns the presence object:
    • presence: Information about an agent's current presence state and channel. Output example below.
    • presence.name: Name of the agent's presence state.
    • presence.sys_id: Presence state sys_id. Located in the Presence States [awa_presence_state] table.
    • 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.name: Channel name, such as Chat or Phone.
    • presence.channels.available: Flag that indicates whether the channel is available.
    • presence.channels.sys_id: Channel sys_id. Located in the Service Channels [awa_service_channel] table.
    • presence.channels.restrict_update: Flag that indicates whether the user can restrict updates.
    		 
    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":"<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()

    Returns the OpenFrame API version.

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

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