5 The Inventory and Capacity Management API

The Inventory and Capacity Management (ICM) API provides the IDL for importing equipment and exporting circuits and equipment. The ICM API provides beginning-to-end visibility of service and network assets, including facilities, equipment, and circuits. By exposing equipment specifications and installed locations, as well as circuit, trunk, and facility capacity, the ICM API enables you to query for your capacity on facilities, trunks, PVCs, and SONET networks.

The ICM API also allows you to query for all equipment located at a network location, including all associated port information, hard-wired cross-connect information, and software cross-connect information.

The ICM API also enables you to take these actions in the Oracle Communications MetaSolv Solution database:

Assign and unassign IP addresses
Create, update, and delete network elements
Create and destroy hard-wired cross-connects
Create, update, and delete condition codes and comments for one or more physical port addresses or equipment mounting positions on a piece of equipment
Install, update, move, copy, uninstall, and delete equipment
Query for condition codes
Query for IP addresses
Query for network elements
Query for network element types
Validate network element type references

The CORBA-registered name for the API server process used by the ICM API is DLRSERVER.

Note:

The ICM API does not include the getSwitchActivation_V5 and getTransportProvisioning_V5 operations that are described in the IDL files used by the ICM API. The getSwitchActivation_V5 operations is enabled only if you have purchased a license for the Switch Provisioning Activation API. The getTransportProvisioning_V5 operation is enabled only if you have purchased a license for the Transport Provisioning Activation API.

Key MetaSolv Solution Concepts

This section of the chapter identifies and describes key concepts used in MetaSolv Solution that are also used by the ICM API.

Equipment Types, Equipment Specifications, and Equipment

In order to understand how MetaSolv Solution represents your equipment inventory in its database, you must understand the distinction between equipment types, equipment specifications, and individual pieces of equipment.

An equipment type is a broad categorization of the different kinds of equipment used in a telecommunications network, such as the types RELAY RACK, CHANNEL BANK, and CARD. All relay racks are categorized as type RELAY RACK, regardless of the manufacturer or part number. Details that differentiate one relay rack from another are defined in the equipment specifications for those pieces of equipment. Equipment type is a property of an equipment specification.

An equipment specification is a reusable definition of a specific kind of equipment. Equipment specifications identify the basic characteristics of a piece of equipment that are shared with other pieces of the same model of equipment, including:

Equipment type
Manufacturer
Model number
Number of physical mounting positions
Number of logical port addresses
Number of port address placeholders for each mounting position
Transmission rates for each port address and port address placeholder

A piece of equipment is an instance of an equipment specification. An individual piece of equipment is a single, concrete piece of equipment that performs a function, such as a channel card, provides a service to other equipment, such as a jack panel, or houses other pieces of equipment, such as a relay rack. Information that is specific to a specific piece of equipment, such as serial number, is stored in the database record for that piece of equipment.

Typically, the smallest piece of equipment tracked in the MetaSolv Solution database is a card, such as a channel card. The individual electronic components that make up a card, such as buttons, fuses, transistors, capacitors, and diodes, are not normally included in the MetaSolv Solution equipment inventory. The physical connection ports on a piece of equipment are discussed later in this chapter.

In MetaSolv Solution, the cables, wires, and fiber strands that are also part of your network are not part of your equipment inventory. Instead, those items are part of your plant inventory. Plant inventory information and operations are available in the MetaSolv Solution Plant API. See "The Plant API" for more information.

Equipment Network Elements

Network elements represent intelligent devices that make up a telephony or data network and allow communication and transmission between different types of networks. A network element can be composed of a system with many shelves, such as a switch or digital cross-connect system (DCS), or it can be a SONET node. SONET nodes are defined in the MetaSolv Solution SONET network design module. Network elements are defined in the MetaSolv Solution Equipment Administration module.

Network elements can also be defined as gateway network elements (GNEs), allowing them to be communicated with locally, remotely, and via other network devices, such as a Network Management System (NMS). Defining a network element as a gateway network element allows you to log into that element, enabling communication and exchange transactions, such as software cross-connect commands. Defining remote access information is optional for network elements, but it is required for GNEs. GNEs must have one of the following fields or field combinations defined on the MetaSolv Solution Network Element Properties window - Node tab.

The IP Addr, Port, and Shelf fields
The Dial Up field
The Other field

Target identifiers (TIDs) can be associated with multiple shelves through the network element, eliminating the need for separate identifiers at the shelf level when all the shelves are part of the same system, such as in the case of a switch or a DCS. TIDs are displayed on the CLR/DLR when an assignment is made to a card that is installed in a shelf that is associated with the element. TIDs are also displayed on the CLR/DLR when an assignment involves equipment that is associated with a node, whether it be through a physical assignment or an enabled port assignment. This also applies to network route assignments, network assignments, facility assignments, and equipment assignments.

Equipment Name Aliases

You can use an equipment name alias to give a second name to a piece of equipment. This allows you to refer to that piece of equipment by either name.

You might need to use equipment name aliases if a company you share data with uses a different naming convention than you do. For example, equipment or circuits that you do not own might be inventoried as part of your network. This might be required if equipment is located in a co-located environment, such as an associated Local Exchange Carrier's (LECs) or Inter-Exchange Carrier's (IXCs) building, where different names are used for equipment.

Equipment name aliases are displayed on the CLR/DLR in the Notes section, but can be suppressed when the associated design lines are suppressed.

Equipment Installation in MetaSolv Solution

Equipment installation is the process of selecting an equipment specification and associating it with a specific network location.

Note:

When importing equipment via the ICM API, you must import only one piece of equipment at a time. You cannot import an entire hierarchy of equipment with a single operation.

When you install a piece of equipment in MetaSolv Solution, you must:

Indicate which equipment specification you want to use as the basis for the piece of equipment you are installing
Specify additional details about the piece of equipment you are installing to distinguish it from other pieces of equipment installed at the same network location from the same equipment specification

If the equipment has defined mounting positions, you can install other pieces of equipment in those mounting positions.

In addition to installing equipment, you can:

Move equipment between mounting positions at the same network location
Move equipment between network locations
Uninstall equipment (move equipment from the installed equipment hierarchy to the spare equipment hierarchy at a network location)
Copy equipment definitions to additional mounting positions or to other locations
Delete equipment from a network location
Specify hard-wired cross-connects between port addresses on two pieces of equipment at the same network location
Specify condition codes for any physical port addresses and mounting positions on an installed or spare piece of equipment
Assign and unassign IP addresses to physical and virtual port addresses

Mounting Positions

A mounting position is a physical place on a piece of equipment where other equipment can be fastened or installed. For example, the mounting positions on a relay rack are a series of boltholes, while the mounting positions in a channel bank are a series of card slots. Other pieces of equipment can be fastened or installed in those mounting positions.

Note:

The presence of a mounting position does not imply programmed or engineered capability to recognize, process or forward transmissions.

Mounting positions are only specified for equipment that has one or more places where other equipment is fastened or installed. For example, a D4 channel bank has 48 mounting positions. Therefore, the equipment specification for the D4 channel bank card indicates that it has 48 mounting positions. The channel cards, which occupy the D4 channel bank's 48 mounting positions, have no mounting positions. Therefore, the equipment specifications for the channel card indicate that they do not have mounting positions.

Ports and Port Addresses

Physical ports, also referred to as port addresses, usually provide the means to connect equipment in a network by using a plug and socket connection. A physical port is a physical location on a piece of equipment where signals enter or leave.

Because signals enter or exit, ports are assigned a rate code. The rate code assigned to a port implies the ability to attach a circuit with a rate code of equal value.

Virtual Port Addresses

Virtual ports are conceptual ports that do not physically exist on a piece of equipment. Virtual ports allow you to work with digital loop carrier (DLC) systems, where the capacity of the system is greater than the transport channels available. Virtual ports also allow you to assign an IP address to a piece of equipment rather than to a specific physical port.

You can only assign circuits to the lowest level virtual ports. Once you assign a circuit to the lowest level (child) virtual port, the status of the parent-level virtual port remains unassigned and the status of the child-level virtual port changes as follows:

If the circuit is associated with a service request, the circuit goes into ”Pending” status immediately, and then into ”In Service” status when the service request's Due Date task is completed.
If the circuit is not associated with a service request, the circuit goes directly into ”In Service” status.

Enabled Ports and Enabled Port Addresses

Unlike ordinary ports, an enabled port is not a physical place on a piece of equipment. Instead, it is a port that the equipment creates through its internal software. For example, a DCS is used to cross-connect channels from one facility to another. This connection is accomplished digitally through enabled ports. A DCS with two physical DS1 ports may have no mounting positions, but can still enable, via software, 24 ports for each DS1. The software-enabled ports are then used to cross-connect DS0 channels riding the DS1s.

The rate code for an enabled port address cannot exceed the rate code for the primary port address. The DCS in the example has two primary port addresses with DS1 transmission rates. Therefore, the DCS can enable only a DS1 or DS0 transmission rate port.

Port Address Placeholders

As a rule, mounting positions do not provide physical ports for attaching circuits. A port address placeholder is a construct in the MetaSolv Solution database that allows you to assign logical ports to mounting positions where equipment with physical ports is scheduled to be installed. In short, port address placeholders allow circuit design work to continue when equipment is not yet installed.

For example, you want to cross-connect a jack panel to a shelf before the shelf's cards are installed. However, at this point there are no port addresses to cross-connect to, because the port addresses are on the cards and the cards are not installed. The solution is to define placeholders for the shelf's mounting positions (the potential number of port addresses available once a card is installed in the mounting position). As a result, you can cross-connect to the port address placeholders before a card is installed. When you install a card, its port addresses are automatically associated with the mounting position's port address placeholders.

The act of installing equipment in a mounting position that has port address placeholders does associate the circuits as directed by the placeholders, but does not remove the underlying placeholders themselves. This allows you to move cards in and out of a mounting position without removing the underlying cross-connects. When the equipment is removed, the port address placeholder remains, awaiting the next equipment installed in that mounting position.

When you specify port address placeholders for a mounting position, verify that the number of port address placeholders match the number of ports on the equipment that is to be installed in those mounting positions. Also, the rate code assigned to the port address placeholders must match the rate code of the ports on the equipment you install.

Port Address Aliases

You can use a port address alias to give a second node address to a port. This allows you to refer to that port address by either node address.

You may need to use port address aliases if a company you share data with uses a different addressing format than the one you use. In a co-located environment, equipment or circuits that you do not own may be inventoried as part of your network.

Port aliases are included on the CLR/DLR in the Notes section, but can be suppressed when the associated design lines are suppressed. Notes in the Notes section of the CLR/DLR include port aliases to which circuits have been assigned or those that have been cross-connected to a port address. If the cross-connected port address has an alias, both aliases display.

Nodes and Node Addresses

A node is a piece of equipment on a network with the ability to recognize, process, or forward signals to other equipment. For example, a node can be a router in a token ring or an OC12 terminal in a SONET network.

A node is aware of other nodes on the network and is capable of receiving transmissions from or forwarding transmissions to other nodes. Like a letter delivered to its recipient through a series of postal centers, a communications signal travels across a network among nodes to reach its destination.

A node address is an identifier that is unique to each node, distinguishing one node from another. MetaSolv Solution can base node addresses on a hierarchy of the physical components comprising the node: rack, shelf, and card. You can manually replace or alter, override, this hierarchical (or concatenated) node address by using hard and soft node address overrides on individual ports. You can also define a sequential numbering scheme for mounting positions on an equipment specification in order to automatically number ports sequentially across cards in a shelf.

Sequential Port Address Numbering

You can define a sequential numbering scheme for mounting positions on an equipment specification in order to number ports sequentially across cards in a shelf. You can use this automated numbering method, instead of hard and soft node address overrides, when working with multiple shelves of a DCS system where sequential numbering is applied to all ports of a given rate code. As with hard and soft node address overrides, the sequential numbering scheme you define replaces the concatenated node address.

Each shelf using sequential numbering is identified by a unique combination of unit number, unit extension, and network element location ID. The unit number identifies a piece or multiple pieces of equipment that contain cards. Every unit associated with a network element has a unique unit number and unit extension identifier. If the unit contains one shelf, that shelf has a unique unit number and a unit extension of zero.

For example, each of the 16 shelves in a Lucent DACSII Capacity Expansion Frame has a unique unit number between one and 16 and has a unit extension of zero. If the unit contains a group of shelves, each shelf in the group has the same unit number with a unique unit extension. This means that each of the four ATM shelves in a Lucent DACSII Single Bay has the same unit number with a unique unit extension. The first shelf is unit number one, unit extension one. The second shelf is unit number one, unit extension two, and so on.

The numbering sequence for card ports installed in a shelf's mounting positions is independent of the bay in which the unit is installed and independent of the order in which the units are installed. Thus, you can install Unit 5 in Bay 1 before you install Unit 4 in Bay 3 without affecting the numbering of the ports. Figure 5-1 illustrates sequential numbering of port addresses for DSPU cards in a Lucent DACSII.

Figure 5-1 Example of Sequential Numbering of Port Addresses

Description of "Figure 5-1 Example of Sequential Numbering of Port Addresses"

The sequential numbering scheme for a DCS shelf is defined on the equipment specification. You can create a variety of sequential numbering schemes, including straight sequential (with or without channel assignments) and sequential with augmentation. Upon installation of the shelf, you can disable numbering for selected ports by checking the Disable PA check box in the MetaSolv Solution Equipment window - Mounting Positions tab to create a sequential with skipped numbers scheme. Once the shelf is installed and a unit number and unit extension are defined, you cannot edit the sequential numbering scheme unless you uninstall the shelf. If a shelf is installed without a unit number and unit extension, and you add a numbering scheme to the equipment specification, the numbering scheme is not copied to the installed shelf unless you assign a unit number and unit extension and associate the shelf with a network element.

You can use the same specification to accommodate both sequential port numbering and hierarchical port numbering schemes. If you want to use a concatenated hierarchical port numbering scheme for a DCS systems, disable the numbering defined in the specification for each shelf in the DCS by unchecking the Seq Port Numbering check box on the MetaSolv Solution Equipment window - Mounting Positions tab.

Hard-Wired Cross-Connects

To a field engineer, a hard-wired cross-connect, also referred to as cabling, is the wiring of one equipment port to another. The hard-wired cross-connects you create in the MetaSolv Solution database represent the actual hard-wired cross-connects between equipment ports. An example of a hard-wired cross-connect is the cabling between a shelf and a DSX jack panel.

Hard-wired cross-connects remain intact as circuits are assigned or unassigned to cross-connected ports. In other words, an equipment port is dedicated to another equipment port so that when you assign a circuit to the first equipment port, through Circuit Design, the other equipment port is also included on the DLR/CLR for that circuit. When the circuit is disconnected, the hard-wired cross-connect remains, awaiting the next circuit assignment.

You can create cross-connects in the MetaSolv Solution database to represent physical cross-connects that exist in your equipment inventory. You can make cross-connects between ports on a single piece of equipment or between ports on two separate pieces of equipment. You can also create cross-connects between a port address placeholder and a port address or port address placeholder. However, just as it is physically impossible to connect a given port address to itself, you cannot cross-connect port addresses and port address placeholders to themselves.

It is possible to cross-connect two pieces of equipment that have different Network Locations, allowing you to cross-connect equipment in two different locations. For example, in a co-located environment, you might want to cross-connect two pieces of equipment that are physically located in the same place but have different Network Location code assignments. When you use MetaSolv Solution to cross-connect equipment in two different locations, an informational message reminds the user that the locations are different.

The MetaSolv Solution cross-connect functionality allows you to create cross-connects for enabled port addresses. This functionality allows you to cross-connect equipment software to equipment hardware internally.

Several scenarios exist in which cross-connecting equipment is not allowed. Most of these scenarios relate to the existence of circuit assignments to one or both of the ports involved in the cross-connect.

The following scenarios describe instances when you cannot cross-connect equipment due to the existence of circuits that are already assigned to the port addresses being cross-connected.

You cannot cross-connect a physical port address to an enabled port address if the physical port address has an assigned circuit and the enabled port address is already mapped.
You cannot cross-connect a physical port address to an enabled port address if the physical port address has a circuit assignment and the enabled port address was not mapped.
You cannot cross-connect a physical port address to another physical port address if both of the port addresses have different assigned circuits.
You cannot cross-connect a physical port address that has a circuit assignment to a cross-connect chain that contains a mappable port.
You cannot cross-connect an enabled port address to another enabled port address if both enabled port addresses are mapped to the same circuit and different circuit assignments exist for each enabled port address being cross-connected.
You cannot cross-connect a physical port address to another physical port address if the port addresses have different pending assignments.

In the ICM API, an additional condition applies: if there is a ”Blocked” condition code anywhere in the entire chain of circuits that would be created by a cross-connect, the ICM API does not create the requested cross-connect.

Condition Codes

Condition codes identify the condition of certain mounting positions, port addresses, or cable pairs. Using condition codes helps you prevent inventory from being used or better defines its capabilities. For example, if you wanted to mark a cable pair to no longer be in service, you could give it a condition code of Bad. A Local Assignment condition code could denote that a port address has already been used on a local order. You can assign the type of warning that is given when an assignment is made to a circuit position, port address or cable pair with a certain condition code.

Circuit positions, mounting positions, and port addresses with condition codes are labeled [Information] or [Blocked] when you view them in the Equipment Install window or the Circuit Hierarchy window, depending on the condition code type.

IP Address Management in MetaSolv Solution

The MetaSolv Solution Infrastructure module includes an IP Address Management function that inventories all IP addresses owned by an ISP. IP addresses are unique numbers that identify a computer or device on a network. Public IP addresses are part of a standardized plan for identifying machines connected to the Internet. Using the IP Address Management function, you can keep track of IP addresses. The IP Address Management function lets you:

Define base networks in your inventory
Create subnets or pools from base networks
Divide a subnet into more subnets
View host IP addresses within a subnet
Track the status of an IP address
Query for existing IP addresses
Combine subnets
Create IP pools
Delete subnets, IP pools, and base networks
Recall IP addresses for reuse

The American Registry for Internet Numbers (ARIN) or your upstream ISP allocates base networks to you.

An IP address can be expressed as four decimal numbers separated by dots. Each number can have a value of zero to 255. An example of an Internet address is 130.5.5.171.

The size of base networks, which can be displayed as an IP address followed by a network prefix length (130.5.5.25/24). For example, a /24 network block has 256 IP addresses, where the first address is the subnet network address, the last address is the broadcast address and the remaining 254 addresses are host addresses. A network prefix can also be displayed as a subnet mask. For example, /24 is the same as a 255.255.255.0 submask.

In MetaSolv Solution, you can define your base network in one of two ways:

You can divide your base network into two or more subnets of the same size.
You can leave your base network as a pool of available addresses from which you can create subnets of varying sizes as you need them.

If you divide your base network into subnets and then divide any of the initial subnets into multiple smaller subnets, you can reverse this process by combining subnets to create a single larger subnet. You can delete a subnet as long as it is not assigned and none of its host addresses are assigned. When you delete a subnet, its unassigned addresses become pooled addresses. Pooled addresses are not available for assignment. To be available for assignment, IP addresses must be part of a subnet.

When you define the base network, you can divide the IP address blocks into subnets or IP pools based on your business needs. Your specific business needs determine the number of subnets required and the size of each.

Overview of Assigning IP Addresses to Ports

You can assign an IP address to either a physical or virtual port. A physical port is a physical location on a piece of equipment where you can connect the equipment to a network by using a plug and socket connection. A virtual port is a conceptual port that does not physically exist on a piece of equipment. Virtual ports allow you to assign IP address generically to a piece of equipment, rather than to a specific physical port. You can assign to either a physical or a virtual port, depending on the situation. For example, if you are working with a router, you must assign an IP address to a specific serial (or physical) port. If you are working with a Web server, you assign the IP address for the customer's domain to the Web server and not to a specific port on that server.

The following rules apply to assigning IP addresses to port addresses:

You can only assign one host number to a physical port.
You can assign any number of subnets and/or host IP addresses to a virtual port address.
You cannot assign IP addresses to a physical enabled port address or to a virtual enabled port address.
If a subnet is assigned to a virtual port address, it must be at the lowest subnet level. The subnet cannot have any subnets defined below it.
You cannot individually unassign host number IP addresses from a virtual port address once the subnet is assigned. You can only unassign the subnet.
If you unassign the subnet from a virtual port address, all of the host numbers are also unassigned.
A port address or its related equipment and an IP address may be associated with one or more network areas. The network area associated with a port address and its related equipment does not have to be the same as the network area associated with the IP address.
Equipment connected by the same circuit must have IP addresses from the same subnet.
You cannot assign the same circuit to more than two pieces of equipment with IP addresses.

An IP Address assigned to a physical port displays on the MetaSolv Solution Equipment Install window at the port address level. If a circuit is also assigned to the port address, the IP address displays before the Circuit ID. For example:

     (STS1 –In Service), 123.123.123.123, 1515 /ST01 /PLANTXXA 
/PLANTXXB(In Service)

An IP Address assigned to a virtual port also displays on the MetaSolv Solution Equipment Install window at the port address level. Since multiple subnets and/or host numbers can be associated with the virtual port address, an IP address displays followed by the (…) symbol to indicate that more might exist. If a circuit is also assigned to the port address, the IP address displays before the Circuit ID. For example:

     (STS1 –In Service), 123.123.123.123 (...), 1515 /ST01 /PLANTXXA 
/PLANTXXB (In Service)

Some Common Questions About Equipment in MetaSolv Solution

This section identifies a number of questions MetaSolv Solution users commonly ask when first implementing the Equipment Administration module.

How can I more quickly install equipment with the same configuration?

If you have certain pieces of equipment that you install the same way repeatedly, create a ”template” Network Location and copy the equipment from the template to real Network Locations.
Can I inventory equipment that is stored in my warehouse?

You can maintain a warehouse location that is used to inventory spare equipment. Make up a warehouse Network Location in which to ”install” the equipment, then as the equipment is physically installed in its working location, move the equipment from the warehouse location to the working location.
When I copy equipment, are associated condition codes also copied?

No. When you copy equipment from one location to another, condition codes assigned to equipment positions are not copied.
Should I define Slot Node and Port Addresses on equipment specs or during installation?

Several scenarios exist that determine at what point you want to define slot node addresses and port addresses:
- If the node address for an equipment type will always be the same, regardless of where it is installed, define the node address on the equipment specification.
- If a single or common address exists for a specific piece of equipment, add the addresses to the shelf into which the equipment is installed.
- If multiple ports exist on a card, and the address is always the same, add port addresses on the card's equipment specification.
- If the node address for any type of equipment is determined when the equipment is installed in an office, add the slot node address or port address to each piece of equipment when it is installed.

See the online Help for more information.

ICM API Implementation Concepts

This section identifies key concepts you must know and key issues you must consider when developing applications that utilize the ICM API.

Transaction Management and the ICM API

The ICM API manages transaction processing on behalf of your application. That is, the ICM API handles all commits and rollbacks to the MetaSolv Solution database instead of requiring your application to explicitly commit or rollback transactions. When an operation you requested succeeds, the ICM API immediately commits the results of the operation, then notifies you of the success of the operation. When an operation you requested fails, the ICM API immediately rolls back the results of the operation, then notifies you of the failure.

Note:

Some of the older ICM API export operations still require you to supply a valid WDITransaction object reference. In these cases, you should still call the commit operation when using these export operations in order to release the read locks the database places on the exported records. Also in these cases, you must call the destroyTransaction operation in order to free the allocated resource.

Network Inventory Gateway Events and the ICM API

The ICM API and the MetaSolv Solution Network Management module support the use of gateway events for network inventory. Network inventory gateway events signal a third party that significant additions, deletions, or changes have occurred in the network inventory.

Network inventory gateway events are generated automatically based upon the settings of the rules/behaviors functionality in the MetaSolv Solution Work Management module. The actions in the Network Inventory module that can trigger evaluation of rules are:

Installing or uninstalling equipment
Copying equipment to a new location
Modifying installed equipment
Modifying condition codes for equipment mounting positions or port addresses individually
Modifying condition codes for equipment mounting positions or port addresses by range
Modifying virtual ports for equipment
Moving equipment to an empty mounting position
Assigning or unassigning an IP Address to equipment
Assigning or unassigning a circuit to equipment
Modifying hard-wired cross connects on equipment
Modifying equipment specifications
Modifying network elements on equipment

The actions listed above only trigger an equipment gateway event when the Work Management subsystem's rules and behaviors functionality is configured to do so.

Deleting equipment cannot trigger gateway events. When you delete installed equipment, the result of the deletion is that the equipment ID is removed from the MetaSolv Solution database. No equipment event can be sent in this case, because there is no equipment ID to pass.Therefore, you should uninstall the equipment to move it to ”Spare” status, which can generate an equipment event, then delete the equipment.

DLR Mass Reconcile

When you edit equipment or equipment specifications, modify network elements, or move equipment with assigned circuits, the design layout reports (DLRs) for those circuits are reconciled to reflect the change, including pending assignments. The ICM API sends these reconciliations to the Background Processor utility. The ICM API does not support printing of design lines during DLR mass reconcile.

ICM API IDL files

The ICM API is described in these IDL files:

WDI.idl
WDICircuit.idl
WDICircuitTypes.idl
WDICircuitTypes_v2.idl
WDICircuitTypes_v3.idl
WDIDLR.IDL
WDIDLRQueryTypes.idl
WDIDLRQueryTypes_v2.idl
WDIDLRQueryTypes_v3.idl
WDIDLRTypes.idl
WDIDLRTypes_v2.idl
WDIDLRTypes_v3.idl
WDIDLRTypes_v4.idl
WDIDLRTypes_v5.idl
WDIEquipment.idl
WDIEquipmentTypes.idl
WDIEquipmentTypes_v2.idl
WDIEquipmentTypes_v3.idl
WDIVLRTypes.idl
WDIVLRTypes_v2.idl

The WDIPlant.idl and WDIPlantTypes.idl files are also included in the ICM API. See "The Plant API" for a complete description of the operations in these files.

ICM API Interfaces

Figure 5-2 shows the relationships of the modules and interfaces in the ICM API.

Figure 5-2 ICM API Interfaces

Description of "Figure 5-2 ICM API Interfaces"

WDIManager Interface

Table 5-1 lists the operations available in the WDIManager interface of the WDIDLR.idl file.

Table 5-1 WDIManager Interface Operations

Operation	Description
destroyCircuitHierarchySession	Terminates the Circuit HierarchySession
destroyDLRSession	Terminates the DLRSession
destroyEquipmentSession	Terminates the EquipmentSession
destroyInSignal	Terminates the InSignal
destroyPlantSession	Terminates the PlantSession
destroySignal	Terminates the Signal
destroySignal2	Terminates the Signal2
destroyTransaction	Terminates the Transaction
startCircuitHierarchySession	Obtains the object reference for the Circuit HierarchySession
startDLRSession	Obtains the object reference for the DLRSession
startEquipmentSession	Obtains the object reference for the EquipmentSession
startInSignal	eventInProgress eventCompleted eventErrored
startPlantSession	Obtains the object reference for the PlantSession
startSignal	eventOccurred eventTerminated eventInProgress eventCompleted eventErrored
startSignal2	eventOccurred eventTerminated eventInProgress eventCompleted eventErrored
startTransaction	Obtains a handle to a database transaction

Note:

See "Common Architecture" for a complete description of the operations.

CircuitHierarchySession Interface

Table 5-2 lists the operations available in the CircuitHierarchySession interface of the WDICircuit.idl file.

Table 5-2 CircuitHierarchySession WDINotification Operations

Operation	WDINotification
getBandwidthCircuits	getBandwidthCircuitsSucceeded getBandwidthCircuitsFailed
getCircuitPositionConditionCodes	getCircuitPositionConditionCodesSucceeded getCircuitPositionConditionCodesFailed
getCircuitPositionHierarchy	getCircuitPositionHierarchySucceeded getCircuitPositionHierarchyFailed
getCircuitPositionHierarchy_v3	getCircuitPositionHierarchySucceeded_v3 getCircuitPositionHierarchyFailed_v3
getCircuitPositionPending	getCircuitPositionPendingSucceeded getCircuitPositionPendingFailed
getCircuitPositionPrevious	getCircuitPositionPreviousSucceeded getCircuitPositionPreviousFailed
getNetworkRouteSegments_v2	getNetworkRouteSegmentsSucceeded_v2 getNetworkRouteSegmentsFailed
getNetworkSegmentCircuits_v2	getNetworkSegmentCircuitsSucceeded_v2 getNetworkSegmentCircuitsFailed_v2
getNetworkSegmentCircuits_v3	getNetworkSegmentCircuitsSucceeded_v3 getNetworkSegmentCircuitsFailed_v3
getTrunkGroup_v2	trunkGroupGetSucceeded_v2 trunkGroupGetFailed
queryNetworkRoutes_v2	queryNetworkRoutesSucceeded_v2 queryNetworkRoutesFailed_v2
queryTrunkGroups_v2	trunkGroupQuerySucceeded_v2 trunkGroupQueryFailed_v2
getTrunkGroupQueryValidValues_v2. This value is returned when implemented by the DLRSERVER.	N/A
getMaximumReturnedRows. This operation is implemented by the caller and returns a long. This allows the server to return maximum number of records for certain queries (0 = no limit.)	N/A

The following list contains a description of the operations available in the CircuitHierarchySession interface:

getNetworkSegmentCircuits_v2

Note:
In MetaSolv Solution, when a SONET path-switched ring is built, two SONET routes are created. For example, for a 4 node ring, A-B-C-D, if the circuit requires entrance at node A and exit at node B, then there are two paths that can be traversed. These are A-B and A-D-C-B. Because of the rules surrounding a path-switched ring, MetaSolv Solution displays only one route, but combines the mileage and the connecting facilities under one segment tree item. This feature occurs on the display, even though both SONET routes are extracted from the database. However, the ICM API provides all of the SONET routes, with the ability to query each route individually. The assumption in the API is that, in the case of path-switched rings, the client program can combine the mileage and circuits for display purposes.
getCircuitPositionHierarchy

Note:
Since hierarchy operations can return substantial amounts of data, a oneLevelOnly parameter is provided in the request structure to limit results to the first level of data directly beneath the request item for tree-structured data.
getTrunkGroupQueryValidValues_v2

If you pass empty criteria, the operation returns all valid values. If you pass match criteria for a field, the operation will return one QueryField full of matches for that field.
getMaximumReturnedRows

Implemented by caller, returns a long value. This operations allows the API server to return the maximum number of records for certain queries (0 = no limit.)

EquipmentSession Interface Operations

Table 5-3 lists the operations available in the EquipmentSession interface of the WDIEquipment.idl file.

Table 5-3 EquipmentSession WDINotification Operations

Operation	Description
destroyCrossConnectSubSession	Terminates the CrossConnectSubSession.
destroyInstallationSubSession	Terminates the InstallationSubSession.
destroyNetworkElementSubSession	Terminates the NetworkElementSubSession.
destroySoftwareSpecSubSession	Terminates the SoftwareSpecSubSession.
destroySpecificationSubSession	Terminates the SpecificationSubSession.
startCrossConnectSubSession	Obtains the CrossConnectSubSession object reference.
startInstallationSubSession	Obtains the InstallSubSession object reference.
startNetworkElementSubSession	Obtains the NetworkElementSubSession object reference.
startSoftwareSpecSubSession	Obtains the SoftwareSpecSubSession object reference.
startSpecificationSubSession	Obtains the SpecificationSubSession object reference.

SpecificationSubSession Interface Operations

The SpecificationSubSession interface exposes operations for querying equipment specifications. Table 5-4 lists the operations and their corresponding WDINotification operations available in the SpecificationSubSession interface of the WDIEquipment.idl file. These operations reproduce the same type of functionality as the corresponding function of MetaSolv Solution.

Note:

All failed operations in the SpecificationSubSession interface are reported via the generic operationFailed notification.

Table 5-4 SpecificationSubSession and WDINotification Operations

Operation	WDINotification
getEquipSpecQueryValidValues_v2. This value is returned when implemented by the DLRSERVER.	N/A
getEquipSpec_v2	getEquipSpecSucceeded_v2
getEquipType_v3	getEquipTypeSucceeded_v3
getUsageReport_v2	getUsageReportSucceeded_v2
queryEquipSpec_v2	queryEquipSpecSucceeded_v2
getEquipSpec_v3	getEquipSpecSucceeded_v3

SoftwareSpecSubSession interface operations

The SoftwareSpecSubSession interface exposes operations for querying software specifications. Table 5-5 lists the operations and their corresponding WDINotification operations available in the SoftwareSpecSubSession interface of the WDIEquipment.idl file. These operations reproduce the same type of functionality as the corresponding function of MetaSolv Solution. All failed operations in the SoftwareSpecSubSession interface are reported via the generic operationFailed notification.

Table 5-5 SoftwareSpecSubSession and WDINotification Operations

Operation	WDINotification
getSoftwareSpec	getSoftwareSpecSucceeded
querySoftwareSpec	querySoftwareSpecSucceeded

InstallationSubSession Interface Operations

The InstallationSubSession interface exposes operations for installing equipment and querying on installed equipment. Table 5-6 lists the operations and their corresponding WDINotification operations available in the InstallationSubSession interface of the WDIEquipment.idl file. These operations reproduce the same type of functionality as the corresponding function of MetaSolv Solution. All failed operations in the InstallationSubSession interface are reported via the generic operationFailed notification.

Table 5-6 InstallationSubSession and WDINotification Operations

Operation	WDINotification
addMountPosConditionCode	addMountPosConditionCodeSucceeded
addPortAddressConditionCode	addPortAddressConditionCodeSucceeded
assignIPAddress	assignIPAddressSucceeded
copyEquipment	copyEquipmentSucceeded
deleteEquipment	deleteEquipmentSucceeded
deleteMountPosConditionCode	deleteMountPosConditionCodeSucceeded
deletePortAddressConditionCode	deletePortAddressConditionCodeSucceeded
getEquipInstall_v2	getEquipInstallSucceeded_v2
getEquipInstall_v3	getEquipInstallSucceeded_v3
getEquipInstallMaint_v2	getEquipInstallMaintSucceeded_v2
getMountingPositionConditionCodes_v2	getMountingPositionConditionCodesSucceeded_v2
getPortAddressConditionCodes_v2	getPortAddressConditionCodesSucceeded_v2
getPortAddressInstall_v2	getPortAddressInstallSucceeded_v2
getPortAddressInstall_v3	getPortAddressInstallSucceeded_v3
getPortAddressIPAddress	getPortAddressIPAddressSucceeded
getPortAddressIPAddress_v2	getPortAddressIPAddressSucceeded_v2
installEquipment	installEquipmentSucceeded
moveEquipment	moveEquipmentSucceeded
queryEquipInstall_v2	queryEquipInstallSucceeded_v2
searchEquipInstall_v2	searchEquipInstallSucceeded_v2
unassignIPAddress	unassignIPAddressSucceeded
uninstallEquipment	uninstallEquipmentSucceeded
updateEquipment	updateEquipmentSucceeded
updateMountPosConditionCode	updateMountPosConditionCodeSucceeded
updatePortAddressConditionCode	updatePortAddressConditionCodeSucceeded
validateNetworkElementMatch	validateNetworkElementMatchSucceeded
getEquipInstallQueryValidValues_v2. This operation is implemented by the DLRSERVER. It returns all valid values.	N/A

Comments Concerning Specific InstallationSubSession Operations

The ICM API does not support creation of equipment specifications. In order to install a piece of equipment, the equipment specification must already be defined in the MetaSolv Solution database.

Operations in the InstallationSubSession interface provide functionality equivalent to what exists in MetaSolv Solution to:

Install a piece of equipment at a network location, including installing spare equipment
Edit a piece of equipment at a network location
Copy a piece of equipment, including:
- Copying base equipment to a different location
- Copying any equipment to or from spare
- Copying non-base equipment to a different parent
- Copying non-base equipment to different mounting positions within the same parent
Move a piece of equipment, including:
- Moving base equipment to a different location
- Moving any equipment to or from spare
- Moving non-base equipment to a different parent
- Moving non-base equipment to different mounting positions within the same parent
Uninstall a piece of equipment from a network location
Delete a piece of equipment from a network location

You can use the InstallationSubSession interface operations listed below to perform the indicated functions:

The queryEquipInstall_v2 operation queries first level equipment.
The searchEquipInstall_v2 operation searches for a specific piece of installed equipment.
The searchEquipInstall_v3 operation searches for a specific piece of installed equipment.
The getEquipInstall_v2 operation returns the equipment tree for a piece of equipment.
The getEquipInstall_v3 operation returns the equipment tree for a piece of equipment.
The getPortAddressInstall_v2 operation returns port addresses for a piece of equipment.
The getPortAddressInstall_v3 operation returns port addresses for a piece of equipment.
The getEquipInstallMaint_v2 operation returns miscellaneous information for a piece of equipment.
The getMountingPositionConditionCodes_v2 operation returns mounting position condition codes for a mounting position.
The getPortAddressConditionCodes_v2 operation returns port address condition codes for a port address.
The installEquipment operation installs a new piece of equipment.
The updateEquipment operation updates information on an existing piece of equipment.
The copyEquipment operation copies a piece of equipment to another location or mounting position.
The moveEquipment operation moves a piece of equipment to another location or mounting position.
The deleteEquipment operation deletes a piece of equipment.
The uninstallEquipment operation move a piece of equipment to spare.
The addMountPosConditionCode operation adds one or more condition codes to one or more mounting positions of a piece of equipment.
The addPortAddressConditionCode operation adds one or more condition codes to one or more port addresses of a piece of equipment.
The deleteMountPosConditionCode operation deletes one or more condition codes from one or more mounting positions of a piece of equipment.
The deletePortAddressConditionCode operation deletes one or more condition codes from one or more port addresses of a piece of equipment.
The updateMountPosConditionCode operation updates the comment for one or more condition codes on one or more mounting positions of a piece of equipment.
The updatePortAddressConditionCode operation updates the comment for one or more condition codes for one or more port addresses of a piece of equipment.
The validateNetworkElementMatch operation validates that the network element type associated to the input equipment specification is the same as the network element type associated to the input network element.
The assignIPAddress operation assigns input IP addresses to the input equipment port address.
The getPortAddressIPAddress operation retrieves IP addresses associated to the input equipment port address.
The unassignIPAddress operation unassigns input IP addresses from the input equipment port address.

CrossConnectSubSession Interface Operations

The CrossConnectSubSession interface exposes operations for installing and querying on hardwired and software cross connects. Table 5-7 lists the operations and their corresponding WDINotification operations available in the CrossConnectSubSession interface of the WDICircuit.idl file. These operations reproduce the same type of functionality as the corresponding function of MetaSolv Solution. All failed operations in the CrossConnectSubSession interface are reported via the generic operationFailed notification.

Table 5-7 CrossConnectSubSession and WDINotification Operations

Operation	WDINotification
getHardwiredCrossConnects_v2	getHardwiredCrossConnectSucceeded_v2
getSoftwareCrossConnects_v2	getSoftwareCrossConnectSucceeded_v2
hwccRequest	hwccRequestSucceeded

For the most part, the CrossConnectSubSession interface operations duplicate the functionality of the MetaSolv Solution client. However, the API operations remove some of the restrictions the client imposes on making cross connects.

Any given piece of equipment can have four different type of port addresses:

Port Addresses (PA)
Enabled Port Addresses (EPA)
Port Address Placeholders (PAPH)
Virtual Enabled Port Addresses (VEPA)

In the CrossConnectSubSession, each of those four types of port addresses is considered a section. Hard-wired cross connections are made only for the ports belonging to a section at a time. The ICM API requires that all ports in the sequence be of the same type: PA, EPA, VEPA, or PAPH. Each section can repeat more than once, but intermingling of ports from different sections is not allowed. However, the FROM side port address type can be different from the TO side port address type.

For example, for two sets of starting port address numbers for cross connection on the FROM side, you specify [32, 20] and [102, 50]. For the corresponding TO side port addresses for connection, you specify [76, 20] and [210, 50]. The cross-connection process builds a FROM side list of 20 assignable ports for cross-connection starting from port 32, in ascending port order sequence, then builds a TO side list of 20 assignable ports starting from port number 76. Once both the FROM and TO lists are ready, the ICM API attempts the requested cross-connects.

Formats for Specifying FROM Side Port Addresses

FROM port addresses for hardwired cross-connects are specified in one of three formats. The FROM and TO side formats are independent, and any format on the FROM side can be combined with format case on the TO side.

All ports format

The request is for cross-connecting all the ports on the FROM side equipment, starting from the first port on the FROM side. In this case the PortAddrSeqFrom has no entry.
Specified range format

The request is for cross-connecting a range of ports on the FROM side equipment. In this case, PortAddrSeqFrom has the range of ports for cross-connection. portAddrSeqStart contains the value of first port address of the range. nbrOfPorts specifies the number of ports to be cross-connected, starting from the port identified in portAddrSeqStart. For example, to cross-connect 100 ports from port number 132, specify [132,100]. To cross-connect an additional range of 50 ports starting from port number 760, follow the entry of [132,100] with a second entry of [760, 50].

Note:
In the example, if you specify 0 (zero) as the brOfPorts, that is, you specify [132,0], the operation connects all ports starting with port number 132.

The range of specified ports cannot span across sections. To illustrate this using the preceding preceding example, assume that port number 132 is an Enabled Port Address (EPA). If port number 150 is NOT an EPA, the API gives a validation error. For all ports in a range to be cross-connected, all of the ports must be in the same section.
Specified list of ports format

The request is for cross-connecting a list of ports on the FROM side equipment. This situation can be treated as a special situation of the specified range format. In this case, the PortAddrSeqFrom has the list of ports for cross-connection. Each portAddrSeqStart contains the value of the port address to be cross-connected and the nbrOfPorts has a value of 1.

Formats for Specifying TO-Side Port Addresses

TO port addresses for hardwired cross-connects are specified in one of three formats. The FROM and TO side formats are independent, and any format on the FROM side can be combined with format case on the TO side.

All ports format

The request is for cross-connecting all the specified ports from the FROM side equipment to the TO side equipment, starting from the first port on the TO side. In this case, the PortAddrSeqTo has no entry.
Specified range format

The request is for cross-connecting all the specified ports from the FROM side equipment to the specified range of ports on the TO side equipment. In this case, the PortAddrSeqTo has the range of ports for cross-connection. Each portAddrSeqStart contains the value of the first port address of the range. The nbrOfPorts specifies the number of ports for cross-connection starting from the portAddrSeqStart. For example, to cross-connect 20 ports starting from port number 432, specify [432, 20]. To cross-connect an additional range of 75 ports starting from port number 320, the first entry of [432, 20] is followed by a second entry of [320, 75]. The range of specified ports can span across sections.
Specified list of ports format

The request is for cross-connecting all the specified ports from the FROM side equipment to the specified list of ports on the TO side equipment. This can be treated as a special situation of the specified range format. In this case, the PortAddrSeqTo has a list of ports for cross-connection. Each portAddrSeqStart contains the value of the port address to be cross-connected to, and nbrOfPorts has a value of 1.

Comments concerning specific CrossConnectSubSession operations

Operations available in the CrossConnectSubSession interface:

getHardwiredCrossConnects_v2

Queries for hard-wired cross-connects.
hwccRequest

Requests creation of new hard-wired cross-connects.
getSoftwareCrossConnects_v2

Queries for software cross-connects.

NetworkElementSubSession Interface Operations

Table 5-8 lists the operations and their corresponding WDINotification operations available in the NetworkElementSubSession interface of the WDIEquipment.idl file. These operations reproduce the same type of functionality as the corresponding function of MetaSolv Solution. All failed operations in the NetworkElementSubSession interface are reported via the generic operationFailed notification.

Table 5-8 NetworkElementSubSession and WDINotification Operations

Operation	WDINotification
createNetworkElement	createNetworkElementSucceeded
createNetworkElement_v2	createNetworkElementSucceeded_v2
deleteNetworkElement	deleteNetworkElementSucceeded
getNetworkElement	getNetworkElementSucceeded
getNetworkElement_v2	getNetworkElementSucceeded_v2
getNetworkElementType	getNetworkElementTypeSucceeded
queryNetworkElement	queryNetworkElementSucceeded
queryNetworkElement_v2	queryNetworkElementSucceeded_v2
queryNetworkElementType	queryNetworkElementTypeSucceeded
updateNetworkElement	updateNetworkElementSucceeded
updateNetworkElement_v2	updateNetworkElementSucceeded_v2

Comments Concerning Specific NetworkElementSubSession Operations

You can use the InstallationSubSession interface operations listed below to perform the indicated functions:

The createNetworkElement operation creates a network element.
The createNetworkElement_v2 operation creates a network element.
The deleteNetworkElement operation deletes a network element.
The getNetworkElement operation retrieves the network element for the specified network node ID.
The getNetworkElement_v2 operation retrieves the network element for the specified network node ID.
The queryNetworkElement operation queries for a network element.
The queryNetworkElement_v2 operation queries for a network element.
The updateNetworkElement operation updates the specified network element.
The updateNetworkElement_v2 operation updates the specified network element.

DLRSession Interface Operations

Table 5-9 lists the operations available in the DLRSession interface of the WDIDLR.idl file. These operations reproduce the same type of functionality as the corresponding function of MetaSolv Solution.

Table 5-9 DLRSession WDINotification Operations

Operation	WDINotification
getCircuitByWDIEvent	getCircuitByWDIEventSucceeded getCircuitByWDIEventFailed
getCircuitDLRs_v2	getDLRsByCircuitSucceeded_v2 getDLRsByCircuitFailed
getDLR_v2	DLRGetSucceeded_v2 (Deprecated) DLRGetFailed_v2 (Deprecated)
getDLR_v3	DLRGetSucceeded_v3 DLRGetFailed_v3
getDLR_v4	DLRGetSucceeded_v4 DLRGetFailed_v4
getDLR_v5	DLRGetSucceeded_v5 DLRGetFailed_v5
getDLRQueryOptionValues	This is a synchronous method so no notification method exists
getEndUserSpecialTrunkActivation_v2	endUserSpecialTrunkActivationGetSucceeded_v2 endUserSpecialTrunkActivationGetFailed
getEndUserSpecialTrunkActiviation_v4	endUserSpecialTrunkActivationGetSucceeded_v4 endUserSpecialTrunkActivationGetFailed_v4
getEndUserSpecialTrunkActiviation_v5	endUserSpecialTrunkActivationGetSucceeded_v5 endUserSpecialTrunkActivationGetFailed_v5
getEndUserSpecialTrunkTranslation_v2	endUserSpecialTrunkTranslationGetSucceeded_v2 endUserSpecialTrunkTranslationGetFailed_v2
getFlowThrough_v2	flowThroughGetSucceeded_v2 flowThroughGetFailed_v2
getQueryCircuits .	getQueryCircuitsSucceeded . getQueryCircuitsFailed
getQueryCircuits_v2	getQueryCircuitsSucceeded_v2 getQueryCircuitsFailed_v2
getQueryDLRs_v2.	getDLRsByQuerySucceeded_v2. getDLRsByQueryFailed_v2.
getQueryDLRs_v3	getDLRsByQuerySucceeded_v3 getDLRsByQueryFailed_v3
getServiceRequestDLRs_v2	getDLRsByServiceRequestSucceeded_v2 getDLRsByServiceRequestFailed
getSwitchActivation_v2	switchActivationGetSucceeded_v2 switchActivationGetFailed_v2
getSwitchActivation_v4	switchActivationGetSucceeded_v4 switchActivationGetFailed_v4
getSwitchActivation_v5	switchActivationGetSucceeded_v5 switchActivationGetFailed_v5
getSwitchTranslation_v2	switchGetSucceeded_v2 switchGetFailed_v2
getTransportProvisioning_v2	transportProvisioningGetSucceeded_v2 transportProvisioningGetFailed
getTransportProvisioning_v4	transportProvisioningGetSucceeded_v4 transportProvisioningGetFailed_v4
getTransportProvisioning_v5	transportProvisioningGetSucceeded_v5 transportProvisioningGetFailed_v5
getVLR_v2	VLRGetSucceeded_v2 VLRGetFailed_v2
getDLRQueryOptionValues_v2. This operation is implemented by the DLRSERVER.	N/A
getMaskLocationCodes. This operation is implemented by the DLRSERVER.	N/A
getMaximumReturnedRows: This operation is implemented by the caller and returns a long. This allows the server to return maximum number of records for certain queries (0 = no limit.)	N/A

The ICM API does not have a generic query operation. However, you can use the getDLR_v5 query for most generic query purposes.

Process Flows

This section contains sample process flows for solicited and unsolicited messages. Use the sample flow as a template for developing your own process flows.

Solicited Messages

A solicited message is a message initiated by MetaSolv Solution. MetaSolv Solution plays the role of the client and the third-party activation server plays the role of the server.

Sample Solicited Message Process Flow

When MetaSolv Solution is the client, the overall process flows as follows:

The client binds to the third-party server to get a WDIRoot object reference.
The client invokes the connect operation of the WDIRoot interface, and the connect operation yields a WDIManager object reference.
The client invokes the startSignal operation of the WDIManager interface to get a WDISignal object reference.
The client invokes the eventOccurred operation of the WDISignal interface to notify the third-party vendor that an event registered to them has occurred within MetaSolv Solution.
The client invokes the destroySignal operation of the WDIManager interface.
The client invokes the disconnect operation of the WDIRoot interface.

If the third-party application encounters an error, it throws a WDIExcp as defined by the IDL. The client handles CORBA system exceptions and WDIExcp exceptions.

Unsolicited Messages

An unsolicited message is a message initiated by the third-party application. MetaSolv Solution plays the role of the server, and a third-party application plays the role of the client with the exception of the callback processing.

Sample Unsolicited Message Process Flow for Exporting

The overall process flow for exporting a DLR follows:

The third-party application binds to the API server to get a WDIRoot object reference.
The third-party application invokes the connect operation of the WDIRoot interface, which then yields a WDIManager object reference.
The third-party application invokes the startTransaction operation of the WDIRoot interface to get a WDITransaction object reference and to start a database transaction.
The third-party application invokes the startDLRSession operation of the WDIManager interface to get a DLRSession object reference.
The third-party application instantiates a third-party implementation of a WDINotification object. The internal state of the client-supplied WDINotification object can be initialized, so the getMaximumReturnedRows function, when called by the server, returns the maximum number of entries to the client. If the function returns 0, entries for all objects matching the query criteria are returned.
The third-party application instantiates and populates a DLRQuery object. If necessary, the third party invokes the getDLRQueryOptionValues to obtain valid values to populate the DLRQuery object.
The third-party application then invokes the appropriate query operation on the DLRSession interface. In this example, DLRQuery, WDITransaction, and WDINotification are supplied as input parameters.
The API server invokes the operation DLRSession. The appropriate callback operation of the input WDINotification is called upon completion of the invocation of the DLRSession. In this example, the operations are getDLRsByQuerySucceeded and getDLRsByQueryFailed. The third party determines which circuit DLR to retrieve from the returned DLRResults.
The third-party application instantiates another WDINotification object and a DLRRequest structure, populated with the desired circuit and issue.
The third-party application invokes the getDLR operation of the DLRSession object, passing the DLRRequest and WDINotification object.
The DLR data structure is returned asynchronously via invocation of the DLRGetSucceeded/Failed operation of the WDINotification object.
The third-party application invokes the destroyDLRSession operation of the WDIManager interface.
The third-party application invokes the destroyTransaction operation on the WDIManager interface.
The third-party application invokes the disconnect operation of the WDIRoot interface.