Create a custom connector

A custom connector requires a script, connector definition, and connector instance to retrieve events on behalf of an event source.

Before you begin

Role required: evt_mgmt_admin

About this task

A custom connector script can make remote API calls for a new event source to send events to the ServiceNow instance. You can create a script, and then add it as part of a new Event Management connector definition and connector instance. The custom code that accomplishes these actions must:
  • Connect to an event monitoring tool.
  • Retrieve events from an event monitoring tool.
  • Send events to the Event [em_event] table using a web service API. See REST API.

Procedure

  1. Create a custom MID Server script include. This example uses Groovy (deprecated). In place of a script include in Groovy, it is recommended to use JavaScript.
    1. Implement these methods:
      • @Override OperationStatus testConnection()
      • @Override OperationStatus execute()
    2. Design the class to extend the ThirdPartyConnector.
       public class HypericConnector extends ThirdPartyConnector
      
    3. Import platform classes for event creation, sending, logging, and third-party connector base classes.
      package com.service_now.mid.probe.tpcon.test
      
      import com.glide.util.Log
      import com.service_now.mid.MIDServer
      import com.service_now.mid.probe.event.IEventSender
      import com.service_now.mid.probe.event.SNEventSender
      import com.service_now.mid.probe.tpcon.OperationStatus
      import com.service_now.mid.probe.tpcon.OperationStatusType
      import com.service_now.mid.probe.tpcon.ThirdPartyConnector
      import com.snc.commons.eventmgmt.Event
       
    4. Connect to the data collector, such as SCOM or VMware vRealize Hyperic (Hyperic), with the API provided by the collector. Use the context parameters to set the event field values that came from a connector instance.
      def authString = (context.username + ':'+ context.password).getBytes().encodeBase64().toString()
      def urlStr = 'http://'+context.host + ':' + context.parameters.port + '/' + apiFunction
      
    5. Implement the execute function in the script. It reads events from the connector using its API to create Event objects and send them to the ServiceNow instance. For example:
      GPathResult alertsResponse1 = readAlerts('hqu/hqapi1/alert/find.hqu?begin=' + lastSignatureStr +
      '&end='+ tillStr +'&count=1000000&severity=1&inEscalation=false&notFixed=false');
      
      Event event = new Event()
      event.emsSystem = context.name
      event.source = "Hyperic"
      event.description = it.@reason
      event.type = it.@name
      ...
      IEventSender eventSender = MIDServer.getSingleton(SNEventSender.class)
          for (Event event  : list) {
              eventSender.sendEvent(event)
           }
      
  2. Navigate to MID Server > MID Server Script Files and create a script. Specify the Parent field as Groovy, complete the form as appropriate, and then click Submit.
  3. Navigate to Event Management > Connector Definitions and create a connector definition.
  4. In the Groovy script to run field, select the MID Server script file, complete the form as appropriate. In addition to username or host, you can add any other parameter, for example, port, and then click Submit.
  5. Navigate to Event Management > Connector Instances and create a connector instance.
  6. In the Connector definition field, select the connector definition, complete the form as appropriate, and then click Submit.
  7. To confirm or debug the script, use debug printouts from Groovy to the MID Server log.
  8. To monitor incoming events using the custom connector instance, navigate to ECC > Queue and filter on ConnectorProbe.