4 Working with Discrepancies

This chapter provides an overview of discrepancies in Oracle Communications Network Integrity.

About Discrepancies

When Network Integrity detects a difference while comparing import and discovery data, it generates a discrepancy. The discrepancy captures all vital information about the difference, such as the entity and the name of the attribute or relationship containing the difference, the type of difference, and the values on both sides (that is to say, on the Compare, and the Reference sides).

These topics are further explored in:

About the Compare and Reference Sides
About Discrepancy Types
About Discrepancy Status
About Discrepancy Detail

About the Compare and Reference Sides

When dealing with discrepancies, the data from the two sides are named Compare and Reference. The significance is that the Compare side is the side of the scan that triggered the discrepancy comparison.

If a scan using a discovery action was also configured to detect discrepancies, the discrepancies created by that scan have discovery data on the Compared side, and import data on the Reference side.

On the other hand, if a scan uses an import action with detect discrepancies configured, the Compared fields of a discrepancy contain import data, and the Reference fields contain discovery data.

The discrepancy field CompareSource holds a value that indicates the origin of the compare-side data. The value is NETWORK for a discovery or an Assimilation scan, or INVENTORY for an import scan.

Table 4-1 shows CompareSource values for different discrepancy origins.

Table 4-1 Listing CompareSource Values for Different Discrepancy Origins

Discrepancy Origin	Compared Side	CompareSource	Reference Side	ReferenceSource
Discovery Scan	Discovery Data	NETWORK	Import Data	INVENTORY
Import Scan	Import Data	INVENTORY	Discovery Data	NETWORK
Assimilation Scan	Discovery Data	NETWORK	Import Data	INVENTORY

About Discrepancy Types

There are seven types of discrepancy; they can be divided into four groups of related issues.

Attribute Value Mismatch. See "Attribute Value Mismatch".
Extra Entity, Missing Entity. See "Extra Entity and Missing Entity".
Extra Association, Missing Association. See "Extra Association and Missing Association".
Ordering Error, Association Ordering Error. See "Ordering Error and Association Ordering Error".

Network Integrity does not allow new discrepancy types to be defined.

Attribute Value Mismatch

This discrepancy indicates that an entity exists in both the Compare and Reference results, but an attribute was found not to have the same value on both sides.

Each discrepancy reports a mismatch problem on a single attribute. An entity can have multiple Attribute Value Mismatch discrepancies reported, if it has several mismatched attributes on both sides.

Table 4-2 shows discrepancy attributes and descriptions.

Table 4-2 Attribute Value Mismatch: List of Discrepancy Attributes

DisDiscrepancy Attribute	Description
compareEntity	This is the target entity whose attribute has a mismatched value.
referenceEntity	This is the matching entity on the other side of the discrepancy detection.
childTargetEntity	Not used. This has no value.
attributeOrRelationshipName	This holds the name of the attribute containing the mismatch.
compareValue	The value of the attribute on the target entity.
referenceValue	The value of the attribute on the matching entity on the other side.

Extra Entity and Missing Entity

This discrepancy indicates that an entity (and any dependent children) is present on one side of the comparison, but is absent from the other side.

An Extra Entity discrepancy indicates that the entity is present in the Compared side, but not in the Reference side.

In Figure 4-1, the example for the Extra Entity discrepancy shows an FDDI card in slot 7 present on the Compared side that is missing on the Reference side.

A Missing Entity discrepancy indicates the reverse: the entity is absent is the Compared side, but present in the Reference side.

In Figure 4-1, the example for the Missing Entity discrepancy shows that slot 7 is missing an FDDI card on the Compared side that is present on the Reference side.

Figure 4-1 Examples of Extra Entity and Missing Entity

Table 4-3 shows discrepancy attributes and descriptions.

Table 4-3 Discrepancy Attributes and Descriptions

DisDiscrepancy Attribute	Description
compareEntity	This is the parent entity on one side of the comparison.
referenceEntity	This is the parent entity on the other side of the comparison.
childTargetEntity	This is the extra child entity on one side. The entity exists on the Compared entity tree when the discrepancy type is Extra Entity. The entity exists on the Reference entity tree when the discrepancy type is Missing Entity.
attributeOrRelationshipName	This holds the name of the association on the parent entity, which references the childTargetEntity.
compareValue	Not used. This has no value.
referenceValue	Not used. This has no value.

When resolving an Extra/Missing Entity discrepancy, the processor is tasked with either adding or removing an object from its target system. The processor must consider the system that it is managing (Import/Inventory or Discovery/Network), and examine the following discrepancy fields to determine the appropriate action:

DiscrepancyType
CompareSource

For example: A discrepancy resolution processor is created to make corrections to an inventory system. When this processor receives an Extra Entity discrepancy, it must check the value of CompareSource. If this value is NETWORK, the extra entity occurs in the network, and therefore it must be missing from the inventory system. The processor takes the corrective action of creating this entity in the inventory system.

However, if the discrepancy type is still Extra Entity, and CompareSource value is INVENTORY, the extra entity occurs in inventory.

Table 4-4 shows the resolution operations for the example processor, given the actual factors to be considered. The Present in columns indicate the system has the extra entity. The Resolution Operation column lists the appropriate inventory operation to resolve this discrepancy.

Table 4-4 Appropriate Resolution Operations for Sample Processor

Discrepancy Type	Compare Source	Referece Source	Present in Network	Present in Inventory	Resolution Operation
Extra Entity	Network	Inventory	Yes	No	Add the network entity into Inventory.
Missing Entity	Network	Inventory	No	Yes	Remove the inventory entity.

Note:

Table 4-4 assumes that the discrepancy detection action was triggered from a Discovery scan.

If the discrepancies are generated by a discrepancy detection action that listens for results from Import scans, the compare source and reference source are reversed, and subsequently, the appropriate inventory operations are reversed as well. (This situation is not usual, but is certainly possible.) See Table 4-5 for this example.

Table 4-5 Appropriate Resolution Operations for Sample Processor (Import Scan)

Discrepancy Type	Compare Source	Referece Source	Present in Network	Present in Inventory	Resolution Operation
Extra Entity	Inventory	Network	No	Yes	Remove the inventory entity.
Missing Entity	Inventory	Network	Yes	No	Add the network entity into Inventory.

Network Integrity does not report Missing Entity discrepancies on the circuit of a root entity when the root entity is absent from either the Compared side or the Reference side.

For example, if a discovery scan finds Device1 with circuits A and B in the network, and the same device exists in inventory, but with circuits A, B, and C, Network Integrity reports a Missing Entity discrepancy on circuit C in the network.

In the above example, Network Integrity can fully compare the results for Device1 from the Compared side and the Reference side.

However, by default, when Device1 is not listed in the discovery results, Network Integrity does not report Missing Entity discrepancies on the device.

You can build a discrepancy detection action or extend the base discrepancy detection action to report missing Entity discrepancies on root entities. See "About Discrepancy Detection Actions" for more information.

Extra Association and Missing Association

This discrepancy indicates that an association in one entity (source) referencing another entity (target) is present on one side of the comparison, but is absent from the other side.

An Extra Association discrepancy indicates that the association is present in the Compared side, but not in the Reference side.

In Figure 4-2, the example for the Extra Association discrepancy shows a Mapped Device Interface association from Port 1 to Interface 2 present on the Compared side that is missing on the Reference side.

A Missing Association discrepancy indicates the reverse: the association is absent in the Compared side, but is present in the Reference side.

In Figure 4-2, the example for the Missing Association discrepancy shows that the Mapped Device Interface association from Port 1 to Interface 2 is missing on the Compared side but is present on the Reference side.

Each discrepancy indicates a problem with a single direction of association. If two entities have a bidirectional association with each other, and this bidirectional association is completely missing on one side, two discrepancies are generated by Network Integrity.

Figure 4-2 Examples of Extra Association and Missing Association

Illustrates extra and missing association

Table 4-6 shows discrepancy attributes and descriptions.

Table 4-6 Extra Association and Missing Association: List of Discrepancy Attributes

DisDiscrepancy Attribute	Description
compareEntity	This is the source entity on one side of the comparison.
referenceEntity	This is the source entity on the other side of the comparison.
childTargetEntity	This is the target entity of the association. The entity exists on the Compared side when the discrepancy type is Extra Association. It exists on the Reference side when the discrepancy type is Missing Entity.
attributeOrRelationshipName	This holds the name of the association on the source entity which references the childTargetEntity.
compareValue	Not used. This has no value.
referenceValue	Not used. This has no value.

The processor must examine the discrepancy to determine whether the appropriate resolution operation is to add the association, or to remove it.

Table 4-7 shows the appropriate operation, given the values of discrepancy type, compare source, and reference source within the discrepancy.

Table 4-7 Appropriate Resolution Operations for Sample Processor

Discrepancy Type	Compare Source	Reference Source	Present in Network	Present in Inventory	Resolution Operation
Extra Association	Network	Inventory	Yes	No	Add the association into the inventory entity.
Missing Association	Network	Inventory	No	Yes	Remove the association from the inventory entity.

If the discrepancies are generated by a discrepancy detection action that listens for results from Import scans, the compare source and reference source are reversed, and subsequently, the appropriate inventory operation are reversed as well. (This situation is not usual, but is certainly possible.)

Table 4-8 shows the appropriate operation for this particular situation.

Table 4-8 Appropriate Resolution Operations for Sample Processor (Import Scan)

Discrepancy Type	Compare Source	Reference Source	Present in Network	Present in Inventory	Resolution Operation
Extra Association	Inventory	Network	No	Yes	Remove the association from the inventory entity.
Missing Association	Inventory	Network	Yes	No	Add the association into the inventory entity.

Ordering Error and Association Ordering Error

In some cases, the ordering of child or associated entities is significant. This discrepancy indicates that matched entities appear in different orders between the two sides. The only difference between the two types of discrepancy is that an Ordering Error indicates a problem with a parent/child association, while an Association Ordering Error indicates a problem with some other association.

Table 4-9 shows discrepancy attributes and descriptions.

Table 4-9 Ordering Error and Association Ordering Error: List of Discrepancy Attributes

DisDiscrepancy Attribute	Description
compareEntity	This is the source/parent entity on one side of the comparison.
referenceEntity	This is the source/parent entity on the other side of the comparison.
childTargetEntity	Not used. This has no value.
attributeOrRelationshipName	This holds the name of the association having the ordering problem.
compareValue	Not used. This has no value.
referenceValue	Not used. This has no value.

About Discrepancy Status

The discrepancy status field identifies the state of a discrepancy within its life cycle. Table 4-10 lists the possible discrepancy statuses.

Table 4-10 Discrepancy Statuses

Status	Status Change Trigger	Valid Follow-On Statuses
Opened	NA	Ignored, Identified
Ignored	UI command	Opened, Identified
Identified	UI command	Submitted, Ignored, Opened
Submitted	Programmatic operation	Received, Failed, Processed, Not Implemented
Received	Programmatic operation	Failed, Processed
Failed	UI command	Ignored, Identified
Not Implemented	NA	NA
Processed	NA	NA

Figure 4-3 shows the discrepancy status lifecycle diagram.

Figure 4-3 Discrepancy Status Life Cycle

Illustrates discrepancy status lifecycle

Every discrepancy begins with a status of OPENED when it is first detected. It can then be moved to one of two states by a user using a web UI operation:

IDENTIFIED, by using a resolution action menu item
IGNORED, by using the Ignore menu item

When a discrepancy is in the IDENTIFIED state, a user can use the Submit operation to move it to the SUBMITTED state. At this point, the discrepancy has moved out of user control, and into the control of a resolution action.

The resolution action processes the submitted discrepancy, and reports the outcome by setting the status to:

PROCESSED, or
FAILED

If the status is PROCESSED, the operation has succeeded, and the discrepancy can no longer be acted upon. If the status is FAILED, it becomes available for the user to specify an operation again, just like when it was first opened.

A resolution action may set a discrepancy status to RECEIVED immediately after the submit operation. This status indicates that the resolution operation is in progress, and reports its final operation status later.

About Discrepancy Detail

Table 4-11 lists all the attributes of a discrepancy. The Java type of a discrepancy is DisDiscrepancy. Use Java getter and setter patterns to retrieve and set the attribute's value. For example use the getPriority() method to get the value of priority, and setPriority(String) method to change its value.

Although the setters for all attributes are public, most fields should not be directly set by the processors. The following fields are safe to be used by processor Java implementations:

priority
notes
discrepancyOwner

The status and failureReason fields should be set using the context methods when inside a processor invoke method. Otherwise, they can also be set using setters.

Table 4-11 Discrepancy Attributes

DisDiscrepancy Attribute	Type	Description
type	DisDiscrepancyType (Enum)	The discrepancy type. Valid values are: ATTRIBUTE_VALUE_MISMATCH EXTRA_ENTITY MISSING_ENTITY EXTRA_ASSOCIATION MISSING_ASSOCIATION ORDERING_ERROR ASSOCIATION_ORDERING_ERROR
severity	DisDiscrepancySeverity (Enum)	The severity of the discrepancy. The values are (from most severe to least): CRITICAL MAJOR MINOR WARNING
entityName	String	The name of the entity for which this discrepancy is raised.
externalEntityType	String	The name of the specification, if the entity has a specification. Otherwise, the same value as staticEntityType.
staticEntityType	String	The name of the base entity type of the entity.
attributeOrRelationshipName	String	This holds the name of the attribute or relationship having the discrepancy.
compareEntity	long (Weak Reference)	This is the entityID of the entity for which this discrepancy is raised.
compareSystem	DisSource (Enum)	Indicates whether the compare data comes from Network (Discovery) or Inventory (Import) system. Valid values are NETWORK and INVENTORY.
compareValue	String	This is used by attribute value mismatch discrepancies to hold the value of the attribute on the compare side.
compareSource	String	The source value of the compareEntity. This value is copied from the Source field of the Scan configuration used to discover/import this entity into Network Integrity.
referenceEntity	long (Weak Reference)	This is the entityID of the entity of the discrepancy on the opposite side to the compareEntity.
referenceSystem	DisSource (Enum)	This indicates whether the reference data comes from Network (Discovery) or Inventory (Import) system. Valid values are NETWORK and INVENTORY.
referenceValue	String	This is used by attribute value mismatch discrepancies to hold the value of the attribute on the reference side.
referenceSource	String	This is the source value of the referenceEntity. This value is copied from the Source field of the Scan configuration used to discover/import this entity into Network Integrity.
childTargetEntity	long (Weak Reference)	Used by Extra/Missing discrepancies to indicate the child/target entityID of the entity of an association.
ancestorEntityName	String	This is the name of the ancestor (parent) entity for the discrepancy.
ancestorEntityType	String	This is the name of the specification, if the ancestor entity has a specification. Otherwise, it takes the same value as ancestorStaticEntityType.
ancestorStaticEntityType	String	This is the name of the base entity type of the ancestor entity.
parentResultGroup	DisResultGroup	This is a reference of the parent scan result detail (that is, the result group) of the compareEntity.
path	String	This is the path to the entity for this discrepancy. It is a comma-delimited list of entity IDs that describes the path from the root entity. For Missing Entity and Missing Association discrepancies, it is the path to the compareEntity followed by the entityID of the referenceEntity. For other discrepancy types, it is the path to the compareEntity.
priority	String	This is a user-editable field used to indicate the priority of this discrepancy. This would typically be used for customer-specific categorization, enabling a finer control than using severity alone.
notes	String	This is a user-editable field for comments.
discrepancyOwner	String	This is a user-editable field used to indicate an external owner of the discrepancy. It may be used for other purposes if desired.
operation	String	This holds the name of the resolution action being invoked.
operationIdentifiedBy	String	This is the ID of the user who identified the resolution action (the UI action to set the resolution operation, before the submit operation).
operationSubmittedBy	String	This is the ID of the user who submitted the resolution action.
submittedTime	Date	This is the timestamp when the status changed to OPERATION_SUBMITTED.
status	DisDiscrepancyStatus (Enum)	This is the current status of this discrepancy. Valid values are: DISCREPANCY_OPENED DISCREPANCY_IGNORED OPERATION_IDENTIFIED OPERATION_SUBMITTED OPERATION_RECEIVED OPERATION_NOT_IMPLEMENTED OPERATION_PROCESSED OPERATION_FAILED
lastStatusChangeTime	Date	This is the timestamp when the status attribute was last updated.
reasonForFailure	String	This holds the error message set by the processor using context.discrepancyFailed() method.
entityID	long	This is an Internal identifier.