ModelOp Center seamlessly integrates with existing ticketing systems, such as ServiceNow, to allow enterprises to orchestrate seamlessly change requests and incidents as part of the model life cycle.

Table of Contents

1 Introduction
2 ServiceNow Integration Setup
- 2.1 Prerequisites
- 2.2 moc-builder ServiceNow Configuration
3 Security
4 ServiceNow Ticket Customization
- 4.1 Ticket Creation
- 4.2 Ticket Updates
- 4.3 Ticket Lifecycle
5 Raising/Managing Change Requests
6 Raising/Managing Incidents
7 MLC Example Usages
- 7.1 Related Articles

Introduction

ModelOp Center provides the ability for the Model Life Cycle to create and manage tickets within an existing ServiceNow system. The ticket types supported include change requests and incidents created and managed using the Table or Import Set APIs. This guide details the steps to enable integration.

ServiceNow Integration Setup

Prerequisites

This guide assumes moc-builder has been installed. Please request download instructions for moc-builder here. Before configuring moc-builder, the ServiceNow instance will need a service account created and configured. For an example of how to set up a service account see the instructions at https://community.servicenow.com/community?id=community_blog&sys_id=b4fca2a5dbd0dbc01dcaf3231f961900. This guide assumes that the service account uses the email "servicenow@modelop.com". There is no need to provide a ServiceNow related flag when bringing up the fleet as the ServiceNow instance will always be an external service.

moc-builder ServiceNow Configuration

The following configurations are required to integrate ServiceNow into ModelOp Center.

In the config/config.json file for the environment, in the translator->backing_services section, include a value for SERVICENOW_URI, like https://instance.servicenow.com
In secrets/secrets.jsonadd values for SERVICENOW_USERNAMEand SERVICENOW_PASSWORD

In environments/<environment>/config/required.json, under variables->mlc-manager you should see SERVICENOW_URI, and under variables->secrets->mlc-manager you should see SERVICENOW_USERNAME and SERVICENOW_PASSWORD.

In the environments/<environment>/spring_config/<type>/mlc-manager/application.yaml file you should see some ServiceNow-specific config as below

mlc:
...
  servicenow-task-monitor:
    poll-rate: 5000
    user: ${SERVICENOW_USERNAME}
    password: ${SERVICENOW_PASSWORD}
    url: ${SERVICENOW_URI}

You can have multiple ServiceNow instances listed in storedCredentials. When connecting to ServiceNow, ModelOp Center will look through the list and use the SERVICENOW_USERNAME and SERVICENOW_PASSWORD corresponding to the SERVICENOW_URI that matches the request. However, currently only a single ServiceNow client is created using the URI from mlc.servicenow-task-monitor.url. To have multiple sets of ServiceNow credentials, add more values to secrets/secrets.jsonand reference the new values in your environments/<environment>/spring_config/<type>/mlc-manager/application.yaml and environments/<environment>/config/required.json files.

Security

As mentioned in Prerequisites we recommend using a service account for the ServiceNow integration. Limit the access rights of the service account to just those needed for the integration and only use the service account for the integration. The security advantages to using a service account are explained here.

The integration uses Basic Authentication to authenticate REST calls to ServiceNow. The credentials can be set up using Kubernetes secrets, as in the configuration example above, or using Vault.

ServiceNow Ticket Customization

The integration provides a variety of parameters to allow customization of ServiceNow ticket creation and lifecycle management within the Model Life Cycle. Some of these parameters are discussed in more detail below.

Ticket Creation

SERVICENOW_API - The API to use when creating tickets (table or import). The integration supports both the Table API and the Import Set API for ticket creation.

SERVICENOW_TABLE_NAME - The table to create new tickets in. This is the path parameter of the API being used. This is usually change_request, incident, or the name of an Import Set.

SERVICENOW_CUSTOM_FIELDS - A JSON string containing any custom fields to send with the creation request. By default the implementation will provide data for a few fields and this parameter allows setting as many fields as needed. The custom fields can also be used to override the value traditionally sent for that field. One exception to the override functionality is the description field. If the description field is overridden, the custom override value will be used as a notification message within the description and the default description template will still be used to ensure that links back to the appropriate entity are included in the description. If a uuid or u_uuid field is required per request, including retries, then set the field to empty string and the integration will generate a random UUID to use for each request.

Ticket Updates

SERVICENOW_UPDATES - A JSON string specifying additional updates to make to the ticket after creation. Some workflows require additional automated updates to the ticket after creation. This field includes the required information to make those updates. UUID generation works here the same as for SERVICENOW_CUSTOM_FIELDS. If a field needs to use the value from the current state of the ticket include that field in the payload and set the value to empty string. The integration will replace the value with the value of the field in the ticket. The structure of the JSON is shown below:

[
  {
    "serviceNowApi" : "(table|import)",
    "serviceNowTableName" : "tableName",
    "serviceNowCustomFields" : {
      "field1":"value1",
      "replacement": "",
       ...
  }
  ...
]

Ticket Lifecycle

SERVICENOW_EXIT_STATUS_FIELD - The field on the ticket to watch for an exit state. The Model Life Cycle waits until this field reaches a desired SERVICENOW_EXIT_STATUS. By default the integration watches the state field. The display_value of the field is watched.

SERVICENOW_EXIT_STATUS - A string listing out the exit statuses for the ticket. When the SERVICENOW_EXIT_STATUS_FIELD reaches one of the exit statuses in this parameter the Model Life Cycle will stop watching the ticket and proceed.

SERVICENOW_EXIT_CONDITIONS - A string listing out a list of statuses and exit conditions that must be met for the status to be realized. Some workflows require considering multiple fields to determine if the ticket has met its exit status. This field uses a CSV-like format to list out conditions. Specifically,

Status1,ConditionType1,Condition1
Status2,ConditionType2,Condition2
…

where commas are used as a separator. Commas are permitted in the condition. A new line indicates the beginning of a new condition. Both juel and spel conditions are supported.

As an example, a workflow may require watching the state field to reach canceled or for the approval field to reach approved or rejected. The conditions for such a workflow could look like the following.

The conditions are evaluated in the order they are listed. The ticket variable is provided for expression evaluation by the integration and represents the current state of the ticket. The \$ is escaped in the example above so that Camunda itself will not attempt to evaluate the juel conditions. When a condition is satisfied the TICKET_STATUS variable will be set to the matching status for further use in the Model Life Cycle.

Only one of SERVICENOW_EXIT_CONDITIONS and SERVICENOW_EXIT_STATUS will be used when determining if a ticket has reached exit status with the following priority order:

Local SERVICENOW_EXIT_CONDITIONS variable
Local SERVICENOW_EXIT_STATUS variable
SERVICENOW_EXIT_CONDITIONS variable
SERVICENOW_EXIT_STATUS variable

In cases 2 and 4 SERVICENOW_EXIT_STATUS can be set to null to indicate that there should be no wait after creation and update. If SERVICENOW_EXIT_CONDITIONS is used then SERVICENOW_EXIT_STATUS_FIELD has no affect.

Raising/Managing Change Requests

To use a change request within a Model Life Cycle a notification must be created and stored and then the ticket created and the lifecycle managed. We provide examples of how to use the different notifications in the mlc-building-blocks. A simple example is shown below.

The Simple Notification requires the following parameters.

NOTIFICATION_MESSAGE - A message to include in the notification. This message will appear on the ModelOp dashboard. It will also appear as part of the short_description and in some cases description of the ServiceNow ticket unless those fields are overridden using SERVICENOW_CUSTOM_FIELDS.

NOTIFICATION_SEVERITY - The severity of the notification (INFO, WARN, ERROR, etc.). This will be reflected in the ModelOp dashboard notification.

SERVICENOW_API - The API to use for creating the ServiceNow ticket (table or import).

SERVICENOW_TABLE_NAME - The ServiceNow table to create the ticket in. If using the Table API this will be change_request. If using the Import Set API this will be the name of the import set.

Supplying these parameters correctly will result in a dashboard notification and a ServiceNow ticket being created. After ticket creation, however, the Model Life Cycle will continue on and not wait for any specific status of the ticket. In some cases this is desirable but often waiting for a specific status is the desired behavior. The SERVICENOW_EXIT_STATUS variable can be used to set the the status to wait for. For example, if set to “Closed,Canceled” then the Model Life Cycle will wait until the ticket’s state.display_value has reached either the closed or canceled status before continuing. The final status will be set in the TICKET_STATUS variable which the Model Life Cycle can use to determine different paths of execution. See ServiceNow Ticket Customization for more parameters for customizing ticket creation, updates, and lifecycle management.

Raising/Managing Incidents

Raising and managing an incident is nearly identical to Raising/Managing Change Requests. Ensure that SERVICENOW_TABLE_NAME is set to either incident (if using the Table API) or the name of the appropriate import set. That’s it! An incident will be created instead of a change request. Update any other parameters as needed to manage creation, updates, and lifecycle.

MLC Example Usages

The most common pattern when managing ServiceNow tickets in a Model Life Cycle is a three step pattern of Create Notification, Store Notification, and Review Notification. This pattern occurs twice in the RunAssociatedModelMetricsServiceNow Model Life Cycle as shown below. In each of the three step patterns the first activity is used to indicate the type of Notification to create as well as the ServiceNow notification assignment information. (See mlc-building-blocks for more examples of creating ServiceNow tickets.)

Each notification created will appear on the notification dashboard (Model Review Notifications also appear on the snapshot page). After the ticket is created the notification will be updated with a link to the ticket. The ticket status for the notification will be updated periodically while the Model Life Cycle is waiting on the exit status of that ticket. An example of one of these dashboard notifications is shown below.

ModelOp Documentation Hub V2.5

Integrate with ServiceNow

Introduction

ServiceNow Integration Setup

Prerequisites

moc-builder ServiceNow Configuration

Security

ServiceNow Ticket Customization

Ticket Creation

Ticket Updates

Ticket Lifecycle

Raising/Managing Change Requests

Raising/Managing Incidents

MLC Example Usages

Introduction

ServiceNow Integration Setup

Prerequisites

moc-builder ServiceNow Configuration

Security

ServiceNow Ticket Customization

Ticket Creation

Ticket Updates

Ticket Lifecycle

Raising/Managing Change Requests

Raising/Managing Incidents

MLC Example Usages

Related Articles