{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":931,"path":"api-reference/server-api-reference/TopicUtilOOBAPIScoped.md","title":"TopicUtilOOB - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# TopicUtilOOB- Scoped\n\nThe `TopicUtilOOB` script include contains functions that enable you to query and manipulate records in the Topic \\[sn\\_api\\_notif\\_mgmt\\_topic\\] table. This class operates at the service layer that interacts with the Data Access Object \\(DAO\\) class.\n\nThese functions are called when the **Get Topics** button is selected on the Topics form. If you want to change the default functionality of this script include, you must override the functions contained in this script include in the `TopicUtil` script include.\n\nBoth script includes run in the `sn_api_notif_mgmt` namespace.\n\nFor additional information on topics, see [External event management via Telecommunications API notifications](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/telecom-service-ops/telecommunications-api-notification.md).\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## TopicUtilOOB - createTopic\\(Object topicObj\\)\n\nCreates a record in the Topic \\[sn\\_api\\_notif\\_mgmt\\_topic\\] table using DAO insert.\n\nTypically you will call this function within the [validateAndInsertTopic](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/TopicUtilOOBAPIScoped.md) function that also performs various validations on the content.\n\n<table id=\"table_s5t_gxw_1zb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ntopicObj\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that contains the fields to store in the topic record. For the base implementation the object has the following format. If you modify or extend the Topics table, this object should reflect that structure. Ensure that you include any required fields.```\n\"topicObj\": {\n  \"content_query\": \"String\";\n  \"description\": \"String\";\n  \"header_query\": \"String\";\n  \"namespace\": \"String\";\n  \"topic_id\": \"String\";\n  \"topic_name\": \"String\";\n  \"type\": \"String\";\n}\n```\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|String|Sys\\_id of the created topic record.|\n\nThe following code example shows how to call this function.\n\n```\nvalidateAndInsertTopics: function(topicsResponse) {\n  if (!gs.nil(topicsResponse)) {\n    var topicsArr = topicsResponse.response;\n    for (var i = 0; i < topicsArr.length; i++) {\n      var name = topicsArr[i].name;\n      var headerQuery = topicsArr[i].headerQuery;\n      var contentQuery = topicsArr[i].contentQuery;\n      var namespace = topicsArr[i].namespace;\n      var id = topicsArr[i].id;\n      var description = topicsArr[i].description;\n      var topicGr = TopicDAO.getTopicByNameHeaderContentNamespace(name, headerQuery, contentQuery, namespace,'');\n      if (topicGr && !topicGr.hasNext()) {\n        var topicObj = new sn_tmt_core.BaseObject();\n        topicObj.setValue('topic_name', name);\n        topicObj.setValue('header_query', headerQuery);\n        topicObj.setValue('content_query', contentQuery);\n        topicObj.setValue('namespace', namespace);\n        topicObj.setValue('description', description);\n        topicObj.setValue('topic_id', id);\n        topicObj.setValue('type', Constants.TYPE_INGRESS);\n        this.createTopic(topicObj);\n      }\n    }\n  }\n}\n```\n\nThe following code example shows how to override this function.\n\n```\nvar TopicUtil = Class.create();\nTopicUtil.prototype = \n  Object.extendsObject(TopicUtilOOB, { \n\n  // Define overriding functions here. Pass a topic record object with \n  // values for a single Topic table record.\n\n  createTopic: function(topicObj){ \n    return this.topicDAO.create(topicObj); \n  } \n\n  type: TopicUtil \n\n});\n```\n\n## TopicUtilOOB - getSubFlowName\\(\\)\n\nReturns the name of the subflow to call to obtain topics from an external system.\n\nTypically this function is called from the [triggerSubflow\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/TopicUtilOOBAPIScoped.md) function. This subflow is responsible for contacting an external system and obtaining any topic records that need to be inserted in the Topics \\[sn\\_api\\_notif\\_mgmt\\_topic\\] table.\n\nThe name of the subflow is defined in `Constants.GET_TOPICS_SUBFLOW`. For the demo implementation this subflow is `sn_ind_tmf642.event_alarm_notifications_api` and generates a \"mock\" response \\(doesn't call an external system\\) to show the end-to-end processing.\n\nYou can change this functionality to include the name of your own subflow by overriding the name of the subflow to execute in the `sn_api_notif_mgmt.Constants` script include.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|Name of the subflow to use to obtain topics from an external system.|\n\nThe following code example shows how to override this function.\n\n```\nvar TopicUtil= Class.create();  \nTopicUtil.prototype = \n  Object.extendsObject(TopicUtilOOB, { \n\n  // Define overriding function here. In TopicUtilOOB it returns the flow name of a GET outbound API call that mocks the GET call.\n  // Override this function to return a flow that returns topics from an external system. \n\n  getSubflowName: function(){ \n    return <flow_name>; // Return the name here\n  } \n\n  type: TopicUtil \n\n});\n```\n\n## TopicUtilOOB - triggerSubflow\\(\\)\n\nTriggers the subflow that is responsible for obtaining topic records from an external system.\n\nThis function is called when the user selects the **Get Topics** button on the Topics form.\n\nThe name of the subflow that gets triggered is defined in `Constants.GET_TOPICS_SUBFLOW`. For the demo implementation this subflow is `sn_ind_tmf642.event_alarm_notifications_api` and generates a \"mock\" response \\(doesn't call an external system\\) to show the end-to-end processing.\n\nYou need to change this functional to include the name of your own subflow by overriding the name of the subflow to execute in the `sn_api_notif_mgmt.Constants` script include.\n\nWithin the subflow you must create a REST step, connection alias, or other implementation to provide an endpoint URL that retrieves topics from your external network. When the topics are returned by that subflow, you call the [validateAndInsertTopics](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/TopicUtilOOBAPIScoped.md) function to verify the passed back topic payload and insert/update the records in the Topic table.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows how to override this function.\n\n```\nvar TopicUtil = Class.create();\nTopicUtil.prototype = \n  Object.extendsObject(TopicUtilOOB, { \n\n  // Define overriding functions here. Override this function to call your own GET API outbound call subflow.\n  triggerSubflow: function(){\n    var result =''; // Pass the subflow here \n\n    try {\n      var flowOp = sn_fd.FlowAPI.getRunner().subflow(result).inBackground().withInputs().run();\n      if (flowOp) { \n        gs.addInfoMessage(gs.getMessage('Please refresh the list to see new Topics.'));\n      } \n    } catch (ex) {\n      gs.addInfoMessage(gs.getMessage(ex + ' Please check if the trigger is defined and passed correctly')); \n    }\n  } \n\n  type: TopicUtil \n\n});\n```\n\n## TopicUtilOOB - validateAndInsertTopics\\(Array topicsResponse\\)\n\nValidates the passed in topic record payload and inserts records in the Topic \\[sn\\_api\\_notif\\_mgmt\\_topic\\} table containing this data.\n\nThe passed topics payload is obtained from the \"GET API endpoint\" used to retrieve topics from an external system. For more information on triggering this GET API, see [triggerSubflow\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/TopicUtilOOBAPIScoped.md).\n\nYou can change this functionality to include your own validation rules and topic record fields by overriding this function in the `TopicUtil` script include.\n\n<table id=\"table_d5m_bcx_1zb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ntopicsResponse\n\n</td><td>\n\nArray of objects\n\n</td><td>\n\nTopic record payload returned by the external system through the GET API endpoint within the subflow. This payload should match the structure of the Topics \\[sn\\_api\\_notif\\_mgmt\\_topic\\] table. Each object within the array is a separate topic. For example, in the demo implementation this is:```\n\"topicResponse\": [\n  {\n    \"name\": \"String\";\n    \"header_query\": \"String\";\n    \"content_query\": \"String\";\n    \"namespace\": \"String\";\n    \"id\": \"String\";\n    \"description\": \"String\"\n  },\n  {\n    \"name\": \"String\";\n    \"header_query\": \"String\";\n    \"content_query\": \"String\";\n    \"namespace\": \"String\";\n    \"id\": \"String\";\n    \"description\": \"String\"\n  }\n]\n```\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows how to override this function.\n\n```\nvar TopicUtil= Class.create();  \nTopicUtil.prototype = \n  Object.extendsObject(TopicUtilOOB, { \n\n  // Define overriding functions here. Override this function to include custom \n  // validations on topic payload parameters and insert the record into the Topics table. \n\n  validateInsertTopics: function(topicsResponse){ \n\n    // Provide validation on the passed payload. \n    this.createTopic(topicObj);\n  } \n\ntype: TopicUtil \n\n});\n```\n\n## TopicUtilOOB - verifyTopics\\(String topicname, String headerQuery, String contentQuery, String namespace, String previousSysId\\)\n\nDetermines whether any other topic record in the Topic \\[sn\\_api\\_notif\\_mgmt\\_topic\\] table contains the specified combination of fields as its composite key, indicating a duplicate topic.\n\n<table id=\"table_thz_wdx_1zb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ntopicname\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the topic.\n\n</td></tr><tr><td>\n\nheaderQuery\n\n</td><td>\n\nString\n\n</td><td>\n\nFilter to apply to the content of the event header properties. This query defines the type of events to listen to for the associated topic. You can pass this parameter as a nested query.For example: `\"headerQuery\": \"eventType=AlarmCreateNotification&domain=Paris\",`\n\nFor additional information, refer to the [TMF688 Event Management API User Guide](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/).\n\n</td></tr><tr><td>\n\ncontentQuery\n\n</td><td>\n\nString\n\n</td><td>\n\nFilter to apply to the content of the event. This query is a deeper event filter that is used to find information such as event severity or probable cause. You can pass this parameter as a nested query.For example: `\"contentQuery\": \"event.alarm.perceivedSeverity=CRITICAL\",`\n\nFor additional information, refer to the [TMF688 Event Management API User Guide](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/).\n\n</td></tr><tr><td>\n\nnamespace\n\n</td><td>\n\nString\n\n</td><td>\n\nNamespace in which the associated topic resides. Topics can’t be duplicated within a domain, but can be contained in multiple domains.\n\n</td></tr><tr><td>\n\npreviousSysId\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Sys\\_id of the topic to update. Only pass this value when updating an existing topic.\n\n</td></tr></tbody>\n</table><table id=\"table_uhz_wdx_1zb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether another record in the Topic table contains the specified combination of fields.\n\n Possible values:\n\n-   true: Another record in the Topic table contains the combination of fields.\n-   false: No other record in the Topic table contains the combination of fields.\n\n</td></tr></tbody>\n</table>The following code example shows how to override this function.\n\n```\n\nvar TopicUtil= Class.create();\nTopicUtil.prototype = \n  Object.extendsObject(TopicUtilOOB, {\n\n  // Define overriding functions here. Override this function to provide custom validations on \n  // the passed parameters and to verify whether an insert is possible or not. \n\n  verifyTopics: function(topicname, headerQuery, contentQuery, namespace, previousSysId) { \n\n    // Write modified code here to get any combination of records present in the current Topic table. \n    // In the current implementation, the function checks if there is a duplicate topic record that contains the\n    // passed parameters. \n\n  },\n\ntype: TopicUtil \n\n});\n```\n\n"}}