Share via

Integrate a preconfigured service agent in ServiceNow

  • Article

You can embed preconfigured service agents directly into the ServiceNow desktop with contextual awareness of the underlying platform. This integration helps the application provide better responses, and helps to further streamline the workflow for your agents.

Prerequisites

Before you begin, you must have the following environments and console:

  • A Copilot for Service instance connected to a ServiceNow environment.
  • A ServiceNow production environment or trial environment.

Additionally, for your customer service representatives to be able to use agents in ServiceNow, you must assign the agent role to them. For information on how to assign this role to agents, see Assign a security role to a user.

Step 1: Copy the Copilot for Service widget URL

  1. Sign in to your Copilot for Service instance.
  2. On the sitemap, select Channels, and then select ServiceNow.
  3. Copy the URL starting after <iframe src=. For example, https://copilotforservice-test.azureedge.net/widget/index.html?dynamicsUrl=https://XXXXXX.crm10.dynamics.com
  4. Save the URL locally, where you can copy and paste it in a later step.

Step 2: Install the Knowledge API plugin

  1. In your ServiceNow environment, select All, search for plugins, and then select System Definition > Plugins.
  2. Search for Knowledge API. The system should return knowledge api plugin (App id: sn_km_api).
  3. Select the Knowledge API card.
  4. Select Install, and then select the latest version.
  5. Select Install now, and then wait for the Knowledge API installation to complete.

Step 3: Install the Openframe plugin

  1. In your ServiceNow environment, select All, search for plugins, and then select System Definition > Plugins.
  2. Search for Openframe. The system should return openframe plugin (Plugin id: com.sn_openframe).
  3. Select Install to start the plugin installation.
  4. Select Install, and then wait for the installation to complete.

Step 4: Install the Customer Service plugin

  1. In your ServiceNow environment, select All, search for plugins, and then select System Definition > Plugins.
  2. Search for com.sn_customerservice. The system should return Customer Service (Plugin id: com.sn_customerservice).
  3. Select Install to start the plugin installation.
  4. Select Install, and then wait for the installation to complete.

Step 5: Add the UI script for workspace navigator

  1. In your ServiceNow environment, ensure that you're in the Global workspace: Select the globe icon in the upper-right corner, and then verify that Application scope is set to Global.
  2. Select All, and then search for UI Scripts, and then select System UI > UI Scripts.
  3. Select New, and then fill in the form as follows:
    • API Name: Copilot open frame workspace script
    • UI type: Mobile/Service Portal
    • Script: Copy the contents of the following script:
 (function () {
  try {
    var logMoniker = "Copilot Navigator UI script: ";

    if (!globalThis.copilotNavigationWorkspaceListenerAdded) {
      console.log(logMoniker + "loading workspace navigator....");
      var payload = {
        url: globalThis.window.location.href,
        source: "workspaceUIScript",
        sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
        configType: "singleFrame"
      };
      var context = {
        payload: JSON.stringify(payload),
        method: "openframe_communication"
      };
      globalThis.CustomEvent.fireAll("openframe_request", context);

      globalThis.window.navigation.addEventListener("navigate", (event) => {
        console.log(
          logMoniker +
            "Workspace PAGE NAVIGATED: " +
            "\n Old Url: " +
            globalThis.window.location.href +
            "\n New url: " +
            event.destination.url
        );

        var payload = {
          url: event.destination.url,
          source: "workspaceUIScript",
          sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
          configType: "singleFrame"
        };
        var context = {
          payload: JSON.stringify(payload),
          method: "openframe_communication"
        };
        globalThis.CustomEvent.fireAll("openframe_request", context);
      });

      globalThis.copilotNavigationWorkspaceListenerAdded = true;
    } else {
      console.log(logMoniker + "Workspace navigator already loaded....");
    }
  } catch (error) {
    console.error(logMoniker + "Workspace Navigator error");
    console.error(error);
  }

  function initialiseScript() {
    // do nothing
  }

  return initialiseScript;
})();

Step 6: Add the UI script for classic UI navigator

  1. In your ServiceNow environment, ensure that you're in the Global workspace: Select the globe icon in the upper-right corner, and then verify that Application scope is set to Global.
  2. Select All, and then search for UI Scripts, and then select System UI > UI Scripts.
  3. Select New, and then fill in the form as follows:
    • API Name: Copilot open frame desktop script
    • UI Type: Desktop
    • Select the Global checkbox.
    • Script: Copy the contents of the following script:
 (function () {
  try {
    var logMoniker = "Copilot Navigator UI script: ";
    if (
      !window.parent.navigationListenerAdded &&
      !window.copilotNavigationClassicListenerAdded
    ) {
      console.log(logMoniker + "loading desktop navigator....");
      var payload = {
        url: window.location.href,
        source: "classicUIScript",
        sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
        configType: "singleFrame"
      };
      var context = {
        payload: JSON.stringify(payload),
        method: "openframe_communication"
      };
      CustomEvent.fireAll("openframe_request", context);

      window.navigation.addEventListener("navigate", (event) => {
        console.log(
          logMoniker +
            "desktop PAGE NAVIGATED: " +
            "\n Old Url: " +
            window.location.href +
            "\n New url: " +
            event.destination.url
        );

        var payload = {
          url: event.destination.url,
          source: "classicUIScript",
          sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
          configType: "singleFrame"
        };
        var context = {
          payload: JSON.stringify(payload),
          method: "openframe_communication"
        };
        CustomEvent.fireAll("openframe_request", context);
      });

      window.copilotNavigationClassicListenerAdded = true;
    } else {
      console.log(logMoniker + "Skipping desktop navigator load....");
    }
  } catch (error) {
    console.log(logMoniker + "Classic UI navigator error");
    console.log(error);
  }
})();

Step 7: Add client scripts for linking tables

  1. In your ServiceNow environment, ensure that you're in the Global workspace: Select the globe icon in the upper-right corner, and then verify that Application scope is set to Global.
  2. Select All, and then search for Client Scripts, and then select System Definition > Client Scripts.
  3. Select New, and then fill in the form as follows:
    • Name: Copilot open frame incident table script
    • Table Incident [incident]
    • UI Type: Desktop
    • Type onLoad
    • Script: Copy the contents of the following script:
 function onLoad() {
  try {
    var tableName = g_form.getTableName();
    var id = g_form.getUniqueValue();
    var payload = {
      recordId: id,
      objectType: tableName,
      source: "classicClientScript",
      sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
      configType: "singleFrame"
    };
    var context = {
      payload: JSON.stringify(payload),
      method: "openframe_communication"
    };
    CustomEvent.fireAll("openframe_request", context);
  } catch (error) {
    console.log(
      "Copilot Navigator UI script: CopilotClassicClientScriptCase navigator error"
    );
    console.log(error);
  }
}
  1. Select New again, and then fill in the form as follows:
    • Name: Copilot open frame email table script
    • Table: Email [sys_email]
    • UI type: Desktop
    • Type onLoad
    • Script: Copy the contents of the following script.
  function onLoad() {
  try {
    var tableName = g_form.getTableName();
    var id = g_form.getUniqueValue();
    var payload = {
      recordId: id,
      objectType: tableName,
      source: "classicClientScript",
      sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
      configType: "singleFrame"
    };
    var context = {
      payload: JSON.stringify(payload),
      method: "openframe_communication"
    };
    CustomEvent.fireAll("openframe_request", context);
  } catch (error) {
    console.log(
      "Copilot Navigator UI script: CopilotClassicClientScriptCase navigator error"
    );
    console.log(error);
  }
}
  1. Select New again, and then fill in the form as follows:
    • Name: Copilot open frame case table script
    • Table: Case [sn_customerservice_case]
    • UI type: Desktop
    • Type onLoad
    • Script: Copy the contents of the following script.
  function onLoad() {
  try {
    var tableName = g_form.getTableName();
    var id = g_form.getUniqueValue();
    var payload = {
      recordId: id,
      objectType: tableName,
      source: "classicClientScript",
      sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
      configType: "singleFrame"
    };
    var context = {
      payload: JSON.stringify(payload),
      method: "openframe_communication"
    };
    CustomEvent.fireAll("openframe_request", context);
  } catch (error) {
    console.log(
      "Copilot Navigator UI script: CopilotClassicClientScriptCase navigator error"
    );
    console.log(error);
  }
}
  1. Select New again, and then fill in the form as follows:
    • Name: Copilot open frame email table script
    • Table: Email [sys_email]
    • UI type: Desktop
    • Type onLoad
    • Script: Copy the contents of the following script:
 function onLoad() {
  try {
    var tableName = g_form.getTableName();
    var id = g_form.getUniqueValue();
    var payload = {
      recordId: id,
      objectType: tableName,
      source: "classicClientScript",
      sourceId: "b54abfa8-3d78-4aa0-ae3f-1e2ffbc56850",
      configType: "singleFrame"
    };
    var context = {
      payload: JSON.stringify(payload),
      method: "openframe_communication"
    };
    CustomEvent.fireAll("openframe_request", context);
  } catch (error) {
    console.log(
      "Copilot Navigator UI script: CopilotClassicClientScriptCase navigator error"
    );
    console.log(error);
  }
}

Step 8: Configure widget in ServiceNow

  1. In your ServiceNow environment, select All, search for OpenFrame, and then select Openframe > Configurations.
  2. In the upper-right corner, select New.
  3. Type Microsoft Copilot for the name and title.
  4. Type 450 for the width and 600 for the height.
  5. Select the User Groups you want to enable Copilot for Service for.
  6. Select the lock icon next to the URL field to unlock it, and then paste the Copilot for Service widget URL you saved earlier from the Copilot for Service admin page.
  7. Select Submit.
  8. Refresh the page. The Copilot for Service widget should be available on the top navigation bar for the icon you selected.
  9. Before you open Copilot for Service, ensure that you allowed popups from your ServiceNow page.