5 Reconciling Dynamic Rate Code Changes

UIM supports reconciliation of dynamic rate code changes for physical ports and device interfaces. Use the LogicalDeviceManager reconciliation APIs to reflect the changes in operational speed or rate code information in UIM inventory between reconciliation cycles.

Discovery and reconciliation integrations can use these APIs to update UIM inventory when rate code or operational speed changes are detected. Oracle Communications Network Integrity (NI) can invoke these APIs during its discovery and reconciliation workflows to propagate detected changes to UIM. Custom SOAP services, REST services, orchestration layers, mediation frameworks, and UIM rulesets can also call these APIs.

The APIs reconcile the impact of rate code and operational speed changes at the immediate connectivity layer associated with the affected physical port or device interface.

About the Reconciliation Model

In the UIM model, the rate code is maintained on the device interface. Physical ports can maintain speed-related characteristics that correspond to the device-interface rate code. Physical ports and device interfaces are mapped entities.

A change in operational speed or rate code can require UIM to delete and re-create associated inventory entities. The reconciliation APIs automate the replacement workflow and help maintain model consistency.

Connectivity Layers Included in Reconciliation

The reconciliation APIs address impacts only at the directly associated connectivity layer.

The APIs do not propagate reconciliation impacts beyond the immediate connectivity layer that is associated with the affected physical port or device interface. The following modeled entities are outside the reconciliation scope:

  • Connectivity objects layered on top of other connectivities
  • Networks associated with impacted physical ports, device interfaces, or connectivities
  • Services associated with impacted physical ports, device interfaces, or connectivities
  • Higher-order service-resource relationships

Supported Reconciliation Scenarios

Use the reconciliation APIs when all of the following conditions apply:

  • Discovery detects a change to a device-interface rate code or mapped physical port speed.
  • The integration must reconcile the affected inventory entity in UIM.
  • The affected entity already exists in UIM.
  • The reconciliation scope is limited to the immediate connectivity layer.

The supported reconciliation scenarios include:

  • Oracle Communications Network Integrity discovery reconciliation flows
  • Custom reconciliation web services
  • External inventory synchronization systems
  • Ruleset-driven reconciliation processing
  • Mediation-based topology synchronization

Supported APIs

This section includes the supported reconciliation APIs.

Device Interface Reconciliation API

Overview

This section describes the Oracle Communications Unified Inventory Management (UIM) API method that reconciles rate code changes for a device interface.

Use the LogicalDeviceManager.handleRateCodeImpactsForInterface method when the device interface rate code changes.

API Method Summary

Table 5-1 Reconciling Device Interface Rate Code Changes

Topic Information
Name LogicalDeviceManager.handleRateCodeImpactsForInterface
Description This method reconciles the affected device interface and its mapped physical port when the device interface rate code changes.
Precondition The affected device interface exists in UIM and, if applicable, is mapped to a physical port.
Implementation The implementation is as follows:
  • UIM identifies the existing device interface.
  • Deletes connectivities that directly use the affected device interface.
  • Deletes the existing device interface.
  • Creates a replacement device interface.
  • Copies characteristics from the old device interface to the new device interface.
  • Updates the configured rate code characteristic.
  • Deletes and re-creates the mapped physical port by using the corresponding reconciliation logic.
Post-condition UIM creates a replacement device interface and reconciles the mapped physical port at the directly associated connectivity layer.

Note:

Call this method only for device interface reconciliation events.

Method Syntax

The method syntax is as follows:

void handleRateCodeImpactsForInterface(
    String oldDIId,
    String rateCode,
    String newDISpec,
    String newDIName,
    String rateCodeCharName)
    throws ValidationException

Parameters

Table 5-2 Parameters for Device Interface Reconciliation API

Parameter Description
oldDIId Identifier of the device interface whose rate code or mapped physical port speed changed.
rateCode New rate code.
newDISpec Device interface specification that is associated with the new rate code. If this parameter is not provided, UIM uses the rate code as the default value.
newDIName Device interface name that is associated with the new rate code. If this parameter is not provided, UIM uses the existing device interface name.
rateCodeCharName Characteristic name where the rate code is maintained.

Exceptions

The exception for Device Interface Reconciliation API is as follows:

ValidationException: This exception is thrown when reconciliation validation fails.

Physical Port Reconciliation API

Overview

This section describes the UIM API method that reconciles speed or rate code changes for a physical port.

Use the LogicalDeviceManager.handleRateCodeImpactsForPort method when the speed characteristic that is associated with a physical port changes. Although the UIM model maintains the rate code on the device interface, this method supports reconciliation that starts from the physical port.

Method Summary

Table 5-3 Reconciling Physical Port Rate Code Changes

Topic Information
Name LogicalDeviceManager.handleRateCodeImpactsForPort
Description This method reconciles the affected physical port and its mapped device interface when the physical port speed or rate code characteristic changes.
Precondition The affected physical port exists in UIM and, if applicable, is mapped to a device interface.
Implementation UIM identifies the affected physical port, deletes the existing physical port, creates a replacement physical port, copies characteristics from the old physical port to the new physical port, updates the configured speed or rate code characteristic, and deletes and re-creates the mapped device interface by using the corresponding reconciliation logic.
Post-condition UIM creates a replacement physical port and reconciles the mapped device interface at the directly associated connectivity layer.

Note:

Call this method only for port-driven reconciliation events.

Method Syntax

void handleRateCodeImpactsForPort(
    String oldPortId,
    String rateCode,
    String newPortSpec,
    String newPortName,
    String rateCodeCharName)
    throws ValidationException

Parameters

Table 5-4 Parameters for Physical Port Reconciliation API

Parameter Description
oldPortId Identifier of the physical port whose speed changed.
rateCode New rate code.
newPortSpec Physical port specification that is associated with the new rate code. If this parameter is not provided, UIM uses the rate code as the default value.
newPortName Physical port name that is associated with the new rate code. If this parameter is not provided, UIM uses the existing physical port name.
rateCodeCharName Characteristic name where the speed or rate code is maintained.

Exceptions

The exception for Physical Port Reconciliation API is as follows:

ValidationException: This exceptions is thrown when reconciliation validation fails.

Selecting a Reconciliation API

For a single reconciliation event, integrations must call only one reconciliation API.

Use these following conditions to select the reconciliation API:

  • Use handleRateCodeImpactsForInterface for device interface reconciliation events.
  • Use handleRateCodeImpactsForPort for port-driven reconciliation events.
  • Do not call both APIs for the same reconciliation event.
  • Determine which API to call from the entity type in the discovery or synchronization payload.

Integration and Reconciliation Considerations

Discovery and reconciliation integrations can call these APIs when operational speed or rate code changes are detected for mapped device interfaces or physical ports.

Typical reconciliation processing includes the following tasks:

  • Detect a rate code or speed change.
  • Validate reconciliation inputs.
  • Select the reconciliation API based on entity type.
  • Call either the port API or the interface API for the reconciliation event.
  • Record reconciliation status and sequencing information.

Integrations can call these APIs through custom SOAP services, REST services, orchestration layers, mediation frameworks, or UIM rulesets.

Integrations must process reconciliation events in a consistent order. Use the following guidelines to prevent duplicate or inconsistent reconciliation:

  • Process each reconciliation event only one time.
  • Avoid stale updates.
  • Avoid concurrent reconciliation requests for the same entity.
  • Route each reconciliation event to only one API.
  • Call either the port API or the interface API, but not both.

Reconciliation API Sample

Reconciliation API sample is as follows:

public void reconcileRateCode(
        String entityType,
        String objectId,
        String rateCode,
        String newSpec,
        String newName,
        String rateCodeCharName,
        LogicalDeviceManager logicalDeviceManager)
        throws ValidationException {

    // Validate required inputs
    if (objectId == null || objectId.isBlank()
            || rateCode == null || rateCode.isBlank()
            || rateCodeCharName == null || rateCodeCharName.isBlank()) {

        throw new IllegalArgumentException(
                "Missing required reconciliation data.");
    }

    /*
     * Recommended integration behavior:
     * - perform duplicate-event detection
     * - validate event ordering
     * - suppress unchanged updates
     */

    if ("DEVICE_INTERFACE".equalsIgnoreCase(entityType)) {

        logicalDeviceManager.handleRateCodeImpactsForInterface(
                objectId,
                rateCode,
                newSpec,
                newName,
                rateCodeCharName);

    } else if ("PORT".equalsIgnoreCase(entityType)) {

        logicalDeviceManager.handleRateCodeImpactsForPort(
                objectId,
                rateCode,
                newSpec,
                newName,
                rateCodeCharName);

    } else {

        throw new IllegalArgumentException(
                "Unsupported reconciliation entity type: "
                        + entityType);
    }
}