5 The Inventory and Capacity Management 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 through other network devices, such as a Network Management System (NMS). Defining a network element as a gateway network element enables 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 enables 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 collocated 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.

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.

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, through 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 enables 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 enables 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 enables 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 collocated 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. Therefore, 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 collocated 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 enables you to create cross-connects for enabled port addresses. This functionality enables 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 if 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.

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.

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.

WDIManager Interface

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

CircuitHierarchySession Interface

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

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.

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.

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 through the generic operationFailed notification.

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 through the generic operationFailed notification.

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 through the generic operationFailed notification.

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.

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 through the generic operationFailed notification.

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.

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

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.

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.