Integrate with push connectors

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read

    • Integrate with a push connector to connect to an external event source. Push connectors process the collected event messages and transform them to the required event format.

    Before you begin

    Ensure that the Event Management Connectors (sn_em_connector) plugin is installed.

    Role required: evt_mgmt_admin

    Note:
    If you are upgrading a ServiceNow AI Platform instance from Paris or earlier, you can use legacy listener transform scripts. See Use legacy listener transform scripts for further information.

    About this task

    The push connectors accept event messages that are generated by external event sources.

    Configure a connector to listen to an external event source. Using a custom push connector, send the event messages through either the MID Server or the instance.

    Note:
    You can use this generic JSON target URL to collect events:https:/<<INSTANCE>>/api/sn_em_connector/em/inbound_event?source=genericJson. This URL can be used as-is and requires that an event rule be configured.

    Procedure

    1. Navigate to All > Event Management > Integrations > Push Connectors.
    2. Click New or click the push connector that you want to modify, for example, AWS or Azure.
    3. On the form, fill in the fields.
      Field Description
      Name Unique name for this push connector for easy identification.
      Description Enter a description for the use of the push connector.
      Header name Specify the name of the header that you want the value for, such as Set-Header.
      Header value The value of the header name that you want the value for, such as Set-Header.
      Type Select to send events either Instance or MID. In each case, use the URL of the selected type. See the description of the URL parameter value field.
      Active Select to enable pulling events from this external event source.
      Order Order in which an event rule is evaluated when multiple rules are defined for the same type of event. Event rules are evaluated in ascending order.
      URL parameter value
      • Send events to the instance.

        Use the URL in this format for all connectors: https://<<INSTANCE>>/api/sn_em_connector/em/inbound_event?source={URL_parameter_value}

      • Send events through the MID Server.

        Use the URL in the format:http://{MID_Server_IP}:{MID_Web_Server_Port}/api/mid/em/inbound_event?Transform={Transform_script}

        Note:
        Sending events to the MID Server requires the prior configuration of the MID WebService Event Listener extension.
    4. In the Script section:
      • If the value selected for the Type field is MID, the Transform script field appears. In this field, specify or search for the name of the MID script include that accepts event messages that the required external event source generates and that the script parses into the required event format. Use this naming convention for the script: TransformEvents_<your source>
      • If the value selected for the Type field is Instance, the Script editor appears. In the Script editor, enter the customized script that accepts event messages that the required external event source generates and that the script parses into the required event format.
      This example shows the fields that have been transformed, being added to an event form.
      (function process(/*RESTAPIRequest*/ request, body) {
	/*Function that receives a JSON object, adding all its fields to the Additional information object. The field name is a concatenation of the field key and the parent field key if it exists.*/
	function updateAdditionalInfo(event, field,jsonObject,additionalInfo) {
        for (var key in jsonObject) {
            var newKey = key;
            if (field != "") {
                newKey = field + '_' + key;
            }
			// You can do some transformation here and set fields on the event
			//if(key == "MySource")
			//   event.source = jsonObject[key];
            additionalInfo[newKey] = jsonObject[key];
        }
    }
    
    try
	{		
        gs.info("TransformEvents_generic received body:" + body);
		var jsonObject = JSON.parse(body);
        var event = new GlideRecord('em_event');
		event.source = "GenericJson"; //TODO: Need to define
        event.event_class = "GenericJsonClass"; //TODO: Need to define
        event.severity = "5";
		
        var additionalInfo = {};
        updateAdditionalInfo(event, "",jsonObject,additionalInfo);
		/*Iterates over Additional information JSON object and adds all nested objects' fields as fields of the Additional information object*/
        var notDone = true;
        while (notDone) {
            notDone = false;
            for (var key in additionalInfo) {
                if (Object.prototype.toString.call(additionalInfo[key]) == '[object Object]') {
                    notDone = true;
                    updateAdditionalInfo(event, key,additionalInfo[key],additionalInfo);
					additionalInfo[key] = "";
                }
            }
        }
		gs.info("TransformEvents_generic generated additional information:" + JSON.stringify(additionalInfo));
        event.additional_info = JSON.stringify(additionalInfo);
        event.insert();
	}
	catch(er){
		gs.error(er);
		status=500;
		return er;
	}
	return "success";
})(request, body);