Availability

Oracle Communications Unified Assurance uses the Availability Common Object Model (ACOM) defined in a rules file to discover and monitor the operational and administrative state of device resources. ACOM provides ready-to-use availability monitoring for a library of supported devices.

The SNMP Poller uses ACOM during device discovery, instance discovery, and availability polling. The collected availability data is used by graph-based topology modeling and the RCA Availability Engine.

The ACOM file is located in the Rules UI at:

Core Rules (core)/Default read-write branch (default)/collection/metric/snmp/_objects/acom

To open the Rules UI, from the main navigation menu, select Configuration, then Rules.

ACOM Schema and Definitions

An ACOM file consists of attributes that define how Unified Assurance discovers availability objects, identifies monitored instances, collects availability information, and processes collected data. Common examples of availability objects include interfaces, routing peers, hardware entities, power supplies, fans, and vendor-specific resources.

The following are the top-level attributes of the ACOM file:

Object Definitions

Each entry within the objects attribute defines a single availability object.

The following attributes are nested within the objects attribute:

SNMP Definitions

The following attributes are nested within the snmp attribute:

ACOM Processors

ACOM processors provide a transformation layer within the SNMP Poller that allows collected instance and availability data to be normalized, enriched, or converted before it is used by downstream Unified Assurance components.

Processors are commonly used to derive stable instance identifiers from raw SNMP values, normalize vendor-specific values, map enumerations to meaningful representations, extract information from SNMP indexes, and create derived availability properties.

ACOM supports the following two processor arrays:

The processor array determines when the processor runs and the processor type determines what the processor does. The following processor types are supported for ACOM:

set

The set processor builds a new string by formatting a source template with one or more input values and writing the result to a target field.

Use this processor to create derived instance names, combine multiple SNMP values into a single field, and format identifiers for display.

Configure the set processor using the following fields:

For example:

{
    "set": {
        "source": "%s(%s/%s)",
        "args": [
            "$.hwInterfaceName",
            "$.hwInterfaceId",
            "$.hwInterfaceModuleId"
        ],
        "targetField": "$.updatedInterfaceName"
    }
}

map

The map processor replaces a collected value using a lookup table.

Use this processor to convert enumerated values into meaningful text, normalize vendor-specific states, and translate device-specific values into standardized values.

Configure the map processor using the following fields:

For example:

{
    "map": {
        "source": "$.sonusEthernetPortMgmtPortStatusNegotiatedSpeed",
        "values": {
            "1": "speed10Mbps",
            "2": "speed100Mbps",
            "3": "speed1000Mbps",
            "4": "unknown",
            "5": "speed10000Mbps"
        }
    }
}

math

The math processor performs arithmetic operations on numeric values.

Use this processor to calculate offsets, derive index positions, and generate intermediate values for processor chains.

Configure the math processor using the following fields:

For example:

{
    "math": {
        "source": "$.localmem.iidArr[0]",
        "value": 1,
        "operation": "+",
        "targetField": "$.localmem.endIndexCeName"
    }
}

Note:

Division or modulo by zero does not stop the processor chain. The runtime logs a warning and writes 0 for that row.

length

The length processor returns the length of a string or size of a list.

Use this processor to determine the length of a string or the size of a list.

Configure the length processor using the following fields:

For example:

{
    "length": {
        "source": "$.fullName",
        "targetField": "$.fullLen"
    }
}

slice

The slice processor extracts a portion of a string or list.

Use this processor to extract a portion of a string or list.

Configure the slice processor using the following fields:

For example:

{
    "slice": {
        "source": "$.localmem.iidArr",
        "start": 1,
        "end": "$.localmem.endIndexCeName",
        "targetField": "$.localmem.encodedCeNameAsciiArray"
    }
}

split

The split processor splits a string into a list using a delimiter.

Use this processor to split a string into a list using a specified delimiter.

Configure the split processor using the following fields:

For example:

{
    "split": {
        "source": "$.localmem.iid",
        "delimiter": "\\.",
        "targetField": "$.localmem.iidArr"
    }
}

join

The join processor combines a list into a string.

Use this processor to combine the elements of a list into a string using a specified delimiter.

Configure the join processor using the following fields:

For example:

{
    "join": {
        "source": "$.localmem.portNameCharArray",
        "delimiter": "",
        "targetField": "$.localmem.portName"
    }
}

converter

The converter processor performs type-specific transformations.

Use this processor to perform type-specific transformations. The transformation performed depends on the configured converter type.

Only the asciiArrayToCharArray is supported. This converter transforms an array of ASCII integer values into an array of characters.

This processor is commonly used when an SNMP index or field encodes names as ASCII values.

Configure the converter processor using the following fields:

The converter expects the source to resolve to a list of integer values in the ASCII range 0 through 127. If the source is not a list, or if any element is not a valid ASCII integer, the processor fails.

For example:

{
    "converter": {
        "type": "asciiArrayToCharArray",
        "source": "$.localmem.encodedPortNameAsciiArray",
        "targetField": "$.localmem.portNameCharArray"
    }
}

The asciiArrayToCharArray converts the following input:

[112, 107, 116, 49]

to the following output:

['p', 'k', 't', '1']

The resulting character array can then be passed to a join processor to produce pkt1.

About Processor Operation

Processors run sequentially in the order in which they are defined. The output of one processor can be used as the input to the next, allowing complex transformations to be implemented as a sequence of simple operations.

Processors operate on SNMP tables rather than on individual values. Each processor runs independently for every IID (Instance Identifier), processing the data associated with the current row and writing the result to a corresponding output table. For example, if a processor references:

"source": "$.localmem.iid"

It receives the IID associated with the current row rather than the entire table.

Processors can store temporary values in the \$.localmem namespace. The SNMP Poller automatically provides \$.localmem.iid, which contains the current SNMP index for the row being processed.

Processor fields such as source, args, and targetField reference data using the following expression formats:

Source fields also support indexed references:

indexing is not supported for target fields.

Processor Chaining and Example

Processor chaining allows multiple processors to run sequentially, with the output of one processor becoming the input to the next.

The following example uses instance processors to derive a stable instance identifier from an SNMP index.

"processors": [
    {
        "split": {
            "source": "$.localmem.iid",
            "delimiter": "\\.",
            "targetField": "$.localmem.iidArr"
        }
    },
    {
        "math": {
            "source": "$.localmem.iidArr[0]",
            "value": 1,
            "operation": "+",
            "targetField": "$.localmem.endIndexCeName"
        }
    },
    {
        "slice": {
            "source": "$.localmem.iidArr",
            "start": 1,
            "end": "$.localmem.endIndexCeName",
            "targetField": "$.localmem.encodedCeNameAsciiArray"
        }
    },
    {
        "math": {
            "source": "$.localmem.iidArr[0]",
            "value": 2,
            "operation": "+",
            "targetField": "$.localmem.startIndexPortName"
        }
    },
    {
        "slice": {
            "source": "$.localmem.iidArr",
            "start": "$.localmem.startIndexPortName",
            "targetField": "$.localmem.encodedPortNameAsciiArray"
        }
    },
    {
        "converter": {
            "type": "asciiArrayToCharArray",
            "source": "$.localmem.encodedPortNameAsciiArray",
            "targetField": "$.localmem.portNameCharArray"
        }
    },
    {
        "join": {
            "source": "$.localmem.portNameCharArray",
            "delimiter": "",
            "targetField": "$.localmem.portName"
        }
    },
    {
        "converter": {
            "type": "asciiArrayToCharArray",
            "source": "$.localmem.encodedCeNameAsciiArray",
            "targetField": "$.localmem.ceNameCharArray"
        }
    },
    {
        "join": {
            "source": "$.localmem.ceNameCharArray",
            "delimiter": "",
            "targetField": "$.localmem.ceName"
        }
    },
    {
        "set": {
            "source": "%s(%s)",
            "args": [
                "$.localmem.portName",
                "$.localmem.ceName"
            ],
            "targetField": "$.updatedInstanceKey"
        }
    }
]

This produces a stable instance name such as:

pkt1(USAZPHXSBC7K1A)

This processor chain:

The SNMP Poller repeats the same chain independently for each IID in the table.

Writing Good ACOM Processors

When writing ACOM processors, follow these guidelines:

Availability Support Workflow

ACOM definitions are used by the SNMP Poller during both discovery and polling operations.

During the Discovery flow, the SNMP Poller uses discovery OIDs, filters, instance definitions, instance processors, availability definitions, and availability processors to identify and create monitored availability instances.

During the Polling flow, the SNMP Poller uses the same ACOM definition to collect the current availability state of previously discovered instances.

Availability entries marked with discoverOnly: true are collected during discovery but are skipped during normal availability polling.

At runtime, the SNMP Poller processes an ACOM object in the following order:

  1. Load the ACOM object definition from the Rules repository.

  2. Evaluate the snmp.discovery OID to determine whether the device supports the availability object.

  3. Apply any configured snmp.filter definitions to remove invalid or unwanted instances.

  4. Collect the candidate instance sources defined in snmp.instance.values.

  5. Run any snmp.instance.processors to transform or derive instance identifiers.

  6. Select the first processed or original instance source that produces unique, non-blank instance names.

  7. Collect the availability properties defined in snmp.availability.

  8. Run any snmp.processors to normalize, map, or derive availability properties.

  9. During discovery, create availability instances and associate any configured Graph metadata, such as vertex and edge types.

  10. During polling, recollect availability values and publish the resulting instance state to the availability processing pipeline.

The resulting availability information is consumed by downstream Unified Assurance components, including Graph-based topology management and the RCA Availability Engine.

ACOM Curation

ACOM curation is the process of creating an ACOM file from MIB information so that Unified Assurance can discover availability objects, identify monitored instances, collect availability state, and pass the collected data to downstream availability processing.

The curation process is a manual activity. It involves reviewing the MIB objects exposed by a device, identifying which objects represent availability state, determining how those objects are indexed, and arranging the selected information in the ACOM schema.

Before curating an ACOM file, identify the following information:

Use the following process to curate an ACOM file:

  1. Identify the availability object to model.

    Review the MIB and identify the table or object that represents the resource whose availability must be monitored.

    This step is about deciding what resource Unified Assurance should model, such as an interface, routing peer, hardware entity, port, power supply, fan, or vendor-specific object.

    Use the selected table or object to define the ACOM object-level fields, such as @objectName, class, subClass, description, and domain.

  2. Choose the discovery OID for that availability object.

    Select the specific SNMP OID that Unified Assurance can query to determine whether the device supports the availability object.

    The discovery OID might be a table entry OID, a name or description OID in the table, or another stable object that returns data only when the device supports the resource.

    Configure this information in snmp.discovery.

  3. Define the SNMP behavior for the object.

    Complete the snmp section by defining how Unified Assurance should filter discovered rows, identify monitored instances, collect availability properties, and process collected values.

    At this stage, define the following as needed:

    • snmp.filter, to exclude indexes that should not become monitored instances

    • snmp.instance, to identify monitored instances and optional Graph metadata

    • snmp.availability, to specify the availability properties to collect

    • snmp.instance.processors, to derive or normalize instance identity

    • snmp.processors, to normalize collected availability values

    For details about these attributes, see SNMP Definitions.

  4. Add Graph metadata, if the instance must be modeled in Graph database.

    If the availability object represents a new or vendor-specific resource that must appear in Graph, define the following Graph-related fields under snmp.instance:

    • inVertexType

    • outVertexType

    • edgeType

    • edgeDirection

    These values must match the corresponding Graph metadata configured in Unified Assurance.

  5. Validate the curated ACOM file.

    Confirm that the discovery OID returns data, filters keep the correct indexes, instance names are unique and non-blank, availability properties are collected, processors produce the expected output, and Graph metadata aligns with the configured Graph types.

Example ACOM file

The following example shows the overall shape of an ACOM file:

{
    "@vendor": "EXAMPLE-VENDOR",
    "mibs": [
        "EXAMPLE-MIB"
    ],
    "notes": "",
    "enterpriseOids": [],
    "aliases": [],
    "objects": [
        {
            "@objectName": "EXAMPLE-MIB::examplePortTable",
            "certification": "STANDARD",
            "class": "NETWORK",
            "description": "Availability of example ports",
            "domain": "AVAILABILITY",
            "metaData": {
                "certified": true
            },
            "method": "snmp",
            "snmp": {
                "discovery": {
                    "name": "EXAMPLE-MIB::examplePortName",
                    "oid": "1.3.6.1.4.1.9999.1.1.1",
                    "limit": 1000
                },
                "filter": [
                    {
                        "operator": "!=",
                        "property": {
                            "name": "EXAMPLE-MIB::examplePortAdminState",
                            "oid": "1.3.6.1.4.1.9999.1.1.2"
                        },
                        "value": "0"
                    }
                ],
                "instance": {
                    "type": "ExamplePort",
                    "inVertexType": "ExamplePort",
                    "outVertexType": "Device",
                    "edgeType": "HasExamplePort",
                    "edgeDirection": "Directed",
                    "values": [
                        {
                            "name": "EXAMPLE-MIB::examplePortName",
                            "oid": "1.3.6.1.4.1.9999.1.1.1",
                            "weight": 1
                        }
                    ],
                    "processors": []
                },
                "availability": [
                    {
                        "name": "EXAMPLE-MIB::examplePortOperState",
                        "oid": "1.3.6.1.4.1.9999.1.1.3"
                    },
                    {
                        "name": "EXAMPLE-MIB::examplePortSpeed",
                        "oid": "1.3.6.1.4.1.9999.1.1.4",
                        "discoverOnly": true
                    }
                ],
                "processors": []
            },
            "subClass": "AVAILABILITY_VENDOR_EXAMPLE_PORT",
            "weight": 1
        }
    ]
}