Common Incident Data Model

When you send incident-related data from other products to IBM Z® ChatOps, you must make sure that your data format is correct. Only valid incident data is accepted. Invalid data or data that does not conform to the correct format will be rejected with status code 400 and status message BNZCOM007E.

Refer to the JSON data model below to see the data structure and required fields and values.

{
    "id": "Incident ID",
    "summary": "Incident title",
    "description": "Incident description",
    "priority": "high | medium | low",
    "severity": "fatal | critical | major | minor | low",
    "category": "incident | event | alert | forecast",
    "dateTime": {
        "occurred": "Incident occurred timestamp in UTC (Coordinated Universal Time) format",
        "reported": "Incident reported timestamp in UTC (Coordinated Universal Time) format"
    },
    "location": {
        "domainName": "Name of the automation or NetView domain where the incident occurred",
        "sysplexName": "Name of the sysplex where the incident occurred",
        "systemName": "Name of the system where the incident occurred",
        "smfId": "SMF ID of the system where the incident occurred",
        "subsystemName": "Name of the subsystem where the incident occurred",
        "resourceName" : "Name of the resource where the incident occurred",
        "jobName" : "Name of the job where the incident occurred",
        "processId": "Id of the process where the incident occurred",
        "serverName": "Name of the server where the incident occurred"
    },
    "status": "new",
    "reportedBy": {
        "product": "Name of the product reported the incident, e.g. IZOA, SA z/OS, OMEGAMON, Netcool, ServiceNow",
        "userName": "Name of the user reported the incident"
    },
    "chatToolPosted": {
        "teams": [
            {
                "id": "Id of the team that the incident is posted to", 
                "name": "Name of the team that the incident is posted to"
            }
        ],
        "channels": [
            {
                "id": "Id of the channel that the incident is posted to", 
                "name": "Name of the channel that the incident is posted to"
            }
        ],
        "persons": [
            {
                "id": "Id of the person that the incident is posted to", 
                "name": "Name of person team that the incident is posted to"
            }
        ]
    },
    "links": [
        {
            "name": "Name of the link to be shown",
            "url": "URL of the link to be shown",
            "category": "image | webpage",
            "description": "Detailed description of the link to be shown"
        }
    ],
    "customizedFields": [
        {
          "name": "Name of this customized field",
          "value": "Value of this customized field",
          "description": "Description of this customized field"
        }
    ]
}

In the data model above, some fields are required and some are optional. You must provide a value for the required fields so that Z ChatOps can accept and post your incident. Required fields are id, summary, priority, severity, category, dateTime, location, status, reportedBy, and chatToolPosted. You must provide values to these fields to make sure the data structure is complete. For detailed explanation, see the instructions below.

For the field dateTime, the value occurred is required. You must provide the time of when the incident occurred or will occur in the future as a prediction.
For the field location, you must provide at least one location-specific value to tell where the reported incident took place or will take place in the future as a prediction. It can be any item listed in the data model. If you provide domainName, systemName, smfId,and resourceName of IBM Z System Automation, in the incident view, you can see the links that direct to the IBM® Service Management Unite page of the IBM Z System Automation resource. You can also use the drop down in the chat tool to see the details of the resources.
For the field reportedBy, the value product is required. You can provide any product name that reported the incident, for example, IZOA (IBM Z Operations Analytics), SA z/OS® (IBM Z System Automation), OMEGAMON® (IBM OMEGAMON), Netcool® (Tivoli® Netcool), and ServiceNow.
For the field chatToolPosted:
- For chat tools:
  If you want to send incidents to channels of a chat tool, you must fill in the channels field. The specific name is also required so that ChatOps knows where to post the incident. If you want to post to multiple channels, you can add more channels to this array.
  Note: [Mattermost users only] If you do not know the channel name, you can select the channel you want to post incident in and get the channel link. Paste the link into a text editor, and then you can find the channel name.
  Figure 1. Copy link
  
  Figure 2. Channel name
- For embedded chat window:
  If you want to send incidents to a embedded chat window, you must fill in the persons field. The ID and Name are the ID and name of your integrating web application.
The links field is optional. You can define this field to add useful links for users. To define the links, you must enter the values for name, url, and category.

The customizedFields field is optional. You can define this field to provide a link that allows you to view more details about the OMEGAMON resource in IBM Service Management Unite, workload related resource in IBM Z Workload Scheduler, and drop down to see the details of the resources in IBM Z ChatOps. If you have input for these two fields, the values name and value become required. Note that you must define the component first and then specify the link properties. Review the following table for detailed instructions.

Table 1.
Component	Properties	Description
zos	`lpar\|lpar name\|location.systemName`	If the component is `zos`, the `lpar\|lpar name\|location.systemName` property is required. Once defined, a link to the resource of the defined LPAR name on IBM Service Management Unite is provided in the response.
cics	`[cicsplex\|cicsplex name], [cics region\|cics region name]`	The `cicsplex name` and `cics region name` are optional. If you want to provide a link to a CICSPlex® resource on IBM Service Management Unite in the response, then the `cicsplex\|cicsplex name` property is required. If you want to provide a link to a CICS® region resource on IBM Service Management Unite in the response, then `cics region\|cics region name` is required, and `location.smfid` and `cicsplex name` are optional. If your `cics region name` is not unique, to provide an accurate link, you must define the `location.smfid` property or the `cicsplex name` property.
network	`network job\|network job name\|location.jobName`	If you define the component as `network`, the network job name is required. Once defined, a link to the resource of the defined job name on SMU is provided in the response.
storage	`storage group\|storage group name, [location.smfId], [storage volume\|storage volume name], [address space\|address space name]`	If you define the component as `storage`, the storage group name is required. The other properties are optional, but if you want to add the resource link of the volume name on SMU , you must define the `smfId`, `storage volume name`, and `address space name` properties at the same time.
ims	`ims id`	If you define the component as `ims`, the IMS ID is required. Once defined, a link to the resource of the defined IMS ID on SMU is provided in the response.
jvm	`job\|job name\|location.jobName`	If you define the component as `jvm`, the job name is required. Once defined, a link to the resource of the defined job name on SMU is provided in the response.
mq	`queue manager\|queue manager name`	If you define the component as `mq`, the queue manager name is required. Once defined, a link to the resource of the defined queue manager on SMU is provided in the response.
db2	`db2 id`	If you define the component as `db2`, the Db2® ID is required. Once defined, a link to the resource of the defined Db2 ID on SMU is provided in the response.
izws	`location.subsystemName \| owsid \| ojobname \| oadid`	If the component is `izws`, the `location.subsystemName` property is required. Once defined, the link to the resource of the defined engine name on IBM Z Workload Scheduler is provided in the response. The `owsid` property is optional. Once defined, the link to the resource of the defined workstation name on IBM Z Workload Scheduler is provided in the response. The `ojobname` property is optional. Once defined, the link to the resource of the defined job name on IBM Z Workload Scheduler is provided in the response. The `oadid` property is optional. Once defined, the link to the resource of the defined job stream name on IBM Z Workload Scheduler is provided in the response.

Here is an example for defining links to CICS regions.

"customizedFields": [
    {
     "name": "component",
     "value": "cics"       
    },
    {
     "name": "cicsplex",
     "value": "PLEX01"
    },
    {
     "name": "cics region",
     "value": "CICST01A"
    }
]