ServiceNow Integration

Introduction

Secret Server can integrate with ServiceNow's Incident and Change Management service. This integration includes validating ticket numbers, checking their status, and adding Work Detail items to the request. The integration with ServiceNow leverages out-of-the-box REST-based Web services.

Requirements

  • A ServiceNow instance running the Eureka version or later with REST services enabled.
  • A username and password that have access to execute the REST services, specifically GET and MODIFY on the following tables: Change Request and Incident.
  • The Secret Server environment needs to be able to connect to the ServiceNow Web services via port 80 or 443. SSL is highly recommended because the REST messages authenticate with a username and password.

Configurable Settings

The ServiceNow Integration has several configurable settings that the user needs to explore:

  • View Ticket URL Template:

    The format of the URL used for viewing the ticket. This appears in the audit log so you can easily view the corresponding ticket from Secret Server.

    Use the following templates for incident or change management instances:

    • Incident management: https://<instance name>.service-now.com/nav_to.do?uri=incident.do?sysparm_query=number=$TICKETID

    • Change management: https://<instance name>.service-now.com/nav_to.do?uri=change_request.do?sysparm_query=number=$TICKETID

    This field specifies the URL that will be used when displaying a link to a ticket in the audit log. In this field, the $TICKETID parameter will be replaced by the ticket number that is entered by the user.

    For example, if you specify the View Ticket URL Template as http://myticketingsystem/ticket.aspx?ticketid=$TICKETID, and Bob enters 5125-242 as the ticket number, a link will appear in the audit log to http://myticketingsystem/ticket.aspx?ticketid=5125-242.

  • Ticket Number Format Pattern (Regex):

    Before even making a call to the ServiceNow Web service you can have Secret Server validate the number matches a pattern. For example, your incident numbers might all be prefixed with "INC" and you want to ensure they enter this prefix. Some sample expressions to validate the ticket number are listed below:

    • Incident management: ^INC[\d]{7}$

    • Change management: ^CHG[\d]{7}$

  • Ticket Number Validation Error Message:

    The error message to display to the user when their entered ticket number fails the validation pattern regex.

  • Domain Name:

    This is the domain name of your instance in the following format: <instance name>.service-now.com. For example: dev5859.service-now.com.

  • System Credentials:

    Select or create a secret that contains the username and password for a user that has access to execute the REST Web services. Secret Server uses these credentials to authenticate to ServiceNow.

  • Allowed Statuses:

    The allowed statuses for ServiceNow tickets can vary based on the specific configuration and customization of the platform within an organization. Generally, however, the statuses for each type of ticket are as follows:

    • Incident Statuses:

      • New: The incident has been logged but not yet reviewed.
      • In Progress: The incident is being actively worked on.
      • On Hold: Work on the incident is paused, possibly waiting for more information or a third-party response.
      • Resolved: A solution has been implemented, and the incident is awaiting confirmation from the user.
      • Closed: The incident is confirmed resolved and closed.

    • Request Statuses"

      • New: The request has been submitted but not yet reviewed.
      • In Progress: The request is being fulfilled.
      • On Hold: The request is paused, possibly waiting for more information or approval
      • Completed: The request has been fulfilled.
      • Closed: The request is confirmed completed and closed.

    These statuses can be customized, so it's best to check with your organization's ServiceNow administrator for the exact statuses used.

    The comma separated list of statuses provided will be considered legitimate by secret-server.

  • Add Comments to Ticket:

    Check this box if you want the comment that a user enters to be added to the request in ServiceNow. This adds information such as the Secret to which access is requested, who requested access, and their comments. The comment is added as a work note in the activity section of the request.

Testing your Integration Setup

After configuring the ticket system, use the Test Validation button to verify that Secret Server can successfully access ServiceNow. This button opens a dialog in which you can enter a ticket number from ServiceNow. This validation process either succeeds or shows an error code.

Please note, Secret Server validates the ticket number but does not include validation of a ticket's status based on the Action Status in the configuration. To validate the status of the ticket customers need to write a script to validate the status based on the code base. Secret Server only validates based on Ticket ID and whether or not SNOW returns an error.