The Transport Provisioning Activation API supports flow-through provisioning of different kinds of circuit designs. This API enables third-party network management systems to export provisioning information from the Oracle Communications MetaSolv Solution database and use that information to physically implement the design.
The Transport Provisioning Activation API:
Provides a vendor-independent interface to enable flow-through provisioning of Frame Relay and ATM circuits.
Provides flow-through information about any transport equipment assigned to a DLR (for example: SONET and DACS).
Exposes the VLR through an API so customers can write Web applications that display the VLR through a thin client.
The Transport Provisioning Activation API provides the IDL for retrieving DLR, VLR and flow-through information for a given WDIEvent. If the value for the returned ”Type” data element is V, VLR information exists for the circuit; otherwise DLR information exists.
The third-party application is responsible for managing all database transactions, including commit and rollback processing.
Table 12-1 defines the terms that identify the concepts and information that are required to understand flow-through provisioning using the APIs.
Table 12-1 Transport Provisioning API Terminology
Term | Definition |
---|---|
Activation product |
A network management system (NMS), such as Lucent Technology's ACTIVEVIEW product line. |
Activation server |
An application developed by you or a third party that integrates with MetaSolv Solution to export provisioning data and communicate the data to one or more activation products. |
This section provides information about the Transport Activation interface.
Table 12-2 lists the operations available in the DLRSession of the WDIDLR.IDL file that are used by the Transport Provisioning Activation API.
Table 12-2 DLR Session WDINotification Operations
Operations | WDINotification |
---|---|
getTransportProvisioning_v2 |
transportProvisioningGetSucceeded_v2 transportProvisioningGetFailed |
getTransportProvisioning_v4 |
transportProvisioningGetSucceeded_v4 transportProvisioningGetFailed_v4 |
getTransportProvisioning_v5 |
transportProvisioningGetSucceeded_v5 transportProvisioningGetFailed_5 |
This section contains sample process flows for each type of signal: solicited and unsolicited. Use the sample flow as a template for developing your own process flows.
A solicited message is a message initiated by MetaSolv Solution. With this scenario, MetaSolv Solution plays the role of the client, and the third-party activation server plays the role of the server.
Table 12-3 lists the interfaces and operations that the third-party application implements using the IDL file provided with the DLR API.
Table 12-3 Transport Provisioning API Interfaces Solicited Messages Operations
Interface | Operations |
---|---|
WDIRoot |
connect disconnect |
WDIManager |
startTransaction destroyTransaction |
WDITransaction |
N/A |
WDISignal |
eventOccurred eventTerminated |
WDIInSignal |
N/A |
When MetaSolv Solution is the client, the overall process flows as follows:
The API client binds to the third-party server to get a WDIRoot object reference.
The API client invokes the connect operation of the WDIRoot interface, and the connect operation yields a WDIManager object reference.
The API client invokes the startSignal operation of the WDIManager interface to get a WDISignal object reference.
The API client invokes the eventOccurred operation of the WDISignal interface passing a WDIEvent structure to notify the third-party vendor that an event registered to them has occurred within MetaSolv Solution.
The API client invokes the destroySignal operation of the WDIManager interface.
The API client invokes the disconnect operation of the WDIRoot interface.
Once the third-party server completes processing, possibly involving additional unsolicited messages to the MetaSolv Solution Application Server, the third party binds to the application server and follows the same process described above for the MetaSolv Solution client with the exception that the eventCompleted/Errored operations are invoked passing the original WDIEvent structure.
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.
An unsolicited message is a message initiated by the third-party software. 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.
Table 12-4 lists the interfaces and operations that MetaSolv Solution implements using the IDL files provided with the Transport Provisioning Activation API.
Table 12-4 Transport Provisioning API Interfaces Unsolicited Messages Operations
Interface | Operations |
---|---|
WDIRoot |
connect disconnect |
WDIManager |
startTransaction destroyTransaction |
WDITransaction |
commit rollback |
DLRSession |
getTransportProvisioning |
Table 12-5 lists the interfaces and operations for which the third-party application is responsible.
Table 12-5 Transport Provisioning API Third-party Interfaces and Operations
Interface | For Implementing These Operations |
---|---|
WDINotification |
transportProvisioningGetSucceeded_v5 transportProvisioningGetFailed_v5 |
The overall process flow for exporting Transport Provisioning Activation is as follows:
The third-party application binds to the MetaSolv Solution Application Server to get a WDIRoot object reference.
The third-party application invokes the connect operation of the WDIRoot interface, which yields a WDIManager object reference.
The third-party application invokes the startTransaction operation of the WDIRoot interface to get a WDITransaction object reference and starts 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 third-party application invokes the getTransportProvisioning operation of the DLRSession object, passing the WDINotification object.
The TransportProvisioning data structure is returned asynchronously through invocation of the transportProvisioningGetSucceeded/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 of the WDIManager interface.
The third-party application invokes the disconnect operation of the WDIRoot interface.
This section describes the issues that you must be familiar with when building a mediation server application for flow-through provisioning.
Network nodes are the equipment that manages the circuits in the network. They are identified by a unique target identifier (TID). TIDs are used to search for devices on the network. Commands are sent to the network node for flow-through provisioning. For example, a user might designate one network node as the host network element that communicates with the network management system. Essentially, a network node is any device that can be provisioned through software. Network nodes can contain one or more pieces of equipment, and can be directly associated with flow-through provisioning plans on the Network Node Type window in the Infrastructure module.
If flow-through plans are used, the flow-through provisioning process cannot occur without network nodes. Network node types are used in the flow-through provisioning process to categorize network nodes into groups. Network node types represent the activation vendor's requirements for activating the network element, and they are used in the flow-through provisioning process to limit the number of flow-through provisioning plans required.
Flow-through provisioning plans and flow-through provisioning commands are MetaSolv Solution concepts that define optional additional parameters used in the flow-through provisioning process that are not a part of MetaSolv Solution. Below are examples of some of the types of flow-through provisioning plans and commands that can be created:
Plan
Activate a DACS
Command
Config Port A
Config Port B
Parameters
Direction: 1 way
Direction: 2 way
Alarming
The number of flow-through provisioning plans, commands, and parameters that are created will vary according to the requirements of the activation product used for the flow-through provisioning process. The nature of flow-through provisioning plans and commands is to allow MetaSolv Solution to work with any selected activation product. That is, MetaSolv Solution only captures TID, port addresses, and cross-connects for flow-through provisioning. Flow-through provisioning plans and commands provide the ability to capture all the information the activation vendor requires.
Note:
If the selected activation product only requires what the defaults for flow-through provisioning, then it is not necessary to use the PSR module in the flow-through provisioning process at all.A design layout record (DLR) is a document that contains the technical information that describes the physical layout of a circuit at a given location.
The tech translation sheet defines the items required to provision the service in the switch. For switch provisioning activation, once the order is entered, the product and options ordered are the basis for the tech translation sheet.
A virtual layout record (VLR) is a MetaSolv Solution-defined document that contains the technical information that describes the layout of the physical components of an ATM or Frame Relay virtual circuit, and the relationship of the physical components to the logical components (the cloud) of that circuit.
The Transport Provisioning Activation API uses the following modules and subsystems to complete the flow-through provisioning process:
Equipment Administration module
Infrastructure module
Product Service Request (PSR) module
Service Provisioning subsystem
Work Management subsystem
The flow-through provisioning process uses the Equipment Administration module to define the following:
Target identifier (TID) that the activation vendor recognizes
Network node with which the equipment is associated
Note:
A network node must be associated with every piece of equipment (or at a higher level in the equipment hierarchy) used for flow-through provisioning. A network node type must be associated with every network node used for flow-through provisioning.The Infrastructure module is used in the flow-through provisioning process to:
Define new network node types
Associate network node types with flow-through provisioning plans and rate codes
Additionally, the user can access the PSR module's Product Catalog function through the Infrastructure module. The user will only use the Infrastructure module for flow-through provisioning if they need to specify additional data for a network node.
The Product Service Request (PSR) module is used in the flow-through provisioning process to:
Set up flow-through provisioning plans and commands
Enter a service request
Provide service request information related to flow-through provisioning on the tech translation sheet for switch translations
More specifically, the PSR module's Product Catalog function is used in the flow-through provisioning process to define the features that appear on the PSR, as well as the options on those features. Options on the service request used for the flow-through provisioning process include flow-through provisioning plans and commands. These options often have default values, and when a PSR is entered with these options, the service request includes the required default values (also referred to as parameters). The user can use the Product Specifications window to determine if the values or parameters appear on the tech translation sheet.
Note:
All parameters necessary to the flow-through provisioning process (except equipment parameters) are defined in the Product Catalog function.The flow-through provisioning process uses the Service Provisioning subsystem to:
Design the circuit(s) on the PSR used for flow-through provisioning
Verify and modify the flow-through provisioning parameters that are set up in the PSR module
The Service Provisioning subsystem also provides the flow-through provisioning information (such as network node type and network node address) that appears on the CLR, DLR, VLR, and tech translation sheet.
The Work Management subsystem is used in the flow-through provisioning process to:
Associate a gateway event with a provisioning plan task
Initiate a gateway event
Verify the gateway event is complete
Gateway events define when MetaSolv Solution should send flow-through provisioning information to the activation application for processing.
The flow-through provisioning process is used in the MetaSolv Solution client software to:
Order and provision services associated with the line side of a switch
Engineer a service request and provision it without re-entering activation information
Note:
Line side activation includes provisioning dialtone services through a switch. The activation process occurs outside of MetaSolv Solution.See the online Help for detailed instructions on using the flow-through provisioning process.
For flow-through provisioning, the Transport Provisioning API calculates and provides the physical/logical port values for both the A location of the equipment and the Z location of the equipment.
The Transport Provisioning API provides the API user with physical/logical port values and a list of circuit positions ridden for each bandwidth circuit that supports the PVC.
When multiple circuit positions are ridden by a bandwidth circuit, the API throws an exception if all of the circuit positions are not associated with the same logical port.
The API assumes the port calculations do not change when the physical ports are in a virtual path.
The intent of the reference architecture is to provide a logical framework to describe the various implementation concepts. It is not intended to suggest any particular application design.
Figure 12-1 shows the reference architecture for flow-through provisioning.
Figure 12-1 Reference Architecture for Flow-Through Provisioning
Gateway events are utilized to allow your activation server to integrate with the Work Management subsystem.
The signal handler module implements the interfaces required to handle standard gateway events from MetaSolv Solution clients. This module is also responsible for updating gateway event status to ”In Progress”.
The outbound signals sent by the MetaSolv Solution client to your activation server are the flow-through provisioning gateway events. These events are defined at the service item level. Each service item (for example, a phone line, a WATS line, or an ATM/Frame circuit) on the order will have the flow-through provisioning gateway event associated with it. As a result, when an order is processed by the Work Management subsystem, your activation server can potentially receive as many gateway events as there are service items in the order. For example, if a transport provisioning order for ASR equipment comprises six special access circuits, your activation server receives six separate gateway events from the client.
Each gateway event associated with a service item in a service request can be processed independently of the gateway events for any other service item.
Implementation should conform to the outbound signals gateway events pattern. See "Outbound Signals – Gateway Events" for more information. The signal handler module should implement a WDIDLR module with all the interfaces and operations listed in Table 2-6, "Outbound Gateway Event Operations Required For All APIs". Event status updates are performed through DLRSERVER.
Upon receiving an outbound signal conveying gateway event information from the MetaSolv Solution client, the signal handler module activates the request handler module and hands off the event information that was received. In order to avoid locking up the client, it is recommended that the signal handler should return control to the client immediately upon activating the request handler module and updating the event status.
The request handler module retrieves activation data from the MetaSolv Solution database by invoking the getTransportProvisioning operation on DLRSERVER to retrieve transport provisioning data
The operations are standard data export operations. See "Synchronous Interaction Pattern" for more information. This provisioning operation accepts a WDIEvent parameter that allows the request handler to retrieve provisioning data from the database in a single step. The request handler passes in the gateway event structure that was received from the client and DLRSERVER retrieves the required provisioning data.
It is important to understand the data types that are involved in the operation listed above. Data type definitions can be found in file WDIDLRTYPES_v5.IDL. The following Transport Provisioning data structure is returned to the caller (through callback invocation):
Example 12-1 Transport Provisioning Data Structure Example
typedef sequence<DLR> DLRSeq; typedef sequence<MetaSolv::CORBA::WDIVLRTypes::VLR> VLRSeq; struct TransportProvisioning { char type; // CIRCUIT.TYPE CHAR(1) DLRSeq dlr; VLRSeq vlr; ActivationCommandPlanSeq activationCommandPlans ; };
The ActivationCommandPlanSeq data type delivers the FTP Plan for this service item.
The formatting/translation module handles two-way data translation and format conversion required for communicating with the activation product. This module's services are used by the other modules.
The response handler module handles responses received from the activation product. It performs the necessary reverse translation/formatting using the formatting/translation module and then determines the operation status. Based on the success or failure determination, this module updates gateway event status to ”Completed” or ”Errored”. Design of this module depends upon factors such as the synchronous/asynchronous and online/batch nature of the interaction with activation product.
To obtain the full benefit of the automated flow-through capabilities of this API, gateway events must be associated with tasks in Work Management provisioning plans. MetaSolv Solution is pre-configured with gateway templates and gateway event templates for Transport Provisioning.
See the online Help for detailed instructions on using the flow-through provisioning process.
In order to ensure that the provisioning information provided by the Transport Provisioning Activation API is sufficiently completed to be used by your network management system, care must be used when ordering the service.
The PSR module captures default values for items that have pick lists. With flow-through provisioning, defaults are also needed for editable fields. If defaults are not provided, a user would be required to manually enter the same value on every line for an order. Providing a default value in the product catalog for product specifications that are required for flow-through provisioning streamlines the ordering process.
For transport provisioning activation, the network node target identifier (TID) and the equipment port address assignment identifier (AID) in the database identify the equipment and port address. These items should either be used directly by your application or your application should maintain a cross-reference between the identifiers used by your application and the MetaSolv Solution-supplied TID and AID.
Just as the provisioning of switch features requires additional parameters, the provisioning of transport equipment requires additional parameters as well. The transport equipment for dialtone lines is usually digital loop carrier. The CLR represents the provisioning information for this type of equipment. The CLR captures the TID and the AID for the DLC equipment, which is part of the information that is required for activating the service. The TID is determined by identifying the Network Node to which the equipment belongs. The AID is determined using the assignment information that is gathered on the CLR. To provision transport equipment, additional parameters are usually required. These parameters will vary by type of equipment, by transmission rate, and by activation vendor.