Skip to main content
Version: 2.7

ServiceNow

ServiceNow doesn't provide a built-in "iframe tab" the way Halo does, so embedding Cortex there is a small custom build: a UI macro (Jelly) that renders an iframe plus a script that points it at the right requester. It's more involved than Halo, but more straightforward than GLPI, which needs our plugin.

The macro points the iframe at the Cortex embed URL:

https://YOUR_CORTEX_URL/embed?object=BUSINESS_OBJECT&requestor=REQUESTER

with BUSINESS_OBJECT replaced by the type of record to list (e.g. Incident) and REQUESTER by the email address of the requester whose records should be listed.

The key requirement is that the requester's email address in ServiceNow matches the email address in your Cortex data. When an agent opens an incident, the tab then shows that caller's archived records.

Setting up the UI macro​

A UI macro contains two things:

  1. An iframe that displays the Cortex embed page. ServiceNow doesn't give iframes any inherent size, so you must set an explicit width and height (for example width="100%" and a height around 400).
  2. A JavaScript script that runs when the macro loads. It reads the caller on the current incident, looks up that caller's email address, and sets the iframe's src to the Cortex embed URL for that requester.

Ampersands must be escaped twice​

When you build the iframe src inside the UI macro, the & separators in the URL must be escaped twice in the macro source:

https://YOUR_CORTEX_URL/embed?object=Incident&requestor=$email

ServiceNow re-escapes the value a third time when it processes the macro. If you don't escape the ampersands at all, or escape them only once, you'll get an "unterminated HTML entity" error when you save, or the form will render a blank embed after submission.

Adding the embed to the incident form​

  1. Create the UI macro. In ServiceNow, go to System UI > Macros and create a new UI macro containing the iframe and the script described above.
  2. Create a formatter. Go to System UI > Formatters and create a new formatter whose value is the name of your UI macro (for example cortex_embed), of type formatter, associated with the table you want it on (for example Incident).
  3. Place it on the form. Open the table's Form Design, add a new form section (which shows up as a tab), and add the formatter to it. Save and reload the form.

Authentication​

By default the embed relies on the agent already being logged into Cortex, just like the other embed options.