1 The MetaSolv Solution Architecture

This chapter provides a general understanding of the Oracle Communications MetaSolv Solution interface architecture, a group of APIs that allow access to the data in the MetaSolv Solution database. This chapter tells you how MetaSolv Solution provides access to information and software functionality to external applications.

What Does MetaSolv Solution Do?

Oracle is a leading provider of operations support system (OSS) solutions and professional services for service providers in the local exchange, interexchange, wireless, data, and Internet markets. MetaSolv Solution enables service providers to automate and manage their ordering, service activation, and service assurance (trouble management) processes.

The MetaSolv Solution product line is set of subsystems integrated by a common repository, a database, of business data and processes. Each subsystem supports a critical aspect of the service provider's business:

Order Management: Enables the service provider to manage the end-to-end service delivery process. This often involves more than one type of service request or transaction within the organization, as well as transactions with other service or network providers.
Service Provisioning: Facilitates delivery of a full spectrum of services, from simple circuit assignments to complex circuit design and configuration. The integration of the Service Provisioning subsystem with other MetaSolv Solution subsystems provides the service provider with an accurate view of what their customer ordered and what their network can support.
Network Design: Brings together the geographical, physical, electrical, and logical dimensions of the network into a single, cohesive view supported by a set of integrated equipment administration and network design modules. This subsystem supports the design of networks and fulfillment of services across multiple providers and technologies.
Trouble Management: Supports the reporting, tracking, and resolution of trouble associated with providing telecommunication products and services. This subsystem tracks a reported problem from its initial identification to its resolution.
Interface Management: Supports accurate, reliable, and timely exchange of information between MetaSolv Solution and the service provider's other systems and external organizations.
Work Management: Enables work to flow electronically across the organization. This subsystem provides the capability to manage provisioning plans, which are groups of tasks needed to manage the flow of work and information required for the service fulfillment process.

MetaSolv Solution provides a flexible and open architecture. MetaSolv Solution uses an integrated database, where all data is collected and shared across all MetaSolv Solution subsystems. This single database provides a high-level information about the customer's profile.

How Do the MetaSolv Solution APIs Work with MetaSolv Solution?

MetaSolv Solution is developed on an open architecture that recognizes the need to electronically exchange information with a wide array of systems such as the managed network, other enterprise systems, and external trading or service partners and their operations support systems. The MetaSolv Solution APIs were to permit a flow of data between the MetaSolv Solution database and external applications.

Automatic and manual export event triggers exist within MetaSolv Solution providing end users with the capability to send work to the MetaSolv Solution Application Server or to third-party gateways.

The MetaSolv Solution interface architecture provides APIs that enable access to specific parts of data in the MetaSolv Solution database.

Table 1-1 describes the APIs that are available in MetaSolv Solution.

Table 1-1 MetaSolv Solution APIs

API	Description
End User Billing API	The End User Billing API publishes information needed for exporting data from the MetaSolv Solution database to support end-user billing from PSRs. This API integrates MetaSolv Solution order management and provisioning information with billing solutions, defines a standard end-user billing interface, and allows generic support for any billing vendor.
Inventory and Capacity Management (ICM) API	The ICM API provides beginning-to-end visibility of service and network assets, including facilities, equipment, and circuits.
Product Service Request (PSR) Ancillary API	The PSR Ancillary API permits exposure of E911 and LIDB/CNAM information to database providers.
Product Service Request (PSR) Order Entry API	The PSR Order Entry API enables a customer or a customer's third-party developer to insert customer account, service location, and PSR order information into the MetaSolv Solution database. This information is necessary for telecommunication products or services to be provisioned through MetaSolv Solution.
Switch Provisioning Activation API	The Switch Provisioning Activation API provides a vendor-independent interface that enables the flow-through provisioning of switch services such as POTS.
Transport Provisioning Activation API	The Transport Provisioning Activation API provides a vendor-independent interface that enables the flow-through provisioning of Frame Relay, ATM circuits, xDSL, and SONET. Transport provisioning reduces service turn-up time, staffing needs, and provisioning errors.
Trouble Management API	The Trouble Management API provides a mechanism for integrating the MetaSolv Solution Trouble Management subsystem with a third-party network or fault management system. This integration allows for the automatic creation of trouble tickets in the MetaSolv Solution Trouble Management subsystem from the fault management system.
Work Management API	The Work Management API enables customers to generate tasks for an order, view tasks in work queues, and complete, reopen, transfer, or suspend tasks for an order through a web interface.
Infrastructure API	The Infrastructure API provides operations for exporting lists of information from the MetaSolv Solution database. The Infrastructure API can export these types of information from the database: Structure formats and structure format components Geographic areas and types Code categories and code category values, including languages Network locations
Number Inventory API	The Number Inventory API was created to more efficiently handle the administration of telephone numbers and inventory items in MetaSolv Solution. Operations are provided in the WDINI.IDL that provide the following functionality: Export Number Inventory Import Number Inventory Generate User ID Generate User Password Validate Password Update Number Inventory Provisioning Pre-assign Telephone Numbers Remove Inventory Association The following operations provide lookup and export functionality: exportTopLevelDomains exportInventoryTypes exportInventorySubTypes exportInventoryStatus exportInventoryRelationTypes exportInventoryItem exportInventoryItems exportInventoryItemAssociation exportTelephoneNumbers exportAccessTelephoneNumbers The following operations provide import functionality: importNewInventoryItem importUpdatedInventoryItem importInventoryAssociation

Overview of Essential Terminology

Some terminology in the software and telecommunications industries differs from one provider to another. To eliminate confusion, this guide includes a glossary. However; as you read the remainder of this documentation, it is important that you understand the distinctions between the following sets of terms:

Solicited Messages Vs. Unsolicited Messages

The point of reference for this guide is the MetaSolv Solution product line. Therefore, when reading material about messages, whether the API is the initiator of the request determines whether a message is solicited or unsolicited. When MetaSolv Solution initiates the request and your software receives, that request is a solicited message. When your application initiates the request and the API receives the request, that request is called an unsolicited message.

Where the documentation does not refer specifically to solicited or unsolicited messages, the information applies to both solicited and unsolicited messages.

Events Vs. Signals

In the scope of the APIs, an event is the occurrence of something in MetaSolv Solution or in your application that is significant to the MetaSolv Solution user, such as:

A request to export an LSR
A request to send billing information
A change in the status of the import of an LSC

A signal is a logical artifact that communicates information about an event.

Where appropriate or necessary, this documentation refers explicitly to gateway events or application events. If no such distinction is drawn, the information applies to either type of event. See "Understanding Events" for an explanation of the distinctions between application and gateway events.

Inbound Signals Vs. Outbound signals

The point of reference for this guide is the MetaSolv Solution product line. Therefore, when reading material about signals, the direction of the signal in relation to MetaSolv Solution determines whether it is an inbound or outbound signal. When MetaSolv Solution sends the signal, that signal is an outbound signal. When MetaSolv Solution receives the signal, that signal is an inbound signal. Where the documentation does not refer specifically to inbound or outbound signals, the information applies to both types of signals.

Synchronous Vs. Asynchronous

In the scope of this documentation, synchronous operations are those where the application that invokes the operation gets the results of the operation immediately upon the return of the call. No callback mechanism is used in this method. Asynchronous operations are those where control returns to the application that invokes the operation before the operation is acted upon, and the results (if any) are returned to the calling application after the operation is completed. The invoked application uses a callback mechanism to communicate the results to the invoking application. See "Synchronous and Asynchronous Invocation Modes" for more information about the synchronous and asynchronous modes of processing.

API Integration

MetaSolv Solution provides APIs that allow the importing and exporting of data, through the use of the MetaSolv Solution Application Server, to the MetaSolv Solution database. This provides support for interconnection with third-party and legacy applications and allows development of customized interfaces to the MetaSolv Solution database. The APIs are built on the CORBA protocol. MetaSolv Solution defines the APIs using CORBA's IDL.

To provide interconnection, a MetaSolv Solution API provides a data pipe mechanism between your application and the MetaSolv Solution data model. This connection enables you to import and export data without programming language or methodology restrictions. Your software must implement an architecture that provides access to data and, if required, provides a mechanism for updating MetaSolv Solution data.

In addition to importing and exporting data, the APIs ensure the integrity of data in the MetaSolv Solution database by verifying that all imported data meets the MetaSolv Solution data rules. Using an API, MetaSolv Solution can be integrated into a customer's environment. Oracle consultants, third-party consultants, or customers themselves can complete the integration work.

Figure 1-1 shows the process by which the APIs communicate with client applications and other server applications.

Figure 1-1 API Communication Process Overview

Description of ''Figure 1-1 API Communication Process Overview''

MetaSolv Solution API Technical Overview

The MetaSolv Solution interface architecture provides APIs that enable access to specific information in the MetaSolv Solution database. This architecture meets requirements for customers connecting to MetaSolv Solution. Using this architecture, you or third-party developers can easily connect to MetaSolv Solution, providing add-on products and custom solutions.

MetaSolv Solution APIs are IDL files that provide a blueprint for communication between MetaSolv Solution and your software. The third-party server environment can be on any platform and operating system that supports CORBA.

The APIs are bidirectional, they send requests to other software and receive requests from other software. To initiate processing, MetaSolv Solution has defined an event mechanism that sends out pre-defined signals, called application events, and signals defined by you or a third-party developer, called gateway events. See "Understanding Events" for more information.

Understanding Events

One of the most important tools provided by the APIs is the ability for your applications to integrate with the Work Management subsystem. This integration is provided by the exchange of events and signals between the APIs and your applications. An event is a significant occurrence within the workflow of either the Work Management subsystem or your application. A signal is the logical artifact used to communicate information about an event between MetaSolv Solution and your application.

Two types of events are implemented in the Work Management subsystem:

Application events
Gateway events

Application events are pre-defined within MetaSolv Solution and occur at fixed points in the workflow. Application events are always sent by MetaSolv Solution to external applications through an outbound signal that carries MetaSolv Solution-defined data pertaining to the event. The signal that represents an application event carries pre-defined data specific to that event.

Gateway events provide a powerful mechanism for you to insert hooks into the Work Management subsystem. The signal that represents a gateway event can carry only generic data such as a document reference for a document in the MetaSolv Solution database.

Except for the system-defined gateway events used by the PSR Ancillary API, all gateway events are defined by your application and set up in the MetaSolv Solution database using the user interface provided in the Work Management subsystem.

Note:

See "The PSR Ancillary API and Smart Tasks" for more information about the system-defined gateway events supported by the PSR Ancillary API.

Unlike application events, which can only occur within MetaSolv Solution, gateway events can occur within either MetaSolv Solution or your application. Therefore, gateway events must be defined in the MetaSolv Solution database as either outbound or inbound events. Outbound gateway events occur within MetaSolv Solution and are communicated to your application through outbound signals. Inbound gateway events occur in your application and are communicated to the MetaSolv Solution Application Server through inbound signals.

Your application communicates the status of outbound gateway events to the MetaSolv Solution database through the APIs. These statuses indicate changes in the state of the event. The actual status values available for your use are defined in the event-signaling structure of the MetaSolv Solution IDL.

Gateway events must be tied to a task in a provisioning plan in the Work Management subsystem. When that provisioning plan is associated with a new order, the plan ensures that the Work Management subsystem sends or receives the gateway event at the point defined within the provisioning plan.

Table 1-2 summarizes the differences between application events and gateway events.

Table 1-2 Differences Between Application Events and Gateway Events

Difference	Application Events	Gateway Events
How Defined	Pre-defined in MetaSolv Solution	Defined by you (or a third-party developer) and added to the MetaSolv Solution database using the Work Management subsystem's user interface
Association	Tied to a specific MetaSolv Solution application event such as a button click or menu selection	Tied to a task in a provisioning plan in the Work Management subsystem
Signal Direction	Always outbound	Inbound or outbound as defined in the MetaSolv Solution database
Content	MetaSolv Solution-defined data specific to the event	Only generic data such as a document reference

For more information about Work Management integration, contact the Oracle representative at the implementation site.

Synchronous and Asynchronous Invocation Modes

The MetaSolv Solution interface architecture uses two invocation modes for operations:

Synchronous
Asynchronous

All external applications (those developed by you or a third party) that interact with the APIs are required to handle both invocation modes.

Synchronous Operations

In the scope of this documentation, synchronous operations are those where the application that invokes the operation gets the results of the operation immediately upon the return of the call.

The general rules for synchronous operations are as follows:

All operations initiated by MetaSolv Solution or the API software against your application are synchronous. This means your application is required to return the results of the operation upon return of control.
All operations your application invokes on an API server are synchronous, except for data import and export operations, which are asynchronous.

Asynchronous Operations

In the scope of this documentation, asynchronous operations are those where control returns to the application immediately and the results (if any) are returned to the invoking application at a later time. The APIs use a callback mechanism to implement this paradigm. The callback mechanism works as follows:

Your application creates a unique callback object, then passes that object to the appropriate API server along with the rest of the asynchronous operation's parameters. Your application then awaits return of control.
The API server implements the operation and immediately returns the call. Results of the operation are not returned at this time.
Control returns to your application, which now begins to listen to the callback object while it waits on the results.

Note:
If your application can handle multiple threads, the application can continue generating threads, if it remains available to accept and process the invocation of the callback object for each thread.
The asynchronous operation completes the requested task and returns the results to the API server.
The API server invokes an operation on the callback object to return the results to your application.
The callback object hands the results to your application

The general rule for asynchronous operations is that all operations involving movement of data to and from the MetaSolv Solution database, data import and export, are asynchronous.

Note:

See "Synchronous Operations" and "Asynchronous Operations" for more information about implementing synchronous and asynchronous operations.

Transaction Model Used By the APIs

The APIs use a transaction model; however, the APIs do not provide built-in support for nested or linked transactions. With two exceptions, the API servers provide an operation that external applications can invoke to generate a transaction object. The exception is the ICM API and the End User Billing API. These two servers provide all required transaction management functions internally.

Operations that involve movement of data into or out of the MetaSolv Solution database require the external application to supply a transaction object. The transaction object must support two operations:

A commit operation that unconditionally applies all database changes that were performed during that transaction
A rollback operation that cancels all database changes made during that transaction

The responsibility of organizing and managing units of work using the commit and rollback operations rests solely with external applications that use the APIs.

Transaction Objects

Each API server maintains an internal table of all the transaction objects it generates. The scope of a transaction object is ultimately limited to the lifetime of the API server process that created it and the lifetime of the MetaSolv Solution database instance. Transaction objects are re-usable but not portable. Therefore, the same transaction object may be used multiple times while performing operations on the API server that generated it, subject to the transaction lifespan limitations described earlier in this paragraph. You can only use a transaction object on the API server from which it was generated.

Determining the Role Your Application Performs

When developing an application to run against any of the APIs, it is very important to understand the roles that application will be performing. Applications can be developed against the APIs to perform in one of the following roles:

Client only
Server only
Both client and server

Because of the significant differences between developing for these roles, it is important that you understand the differences between the roles. Before beginning development you should determine which role your application will perform in relation to the APIs.

For synchronous transactions each application's role remains constant throughout the transaction and is either the client role or the server role. See "Synchronous Operations" for more information.

The role each application plays is determined by the application that requests the service:

The application that requests a service is the client
The application that supplies the service is the server

For example:

When your application invokes synchronous operations on the API servers to update the status of gateway events, your application is the client. In this case, your application requests the service and the API server supplies the service.
When the Work Management subsystem sends an outbound gateway event to your application, your application is the server. MetaSolv Solution requests the service (in this case, WDISignal::eventOccurred) and your application supplies the service; in this case, whatever the application does when it receives that particular gateway event.

For asynchronous operations, the server role is also determined by which application requests the service, but the role each application plays can change, so role determination is not as simple as in synchronous operations. When invoking asynchronous API operations, perhaps your application will play any of the roles: client only, server only, or both. Therefore, external applications that invoke asynchronous operations against the APIs may have to be implemented with the capability to function as CORBA servers. See "Asynchronous Operations" for more information.

For example, when your application invokes an operation on the API server, your application is the client. However, when the API server invokes operations on a callback object that was provided by your application, the API server plays the client role and your application plays the server role.

Note:

See "HelloAPI: Sample Application that Exports Data" for an example of an external application that plays both the client and server roles.

Importing and Exporting Using the APIs

The major processes supported by the APIs are the import and export of data.

By providing access to specific MetaSolv Solution data, APIs enable you to implement any required type of interface.

Two types of operations are provided by the APIs to enable external access to data stored in the MetaSolv Solution database.

Data export operations are read-only and allow your application to extract data out of the database.
Data import operations enable your applications to modify data stored inside the database.

The APIs provide operations that allow your application to obtain transaction handles to be used in data export and import operations.

Responsibilities When Developing With the APIs

An API provides a platform for integration, but it does not provide the complete functionality required. As a developer of external applications intended to work with the APIs, you should build in support for additional functionality as dictated by your application's unique requirements. The APIs expect your application to perform the following tasks:

Transaction management: You must start and destroy the transaction object. In most cases, you must also define your own units of work and manage your application's interactions with the APIs through the rollback and commit operations provided by the API.
Event handling: Design your applications to receive and process the application events and gateway events that the MetaSolv Solution clients send to your applications.

Also, if you are developing a gateway application, you typically need to build in support for service level agreement (SLA) functionality such as:

Scheduling
Field mapping/translation
Defining protocols
Transmission functionality retries, resends, recovery, and alternative transmission channels

Naming Conventions in the APIs

MetaSolv Solution provides three types of IDL files for each API. The IDL files define the interfaces your application can use to communicate with the MetaSolv Solution product line.

The types of IDL files provided with MetaSolv Solution are:

The WDI.IDL file, a common API file distributed with each API. This file contains the highest level interface structures and operations used by all APIs.
A WDIapiname.IDL file, where apiname represents the specific API name. This file contains the highest level application-specific interfaces and operations for the named API.
One or more WDIapinameTYPES files, where apiname represents the specific API name. These files contain definitions of the data structures. There may be one WDIapinameTYPES.IDL file that contains common access information or any number of additional WDIapinameTYPESn.IDL files, where n represents the types file number.

Note:
The IDL types file for the Number Inventory API is named NITYPESE.IDL. IDL types files for the PSR Order Entry APIs are named PSRTYPES.IDL, PSRTYPES_v2.IDL, and PSRTYPES_v3.IDL.

IDL Versioning for MetaSolv Solution

MetaSolv Solution ensures the backward compatibility of the IDL. IDL is versioned as needed to support new functionality or to correct issues, leaving the original IDL backward compatible. However, in some cases we cannot provide this compatibility. Typically this occurs if an old function cannot be mapped to the new functionality or in cases where the original function signature was incomplete or unusable.

The syntax of the new versioned IDL files, API operations and structures includes a ”_vX” at the end of the old name, where X represents a numeral; for example, importPSROrder is represented as importPSROrder_v2 in the versioned form. For new development use the most current version of an operation or structure. This means you would use operationname_v3 or structurename_v3 instead of operation or structurename_v2.