Date Format

Any modifications to the date format used by all dates must be consistently applied to all consumers of the APIs. API serializes and deserializes the date attributes stored in OpenSearch indexes using following date format:

impactanalysis:
  api:
    dateformat: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

Event Status

Service Impact Analysis API supports the following types of events:

• RAISED: This event type is for new events.
• UPDATED: This event type is for existing events with updated information.
• CLEARED: This event type is for events that have been Closed.
• REJECTED: This event type is for events that are invalid and are rejected through Reject Event action available on Service Impact Analysis UI.

  Note:

  Rejected events move to a different index called smartsearch-rejected-event and are not deleted. Rejecting events is to isolate invalid events that are submitted to the system.

The following event statuses, apart from REJECTED are standard TMF642 event statuses. These event status mappings are part of Unified Assurance integration and should not be changed:

impactanalysis:
  event-status:
    CLEARED: CLEARED
    RAISED: RAISED
    UPDATED: UPDATED
    REJECTED: REJECTED

Event Severity

Service Impact Analysis API and ATA support various types of event severities on a Device. The severities from most severe to least severe are CRITICAL (1), MAJOR (5), WARNING (10), INTERMEDIATE (15), MINOR (20), CLEARED (25), and None (999). Internally, a numeric value is used to identify the severity hierarchy. The top three most severe events (CRITICAL, MAJOR, WARNING) are tracked in ATA.

The following event severities are standard TMF642 event severities. These event severity mappings are part of Unified Assurance integration and should not be changed:

impactanalysis:
  severity:
    CLEARED: CLEARED
    INDETERMINATE: INDETERMINATE
    CRITICAL: CRITICAL
    MAJOR: MAJOR
    MINOR: MINOR
    WARNING: WARNING

Impact Calculation Thread Pool Size

The impact calculation thread pool size defines the maximum number of open REST requests at a time to UIM for fetching impacts.

impact:
  threadPoolSize: 10

SmartSearch and OpenSearch Related Configurations

The configurations related to SmartSearch and OpenSearch are as follows:

• smartsearch.lang: The value of SmartSearch internal field used in lang pipeline processing. The only supported value is en.
• smartsearch.tenantId: The value of SmartSearch internal field for search tenancy. The only supported value is tenant1.
• smartsearch.fetchSize: Defines the number of documents that should be fetched at a time in memory from SmartSearch for processing during bulk operations. The maximum limit for this value is 10000.
• smartsearch.coolDownInterval: Defines the cool-down interval in milliseconds for OpenSearch index after each batch of documents is processed (bulk updates and deletes).

smartsearch:
  language: en
  tenantId: tenant1
  fetchSize: 1000
  coolDownInterval: 1000

Events Related Configurations

The configuration related to events are as follows:

• event.idPrefix: Defines the prefix used during document id generation for OpenSearch event index.
• event.reportPrefix: Defines the prefix used during report id generation when the analysis status of the event transitions to COMPLETED.
• event.defaultOwner: Defines the default owner name value to be used in case the owner field is not populated during event creation.

event:
  idPrefix: UE
  reportPrefix: REP
  defaultOwner: Unassigned

Configuring Incoming Channel

For performance improvement tuning uncomment or add the following in the alarm-consumer-static-config.yaml file to override the default configuration:

• Edit max.poll.interval.ms to increase or decrease the delay between invocations of poll() while using the consumer group management.
• Edit max.poll.records to increase or decrease the maximum number of records returned in a single call to poll().

  mp.messaging:
    incoming:
      toFaultChannel:
  #      max.poll.interval.ms: 300000
  #      max.poll.records: 25
      toRetryChannel:
  #      max.poll.interval.ms: 300000
  #      max.poll.records: 25
      toDltChannel:
  #      max.poll.interval.ms: 300000
  #      max.poll.records: 100

Impact Analysis API

The impact analysis API is as follows:

impactAnalysis:
  url: http://localhost:8084

Resource Type Mappings

The TMF639ResourceType-mappings.yaml file provides mapping from protocol specific to TMF639 sub-resource types supported by UIM. This mappings file should be updated only when the alarm event is not sent with resource type values supported by the UIM.

The alarmedObject.@referredType element value should be representing the TMF639 sub-resource type, which is supported by UIM. You must use this resource mapping extensibility only when the assurance system does not send the resource types which UIM can understand.

For example: Sending some protocol specific object type. The Corba protocol has object types as OT_EQUIPMENT, OT_MANAGED_ELEMENT, and so on.

When an alarm event does not contain UIM's TMF639 sub-resource types, map the protocol-native resource type to its TMF639 sub-resource type in the TMF639ResourceType-mappings.yaml file and upgrade the alarm consumer service.

The TMF639 resource types supported in alarm consumer are: PhysicalDevice, Equipment, PhysicalPort, and DeviceInterface.

deviceTypeMapping:
  PhysicalDevice:
    - OT_MANAGED_ELEMENT
  Equipment:
    - OT_EQUIPMENT
    - CHASSIS
    - BACKPLANE
    - MODEL
    - RACK
    - SHELF
    - CARD
  PhyiscalPort:
    - OT_PHYSICAL_TERMINATION_POINT
    - PORT
    - PTP
  DeviceInterface:
    - OT_CONNECTION_TERMINATION_POINT
    - CTP
  Pipe:
  Connectivity:

Customizing Device Mapping

By default, the device or sub-device is found by name (using the value from the alarmedObject.id). Configuration can be updated to check the device or sub-device by other fields (such as Id or deviceIdentifier) when the alarm event is having id or deviceIdentifier values as part of the alarmedObject.id element.

In order to use different lookup fields, configure the deviceMappings.inventory.lookupFields sub-structure accordingly in the alarm-consumer-static-config.yaml file and upgrade the alarm consumer service.

A sample file is provided in COMMON_CNTK\charts\ata-app\charts\ata\config\alarm-consumer location. If you are modifying it for the first time, rename the alarm-consumer-static-config.yaml.sample file to alarm-consumer-static-config.yaml and update the values accordingly. The supported lookup fields are name, id, and deviceIdentifier. A sample sub-structure is as follows:

deviceMapping:
  inventory:
    lookupFields: # The lookup is done according to the provided order. Supported values are name, id & deviceIdentifier
    - name 
    - id
    - deviceIdentifier
  customizeDeviceLookup:
    enabled: false

The above YAML configuration is used to change the device mapping.

import groovy.json.JsonSlurper
/**
 * The default delimiter is which is available via method argument named "delimiter".
 * The "alarmedObject" parameter is extracted from alarmedObject sub-section as String from the Alarm.
 * The "alarm" parameter is the complete alarm information received as String.
 * The return type must be type of Map of String as key and value.
 */
def getDeviceIds(delimeter,alarmedObject,alarm){
  def jsonSlurper = new JsonSlurper()
  def alo = jsonSlurper.parseText(alarmedObject)
  def aloId = alo.id
  def referredType = alo.'@referredType'
  def device = aloId.split(delimeter)
  def deviceInfo = [:]
  //Custom implementation starts.  The following is default implementation which return the keys.
  //node and subNode should be the name of which will be searched in ATA/Inventory databases.
  if (device.size() == 2) {
    //node-name
    deviceInfo["node"] = device[0]
    //subNode-name
    deviceInfo["subNode"] = device[1]
  } else {
     deviceInfo["node"] = device[0]
     deviceInfo["subNode"] = ""
  }
  //The referredType must match with TMF639ResourceType-mappings.yaml mapping file.  Blank value considered as PhysicalDevice
  deviceInfo["referredType"] = referredType
  //Custom implementation ends
  return deviceInfo;
}

Alarmed Object Extension

If the alarmedObject sub-structure has different values or format than the above sub-sections, the provided Groovy file has to be modified to parse and return the identifier. This groovy custom code runs when the deviceMapping.customizedDeviceLoop.enabled element value is configured to true in the alarm-consumer-static-config.yaml file.

Update the out-of-the-box provided Groovy code and the system returns the node/sub-node identifier and referredType values from this Groovy file. This groovy file is provided in COMMON_CNTK\charts\ata-app\charts\ata\config\alarm-consumer location. Enable the deviceMapping.customizedDeviceLoop.enabled value to true and update the alarm consumer service.

The sample implementation is as follows:

/*
* Copyright (c) 2024. Oracle and/or its affiliates. All rights reserved.
*/
import groovy.json.JsonSlurper
/**
 * The default delimiter is which is available via method argument named "delimiter".
 * The "alarmedObject" parameter is extracted from alarmedObject sub-section as String from the Alarm.
 * The "alarm" parameter is the complete alarm information received as String.
 * The return type must be type of Map of String as key and value.
 */
def getDeviceIds(delimeter,alarmedObject,alarm){
  def jsonSlurper = new JsonSlurper()
  def alo = jsonSlurper.parseText(alarmedObject)
  def aloId = alo.id
  def referredType = alo.'@referredType'
  def device = aloId.split(delimeter)
  def deviceInfo = [:]
  //Custom implementation starts.  The following is default implementation which return the keys.
  //node and subNode should be the name of which will be searched in ATA/Inventory databases.
  if (device.size() == 2) {
    //node-name
    deviceInfo["node"] = device[0]
    //subNode-name
    deviceInfo["subNode"] = device[1]
  } else {
     deviceInfo["node"] = device[0]
     deviceInfo["subNode"] = ""
  }
  //The referredType must match with TMF639ResourceType-mappings.yaml mapping file.  Blank value considered as PhysicalDevice
  deviceInfo["referredType"] = referredType
  //Custom implementation ends
  return deviceInfo;
}

Mounting Groovy Scripts To Alarm Consumer

To mount Groovy scripts to alarm consumer pod:

1. Edit the script in $COMMON_CNTK/charts/ata-app/charts/ata/config/alarm-consumer/DeviceMapping.groovy location.
2. Upgrade ATA instance as follows:

   $COMMON_CNTK/scripts/upgrade-applications.sh -p project -i instance -f $SPEC_PATH/project/instance/applications.yaml -a ata