{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":303,"path":"api-reference/developer-guides/alarm-mgmt_dev-guide.md","title":"Alarm Management Open API Developer Guide","bundle":null,"doc_type":null,"release":"australia","body":"\n# Alarm Management Open API Developer Guide\n\nUse the Alarm Management Open API to create and update data in the Events \\[em\\_event\\] table.\n\nThis developer guide provides information on how to extend the [Alarm Management Open API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/alarm-open-api.md) to make various customizations.\n\n## Extending the Alarm Management Open API\n\nThe Alarm Management Open API can be extended by editing script includes.\n\nThese script includes should only be edited with an understanding of the consequences of the changes.\n\n-   `TMFAlarmAPIConstants`: Contains constants and required parameter information.\n-   `TMFAlarmAPIUtil`: Contains functions to handle API requests.\n-   `AlarmAPIProcessorOOB`: Contains helper functions that support functions in `TMFAlarmAPIUtil`.\n-   `AlarmAPIProcessor`: An empty script include file. Use this file to define any functions that you want to override from `AlarmAPIProcessorOOB`.\n\nExtend the Alarm Management Open API to make the following customizations.\n\n### Required parameters\n\nThe Alarm Management API utilizes JSON schemas to hold required parameters information. 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 referenced directly in script includes and are returned by the following methods in the AlarmAPIProcessorOOB script include:\n\n-   `getCreateEventSchema`: Returns the validating schema for creating an event.\n-   `getClearEventSchema`: Returns the validating schema for clearing an event alarm.\n-   `getPatchEventSchema`: Returns the validating schema for patching an event.\n\nTo override existing schemas, define new schemas in the `AlarmAPIProcessor` script include and override the `AlarmAPIProcessorOOB` script include methods.\n\n```\nvar AlarmAPIProcessor = Class.create();\nAlarmAPIProcessor.prototype = Object.extendsObject(AlarmAPIProcessorOOB, {\n\t// Define overriding functions here\n\t\n\t// Define getCreateEventSchema here to override OOTB method in AlarmAPIProcessorOOB\n\tgetCreateEventSchema: function() {\n\t\treturn JSON.parse(AlarmAPIProcessor.CUSTOMIZED_SCHEMA);\n\t},\n    type: 'AlarmAPIProcessor'\n});\n\n// Define a new schema\nAlarmAPIProcessor.CUSTOMIZED_SCHEMA = \"{\\\"title\\\":\\\"CreateAlarm\\\",\\\"type\\\":\\\"object\\\",\n\\\"properties\\\":{\\\"externalAlarmId\\\":{\\\"type\\\":\\\"string\\\"},\\\"alarmType\\\":{\\\"type\\\":\\\"string\\\"},\n\\\"perceivedSeverity\\\":{\\\"type\\\":\\\"string\\\"},\\\"probableCause\\\":{\\\"type\\\":\\\"string\\\"},\n\\\"alarmedObject\\\":{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"id\\\":{\\\"type\\\":\\\"string\\\"},\n\\\"href\\\":{\\\"type\\\":\\\"string\\\"}},\\\"required\\\":[\\\"id\\\"]},\\\"sourceSystemId\\\":{\\\"type\\\":\\\"string\\\"}},\n\\\"required\\\":[\\\"externalAlarmId\\\",\\\"alarmType\\\",\\\"perceivedSeverity\\\",\\\"probableCause\\\",\n\\\"alarmedObject\\\",\\\"sourceSystemId\\\"]}\";\n```\n\n### Request body validation\n\nTo perform additional validation on the request body, override the following functions in the `AlarmAPIProcessorOOB` script include  . These functions are called by the specified functions in the `TMFAlarmAPIUtil` script include.\n\n-   `verifyCreateEventPayload()` - Called by `processCreateEvent()`.\n-   `verifyClearEventPayload()` - Called by `processClearEvent()`.\n-   `verifyPatchEventPayload()` - Called by `processPatchEvent()`.\n\nAll of these functions return `true` by defalut. If a helper function returns `false` , it stops the API operation.\n\nTo apply custom validations, override AlarmAPIProcessorOOB helper functions with identically-named function names and parameters in AlarmAPIProcessor. The new AlarmAPIProcessor functions are called by TMFAlarmAPIUtil to replace the default AlarmAPIProcessorOOB helper functions.\n\nIn this example, a function in a custom AlarmAPIProcessor script include overrides a default function in AlarmAPIProcessorOOB to perform validation on the name attribute.\n\n```\nvar AlarmAPIProcessor = Class.create();\nAlarmAPIProcessor.prototype = Object.extendsObject(AlarmAPIProcessorOOB, {\n\t// Define overriding functions here\n\t\n    verifyCreateEventPayload: function(eventPayload, apiResponseProcessor){\n        // Returning false terminates the POST request\n        // Make sure to assign error message and reason\n        if (eventPayload.type != \"unique\") {\n            apiResponseProcessor.setMessage(\"Failed\");\n            apiResponseProcessor.setReason(\"No reason needed\");\n            return false;\n        }\n    },\n\t\n    type: 'AlarmAPIProcessor'\n});\n```\n\n### Additional REST operations\n\nTo create additional operations beyond the existing GET, PATCH, and POST operations, [create additional scripted REST resources](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/t_CreateAScriptedRESTAPIResource.md) for the Alarm Management Open API. The logic of the new scripted REST resources should be consistent with the existing operations. Define functions for the new operations in TMFAlarmAPIUtil.\n\n### Field mapping\n\nWhen creating or updating records, the Alarm Management Open API maps request body parameters to event record fields. When retrieving records, the API maps record fields to response object attributes.\n\nThe AlarmAPIProcessorOOB script include contains the following functions to map a PATCH or POST request body to a record in the Event \\[em\\_event\\] table.\n\n-   `mapCreateAlarmObjectToEvent()`\n-   `mapClearAlarmObjectToEvent()`\n-   `mapPatchAlarmObjectToEvent()`\n\nIt also contains the following functions to map an event GlideRecord to a JSON response object for GET, PATCH, or POST requests.\n\n-   `modifyCreateEventResponse()`\n-   `modifyClearEventResponse()`\n-   `modifyPatchEventResponse()`\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 AlarmAPIProcessor to override AlarmAPIProcessorOOB mapping functions. TMFAlarmAPIUtil uses these AlarmAPIProcessor functions to replace the default AlarmAPIProcessorOOB mapping functions.\n\nIn the following example, two AlarmAPIProcessor functions override the default functions in AlarmAPIProcessorOOB to change the **Type** field mapping and add a mapping for the **Severity** field.\n\n```\nvar AlarmAPIProcessor = Class.create();\nAlarmAPIProcessor.prototype = Object.extendsObject(AlarmAPIProcessorOOB, {\n\t// Define overriding functions here\n\t\n    // Function name and parameters must be identical to the function it overrides\n    mapCreateAlarmObjectToEvent: function(eventGr, eventObject){\n        // Override default mapping for the severity field\n        eventGr.severity = \"High\";\n    },\n\n    modifyCreateEventResponse: function(eventGr, eventObject){\n        // Override default mapping for the type field\n        eventGr.type = \"Customized Event\"; \n    },\n\t\n    type: 'AlarmAPIProcessor'\n});\n```\n\n"}}