Custom connector guidelines

You can improve the configuration settings of a custom connector that connects to an external source by considering the following tips.

Best practice Details
Alert information collection Collect the required information about the alerts.
  • Node – Identifier for host (IP/FQDN, mac, name).
  • Resource – For example, disc, CPU.
  • Message key – The default is source&node&type&resource&metricName
  • Severity – If one or more fields in the target monitor must be mapped to ServiceNow severities.
  • Resolution State – If the source monitor has closed alerts, the alerts are closed in the ServiceNow instance.
  • Type - Event type.
  • Metric name - The name and description of the metric to which the alert applies.
  • Additional information – Any other information that might be used to bind the alert to the CI or used for alert rules, metric value, or alert ID in the target monitor.
Create ServiceNow events If an event must be created, ensure that you have the required details. For more information, see Event field format for event collection.

To populate node, source, event class (ems system), resource, message key, severity, state, type, metric name, additional information and description

  • Source – the name of the monitor
  • Event class = ems system = the name of the connector instance = this.probe.getParameter ("connector_name")
  • Consider where you can cache information to avoid unnecessary API calls.
Debugging Save the debugging information to ms.log. This requires being logged in to the MID Server. An example of a ms.log is: ms.log("Solarwinds testing connection")

To find the log, search in the MID Server for agent\logs\agent0.log.0 file. If there is failure, search the log for more information. The log must reveal the cause of the failure, for example, missing DLLs files or incorrect credentials.

Execution
  • Differentiate between the first pull of events with the subsequent events that are pulled. The first pull of events:
    • Takes events that exist.
    • Must be limited either in time or number of events that are pulled.
    • Must only pull open alerts.
  • Use the main API to get all events data since last signature and limit the number of events.
  • Create ServiceNow events by parsing.
  • Send all event using: var sender = SNEventSenderProvider.getEventSender()
  • Update the lastSignature timestamp.
  • Fill the resultant record with the status.
Last signature Each time that events are pulled, all events are pulled with the time of that the event occurred, which is >= last signature timestamp. In cases where the last event arrives at the last signature time, it is pulled repeatedly. To prevent this, ‘remember’ the last event ID. Thereafter, when events are next pulled, exclude this event ID if it is in the group of pulled events and its time of event remains unchanged.
Parameters Determine which parameters are available and how to use them.
  • For context parameters, such as, connector name, user name, password, host, and last event signature. For example: this.probe.getParameter("connector_name").
  • For connector instance values. For example: this.probe.getAdditionalParameter ("port").
Target monitor information collection Collect information about the target monitor.
  • APIs in use, for example, DB or web service.
  • How to connect to the external source:
    • Credentials.
    • Parameters (for example, url, port, protocol).
    • Required Jar or dll files needed to run commands on the MID server.
Test connection Verify the connection with the monitor:
  • A valid connection returns a SUCCESS status.
  • Use the main API that returns alerts/events data without sending data.
  • Fill the result record with status information according to the result of the connection test: retVal['status'] = "" + SUCCESS.toString()/ FAILURE.toString(). Detailed failure information must be saved to a log.
Time of event The Time of event is the time that the event occurred. Convert the event time to GMT using the yyyy-MM-dd HH:mm:ss format.