Integrating Nametag with ServiceNow

ServiceNow is a popular Information Technology Service Managment (ITSM) system that is used as part of a wide range of enterprise operations. Nametag provides an API-driven workflow that can be fully integrated into Servicenow to securely and positively identify an employee or customer as part of a transaction.

These instructions will help you configure Nametag in your ServiceNow environment; for the example in this document we will use the ServiceNow Incidents system (at version “Washingon DC”) as our point of integration.

ServiceNow development

The steps we describe here involve some simple ServiceNow development—don’t worry if you haven’t ever done that before, the instructions here will walk you through the process.

However, to get started, you may need to talk to your ServiceNow administrator to get access to the parts of ServiceNow we will be configuring. If you click the All menu and search for System Definition and don’t get any results, you will need additional privileges granted to you. If you have sufficient privileges when you search for System Definition it will look like

system-definition-menu.png

Once that is working for you, we can proceed.

Assembling the information from Nametag that ServiceNow needs

You will need two things from Nametag to configure ServiceNow: a Nametag Enviroment identifier and a Nametag API key.

If you don’t already have access to a Nametag environment, you will need to create a Nametag instance for yourself. Make sure you have your government-issued photo ID and an Android or iOS mobile phone, then go to https://console.nametag.co/signup and follow the steps. This should take less than 5 minutes, but if you need help please reach out to us at help@nametag.co.

Once you are logged into your Nametag console, click the “Configure” button in the upper right of the screen. The Nametag console Configure button

To get:

  • the Nametag Environment identifier: click on OAuth on the right and copy the Client ID. The Nametag environment identifier
  • the API Key: click on API Keys on the right, then “Create new API key”, fill in a name and copy the API key. For now you can leave the Role as Admin and the Environment as “All environments” The API Key

At this point, you have all the information you need from Nametag ready to use to configure ServiceNow.

Create Custom Fields to store request state

The first thing we will do is create Custom Fields for the Incidents table that we’ll use to store the state needed by the Nametag integration.

  1. Navigate to System Definition > Tables & Columns. (this is the same menu item in the image above)

  2. Locate the Incident [incident] table in the Table Names list, and select it.

  3. Click the Edit Table button located below the list.

  1. Click the New button on the right side of the Columns section to create a new column.

  1. Configure the column:

    a. Type: URL

    b. Column label: Nametag Verification Link (send to end-user)

    c. Active: checked

  1. Click the Submit button to save the new column.

  2. Create another column called “Nametag Request Status” that is of type String. Set its Max length to 80.

  3. Create another column called “Verified Legal Name” that is of type String. Set its Max length to 80.

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.

  1. From the “All” menu, choose “System Web Services” -> “Outbound” -> “REST Message”, like:

  2. Then click “New”

  3. Enter some reasonable names and descriptions in the top part of the form; I used Nametag Identity Verification as the name. The important thing on this configuration panel is to enter https://nametag.co/api/requests in the Endpoint field. It will look about like this:

  4. On the bottom part, choose “Basic” as the Authentication Type, and click the magnifying glass next to “Basic auth profile”. In the box that pops up, click New and you’ll see:

  5. In the pop-up, enter a sensible name. For “Username”, you can enter anything; I’ve entered n for Nametag. For “Password” enter the API key you created in Nametag:

  6. Press Submit on the pop-up and you’ll be returned to the “Rest Message” page, but now it will have a new section on the bottom that lists HTTP Methods:

  7. The Nametag requests API doesn’t use GET, so we can delete that line and replace it with the POST that we need; after clicking New, select POST as the HTTP method. Note that in the Authentication tab it is set to “inherit from parent”

  8. We need to now set the Name, Endpoint, and Content fields. You will need the ID of your organization from above for this step (in case you don’t have it from above, it is available on the OAuth tab of the Nametag configuration console). We will use it in the Content field. A good reference for what goes into the Content field is https://getnametag.com/docs/api/#create-a-request. The screen should look like:

    Then press submit, and you will be returned to the REST Message screen

    a. Note: the Content part is optional here. It’s useful for testing, but when we wire this REST message up to a button, it will get overwritten.

  9. On the REST Message screen you will see the HTTP Method we just created; click it to open it again. Now you’ll see a link called Test on the page:

    Click that link to test that everything is working, you should see a result that looks similar to the one here:

  10. Now you can press “Update” to save everything and you’ll be returned to the REST Messages listing page, and you’ll see the Nametag REST Message in the list:

Create a UI Action

  1. Now we need to create a Nametag template that we’ll reference in the UI Action. Within the Nametag console, select the top nav link labeled Configure, and then select the Request templates tab on the left side of the screen.

  2. Click the Create a template button in the top left corner.

  3. Rename the template to “ServiceNow”. Make sure the template is toggled on, and that the Scopes selector includes the Legal Name scope. You can configure the Expiration time and other options based on your business needs.

  4. Click Save template to save your changes.

  1. Going back to ServiceNow, use the All menu to navigate to System Definition > UI Actions.

  2. Click the New button in the top right corner.

  3. Fill out the following values in the form. This will add a button to the Incident page called “Verify ID”.

    a. Name: Verify ID

    b. Table: Incident [incident]

    c. Action name: create-request

    d. Active: checked

    e. Form button: checked

  1. Scroll down to the Script section, and paste the following code in. Make sure you replace the values for “env” and “template” with values retrieved from the Nametag console.

    a. It’s important that the first argument to sn_ws.RESTMessageV2 matches the name of your Outbound REST Message, and that the second argument matches the name of the POST method we created earlier within that REST Message.

try {
  var ticketId = current.sys_id.toString();
  var requestBody = {
    external_ticket: "sn:" + ticketId,
    env: "kf7ptsy7q6zfwk2", // REMEMBER: replace with your own environment identifier
    template: "ServiceNow", // REMEMBER: replace with your own template name
  };
  var r = new sn_ws.RESTMessageV2("Nametag Identity Verification", "Create Nametag Request"); // REMEMBER: make sure this matches the Outbound REST Message created earlier
  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_send_to_end_user = 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

  1. Click Submit in the top right corner to save your changes.

  2. To test this, navigate to the Incidents page, which can be found at Self-Service > Incidents via the All menu.

  3. Click on any incident number to open up the incident details page.

  1. You should see a button in the top right labeled Verify ID. Click this button. You should see a link appear in the field labeled Nametag Verification Link (send to end-user).

  1. If this doesn’t work for any reason, 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 System Logs > System Log > All via the All menu. This can help you figure out if your script is running, what errors it might be running into, etc.

Get Nametag request status

Create a REST API call

We are going to create another Outbound REST Message to get the status of a request.

  1. Following the same process as above, create a new Outbound REST Message. You can fill out the fields as such:

    a. Name: Get Nametag Identity Verification Status

    b. Description: Get the status of a Nametag Identity Verification request

    c. Endpoint: https://nametag.co/api/envs/${envId}/requests/byexternalticket/sn:${ticketId}

  1. In the Authentication section below:

    a. Select Authentication Type: Basic.

    b. For Basic auth profile, select the “Nametag Basic Auth Config” that we configured for the previous REST Message.

  1. In the HTTP Methods section below, click the New button.

    a. Make sure the fields are filled out as such:

    i.  **Name**: Get request status

ii. **HTTP Method**: GET

iii. **Endpoint**: https://nametag.co/api/envs/${envId}/requests/byexternalticket/sn:${ticketId}

iv. **Authentication Type**: Inherit from parent

    b. Click Update to save changes

  1. Click back into the Get request status method we just made. Scroll down to the Variable Substitutions section. Here we will set up substitutions for the envId and ticketId variables referenced in the path.

    a. Click New

    b. Set Name to envId

    c. Set Test value to the ID for the env you are testing with

    d. Click Submit

    e. Repeat this process to create another variable substitution for ticketId. You can find a test value by opening the Incident page that you just created a Nametag Verification Link on. Locate the sys_id in the URL’s query parameters (for example, ...sys_id%3D552c48888c033300964f4932b03eb092...)

  1. Click the Test link in the Related Links section right above Variable Substitutions. You should get a 200 status response back that looks like this.

Create a server-side script

We will now 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.

  1. Navigate to System Definition > Script Includes

  2. Click the New button in the top right corner

  3. Configure your script:

    a. Name: CheckNametagRequestStatus

    b. Client callable: checked

    c. Active: checked

    d. Description: Check the status of a Nametag Identity Verification request associated with a given ticket

  4. Paste the code below into the Script field. It’s important to make sure that the REST Message names and parameters on lines 16-18 match what we configured for the Outbound REST Message earlier.

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"
        ); // REMEMBER: make sure this matches the REST message you created to retrieve request status
        // REMEMBER: the following variables should match the variables expected by the REST message
        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",
  }
);

  1. Click Submit to save your script.

  2. If asked to choose a User Role for Access Control, select itil.

  3. Note: if you have trouble finding this script later in the Script Includes list page, make sure the page doesn’t have any filtering options selected by default.

  4. If this doesn’t work for any reason, you can debug by adding gs.info and gs.error logs into the script. You can find the output of these logged messages by navigating to System Logs > System Log > All via the All menu. This can help you figure out if your script is running, what errors it might be running into, etc.

Create a client-side script that can handle polling

We’re going to 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.

  1. Via the All menu, navigate to System Definition > Client Scripts

  2. Click the New button in the top right corner to create a new Client Script.

  3. Configure the script as such:

    a. Name: Poll Nametag Request Status

    b. Table: Incident [incident]

    c. UI Type: Desktop

    d. Type: onLoad

    e. Active: checked

    f. 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.

    g. 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", "kf7ptsy7q6zfwk2"); // REMEMBER: makes sure you update this with your Nametag environment 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
}

  1. Click Submit to save your changes.

  2. Let’s test it out! Go back to an Incident page and click the Verify ID button. You should see a link appear in the Nametag Verification Link (send to end-user) field. The Status field should say Pending. Once you complete the request, the Status field should update to say Request completed, and the Verified Legal Name field should populate with your name.

  1. If this doesn’t work for any reason, console.log messages in the client script are a good way to debug what’s going on.

Using your Nametag integration in ServiceNow

You are now fully configured to use Nametag to get a validated and authenticated legal name into ServiceNow. In day-to-day usage, the steps the agent will follow are:

  1. Click the “Verify ID” button at the top right of the ServiceNow screen
  2. Copy the resulting link and deliver that to the end-user; this can be done in ServiceNow or by another means.
  3. Wait for the person to validate their ID
  4. The agent will compare the name from Nametag with the name of the person in the ServiceNow Caller field and ensure they are similar enough to proceed.

As always, if you have any questions or need any help, please reach out to us at help@nametag.co