{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":308,"path":"api-reference/developer-guides/event-mgmt-notif_dev-guide.md","title":"Event Notification Management Open API Developer Guide","bundle":null,"doc_type":null,"release":"australia","body":"\n# Event Notification Management Open API Developer Guide\n\nUse the Event Notification Management Open API to create, update, and delete event records in the Events \\[em\\_event\\] table.\n\nThis developer guide provides information on how to extend the Event Notification Management Open API to make various customizations.\n\n## Extending the Event Notification Management Open API\n\nYou can extend and modify the functionality of the Event Notification Management Open API by editing its associated script include files.\n\nThe following are the script includes that the Event Notification Management Open API uses to process event notification requests passed to the API:\n\n-   `AlarmAPIProcessorOOB`: Contains helper functions that support functions in the `TMFTopicEventAPIUtil` script include. For additional information on the `AlarmAPIProcessorOOB` script include, see the [Alarm Management Open API Developer Guide](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/developer-guides/alarm-mgmt_dev-guide.md).\n-   `AlarmAPIProcessor`: An empty script include file. Update this file to define any functions that you want to override in the `AlarmAPIProcessorOOB` script include.\n-   `JSONSchemaValidation`: Contains functions to handle the validation of schemas for the payload defined in the `TMFAlarmAPIConstants` script include. This script include is under the tmt\\_core plugin.\n-   `TMFAlarmAPIConstants`: Contains constants and required parameter information. It also contains the schemas for the payloads passed in the Event Notification Management Open endpoint.\n-   [`TMFTopicEventAPIUtilOOB`](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/tmftopiceventapiutiloobScopedAPI.md): Contains functions to handle API requests that are triggered by [external trigger definition flows](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/set-up-flow-ihub.md) that have the actions `AlarmCreateNotification`, `AlarmChangeNotification`, `AlarmDeleteNotification` which create, update, and delete events.\n-   `TMFTopicEventAPIUtil`: An empty script include file. Update this file to define any functions that you want to override in the `TMFTopicEventAPIUtilOOB` script include.\n\nThe following sections provide examples of some of the customizations that you can make to the Event Notification Management Open API processing by extending/modifying these script include files.\n\n### Required parameters\n\nThe Event Notification Management API utilizes JSON schemas to define required parameters. These JSON schemas are defined in the `TMFAlarmAPIConstants` script include. These schemas are used to validate whether request payloads are valid. These schemas are not directly referenced in the script includes, but are returned by the following functions in the TMFTopicEventAPIUtilOOB script include:\n\n-   `getAlarmCreateEventSchema()`: Returns the validating schema for creating an event.\n-   `getAlarmDeleteEventSchema()`: Returns the validating schema for deleting an event alarm.\n-   `getAlarmChangeEventSchema()`: Returns the validating schema for changing fields in an event.\n\nTo override the existing schemas, define new schemas in the `TMFTopicEventAPIUtilOOB` script include and override the `TMFTopicEventAPIUtil` script include functions.\n\nFor example:\n\n```\nvar TMFTopicEventAPIUtil = Class.create();\nTMFTopicEventAPIUtil.prototype = Object.extendsObject(TMFTopicEventAPIUtilOOB, {\n\t// Define overriding functions here\t\n\t// Define getAlarmCreateEventSchema here to override OOTB function in TMFTopicEventAPIUtilOOB\n\tgetAlarmCreateEventSchema: function() {\n\t\treturn JSON.parse(TMFTopicEventAPIUtil.CUSTOMIZED_SCHEMA);\n\t},\n    type: ‘TMFTopicEventAPIUtil’\n});\n\n// New schema\nTMFTopicEventAPIUtil.CUSTOMIZED_SCHEMA = \"{\n  \\\"title\\\":\\\"AlarmCreateEvent\\\",\n  \\\"type\\\":\\\"object\\\",\n  \\\"properties\\\":{\n    \\\"event\\\":{\n      \\\"type\\\":\\\"object\\\",\n      \\\"properties\\\":{\n        \\\"alarm\\\":{\n          \\\"type\\\":\\\"object\\\",\n          \\\"properties\\\":{\n            \\\"id\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"href\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"externalAlarmId\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"alarmType\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"perceivedSeverity\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"probableCause\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"alarmedObject\\\":{\n              \\\"type\\\":\\\"object\\\",\n              \\\"properties\\\":{\n                \\\"id\\\":{\n                  \\\"type\\\":\\\"string\\\"\n                },\n                \\\"href\\\":{\n                  \\\"type\\\":\\\"string\\\"\n                }\n              },\n              \\\"required\\\":[\n                \\\"id\\\"\n              ]\n            },\n            \\\"crossedThresholdInformation\\\":{\n              \\\"type\\\":\\\"object\\\",\n              \\\"properties\\\":{\n                \\\"thresholdId\\\":{\n                  \\\"type\\\":\\\"string\\\"\n                }\n              },\n              \\\"required\\\":[\n                \\\"thresholdId\\\"\n              ]\n            },\n            \\\"affectedService\\\":{\n              \\\"type\\\":\\\"array\\\",\n              \\\"properties\\\":{\n                \\\"id\\\":{\n                  \\\"type\\\":\\\"string\\\"\n                },\n                \\\"href\\\":{\n                  \\\"type\\\":\\\"string\\\"\n                }\n              },\n              \\\"items\\\":{\n                \\\"type\\\":\\\"object\\\",\n                \\\"required\\\":[\n                  \\\"id\\\"\n                ]\n              }\n            },\n            \\\"sourceSystemId\\\":{\n              \\\"type\\\":\\\"string\\\"\n            },\n            \\\"specificProblem\\\":{\n              \\\"type\\\":\\\"string\\\"\n            }\n          },\n          \\\"required\\\":[\n            \\\"externalAlarmId\\\",\\\"alarmType\\\",\\\"perceivedSeverity\\\",\\\"probableCause\\\",\\\"sourceSystemId\\\",\\\"alarmedObject\\\"\n          ]\n        }\n      },\n      \\\"required\\\":[\n        \\\"alarm\\\"\n      ]\n    }\n  },\n  \\\"required\\\":[\n    \\\"event\\\"\n  ]\n}\";\n```\n\n### Request body validation\n\nTo perform additional validation on the request body, override the following functions in the `TMFTopicEventAPIUtilOOB` script include. These functions are called by the specified functions in the same script include.\n\n-   `verifyAlarmCreateEventPayload()`: Called by `processAlarmCreateEvent()`.\n-   `verifyAlarmDeleteEventPayload()`: Called by `processAlarmDeleteEvent()`.\n-   `verifyAlarmChangeEventPayload()`: Called by `processAlarmChangeEvent()`.\n\nAll of these functions return success by default. If a helper function returns an error, it stops the API operation.\n\nTo apply custom validations, override the helper functions in the `TMFTopicEventAPIUtilOOB` script include with identical function names and parameters in the `TMFTopicEventAPIUtil` script include.\n\nIn this example, a function in a custom `TMFTopicEventAPIUtil` script include overrides the default function in the `TMFTopicEventAPIUtilOOB` script include to perform validation on the name attribute.\n\n```\nvar TMFTopicEventAPIUtil = Class.create();\nTMFTopicEventAPIUtil.prototype = Object.extendsObject(TMFTopicEventAPIUtilOOB, {\n\n    // Define overriding functions here\n    verifyAlarmCreateEventPayload: function(eventPayload,responseObject){\n\n        // Returning error status terminates the POST request\n        // Make sure to assign error message and reason\n        if (eventPayload.type != \"unique\") {\n            responseObject.setMessage(\"Failed\");\n            responseObject.setReason(\"No reason needed\");\n            return responseObject.status = “error”;\n        }\n    },\n\t\n    type: ‘TMFTopicEventAPIUtil’\n});\n```\n\n### Request body subscription validation\n\nTo modify the request body subscription validation for the API, you need to override the `validateSubscription()` function in the `TMFTopicEventAPIUtilOOB` script include. This function validates whether the callbackURL you are using to create the event notification is registered and determines whether the **eventType** is registered for the raised callback. This function is called by the processAlarmCreateEvent\\(\\), processAlarmDeleteEvent\\(\\), and processAlarmChangeEvent\\(\\) functions which are also in the `TMFTopicEventAPIUtilOOB` script include.\n\n### Field mapping\n\nWhen creating or updating records, the Event Notification Management Open API maps request body parameters to Event record fields. When retrieving records, the API maps Event record fields to response object attributes.\n\nThe `TMFTopicEventAPIUtilOOB` script include contains the following functions that map change, create, and delete requests, based on the value in the **eventType** parameter, to a record in the Event \\[em\\_event\\] table.\n\n-   mapAlarmChangeObjectToEvent\\(\\)\n-   mapCreateAlarmObjectToEvent\\(\\)\n-   mapDeleteAlarmObjectToEvent\\(\\)\n\nYou can customize field mappings to add and retrieve data for additional Event \\[em\\_event\\] table fields or change the default field mappings. To work with mappings, create functions with identical names and parameters in `TMFTopicEventAPIUtil` to override `TMFTopicEventAPIUtilOOB` mapping functions.\n\n"}}