{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":30609,"path":"it-operations-management/event-management/t_EMCreateCustomConnectorDefinition.md","title":"Create a custom pull connector","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create a custom pull connector\n\nYou can create a customized pull connector that requires a script, connector definition, and connector instance, to retrieve events on behalf of an event source.\n\n## Before you begin\n\nRole required: evt\\_mgmt\\_admin\n\n## About this task\n\nA 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. This procedure automatically creates a JavaScript code file using the name that you enter in the **Name** field as the filename. The JavaScript custom code that accomplishes these actions must:\n\n- Connect to an event monitoring tool.\n- Retrieve events from an event monitoring tool.\n- Send events to the Event \\[em\\_event\\] table using a web service API. See [REST API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/c_RESTAPI.md).\n\nEach connector definition is specific to an event source vendor. The connector definition specifies the MID Server script include that pulls events from the external event source. In addition, the connector definition specifies what connector instance value parameters are needed to connect to the external event source host.\n\n## Procedure\n\n1. Create a custom MID Server script include.\n\n This example uses Groovy \\(deprecated\\). In place of a script include in Groovy, it is recommended to use JavaScript.\n\n 1. Implement these methods:\n\n - @Override OperationStatus testConnection\\(\\)\n - @Override OperationStatus execute\\(\\)\n 2. Design the class to extend the ThirdPartyConnector.\n\n ```\n \n public class HypericConnector extends ThirdPartyConnector\n \n ```\n\n 3. Import platform classes for event creation, sending, logging, and third-party connector base classes.\n\n ```\n \n package com.service_now.mid.probe.tpcon.test\n \n import com.glide.util.Log\n import com.service_now.mid.MIDServer\n import com.service_now.mid.probe.event.IEventSender\n import com.service_now.mid.probe.event.SNEventSender\n import com.service_now.mid.probe.tpcon.OperationStatus\n import com.service_now.mid.probe.tpcon.OperationStatusType\n import com.service_now.mid.probe.tpcon.ThirdPartyConnector\n import com.snc.commons.eventmgmt.Event\n \n ```\n\n 4. Connect to the data collector, such as SCOM or VMware vRealize Hyperic \\(Hyperic\\), with the API provided by the collector.\n\n 5. Use the **context** parameters to set the event field values that came from a connector instance.\n\n ```\n \n def authString = (**context**.username + ':'+ **context**.password).getBytes().encodeBase64().toString()\n def urlStr = 'http://'+**context**.host + ':' + **context**.**parameters**.port + '/' + apiFunction\n \n ```\n\n 6. Implement the execute function in the script.\n\n It reads events from the connector using its API to create Event objects and send them to the ServiceNow instance. For example:\n\n ```\n \n GPathResult alertsResponse1 = readAlerts(**'hqu/hqapi1/alert/find.hqu?begin=' + lastSignatureStr +\n '&end='+ tillStr +'&count=1000000&severity=1&inEscalation=false&notFixed=false'**);\n **Event event = new Event\\(\\)**\n event.emsSystem = context.name\n event.source = \"Hyperic\"\n event.description = it.@reason\n event.type = it.@name\n ...\n IEventSender eventSender = MIDServer.getSingleton(SNEventSender.class)\n for (Event event : list) {\n **eventSender.sendEvent\\(event\\)**\n }\n \n ```\n\n2. Navigate to **MID Server** > **MID Server Script Files** and create a script.\n\n3. Specify the **Parent** field as **Groovy**, complete the form as appropriate, and then click **Submit**.\n\n4. Navigate to **Event Management** > **Integrations** > **Connector Definitions** and create a connector definition.\n\n5. In the **Groovy script to run** field, select the MID Server script file, complete the form as appropriate.\n\n In addition to **username** or **host**, you can add any other parameter, for example, **port**, and then click **Submit**.\n\n6. Navigate to **Event Management** > **Integrations** > **Connector Instances** and create a connector instance.\n\n7. In the **Connector definition** field, select the connector definition, complete the form as appropriate, and then click **Submit**.\n\n8. To confirm or debug the script, use debug printouts from Groovy to the MID Server log.\n\n9. To monitor incoming events using the custom connector instance, navigate to **ECC** > **Queue** and filter on **ConnectorProbe**.\n\n10. Create a custom connector definition.\n\n 1. Navigate to **All** > **Event Management** > **Integrations** > **Connector Definitions**.\n\n 2. Click **New**.\n\n 3. In the **Name** field, type a descriptive name for the connector definition.\n\n 4. In the **Script type** field, select **Javascript**.\n\n 5. Right-click the form header and select **Save**.\n\n The **Javascript to run** field is automatically populated with the name of the JavaScript template file.\n\n11. To edit the default JavaScript file, click the information icon \\(\\[Omitted image \"information\\_icon.png\"\\] Alt text: Information icon\\) to the right of the JavaScript file name and follow these steps:\n\n 1. Specify the information required for the **testConnection** function.\n\n This function tests the connector definition to verify if the connection to the target is valid.\n\n 2. Specify the information required for the **execute** function.\n\n This function retrieves the information from the external source.\n\n 3. Specify the information required for the **retrieveKpi** function.\n\n This function retrieves the metric data from the external source.\n\n12. You can replace the default JavaScript with your JavaScript code.\n\n13. Fill in the fields, as appropriate.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nDefault schedule\n\n\n\nThe number of seconds between attempts to receive events.\n\n
\n\nBi-directional\n\n\n\nSpecify to enable the external monitoring system to be updated if the alert is changed. There is default implementation for SCOM.\n\n
\n\nAlert field identifier\n\n\n\nSpecify the alert field that, if changed manually, causes the external monitoring system to be updated. **Note:** This field appears only if **Bi-directional** is selected.\n\n
\n\nCollect metrics\n\n\n\nSelect to enable the collection of metrics. **Note:** Metrics are collected only for SCOM external event sources.\n\n
\n\nMetrics collection default schedule \\(seconds\\)\n\n\n\nSpecify the number of seconds of information that must be collected. The default is 10 seconds. **Note:** This field appears only if **Collect metrics** is selected.\n\n
\n\nConnector Parameters\n\n\n\nSpecify the parameters to enable communication with an event server.\n\n
\n\nConnector Definition to MID Server Capabilities\n\n\n\nThe MID Server name to process events from the event server. If not specified, an available MID Server is used.\n\n
14. Click **Submit**.\n\n\n**Parent Topic:**[Configure Event Management connectors](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-operations-management/event-management/connectors-and-listeners.md)\n\n"}}