Skip Headers
Oracle® Communications Network Integrity Developer's Guide
Release 7.1

E23701-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

12 Working with Discrepancy Resolution Actions and Processors

A discrepancy resolution action is an extendable Network Integrity operation which acts on an external system to resolve a discrepancy. For example, a resolution action updates a mismatch in an inventory system using information gathered from the network or generates a trouble ticket to kick off a network configuration change process.

A discrepancy resolution action operation is initiated by a user of the Network Integrity user interface on the Manage Discrepancy page, using the following steps:

  1. The user identifies the desired resolution action on selected discrepancies. Each discrepancy can have only one resolution action set.

  2. The user submits the discrepancies with identified resolution actions to the system.

On receiving the submitted discrepancies, Network Integrity groups them based on their scan origin, result category, and resolution label, and then invokes the appropriate Discrepancy Resolution Action.

The Action then examines each discrepancy in detail, using the contained information to figure out the appropriate steps to resolve the problem.

As with other types of actions, a discrepancy resolution action is made up of a sequence of discrepancy resolution processors. The processors are shown in the Processor table in Design Studio. At the beginning of an action operation, these processors are invoked serially from top of the table to bottom. The first processor is given the list of submitted discrepancies marked for this action. This processor determines a subset of these discrepancies to handle (which can range from none to all), performs the resolution operation, and sets their status to Processed or Failed. Then, the next processor is given the remaining unhandled discrepancies for processing, and so on.

The action is complete when all the processors are invoked. If there are any discrepancies which remain unhandled at the end, their status is automatically set to Not Implemented.

The following sections in this chapter describe general information about implementing a resolution action. For a detailed discussion of a working sample, see the following documents included with the cartridges:

Creating Discrepancy Resolution Actions

To create a Discrepancy Resolution action, see the Network Integrity Studio Help.

Discrepancy Resolution Action Editor

The Discrepancy Resolution action editor contains several tabbed pages.

The following link takes you to reference topics for the pages used to define an action:

Details Page

The Details page contains general setting for the action.

Item Description
Resolution Action Label See "About the Resolution Action Label".
Description Lets you provide a short description of the action.
Implementation Prefix This takes the value of the component name by default. This field cannot be changed. This field is used by Design Studio when creating some deployable artifacts.
Abstract Lets you specify whether the action is abstract.

If the action is abstract, then it can only be used as a component within another action.

If the action is not abstract, then it can be deployed and a scan can be executed from it.

Documentation Lets you add any other information about the action.

Processors Page

The Processors page is used to define the processors that comprise the action.

See "About the Processors Tab" for further information about the tasks carried out using the Processors tab.

The only processor type that can be created and used for an import action is the discrepancy resolution processor.

Model Page

Use the Model page to specify the model collections that the discrepancy resolution action uses. The model collection defines the parts of Oracle Communications Information Model and the dynamic extensions that are related to the model collection. In effect, the Model tab specifies which parts of the Information Model are used by the discrepancy resolution action.

See "About Model Collections in Actions" for further information about model collections.

Result Source Page

Specifies the input result categories for the action to act upon. See "About Result Sources" for further information.

Conditions Page

The Conditions page allows conditions to be defined. Conditions can be associated with processors to cause conditional execution of the processor.

See "About Conditions" for further information about conditions.

About the Resolution Action Label

The Resolution Action Label identifies the Discrepancy Resolution action in the Network Integrity User Interface (UI). It is displayed as a command in the Actions menu of the Discrepancy Search Results table of the Review Discrepancies page.

Figure 12-1 displays the label corresponding to the command.

Figure 12-1 Resolution Action Label in Actions Menu of Network Integrity UI

Shows resolution action label

This label is a mandatory field. Design Studio reports an error if this label has no value. The use of a command phrase as the label string is recommended. Some example labels are:

  • Correct in Inventory System, or

  • Open a Trouble Ticket

The label input field allows you to choose either a label from another Discrepancy Resolution action defined within your workspace, or to type in a new label. A label can be shared by multiple actions; this implies that multiple actions are sharing a single menu item in the Actions menu of the Discrepancies page.

Network Integrity determines the correct Action to invoke based on a combination of the label and the Result Source.

WARNING:

No two discrepancy resolution actions can have the same Label and the same Result Source.

About Result Sources

The result source is a list of discrepancy filtering criteria. Each criterion represents a single source of discrepancy, and is specified by a combination of the originating scan action and a result category. A resolution action only receives discrepancies from the specified result categories which were created by scans using the specified actions.

Figure 12-2 shows an example of result sources being applied in Network Integrity.

Figure 12-2 Result Source Example 1

Illustrates result source. Example 1.

A criterion that does not specify any result category matches all result categories generated by the scan action in the criterion.

Figure 12-3 shows a representation of the discrepancy types.

Figure 12-3 Result Category Example

Illustrates result source. Example 2.

The result source is a mandatory field; there must be at least one entry in the table. Design Studio marks a discrepancy resolution action with an error during a project build if this table has no entries.

WARNING:

No two discrepancy resolution actions can have the same Label and the same Result Source.

Generated Action MDB and Controller

The discrepancy resolution action is implemented as an MDB, just like any other Network Integrity action.

See "Generated Action MDB and Controller" for more information.

About Discrepancy Resolution Processors

The only type of processor available to the discrepancy resolution action is the discrepancy resolution processor.

As with other types of actions, the list of processors are invoked serially from top of the table to bottom. The first processor is given the list of submitted discrepancies marked for this action. This processor determines a subset of these discrepancies to handle (which can range from none to all), perform the resolution operation, and set their status to either Processed or Failed.

Then, the next processor is given the remaining unhandled discrepancies for processing, and so on. The action is complete when all the processors are invoked. If there are any discrepancies which remain unhandled at the end, their status is set to Not Implemented.

The discrepancy resolution processor is the Java implementation of a discrepancy resolution action. The processor carries out the following tasks:

  • Filter through its input list of discrepancies to process only those discrepancies it can handle

  • Communicate with the discovery or import system to correct a discrepancy

  • Report the status of a correction operation

See "About Processor Implementation" for more information.

Creating a Discrepancy Resolution Processor

See Network Integrity Studio online Help for information about creating a discrepancy resolution processor.

Implementing a Discrepancy Resolution Processor

This section provides details about the discrepancy resolution processor implementation.

About the Implementation Interface

The processor implementation class derives from a Studio-generated interface class. There is a single abstract method that the implementation class must implement. The abstract method has the following interface:

public <Processor_Name>Response invoke(
            DiscoveryResolutionProcessorContext context,
            <Processor_Name>Request request)
      throws ProcessorException
{
}

About the Input Parameters of the Invoke() Method

Table 12-1 describes the methods provided to the developer by the first parameter, context, outlined in "About the Implementation Interface".

Table 12-1 Methods from the context Parameter

Context method Return Object Class Description

getActionName()

String

Getter for the name of this action.

getProcessorName()

String

Getter for the name of this processor.

getUnhandledDiscrepancies()

Collection DisDiscrepancy

Getter for a list of unprocessed discrepancies for this invocation.

getAllDiscrepancies()

Collection DisDiscrepancy

Getter for a list of processed and unprocessed discrepancies for this invocation.

discrepancyProcessed(DisDiscrepancy disc)

void

Sets the status of the input discrepancy to OPERATION_PROCESSED.

discrepancyFailed(DisDiscrepancy disc, String failureMessage)

void

Sets the status of the input discrepancy to OPERATION_FAILED, and also sets the failure message.

discrepancyReceived(DisDiscrepancy disc)

void

Sets the status of the input discrepancy to OPERATION_RECEIVED.


The second parameter, request, contains getters for each item in the Input Parameters table. It also contains a getter to retrieve the groups and items listed in the Properties tabbed page.

Return Type of Invoke()

The return type of the invoke() method varies, depending on the output parameters setting in the Context Parameters tabbed page.

If there is no output parameter, then the return type is void.

If there are one or more output parameters, then the return type is a generated class with the name Processor_NameResponse. This Response class has getters and setters for each item in the Output Parameters table.

About the General Flow of the Discrepancy Resolution Processor

The usual pattern for implementing a discrepancy resolution processor is as follows:

  1. Fetch the list of unhandled discrepancies using context.getUnhandledDiscrepancies()

  2. Allocate discrepancies based on logical groupings; for example: all discrepancies on a single card and on its children port.

    Keep discrepancies that can be handled by this processor, and ignore or remove other discrepancies.

  3. For each group, perform operations to fix the discrepancies, Then, based on operation results, set their status to Processed or Failed.

    An error message can be saved in the Failure Reason field of the discrepancy, which is displayed in the Network Integrity UI.

  4. Set output parameters.

Fetching Discrepancies

The discrepancy resolution processor can use the context input parameter to fetch the list of discrepancies to process. In the general flow, the processor uses the method getUnhandledDiscrepancies() on context to retrieve a list of discrepancies that are not yet handled by any previous processors.

It is also possible to retrieve the original full list of discrepancies by using the method getAllDiscrepancies(), but this list includes discrepancies that are already handled by a prior resolution processor.

It is possible to make updates to already handled discrepancies, such as updating the Notes field to add more text.

See "Details Page" for a list of fields that can be modified and warnings about which fields should not be modified.

See "About Discrepancies" for more information about the attributes of a Discrepancy object.

Grouping Discrepancies

Usually, a single resolution processor is responsible for handling the discrepancies of a single entity type; for example: logical device or device interface only, or more frequently an explicit set of specifications of an entity type.

Sometimes, a processor specializes in handling discrepancies of a very specific nature. Therefore, the next logical task is to examine each unhandled discrepancy, to determine how it should be handled by this processor.

A processor frequently uses one or more of the following discrepancy attributes as criteria for handling. Of course, it may use all other attributes as criteria for determining special handling, if necessary.

See "About Discrepancies" for a detailed explanation of these attributes:

  • Type: indicates the error being reported; for example: attribute mismatch, missing entity, and so on.

  • externalEntityType, staticEntityType: indicates the type and specification of the target entity.

  • attributeOrRelationshipName: indicates the attribute or the association that has the discrepancy

  • compareValue, referenceValue: each attribute indicates the value of an attribute on one side of the comparison

  • compareEntity, referenceEntity: each attribute is a reference to one entity being compared; see "About the Compare and Reference Sides" and "About Discrepancy Types" for important information on what entity each attribute is actually referencing.

  • childTargetEntity: this is an additional entity reference used only for Association or Entity discrepancy types; see "About Discrepancy Types" for further information.

Handling Discrepancies

Now that the target has been identified and grouped, the processor can decide whether to proceed with the handling. If the processor can resolve this discrepancy, then the processor can make appropriate API calls necessary to make the desired resolution on the system, and report the result.

See "Reporting the Resolution Result".

Alternatively, the processor can decide to skip the discrepancy, and begin processing the next one. The skipped discrepancy subsequently appears in the unhandled list of discrepancies for the next processor.

Reporting the Resolution Result

When a discrepancy has resolved successfully, simply pass this discrepancy into the context using the method discrepancyProcessed. This sets the discrepancy status to Processed.

context.discrepancyProcessed( discrepancy );

If the processor fails to resolve a discrepancy, it should set the discrepancy status to Failed using the method discrepancyFailed in the context.

This method takes an additional String argument, which the processor can set a short message to be displayed in the UI. The string is stored in the reasonForFailure attribute of the discrepancy.

Note:

This error message is limited to a maximum of 255 characters.
context.discrepancyFailed( discrepancy, "Sample error message.");

If the processor needs to make a series of asynchronous invocations to handle a discrepancy, it can set the discrepancy status to Received at the end of the first invocation.

This indicates to Network Integrity and to Network Integrity users that the discrepancy resolution is in progress. This is done using the method discrepancyReceived in the context.

context.discrepancyReceived( discrepancy );

See "About Discrepancy Status" for an explanation of the transition rules for status values.

Handling Discrepancies Asynchronously

There are situations in which a discrepancy resolution operation cannot be completed within a single invocation. For example, the CORBA interface for an external system to create a trouble ticket requires the caller to supply a callback object for the notification of the final operation result and ticket ID.

In this example, the resolution processor code can prepare the callback object and make the initial CORBA call to submit the trouble ticket, and then it must return from the invoke() method. The subsequent resolution handling code must reside in the callback object, and receives the notification, updating the discrepancy status accordingly.

In such cases, the processor should set the status of the discrepancy to RECEIVED using context.discrepancyReceived() at the end of the handling code in the processor's invoke() method. This indicates to Network Integrity and to Network Integrity users that resolution processing is in progress, and that additional status updates arrive later.

You must also save the entityID of the discrepancy (using discrepancy.getEntityId()) during the processor's invoke() method. When the subsequent resolution handing operation reaches its conclusion, the status of the original discrepancy must be updated to PROCESSED or FAILED. This is done using the Network Integrity Web Services interface by first retrieving the discrepancy using the entityID, and then updating the status of the discrepancy.

The topic of how to save the entityID and how to create the subsequent code invocation is beyond the scope of this guide. You may use any techniques available in J2EE to perform these tasks.