Skip to main content
Version: 3.2

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.

How it works​

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.

As with the other embed options, 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.

What the embed shows​

  • A filtered grid of records for the requester, scoped to the configured business object type (typically Incident)
  • CSV export - every Cortex grid supports CSV export, and the embed is no exception
  • No Cortex sidebar or navigation - the view is intentionally minimal so it fits cleanly within the ServiceNow ticket layout

Setting up the UI macro​

The macro points the iframe at the standard embed route on your Cortex instance:

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?object=BUSINESS_OBJECT&requestor=REQUESTER

with {DataSourceId} replaced by your data source's ID, BUSINESS_OBJECT by the business object to list (e.g. Incident), and REQUESTER by the caller's email address.

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/data-source/{DataSourceId}/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.

The macro script runs on load: it reads the current incident's caller, resolves the caller's email, and sets the iframe's src to the Cortex embed URL for that email. Agents then see the caller's archived incidents on the new tab.

Authentication​

By default the embed relies on the agent already being logged into Cortex, just like the other embed options. If your ServiceNow users need to view the embed without a separate Cortex login session, contact your account manager to discuss secure authentication options for your setup.

Video walkthrough​