Configure a custom connector

Authenticate your custom connector as a data source to enable the pushing of event information to your ServiceNow instance. Define the custom connector by providing its details and mapping fields. This allows the extracted information from your custom connector's event messages to populate the required event fields. Finally, create and supply a URL for the custom connector webhook.

Before you begin

• Ensure the Event Management connectors (sn_em_connector) plugin is installed on the ServiceNow AI Platform instance. For more information, see Configure Event Management connectors.
• Ensure that the configuration items for the hosts managed by your custom connector exist in the ServiceNow AI Platform instance. These CIs can be physical or virtual and can be either manually created or discovered via IP discovery or Cloud Discovery. For more information, see Access to cloud environments for ITOM products.

Role required: evt_mgmt_admin

About this task

To start pushing event information to your ServiceNow instance, you must set your ServiceNow AI Platform instance as the REST endpoint using a standard webhook on your custom connector.

By providing connector details and mapping fields, you define the custom connector. The extracted information from the custom connector's event messages then populates the required event fields and inserts the event into the database.

The URL is generated by the code based on the ServiceNow instance and the custom connector. Use this URL to create a webhook that enables your custom connector to send events to the ServiceNow instance.

Procedure

1. Navigate to Workspaces > Service Operations Workspace.
2. From the left pane, select the Integrations Launchpad icon ()
3. In the Browse Integrations tab, select the All integrations drop-down list and select Custom.
   Only custom connector tiles are displayed.

   Figure 1. Push connectors

   

4. Select a custom connector type tile.
5. On the Provide details page, provide the details for the connector.

   Figure 2. Custom connectors details page

   

   1. In the Connector name field, enter a unique integration name for the connector.
   2. Optional: In the Tags field, enter tags to help locate and identify connectors of this type on the Express List.
      To add additional tags, select the plus icon () next to the Tags field. The Add tags window opens.

      1. In the Key field, enter a tag key.
      2. In the Value field, enter a tag value.
      3. Select Add.
   3. Optional: In the Description field, enter brief information about this connector.
   4. In the Source field, enter the vendor used to gather events from the external event source.

      The Source field identifies the connector and serves as an identifier to recognize the source of events and alerts once the connector is active.

   5. Optional: From the Assignment group drop-down list, select the group or team that is responsible for managing and maintaining the connector.
6. Optional: Drag or upload an image to display in your connector tile.
   • Drag an image into the box.
   • Browse to the image file by selecting Upload image and then choose the file.
   The maximum upload file size is 1 MB.
7. Determine whether you want to connect events directly to the ITOM instance or through a MID Server.

   • To send events directly to the ITOM instance, select Directly to the ITOM instance.

   • To send events through a MID Server, which processes and then passes the event to the instance, select Via the MID server.

     If a MID Server exists, from the Select MID server field, select an available MID Server connected to an events listener.

     If you must create a MID Server, then select one of the following.

     • Configure MID web server extension
     • Configure MID web service event collector context

     For more information, see Configure the MID Web Server extension and Configure the MID WebService Event Collector Context.
8. Select Next.

   

9. On the Set up input method page, select a method to gather event data.

   Method	Description
   Gather real source events to define fields	Select Gather real source events to define fields. Note: By gathering real-source events from your custom connector, you increase events and alert accuracy by using multiple events as a reference to define the fields. Select Copy to clipboard and copy the URL. Paste the URL into your custom connector's webhook setup to create a webhook that enables your custom connector to send events to the ServiceNow instance. Enter your basic authentication credentials into the monitoring system’s webhook configuration (such as the username and password). The webhook enables your custom connector to send events to the instance. Select Check for events. The number of events are displayed. The event creates JSON files that you can browse after selecting Next.
   Use a JSON sample to map fields	Select Use a JSON sample to map fields. Note: Only if you have a sample JSON select this option. In the Enter payload dialog box, copy and paste your JSON sample payload to create and view the mapping to map the fields. Select Upload JSON. Select Edit or paste new JSON to edit the JSON that you uploaded or paste a new one. Select Copy to clipboard and copy the URL. Paste the URL into your custom connector's webhook setup to create a webhook that enables your custom connector to send events to the ServiceNow instance. Enter your basic authentication credentials into the monitoring system’s webhook configuration (such as the username and password). The webhook enables your custom connector to send events to the instance.

10. Select Next.
    The page opens where you can map fields.

    

11. On the Map fields page, in the connector field names column, enter at least one value that maps to the severity values listed in the ServiceNow Severity field column.
12. On the Map fields page, in the connector field names column, enter at least one value that maps to the severity values listed in the ServiceNow Severity field column.

    You can enter the severity value from the JSON code sample. To set a severity value, you must be familiar with your custom connector's payload and the types of severity it supports. The severity values of the received events must match the generated events in your system.

    Enable the system to create events correctly from incoming data by mapping the fields in your JSON code sample to the ServiceNow fields. The Severity and Message key information are automatically filled in to save you time and effort. The Message key provides the correct identifier for the events, ensuring de-duplication works correctly and redundant alerts are not generated.

13. Optional: To view multiple JSON files, select the arrow above the JSON sample.
14. Optional: In the Other fields section, in your connector column, specify custom event parameters that are optional but provide additional information about the event.
    If you choose not to provide the optional information, leave the field empty.
    1. In the Description field, enter a meaningful alert description.
    2. In the Metric name field, enter a metric name that allows you to associate events with the performance metrics or KPIs that triggered the alert.
    3. In the Node field, enter a node value to be used for CI binding.
    4. In the Event time field, enter the creation time of the custom connector event.
       If the event time isn't mapped, the system will use the default event time.
    5. In the Event time settings field, select the time format and the event time zone.
       • Time format: A GlideDateTime field in UTC or GMT format, with a maximum length of 40 characters.
       • Time zone: Times are stored in Coordinated Universal Time (UTC) and are displayed globally based on the system time zone.
15. Activate and save the connector by selecting Activate and then select OK on the confirmation pop-up window.
    You can view the connector details on the Details tab and your field mappings on the Fields mapping tab.

    Note:

    You cannot modify connector details when it is active. Deactivate the connector to make any changes.

Result

After the connector is activated, events start flowing from your custom connector console into the ServiceNow instance. The plug-in extracts information from the original custom connector event message to populate the required event fields and inserts the event into the database. To see the events in your ServiceNow AI Platform instance, navigate to All Events. For more information, see View events.

What to do next

To verify that the process was successfully completed and events are flowing into the system, view the related events on the Related events tab. If the setup is successful, proceed to Add automation to establish an alert automation. For information on alert automation, see Alert automation in Service Operations Workspace for ITOM.