Reconciling Dynamic Rate Code Changes

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.

UIM 8.26 supports rate code impact reconciliation APIs that accept a RateCodeImpactRequest object. The request allows separate replacement specifications, names, and IDs for device interfaces and physical ports, and controls whether the mapped entity is reconciled. The request class is available at oracle.communications.inventory.api.logicaldevice.model.RateCodeImpactRequest

The earlier parameter versions of handleRateCodeImpactsForInterface and handleRateCodeImpactsForPort are deprecated and retained for backward compatibility. Use the APIs that accept RateCodeImpactRequest for new integrations.

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, when requested, 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. The requested rate code and replacement specifications exist. The replacement device interface specification defines the requested rate code.
Implementation	The implementation is as follows: UIM identifies the existing device interface. Deletes connectivities that directly use the affected device interface or its subinterfaces. Replaces the existing device interface. Copies characteristics supported by the replacement specification. Updates the configured rate code characteristic, when supported. Replaces the mapped physical port if `reconcileMappedEntity` is `true`. Otherwise, UIM retains the physical port and maps it to the replacement interface.
Post-condition	UIM creates a replacement device interface and restores its mapping to the replacement or retained physical port, if applicable. This method returns the replacement device interface ID.

Note:

Call this method only for device interface reconciliation events.

Method Syntax

The method syntax is as follows:

String handleRateCodeImpactsForInterface( RateCodeImpactRequest request) throws ValidationException;Parameters

Table 5-2 Parameters for Device Interface Reconciliation API

Parameter	Description
oldDeviceInterfaceId	An identifier for the device interface with a rate code change. This is a mandatory parameter.
rateCode	New rate code. This is a mandatory parameter.
newDeviceInterfaceSpecificationName	Device interface specification that is associated with the new rate code. If this parameter is `null`, UIM uses the default rate code. The specification must define the requested rate code.
newDeviceInterfaceName	Device interface name that is associated with the new rate code. If this parameter is `null`, UIM uses the default rate code. The specification must define the requested rate code.
newDeviceInterfaceId	Replacing value of the device interface ID. Used only when the replacement specification has `Enter Id Manually` set to `true`. If `null`, UIM reuses the existing interface ID. Ignored when the specification generates IDs automatically.
newPhysicalPortSpecificationName	Replacing value of the mapped port specification. If `null`, UIM uses the resolved replacement device interface specification name. Used when the mapped port is reconciled.
newPhysicalPortName	Replacing value of the mapped port name. If `null`, UIM uses the replacement mapped port name.
newPhysicalPortId	Replacing value of the mapped port ID. Used only when the replacement specification has `Enter Id Manually` set to `true`. If `null`, UIM reuses the existing port ID. Ignored when the specification generates IDs automatically.
rateCodeCharName	Characteristic name where the rate code is maintained on replacement device interfaces or physical ports. UIM updates the characteristic to the new rate code when the replacement specification supports it.
reconcileMappedEntity	Indicates whether the mapped physical port is also reconciled. Defaults to `true`. If `false`, UIM retains the mapped physical port and maps it to the replacement interface.

The oldPhysicalPortId property is not used by this method. UIM identifies the mapped physical port from the source device interface. UIM copies only characteristics supported by the replacement specification. If the specified rate code characteristic does not exist on the source entity but is supported by the replacement specification, UIM creates it on the replacement entity and sets its value to the new rate code. If the replacement specification does not support the specified characteristic, UIM logs a warning and continues without setting it. If rateCodeCharName is null, UIM does not perform the characteristic-specific update. The replacing value of the device interface rate code attribute is set.

Exceptions

The exception for Device Interface Reconciliation API is as follows:

IllegalArgumentException: This exception is thrown when the request object is null.
ValidationException: This exception is thrown when reconciliation validation fails, including when a rider prevents deletion of an affected connectivity.

Some validation failures cause the method to return null and record feedback errors. These include an unknown source interface, unknown rate code, missing replacement interface specification, or a replacement interface specification that does not define the requested rate code.

Check the returned ID and feedback errors before committing the transaction. Roll back if the returned ID is null, feedback errors are present, or an exception occurs.

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, when requested, 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. The requested rate code and replacement port specification exist. If the mapped interface is reconciled, its replacement specification exists and defines the requested rate code.
Implementation	UIM identifies the affected physical port. If `reconcileMappedEntity` is `true`, UIM reconciles the mapped device interface first. UIM replaces the physical port, copies characteristics supported by the replacement specification, updates the configured speed or rate code characteristic when supported, and restores the mapping. If `reconcileMappedEntity` is `false`, UIM retains the mapped interface and maps it to the replacement port.
Post-condition	UIM creates a replacement physical port and restores its mapping to the replacement or retained device interface, if applicable. The method returns the replacement physical port ID.

Note:

Call this method only for port-driven reconciliation events.

Method Syntax

String handleRateCodeImpactsForPort(
        RateCodeImpactRequest request)
        throws ValidationException;

Parameters

Table 5-4 Parameters for Physical Port Reconciliation API

Parameter	Description
oldPhysicalPortId	Identifier of the physical port whose speed changed. This is a mandatory parameter.
rateCode	New rate code. This is a mandatory parameter.
newPhysicalPortSpecificationName	Physical port specification that is associated with the new rate code. If this parameter is `null`, UIM uses the rate code as the default value.
newPhysicalPortName	The replacing physical port name that is associated with the new rate code. If this parameter is `null`, UIM uses the existing physical port name.
newPhysicalPortId	Replacement physical port ID. Used only when the replacement specification has Enter Id Manually set to `true`. If `null`, UIM reuses the existing port ID. Ignored when the specification generates IDs automatically.
newDeviceInterfaceSpecificationName	Replacement mapped interface specification. If `null`, UIM uses the resolved replacement physical port specification name. Used when the mapped interface is reconciled. The specification must define the requested rate code.
newDeviceInterfaceName	Replacement mapped interface name. If `null`, UIM uses the replacement physical port name.
newDeviceInterfaceId	Replacement mapped interface ID. Used only when the replacement interface specification requires manual ID entry. If `null`, UIM reuses the existing interface ID. Ignored when the specification generates IDs automatically.
rateCodeCharName	Characteristic name where the speed or rate code is maintained on replacement physical ports or device interfaces. UIM updates the characteristic to the new rate code when the replacement specification supports it.
reconcileMappedEntity	Indicates whether the mapped device interface is also reconciled. Defaults to `true`. If `false`, UIM retains the mapped interface and maps it to the replacement port.

The oldDeviceInterfaceId property is not used by this method. UIM identifies the mapped device interface from the source physical port.

UIM copies only the characteristics that are supported by the replacement specification. If the specified rate code characteristic does not exist on the source entity but is supported by the replacement specification, UIM creates it on the replacement entity and sets its value to the new rate code.

If the replacement specification does not support the specified characteristic, UIM logs a warning and continues without setting it. If rateCodeCharName is null, UIM does not perform the characteristic-specific update.

Exceptions

The exception for Physical Port Reconciliation API is as follows:

IllegalArgumentException: This exception is thrown when the request object is null.
ValidationException: This exceptions is thrown when an inventory operation fails validation, including operations performed while reconciling the mapped interface.

Some validation failures cause the method to return null and record feedback errors. These include, unknown source physical port, unknown rate code, or missing replacement port specification. Reconciliation of the mapped device interface can also record feedback errors. Check feedback errors even when a replacement ID is returned. Roll back if the returned ID is null, feedback errors are present, or an exception occurs.

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.

Provide separate replacement specifications, names, and IDs when required for the device interface and physical port. Set reconcileMappedEntity to false when only the input entity requires replacement.

Replacement IDs are used only for specifications configured for manual ID entry. If a replacement ID is not included, for such a specification, UIM reuses the existing entity ID. For specifications that generate IDs automatically, explicitly supplied replacement IDs are ignored.

Use the returned replacement entity ID for subsequent processing. Before committing the transaction, check both the returned ID and feedback errors. Roll back the transaction if the returned ID is null, feedback errors are present, or an exception occurs.

Reconciliation API Sample

The following sample uses RateCodeImpactRequest and selects the reconciliation API based on the entity type. It assumes that the caller has established a UIM user environment and transaction. The caller must check feedback errors and the returned ID before committing.

import oracle.communications.inventory.api.logicaldevice.model.RateCodeImpactRequest;

public String reconcileRateCode(
        String entityType,
        String objectId,
        RateCodeImpactRequest request,
        LogicalDeviceManager logicalDeviceManager)
        throws ValidationException {

    // Validate required inputs.
    if (objectId == null || objectId.isBlank()
            || request == null
            || request.getRateCode() == null
            || request.getRateCode().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)) {
        request.setOldDeviceInterfaceId(objectId);
        return logicalDeviceManager.handleRateCodeImpactsForInterface(
                request);
    } else if ("PORT".equalsIgnoreCase(entityType)) {
        request.setOldPhysicalPortId(objectId);
        return logicalDeviceManager.handleRateCodeImpactsForPort(
                request);
    } else {
        throw new IllegalArgumentException(
                "Unsupported reconciliation entity type: " + entityType);
    }
}

Populate the request with the replacement values required by the integration. The following example uses separate device interface and physical port specifications:

RateCodeImpactRequest request = new RateCodeImpactRequest();
request.setRateCode("10GigE");
request.setNewDeviceInterfaceSpecificationName("10GigE_DI");
request.setNewPhysicalPortSpecificationName("10GigE_Port");
request.setNewDeviceInterfaceName("Interface_10G");
request.setNewPhysicalPortName("Port_10G");
request.setRateCodeCharName("currentRateCode");

// Optional IDs for specifications configured for manual ID entry.
request.setNewDeviceInterfaceId("DI_10G_001");
request.setNewPhysicalPortId("PORT_10G_001");

// Defaults to true. Set to false to replace only the input entity.
request.setReconcileMappedEntity(true);

String replacementId = reconcileRateCode(
        "DEVICE_INTERFACE",
        existingDeviceInterfaceId,
        request,
        logicalDeviceManager);

Note:

The specification names and IDs in this example are illustrative. Use valid specifications and IDs for the deployed inventory model.

5 Reconciling Dynamic Rate Code Changes

About the Reconciliation Model

Supported Reconciliation Scenarios

Supported APIs

Device Interface Reconciliation API

Physical Port Reconciliation API

Selecting a Reconciliation API

Integration and Reconciliation Considerations

Reconciliation API Sample