Recently IBM released a Java gateway for ServiceNow (nco_g_servicenow-2_0), which marks the first time that IBM have released a dedicated integration to connect OMNIbus and ServiceNow together.
Previously it has only been possible to connect OMNIbus and ServiceNow via Netcool/Impact (as detailed in one of my previous blogs) however ServiceNow no longer supports the Netcool integration plugin from the Fuji release onward.
Note: This only effects new activations as if the plugin was activated in a production instance then it will not be retired from your instance. Active plugins will remain accessible to you without change and upgrades to the ServiceNow platform will be
unaffected by this change and will carry the content of the plugin forward to the new release.
The old Netcool integration plugin used SOAP however the new Java gateway for ServiceNow uses REST which continues an industry trend towards REST APIs and away from SOAP.
The gateway seems to be based upon the tried and tested XML gateway (nco_g_xml) and leverages .jar files to integrate with ServiceNow.
Out of the box (OOTB) the gateway connects directly via the REST API to the ‘incident’ table in the ServiceNow instance, where the gateway creates, and retrieves details about tickets. This can be adjusted in the gateway props file by setting a value for the ‘Gate.ServiceNow.TableName’ property but ‘incident’ should be fine for most solutions.
Note: if you intend to use this product please ensure that you have the correct licences in place.
As part of the configuration of the ServiceNow gateway the objectserver is modified by running a sql file (servicenow.sql) that is supplied by the gateway. When run this sql file creates four extra columns in alerts.status:
- ServiceNowSysId varchar(32)
- ServiceNowState int
- ServiceNowErrorCode int
- TTNumber varchar(64)
The servcienow.sql file also provides ServiceNowState conversions to convert the integer values in alerts.status into a textual representation when viewed in the AEL or Event Viewer:
- 1 = ‘New’
- 2 = ‘Active’
- 3 = ‘Awaiting Problem’
- 4 = ‘Awaiting User Info’
- 5 = ‘Awaiting Evidence’
- 6 = ‘Resolved’
- 7 = ‘Closed’
On running the ServiceNow gateway with a vanilla configuration I could see that the events in alerts.status were getting populated.
ServiceNowState was populated with the state of the ticket in ServiceNow. You can see from the above image that there are two states present in the image ‘Resolved’ and ‘New’. The ‘Resolved’ value indicates that a ticket was raised as an incident and has since cleared (Severity = 0) and this has been fed back into ServiceNow by the gateway. For example if we take Incident number INC0010084 from the Event Viewer:
On searching for this Incident in ServiceNow I can see that it was marked as ‘Resolved’:
By examining the Activity section (bottom of the incident in my Geneva release), I can see that there has been five ‘Activities’ captured, the initial activity took place at 2016-05-16 14:53:39 where the Incident state was set to ‘New’. The next activity at 2016-05-16 14:56:00 set the Incident State to ‘Resolved’.
To summarise we have the ServiceNow gateway creating an initial incident at 14:53:39 where it was set to ‘New’ and then at 14:56 the event resolved itself on the objectserver side (Severity was set to 0) and the gateway sent an update to ServiceNow which marked the incident as ‘Resolved’. The incident state was then fed back via the gateway which updated the event in alerts.status and set the ServiceNowState field to ‘Resolved’.
It is useful to point out that the gateway queries the ServiceNow instance every 17 seconds by default and this can be adjusted in the gateway props file by setting a value for the ‘Gate.ServiceNow.PollingInterval’ property.
The next functional test was to take an open incident from the Event Viewer and mark the incident as ‘Resolved’, so the change to the incident is being performed on the ServiceNow side of the fence.
To achieve this I selected the following event from the Event Viewer, note the ticket number INC0010102 :
The ticket was located and viewed in ServiceNow:
I manually changed State from ‘New’ to ‘Resolved’ and clicked ‘Update’.
On viewing the associated event in the Event Viewer I could see that the ServiceNowState was set to ‘Resolved’ as expected.
By clicking on the event and viewing the ‘Journal’ tab I can see the activities that have been performed on this incident by the ServiceNow gateway.
You may have noticed a time disparity as my Events are displaying time in UTC while ServiceNow is displaying them in BST (British Summer Time). However this could be easily fixed in a production environment.
Extending the solution
This vanilla configuration can be used to get you up and running in a short space of time. However in a production environment we would not want to be passing all alerts to ServiceNow.
To control what you pass to ServiceNow you would need to define a FILTER statement in the servicenow.rdrwtr.tblrep.def file (located in $OMNIHOME/gates/servicenow) file. By default it passes everything which should be changed in the real world.
The StatusMap file it uses is defined in the servicenow.map file located in $OMNIHOME/gates/servicenow.
The servicenow.map file maps the alerts.status fields to their corresponding ServiceNow fields in line with well-used gateways such as the Reporter gateway.
I would recommend spending some time planning and defining the events that should be passed to ServiceNow, this will ensure that only quality events are raised as incidents.
By default the gateway works as a fully automated service, however many customers would want to use a right click tool to raise incidents in the AEL or the Event Viewer and after a period of time when the operators have got used to the system and have a good idea on what events should be raised as incidents then perhaps progress to a fully automated service.
You could elect to use the clear function, which as the gateway documentation points out is not used by the gateway OOTB. The main reason for this is that when a ticket gets cleared or deleted in ServiceNow, the gateway does not get notified. The gateway only discovers a ticket has been cleared or deleted in ServiceNow when the gateway attempts to update a ticket and gets back an error indicating that the ticket can no longer be found.
In theory, you could use the clear function to set the severity on Events in alerts.status who have a ServiceNowState field set to ‘Resolved’ (6) or you could do it the old fashioned way and just create a temporal trigger which does the same job.
The Java gateway for ServiceNow is a great product to integrate Omnibus with ServiceNow and has been long overdue. This blog was by no means comprehensive as there is much, much more you can do with this gateway but hopefully it has provided a quick overview and some good examples on how the gateway works. If you have any questions on this subject please feel free to contact me at email@example.com