Interface Requirement Specifications (IRS)

“I have discovered that there are two types of command interfaces in the world of computing: good interfaces and user interfaces.”
Daniel J. Bernstein.

OSS don’t add much value in isolation. They need to get data from somewhere and then add value to that data to turn it into insight.

Of course they get some data from manual input, but most of their data come from other sources (eg network devices, element management systems, network management systems, BSS, etc). When getting data from other sources, OSS need to establish an interface to those other systems.

Since a majority of data sources are productised (eg network devices), those products tend to have standardised interfaces that allow the OSS to connect to them. Standardised interfaces generally come with specifications on how to integrate with them and collect data programmatically.

There are many different names for the “middle layer” of integration (ie the object that collects data from the source and maps it to data streams that can be consumed by the OSS) – they are sometimes called probes, robots, mediation devices (MD), mediation device drivers (MDD) and various other proprietary names. These “objects” might take the form of software, applications, appliances, etc.

Before a developer creates these objects, you first need to build an Interface Requirement Specification (IRS) document that defines what the interface should do.

These IRS contain various important pieces of information including:

• Introduction to the interface
• Interface description (eg manufacturer, domain, agent type, version, physical interface, management interface)
• Interface types (eg alarms, performance, inventory / config, provisioning, admin, etc). [Note that a single device type may have completely independent interfaces for each of the interface types]
• Interface protocol (eg SNMP, CORBA, etc)
• Connectivity specifications (eg MIBs, IDLs, etc)
• Code libraries and associated documentation
• Message style – some interfaces use file / log transfers rather than messages, others allow sessions to be established
• Format of the messages (eg header, object identifiers, index/counters, message content, framing, timestamps, timeouts, status, etc).
• List of message types, definitions, variables and usage / description
• Managed objects (eg devices, cards, ports, etc)
• Special interpretations, enrichments, parsing rules, mapping, derivations, thresholds or actions to take with each type of message. [Note that you may even need a description of the network under management, such as topologies, services, naming conventions, etc to explain the interpretation of messages]
• Classification of OSS objects (eg fields in a database) for the source data to be mapped to
• Mapping of messages into OSS objects
• List of violations or exceptions and corresponding descriptions of how to handle them