Integrating with ServiceNow

ServiceNow is a popular information technology service management system that is used as part of a wide range of enterprise operations. Nametag can be fully integrated into ServiceNow to securely and positively identify an employee or customer as part of a service transaction.

Follow these steps to integration Nametag with ServiceNow Incidents system.

Note: Version Washington DC was current at the time of writing this document.

Prerequisites:

A ServiceNow Development Instance
A ServiceNow Administrator privileges
A Nametag Administrator privileges

Access check

To configure Nametag, you will need to perform some basic ServiceNow development. Select All from the menu bar and search for System Definition. If you don’t see any results, you will need additional privileges granted to you. If you have the required privileges, you will see something like this:

Configure Nametag

You will need two things from Nametag to configure ServiceNow:

an environment identifier (ENV_ID)
an API key (API_KEY)

Go to the Nametag console.

Select Configure on the top right.

Select OAuth from the navigation bar on the left, and copy the Client ID. This is your ENV_ID.

Select API Keys from the navigation bar on the left, then select Create new API key, fill in a name and copy the API key. This is your API_KEY.

Select Request templates on the left side of the screen.

Select Create a template in the top left corner and configure it as follows:

Name: ServiceNow (this is your TEMPLATE_NAME which we’ll use later)
Scopes: Legal Name (you can add more scopes later if you like)

If you like, set the Expiration time or other options according to your needs.

Choose Save template.

Create custom fields

Create custom fields for the Incidents that you’ll use to store the state needed by the Nametag integration.

Go to System Definition > Tables & Columns.

ServiceNow system definition menu
Locate the Incident [incident] table in the Table Names list, and select it and choose Edit Table.

Edit the incidents table
Select New on the right side of the Columns section.

Add a new column to the incidents table
Configure the column:

Type

URL

Column label

Nametag Verification Link (send to end-user)

Active

checked

Creating a new column

Choose Submit to save the new column.
Select New on the right side of the Columns section and configure the column:

Type

String

Column label

Nametag Request Status

Max length

80

Choose Submit to save the new column.
Select New on the right side of the Columns section to create a new column. configure the column:

Type

String

Column label

Verified Legal Name

Max length

80

Choose Submit to save the new column.

Create a Nametag request

Create a REST API call

We will now create an outbound REST message that we’ll use to generate a Nametag verification link.

Select All from the menu bar and choose System Web Services > Outbound > REST Message

Choose New on the top right.

Provide the following information:

Name: Nametag IDV Request (this is your REST_MESSAGE which we’ll use later)
Description: Generte a Nametag IDV request URL
Endpoint: https://nametag.co/api/requests
Accessible from: This application scope only

In the Authentication tab, choose Basic from the Authentication type dropdown list.

Select the magnifying glass icon next to Basic auth profile. In the dialog that appears, select New:

Provide the following information:

Name: NT Basic Auth Config
Username: unused (can be anything)
Password: API_KEY (the API key you created in Nametag above)

Choose Submit to save the new basic auth profile and return to the REST message record. Notice that the record contains a new section that lists HTTP methods:

Delete the GET HTTP method. (the requests endpoint uses POST, not GET).

Select New to create a new HTTP method and provide the following information:

Name: NT Get Request URL (this is your METHOD_NAME which we’ll use later)
HTTP Method: POST
Endpoint: https://nametag.co/api/requests

HTTP Query Parameters > Content:

{
    "env": "*ENV_ID*",
    "scopes": ["nt:legal_name"],
}

Replace ENV_ID with the environment identifier you copied from Nametag above.

Note in the Authentication tab it is set to inherit from parent.

Press Submit to be returned to the REST Message screen.

Note: the Content field is only used for testing, so it’s options. When you connect this REST message to a button, it ServiceNow will overwrite it.

Back on the REST Message screen, select the HTTP Method you just created to re-open it. Now you’ll see a Test link:

Go to the Test link. The result should look similar to:

Press Update to save everything and return to the REST Messages list. Check that the Nametag REST Message you created is in the list:

Create a UI action

Select All from the menu bar and choose System Definition > UI Actions

Select New in the top right corner.

Provide the following information:

Name: Verify ID
Table: Incident \[incident\]
Action name: create-request
Active: checked
Form button: checked

Locate the Script section and enter the following code.

try {
  var ticketId = current.sys_id.toString();
  var requestBody = {
    external_ticket: "sn:" + ticketId,
    env: "*ENV_ID*",
    template: "*TEMPLATE_NAME*",
  };
  var r = new sn_ws.RESTMessageV2("*REST_MESSAGE*", "*METHOD_NAME*");
  r.setRequestBody(JSON.stringify(requestBody));
  var response = r.execute();
  var responseBody = response.getBody();
  var httpStatus = response.getStatusCode();

  if (httpStatus === 200) {
    var jsonData = JSON.parse(responseBody);
    if (jsonData && jsonData.link) {
      current.u_nametag_verification_link = jsonData.link; // REMEMBER: make sure this matches the Custom Field we added to the Incidents table
      current.update();
    }
  } else {
    gs.addErrorMessage(
      "Failed to retrieve ID Verification Link. Status: " + httpStatus
    );
  }
} catch (ex) {
  gs.error("UI Action Script Error: " + ex.message);
}
action.setRedirectURL(current); // avoid default behavior of redirecting to incidents list page

Replace the placeholders:

ENV_ID with the value you copied from the OAuth page of the Nametag console.
TEMPLATE_NAME with the name of the template you created in the Nametag console, for example ServiceNow.
REST_MESSAGE with the name of the REST message you created above, for example Nametag IDV Request
METHOD_NAME with the name of the HTTP method you created above, for example NT Get Request URL.

Note: The first argument to sn_ws.RESTMessageV2 must match the name of the outbound REST Message you created earlier. Similarly, the second argument must match the name of the HTTP POST method you created earlier. If you used a different name that the suggestion, ensure it matches here.

Choose Update in the top right corner to save your changes.

Test the UI action

Select All from the menu bar and choose Self-Service > Incidents.

Select any incident number to open up the incident details page.

Select the button on the top right labeled Verify ID. A link appears in the field labeled Nametag Verification Link (send to end-user).

Note: If you’re unable to see the Nametag Verification Link, make sure the Nametag Verification Link field is in the Form Design section of the UI Action. To do this, right select in the UI Form header at the top, select Configure, then select Form Design.

If you don’t see the button or link, you can debug by adding gs.info and gs.error logs into your UI action’s script. You can find the output of these logged messages by navigating to All > System Logs > System Log > All menu. These logs will show output by invoking gs.info and gs.error in your script.

Get Nametag request status

Create a REST API call

Following the same process from above, create a new outbound REST message.

Select All from the menu bar and choose System Web Services > Outbound > REST Message

Choose New on the top right.

Provide the following information:

Name: Get Nametag Identity Verification Status
Description: Get the status of a Nametag Identity Verification request
Endpoint: https://nametag.co/api/envs/${envId}/requests/byexternalticket/sn:${ticketId}

In the Authentication tab, choose Basic from the Authentication type dropdown list.

Select the authentication profile you created earlier (NT Basic Auth Config).

In the HTTP Methods section below, select New. Provide the following information:

Name: Get request status
HTTP Method: GET
Endpoint: https://nametag.co/api/envs/${envId}/requests/byexternalticket/sn:${ticketId}
Authentication Type: Inherit from parent

Select Update to save changes.

Return to the Get request status method. In the Variable Substitutions section, we will set up substitutions for the envId and ticketId variables referenced in the endpoint.

To create a substitution for envId, select New and provide the following information:

Name: envId
Test value: ENV_ID

To create a substitution for ticketId, select New and provide the following information:

Name: ticketId
Test value: TICKET_ID

You can find a test value for TICKET_ID by opening the Incident page that you just created a Nametag Verification Link on. Locate the sys_id%3D in the URL query parameters (for example, ...sys_id%3D552c48888c033300964f4932b03eb092%26sysparm_v, the sys_id would be 552c48888c033300964f4932b03eb092)

Press Submit.

Test the method by selecting the Test link in the Related Links section right above Variable Substitutions. You should get a 200 status response back that looks like the following:

Create a server-side script

Next, create a server-side script to handle calling the REST API call to get the status of the Nametag request associated with the given ticket.

Select All from the menu bar and choose System Definition > Script Includes and press New in the top right corner.

Provide the following information:

Name: CheckNametagRequestStatus
Client callable: checked
Active: checked
Description: Check the status of a Nametag Identity Verification request associated with a given ticket

Script

var CheckNametagRequestStatus = Class.create();
CheckNametagRequestStatus.prototype = Object.extendsObject(
  AbstractAjaxProcessor,
  {
    getStatus: function () {
      var ticketId = this.getParameter("sysparm_ticket_id");
      var envId = this.getParameter("sysparm_env_id");

      if (!ticketId) {
        gs.error("CheckNametagRequestStatus: Missing ticket ID");
        return "";
      }
      if (!envId) {
        gs.error("CheckNametagRequestStatus: Missing environment identifier");
        return "";
      }
      try {
        var restMessage = new sn_ws.RESTMessageV2(
          "Get Nametag Identity Verification Status",
          "Get request status"
        );
        restMessage.setStringParameterNoEscape("ticketId", ticketId);
        restMessage.setStringParameterNoEscape("envId", envId);
        var response = restMessage.execute();
        var httpStatus = response.getStatusCode();

        if (httpStatus == 200) {
          var responseBody = response.getBody();
          var jsonData = JSON.parse(responseBody);
          var result = {
            status: "",
            legalName: "",
          };
          result.status = this.translateStatus(jsonData.status);

          if (jsonData.properties) {
            jsonData.properties.forEach(function (property) {
              if (property.scope === "nt:legal_name") {
                result.legalName = property.value;
              }
            });
          }
          return JSON.stringify(result);
        } else if (httpStatus == 404) {
          // no Nametag request associated with this ticket
          return;
        } else {
          gs.error(
            "CheckNametagRequestStatus: Error response from Nametag API for ticket " +
              ticketId +
              ": HTTP Status = " +
              httpStatus
          );
        }
      } catch (ex) {
        gs.error(
          "CheckNametagRequestStatus: Exception while requesting status for ticket " +
            ticketId +
            ": " +
            ex.message
        );
      }

      return this.translateStatus(status);
    },

    translateStatus: function (statusCode) {
      var statusMap = {
        100: "Pending",
        101: "In progress (user scanning)",
        200: "Request completed",
        403: "Data revoked",
        404: "Request canceled",
        410: "Request expired",
        411: "Shared data expired",
        550: "ID rejected; awaiting appeal",
        551: "ID rejected",
        552: "ID rejected; fraudulent",
      };
      return statusMap[statusCode] || "Unknown";
    },
    type: "CheckNametagRequestStatus",
  }
);

Note: As before make sure that the REST Message names and parameters match what you configured for the outbound REST message earlier.

Press Submit to save your script.

If you are prompted for a User Role for Access Control, choose itil.

Create a client-side script

Create a script that runs on the Incident page and checks for updates on the Nametag request associated with the open ticket using the server-side script we just created.

Select All from the menu bar and choose System Definition > Client Scripts and press New to create a new client script.

Provide the following information:

Name: Poll Nametag Request Status
Table: Incident \[incident\]
UI Type: Desktop
Type: onLoad
Active: checked
Description: Poll every 10 seconds to get the status of the Nametag Identity Verification request associated with this ticket, and display the status to the user.

Script

function checkNametagStatus() {
  if (!g_form.isNewRecord()) {
    // ensure the record is not new
    var ga = new GlideAjax("CheckNametagRequestStatus");
    ga.addParam("sysparm_name", "getStatus");
    ga.addParam("sysparm_ticket_id", g_form.getUniqueValue());
    ga.addParam("sysparm_env_id", "*ENV_ID*");
    ga.getXMLAnswer(function (response) {
      var data = JSON.parse(response);
      if (data) {
        // REMEMBER: make sure the column names referenced here match the custom fields we created earlier
        g_form.setValue("u_nametag_request_status", data.status);
        if (data.legalName) {
          g_form.setValue("u_verified_legal_name", data.legalName);
        }
      }
    });
  }
}

function onLoad() {
  // Call the function immediately on form load
  checkNametagStatus();

  if (typeof window.NametagPolling !== "undefined") {
    clearInterval(window.NametagPolling); // Avoid multiple intervals if the form is reloaded
  }
  window.NametagPolling = setInterval(checkNametagStatus, 10000); // every 10 seconds
}

Press Submit to save your changes.

Testing the scripts

Go back to an Incident page and select Verify ID.

A link will appear in the Nametag Verification Link (send to end-user) field and the Status field says Pending.

Open the link and verify your identity using Nametag. When the request is completed, the Status field is updated to say Request completed and the Verified Legal Name field is populated with your name.

If you have trouble, you can debug by adding gs.info and gs.error logs into your UI action’s script. You can find the output of these logged messages by navigating to All > System Logs > System Log > All menu. These logs will show output by invoking gs.info and gs.error on the server-side script. You can see logs from the client-side script by opening your browser’s developer mode.

Using the integration

To verify the identity of the person making a request in ServicNow, the agent will perform the following steps:

Select Verify ID at the top right of the Incident page.
Copy the resulting link and deliver that to the end-user.
Wait for the person to validate their ID, checking the Status field.
Compare the name Verified Legal Name from Nametag with the name of the person in the ServiceNow Caller field and ensure they are similar enough to proceed.