How do I configure Entuity to send events and/or incidents to ServiceNow?

Preliminary requirement

To set up the ServiceNow configuration file

EMS actions that forward events and incidents to ServiceNow

To forward events from Entuity to ServiceNow

To forward incidents from Entuity to ServiceNow

To log requests to the ServiceNowSent.log file

Preliminary requirement:

Before you can send events and incidents from Entuity to ServiceNow, you must first install the ServiceNow Event Management plugin to your instance of ServiceNow.

To set up the ServiceNow configuration file:

1. Navigate to the sn-example.cfg file, located in the entuity_home/etc directory.
2. Using this example, create a sn.cfg file, and save it to the same entuity_home/etc directory.
3. Update the 'default' section and/or add a named 'section' to the file for each ServiceNow path. 
   Each 'section' is a connection definition used by Entuity to connect to ServiceNow.

4. Add the socketTimeout and connectionTimeout parameters to only one 'section' and enter a value for the parameters, in seconds.
   These values determine the socket and connection timeouts for each ServiceNow request.
   Note, the connectionTimeout value is global to all connections so it must be defined only once within one of the active 'sections' that you create in the sn.cfg file.
   For example:

   [default]
   port = 443
   host = myhost1.service-now.com
   path = /api/now/table/em_event
   user = Entuity
   pass = ServiceNow
   socketTimeout = 20
   connectionTimeout = 15
   
   
   
   [myhost2]
   port = 443
   host = myhost2.service-now.com
   path = /api/now/table/em_event

5. Save the file, and then stop and restart Entuity.

Note, you can enter the value of a 'section' name (default or myhost2 in this example) in the cname parameter later when you configure Entuity to forward events and incidents.

The attributes for the connection definition are as follows:

Mandatory attributes:

• host - host of the connection.
• path - URL path for the connection.
• user * - username to be used for the connection.
• pass * - password/key required for establishing the connection.
  Note, user and pass attributes are not required if using the 'Send to ServiceNow Queue' action, as they can be entered as parameters in the action itself.

Optional attributes:

• proto - protocol to be used, either http or https. Default is https.
• trust - trust https SSL certificate, either 0 or 1. Default is 1. 0 ignores SSL trust certificate and accepts all.
• port - connection port. Default is 443.
• proxyHost - to use proxy connection.
• proxyPort - specify the proxy port. Default is 80.
• socketTimeout - define the timeout, in seconds, for responses.
• connectionTimeout - define the timeout, in seconds, for connections.

EMS actions that forward events and incidents to ServiceNow

To create ServiceNow events, you can configure EMS actions to forward events and/or incidents from Entuity to ServiceNow.

As of Entuity v23.0 P01 upwards, there are two EMS actions for forwarding events and incidents to ServiceNow: 'Send to ServiceNow' and 'Send to ServiceNow Queue'

The 'Send to ServiceNow' action forwards each event and incident directly to ServiceNow, while the 'Send to ServiceNow Queue' action forwards events and incidents to ServiceNow through a queue from the Message Broker. Sending through a queue helps prevent communication or connection errors during the forwarding process, as messages remain in the queue until successfully acknowledged by the target endpoint. A message queue log file is also created when using the 'Send to ServiceNow Queue' action. For more information on message queues, see this article.

For information about EMS actions, see What are EMS actions?

To forward events from Entuity to ServiceNow:

1. From the Main Menu, click Administration.
2. On the Administration page, click Event Administration.
3. On the Event Administration page, click the Rules tab.
4. Select Post Storage in the tree on the left, and then click Add Rule at the bottom of the window.
   
   
    
5. From the Add Rule window that is opened, ensure the Type field is set to 'Generic', and that the enabled checkbox is selected.
6. Complete the Name and Description fields, as appropriate.
7. Leave the Condition field as 'None'.
8. In the Action Steps section, click Add.
   
   
    
9. From the Add Action window that is opened, do the following:
   1. From the Type dropdown field, select 'Send to ServiceNow' or, from Entuity v23.0 P01 upwards, 'Send to ServiceNow Queue'.
   2. If you want to keep the 'cname' parameter value as 'default', skip to step iv. Otherwise, in the Parameters field, click Set to change the 'cname' parameter value. 
      
      
   3. From the Parameter Value window that is opened, enter the 'section' value that you defined in the ServiceNow configuration file, and click OK to save and close the Parameter Value window.
      
      
   4. If you selected the 'Send to ServiceNow Queue' action step in step i (Entuity v23.0 P01 upwards), select the 'username' and 'password' parameters in the Parameters field on the Add Action window, and click Set.
   5. Enter the username and password information in each parameter that Entuity will use to establish a connection with ServiceNow, and click OK.
   6. Click OK to save the action step and return to the Add Rule form.
10. If you want to forward events to multiple ServiceNow paths, repeat step 9 and specify the unique webhook path for each channel.
11. Click OK to save and add the rule, and then click the Save icon in the upper-right of the Event Administration page to save the event project.
12. If you selected the 'Send to ServiceNow Queue' action step in step i (Entuity v23.0 P01 upwards), choose whether to execute callback actions by optionally using the 'Response Callback' action. Do one of the following:
    • If you want a 'Response Callback' action executed when event and incident data is sent to the ServiceNow integration:
      1. Keep the 'callback' parameter in the 'Send to ServiceNow Queue' action step.
      2. Create a ServiceNow-specific 'Response Callback' action from the Actions tab of the Event Administration page, and define which action to execute upon receiving a response from the ServiceNow integration.
      3. Return to the 'Send to ServiceNow Queue' action step in the new rule from the Rules tab (for events) or in the new trigger from the Incidents tab (for incidents) on the Event Administration page.
      4. Enter the name of the newly created 'Response Callback' action as the value of the action step 'callback' parameter.
    • If no 'Response Callback' action is required, set the value to null without quotes.

Note, if events are forwarded through message queues, the 'Set Attribute' option can't be used as a 'Response Callback' action. However, you can use other options in the 'Response Callback' action, such as 'Create Event'.

To forward incidents from Entuity to ServiceNow:

You can forward incidents to ServiceNow by setting up a global incident trigger. You can configure a global trigger so that all incidents are forwarded to the server, or configure individual triggers so that only individual incidents are forwarded:

1. From the Main Menu, click Administration.
2. On the Administration page, click Event Administration.
3. On the Event Administration page, click the Incidents tab.
4. Click Edit Global Triggers at the bottom of the window to open the Edit Global Triggers window.
   
   
    
5. Click Add.
   
   
    
6. On the Create Trigger window that is displayed, complete the Name and Description fields, as appropriate, and ensure that the enabled checkbox is selected..
   
   
    
7. Keep the On Transition To dropdown field set to 'Any Change' so that all incidents raised against the same source are forwarded to ServiceNow.
8. In the Condition dropdown field, select 'All tests must succeed', which updates the window.
9. In the Tests section, click Add to open the Add Test window..
   
   

10. From the Type dropdown field on the Add Test window, select 'Groovy Script' and click OK to prevent notifications from being sent to ServiceNow when the incident changes from the 'Closed' to the 'Expired' state (as this is of no relevance to ServiceNow). 
    The Groovy script uses the following syntax:

    state !=4

    
    
     

11. In the Action Steps section of the Create Trigger window, click Add to open the Add Action window.
    
    

    1. From the Type dropdown field, select 'Send to ServiceNow' or, from Entuity v23.0 P01 upwards, 'Send to ServiceNow Queue'.
    2. In the Parameters field, edit the values of the 'cname', 'user', and 'password' parameters, in the same manner as steps ii - iv of the event process.
    3. Click OK to save the action and close the Add Action window.
       
       
       
12. Click OK to save and add the trigger, and then click the Save icon in the upper-right of the Event Administration page to save the project.
13. If you selected the 'Send to ServiceNow Queue' action step in step i, choose whether to execute callback actions, the same way as step 12 of the event process.

To log requests to the ServiceNowSent.log file:

Each time the 'Send to ServiceNow' action is invoked, the request is logged in the file eventEngine.log. You can also specify that the response for each request be logged in ServiceNowSent.log.

Each log contains a timestamped entry for every time a ServiceNow event is raised from Entuity. The information in these entries can help with troubleshooting.

To log requests in ServiceNowSent.log:

1. Navigate to the entuity_home/install/template/etc/event-engine-log4j2.properties file.

2. At line 131, change the following line:

   logger.SERVICE-NOW-SENT.level = INFO

   to either '= DEBUG' or '= ALL'.

3. Run configure.
   Making the change in this location ensures that the change is not overwritten the next time you run configure. You can also change the same line in the entuity_home/etc/event-engine-log4j2.properties file.