openFrameAPI - Global

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.

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 - openServiceNowForm(Object details)

Opens a form URL in TopFrame.

Table 7. Parameters
Name Type Description
details Object An object of key value pairs. The possible keys are
  • entity, the table name
  • query, an encoded query string
Table 8. Returns
Type Description
void

openFrameAPI.openServiceNowForm({entity:'incident', query:'sys_id=1234567'});

openFrameAPI - openServiceNowList(Object details)

Opens a list URL in TopFrame.

Table 9. Parameters
Name Type Description
details Object An object of key value pairs. The possible keys are
  • entity, the table name
  • query, an encoded query string
Table 10. Returns
Type Description
void

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

openFrameAPI - setIcons(Array icons)

The OpenFrame header can include icons that are placed next to the close icon.

Table 11. Parameters
Name Type Description
icons Array A list of icon configurations, where each icon configuration is an object with key values imageURL, imageTitle, and any other needed context.
Table 12. 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 - setSize(Number width, Number height)

Sets the OpenFrame size.

Table 13. Parameters
Name Type Description
width Number Should be greater than zero.
height Number Should be greater than zero.
Table 14. Returns
Type Description
void

openFrameAPI.setSize(300, 370);

openFrameAPI - setSubtitle(String subTitle)

sets the OpenFrame subtitle.

Table 15. Parameters
Name Type Description
subTitle String A string of 256 or fewer characters.
Table 16. Returns
Type Description
void

openFrameAPI.setSubtitle('+18888888888');

openFrameAPI - setTitle(String title)

Sets the OpenFrame title.

Table 17. Parameters
Name Type Description
title String A string of 256 or fewer characters.
Table 18. Returns
Type Description
void

openFrameAPI.setTitle('Incoming Call');

openFrameAPI - setTitleIcon(Object icon)

Sets the OpenFrame's title icon.

Table 19. Parameters
Name Type Description
icon Object Object of key value pairs. Keys include imageURL, imageTitle, and any other context needed.
Table 20. 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 - show()

Makes the OpenFrame visible in the TopFrame.

Table 21. Parameters
Name Type Description
None
Table 22. Returns
Type Description
void

openFrameAPI.show()

openFrameAPI - subscribe(openFrameAPIEVENT event, function eventCallback)

Subscribes to the an event.

These events are available.
  • openframe_header_icon_clicked -- this event occurs when any icon other than the close icon is clicked on the OpenFrame header. The callback receives the icon object as a parameter.
  • openframe_shown -- this event occurs when the OpenFrame is shown.
  • openframe_hidden -- this event occurs when the OpenFrame is hidden.
  • openframe_before_destroy -- this event occurs before the TopFrame is unloaded.
  • openframe_communication -- this event is application specific and can be customized.
  • openframe_communication_failure -- this event occurs when communication to TopFrame fails.
Table 23. Parameters
Name Type Description
event openFrameAPIEVENT One of the available events.
eventCallback function The method called when the specified event occurs.
Table 24. Returns
Type Description
void

function handleHeaderIconClick(context) {
console.log("Header Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.EVENTS.HEADER_ICON_CLICKED, handleHeaderIconClick);

openFrameAPI - version()

Returns the OpenFrame API version.

Table 25. Parameters
Name Type Description
None
Table 26. Returns
Type Description
String The OpenFrame API version

var version = openFrameAPI.version();

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