Integrating with ServiceNow
ServiceNow is a platform-as-a-service (PaaS) provider of Service Management (SM) software for the entire enterprise. The ServiceNow platform also supports the incident management process with the ability to log incidents, classify according to impact and urgency, assign to appropriate groups, escalate, and manage through to resolution and reporting.
To integrate the eG manager with the incident management process of ServiceNow, do the following:
- Login to the eG administrative interface.
Select the Manager option from the Settings tile.
Figure 1 will then appear. From the manager settings tree in the left panel of Figure 1, select the ITSM/Collaboration Integration node. The third-party ITSM/Collaboration tools that eG Enterprise can integrate with will be listed in the right panel.
- To enable integration with ServiceNow, first slide the ServiceNow slider in Figure 2 to the right.
Then, specify the following in Figure 2:
- URL: The URL using which the eG manager should connect to the ServiceNow installation in your environment.
- Port: The Port at which ServiceNow listens for problem information sent by the eG manager.
Authorization Type: The eG manager sends alarm information to ServiceNow as a web service request to the configured URL. Upon receipt of the request, ServiceNow will attempt to validate the source of the request using one of the following authentication methods:
- Basic authentication
O Auth 2.0 authentication
If ServiceNow enforces Basic Authentication, then select the Basic option from the Authorization Type drop-down. Where Basic Authentication is enforced, ServiceNow requires that web service requests be accompanied by the username and password of a user who has access to the ServiceNow instance. Accordingly, if Basic is set as the Authorization Type, you need to provide the credentials of a user with the right to access ServiceNow in the User and Password text boxes.
On the other hand, if ServiceNow enforces the O Auth 2.0 authentication method, then select the OAuth 2.0 option from the Authorization Type drop-down. O Auth 2.0 lets users access instance resources through external clients by obtaining a token rather than by entering credentials with each resource request. This means that where O Auth 2.0 is enforced, the eG manager needs to obtain an access token, so it can create/modify trouble tickets in ServiceNow. For this, the eG manager should first connect to the ServiceNow instance as a user who is authorized to request for an access token, and then submit web service requests as a valid 'Client'. This is why, if OAuth 2.0 is set as the Authorization Type, you will have to specify the following:
- User and Password: The credentials of a user who is authorized to request for an access token
- Client ID and Client Secret Key: The Client ID is an auto-generated unique ID of the client application - i.e., in our case, the eG manager application - requesting the access token. The Client Secret Key is a shared secret string that the ServiceNow instance and the client applications - i.e., the eG manager - use to authorize communications with one another.
- Does ServiceNow use proxy for connections: If the eG manager needs to communicate with the ServiceNow instance via a Proxy server, then set this flag to Yes.
- Proxy IP/Hostname and Proxy Port: If the Does ServiceNow use proxy flag is set to Yes, then specify the IP/host name of the Proxy server and the port number at which the Proxy server listens in the respective text boxes.
- Does Proxy require authentication: This flag is applicable only if the Does ServiceNow use proxy flag is set to Yes. If so, then use this flag to indicate whether/not the Proxy server requires authentication. Set this flag to Yes, only if the Proxy server requires authentication.
- Proxy UserName and Proxy Password: If the Does Proxy require authentication flag is set to Yes, then provide the credentials of a valid Proxy user here.
- Caller ID: The ID of the user to whom the problems sent by the eG manager are to be assigned.
- Assignment group: The assignment group to which the eG alarms are to be assigned.
- Assigned to: The name of the user to whom the problems sent by the eG manager are to be assigned.
- Category: Indicate how to categorize the eG alarms in the ServiceNow system – whether as a request, enhancement, or an incident.
- Critical due period: The time (in millisecs) by which tickets of a Critical priority will be resolved.
- Major due period: The time (in millisecs) by which tickets of a Major priority will be resolved.
- Minor due period: The time (in millisecs) by which tickets of a Minor priority will be resolved.
Incident title: Next, using the Incident title text box, specify the format in which the title of the trouble ticket is to be displayed in the ServiceNow console. The default format is as follows:
Priority :$prior Component : $cname Component Type : $ctype Layer : $layer Problem Description : $pdesc
The text preceding the ‘:’ (colon) in the format above indicates what information follows. The ‘dollared’ ($) text that follows the ‘:’ (colon) is a key, the value of which varies at run time, depending upon the information contained in the eG alarms. For example, in the default format above, Priority is a label that indicates that the information that follows the ‘:’ is the priority of the alarm. The key $prior that succeeds the ‘:’ represents the alarm priority, and changes according to the priority of the actual alarm that is sent by the eG manager to ServiceNow. While you can change the labels, you are advised against changing any of the keys.
The other keys that are part of the default format are discussed in the table below:
Will display the name of the problem component
Will display the component type to which the problem component belongs
Will display the layer affected by the problem
Will display a brief problem description
So, if a Critical alarm raised by the eG manager for a high CPU usage problem detected in the Operating System layer of the Windows server, 192.168.10.15, is routed to ServiceNow, the web services API of ServiceNow will convert the alarm into a trouble ticket titled (by default) as follows:
Priority:Critical Component:192.168.10.15 Component Type:Windows Layer:Operating System Problem Description:High CPU usage
- Problem description: The eG manager sends alarm information to ServiceNow in the form of a JSON file. Every piece of information contained within an eG alert - eg., priority, component name, component type etc. - is represented in the JSON file as a $key:$value pair, where 'key' denotes the alert field, and 'value' denotes the actual value of that field at run time. In the Problem description text box, specify the exact key in the JSON file that is used to capture the problem description. By default, $pdesc is the key used for reporting the problem description to ServiceNow. Note that the keys in the JSON file will match the keys supported by the ServiceNow REST API.
Custom Payload: Use custom payload to customize the alert information you send to ServiceNow, so that it includes additional static information.
Typically, the details of an eG alert are sent as a JSON file to the configured URL. Every piece of information contained within an eG alert - eg., priority, component name, component type etc. - is represented in the JSON file as a $key:$value pair, where 'key' denotes the alert field, and 'value' denotes the actual value of that field at run time. The 'key' is configured based on the keys supported by the ServiceNow REST API. For instance, if the REST API represents alarm priorities using the key 'prior', then the same key will be used in the JSON file for denoting alarm priorities. Accordingly, the entry for alarm priority in the JSON file will be $prior:$value. The $value will be Critical, Major, Minor, or Normal, depending upon the actual priority of the alarm being sent.
If you want eG incidents routed to ServiceNow to include additional information, then you can define a Custom Payload for that information as a $key:$value pair. For example, say, you want incidents to indicate the FQDN of the eG manager that generated the incidents. Say that the FQDN of your eG manager is egmanager.innovations.com. To include this information in ServiceNow incidents, do the following:
- First, check whether the ServiceNow REST API supports a 'key' that can be used for capturing the 'source' of alerts/incidents. If no such key exists, then you cannot proceed with the Custom Payload configuration. On the other hand, if such a key is available, then proceed to replace the $key in your Custom Payload specification, with that key value. For the purpose of our example, let us assume that the REST API supports the key named 'source'. In this case therefore, substitute '$key' with 'source'.
- Then, proceed to explicitly specify the FQDN of your eG manager in the place of $value. This is because, you can use the Custom Payload configuration to add only 'static' information - i.e., information that you explicitly configure, and hence will never change. In the case of our example therefore, the $value will be egmanager.innovations.com.
- The complete Custom Payload specification will now be: source:egmanager.innovations.com
- Finally, click the Update button in .