Embedding and Integrating UI Builder Pages with Employee Center

[Jonas Svensson]

I recently made a post showing off the ability to run events from a custom Playbook Activity to the Employee Center. In this post I will be showing off a more generic way of communicating with an embedded UI Builder page within Employee Center.

Portal widget

First of all, you will need a portal widget that will include your UI Builder page.

HTML

It's using the same type of iframe that the OOB widget-playbook uses. Replace the ng-src with the actual URL of your UI Builder page.

<iframe 
    id="some-id" 
    ng-src="URL_TO_UI_BUILDER_PAGE" 
    sandbox="allow-forms allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-downloads" 
    width="100%"
    height="100%"
    frameBorder="0"
/>

Javascript

This is optional, it allows the UI Builder to communicate with the widgets client script. Which of course can manipulate the HTML or access its server side script.

You can rename the event if needed. Remember to use the same event name inside UI Builder.

api.controller = function ($scope, spModal, spUtil) {
	var c = this;

	function handlePortalRelay(event) {
		console.log("PORTAL_BRIDGE#MESSAGE:", event.detail);
	}

	window.addEventListener("PORTAL_BRIDGE#MESSAGE", handlePortalRelay);

	$scope.$on("$destroy", function () {
		window.removeEventListener("PORTAL_BRIDGE#MESSAGE", handlePortalRelay);
	});
};

UI Builder

When you've set up your widget and the UI Builder page is included, you now have access to its window.

Using the event listener

This script sends an event to the window parent which has registered the event listener. This is just an example of a payload, you can of course customize as much as you want.

helpers.timing.setTimeout(function () {
	var parentWindow = this.window.parent;

    var customEvent =
        parentWindow.document.createEvent('CustomEvent');

    customEvent.initCustomEvent(
        'PORTAL_BRIDGE#MESSAGE',
        false,
        false,
        {
            "key": "CUSTOM_EVENT",
            "value": {
                "test": 123
            }
        }
    );

    parentWindow.dispatchEvent(customEvent);
});

 

window.parent

Since you have access to the window parent you can also utilize the default window functions. Here are some examples:

Open a URL

Routes the user to a different page.

helpers.timing.setTimeout(function () {
	var parentWindow = this.window.parent;
		parentWindow.open('https://www.servicenow.com/', '_blank');
});

Update params

Allows you to update the URL. Useful if you're using the internal routing of the UI Builder but would like to sync the URL with the portal.

helpers.timing.setTimeout(function () {
	var parentWindow = this.window.parent;
	const url = new parentWindow.URL(parentWindow.location.href);
	url.searchParams.set('sys_id', '123');

	parentWindow.history.pushState({}, '', url.toString());
});

My other post: Playbook in Employee Center - Run events from UI Builder