3 Common Architecture

Figure 3-1 shows the common interfaces of the Oracle Communications MetaSolv Solution APIs.

Figure 3-1 Common IDL Architecture Interfaces

Description of ''Figure 3-1 Common IDL Architecture Interfaces''

Table 3-1 lists the keys for common IDL architecture interfaces.

Table 3-1 Keys for Common IDL Architecture Interfaces

Key	Architecture Description
(1)	At the highest level is the WDIRoot interface, which enables connection management. The WDIRoot layer provides services that are used throughout the architecture and serve as the connection factory. See "WDIRoot Interface" for more information.
(2)	The second level is the WDIManager interface, which enables session, signal, and transaction management. The WDIManager object reference is obtained from a successful connect to the WDIRoot. The connection operation of the WDIRoot object returns an object reference to a WDIManager. WDIManager provides services to start and destroy transaction objects, signal objects, and session objects.
(3)	The third level contains the session, signal, and transaction interfaces, whose object references are obtained from the WDIManager interface. See Figure 3-4, "WDIManager Interface" for more information.
(4)	The optional fourth level contains the more granular subSession object whose object reference is obtained from the parent session interface. Refer to the sample flows presented in each API chapter for examples.
(5)	The API architecture defines a callback mechanism that is exposed by the WDINotification interface.

The session or subSession enables access to business application operations. These operations are detailed business objects that vary by the business functions exposed.

Note:

MetaSolv Solution APIs do not necessarily require every interface defined in this document.

WDIRoot Interface

The connect operation of the WDIRoot interface obtains the object reference to the WDIManager.

Figure 3-2 shows the WDIRoot interface.

Figure 3-2 WDIRoot Interface

Description of ''Figure 3-2 WDIRoot Interface''

Connection to the MetaSolv Solution Application Server

To begin a connection, the third-party application must connect to the MetaSolv Solution Application Server. This connection verifies the user ID and password, and returns the object reference to the APIs WDIRoot. The connection operation returns a reference to a WDIManager object.

Connection to the CORBA Daemon

By default, all APIs perform an impl is ready connection to the daemon in order to register the availability of its object references. The MetaSolv Solution API system administrator can set the StrictOMG system parameter to true in the MetaSolv Solution Application Server INI file. The result is an OMG ORB connect on the WDIRoot object.

After performing the OMG ORB connection, the application server writes an OMG stringified object reference for the WDIRoot object to a file, using the file name specified by the IORPath system parameter in the application server INI file and the name of the API server.

Connection to the Root Object

Figure 3-3 illustrates the connection process.

Figure 3-3 Connection Process

Description of ''Figure 3-3 Connection Process''

Table 3-2 lists the operations exposed by the WDIRoot interface.

Table 3-2 WDIRoot Interface Operations

Operation Name	Description
connect	Returns a reference to WDIManager
disconnect	Terminates the connection

WDIManager Interface

The object reference to the WDIManager is obtained by initiating the connect operation of the WDIRoot interface, as shown in Figure 3-4.

Figure 3-4 WDIManager Interface

Description of ''Figure 3-4 WDIManager Interface''

Table 3-3 lists the operations exposed by the WDIManager interface.

Table 3-3 WDIManager Interface Operations

Operation	Description
startapinameSession	Obtains the object reference of the apinameSession where apiname designates the specific API, as in startLSRSession
destroyapinameSession	Terminates the established session, as in destroyLSRSession
startTransaction	Establishes a database connection using this process: The Start operation makes the connection and establishes a database transaction object. The API returns a handle for that connection to the initiating process. The term, handle, is synonymous with a WDITransaction object reference.
destroyTransaction	Invalidates a database transaction object. Any pending changes are lost when this function is called if it was not preceded by a commit.
startSignal	Obtains the WDISignal object reference
destroySignal	Terminates the Signal
startInSignal	Obtains the WDI Insignal object reference
destroyInSignal	Terminates the Insignal

Note:

Some APIs do not define startSignal, destroySignal, startInSignal, destroyInSignal, startTransaction, or destroyTransaction. For details about a specific API, see the chapter of this guide that describes that API.

API Session Interfaces (Session Processing)

The object reference to the apinameSession is obtained by initiating the startapinameSession operation of the WDIManager, as shown in Figure 3-5.

Figure 3-5 Basic Session Interface

Description of ''Figure 3-5 Basic Session Interface''

Operations in sessions and subsessions vary according to the API.

WDITransaction Interface (Database Transactions)

The object reference to the WDITransaction is obtained by initiating the startTransaction operation of the WDIManager interface. Third-parties can use the API to coordinate the database transactions because no assumed paths or commit points are built into the API. Commit and rollback are operations of the WDITransaction interface.

Figure 3-6 shows the WDITransaction interface.

Figure 3-6 WDITransaction Interface

Description of ''Figure 3-6 WDITransaction Interface''

The commit operation uses a database handle and saves any pending changes to the database. Once a commit has occurred, all database updates are applied to the database. After a commit, the transaction object is still valid and can continue to be used.

The rollback operation uses a database handle and rolls back any pending changes to the database. Once a rollback has occurred, any pending database changes are discarded. After a rollback, the transaction object is no longer valid and cannot be used for further operations.

In APIs that use the commit and rollback operations, your application must specifically call commit and rollback. However, some APIs do not use the WDITransaction interface. In these cases, MetaSolv Solution is responsible for database transaction management.

WDISignal Interface (Outbound Signal Processing)

The object reference to the WDISignal is obtained by initiating the startSignal operation of the WDIManager interface.

If the signal is a gateway event signal, certain key data as defined in the WDIEvent structure (in the IDL) is passed. If the signal is an application event signal, the data to be passed varies, depending on the application.

The third party is responsible for implementing the eventOccurred and eventTerminated operations of the WDISignal interface. MetaSolv Solution is responsible for implementing the remaining operations of the WDISignal interface.

Figure 3-7 shows the WDISignal interfaces.

Figure 3-7 WDISignal Interfaces

Description of ''Figure 3-7 WDISignal Interfaces''

Table 3-4 lists the operations exposed by the WDISignal interface.

Table 3-4 WDISignal Interface Operations

Operation	Description
eventOccurred	MetaSolv Solution initiates a signal indicating that a gateway event of interest to the third-party software has occurred.
eventTerminated	MetaSolv Solution terminates an event to notify the third-party application that MetaSolv Solution is no longer interested in completing the event and is no longer interested in receiving status updates for the event.
eventInProgress	The third-party application sets the status of the gateway event to In Progress when it has received and begun processing the signal.
eventCompleted	The third-party application sets the status of a gateway event to Completed when it has successfully finished processing the event.
eventErrored	The third-party application sets the status of the gateway event to Error when an error has occurred while processing the event. This operation also provides a mechanism for error information to be communicated to the API.

WDIInSignal Interface (Inbound Signal Processing)

The object reference to the WDIInSignal is obtained by initiating the startInSignal operation of the WDIManager interface. The WDIInSignal interface allows the third-party application to update statuses of unsolicited or inbound gateway events in the Work Management subsystem. This is illustrated in Figure 3-8.

Figure 3-8 WDIInSignal Interfaces

Description of ''Figure 3-8 WDIInSignal Interfaces''

Table 3-5 lists the operations exposed by the WDIInSignal interface.

Table 3-5 WDIInSignal Interface Operations

Operation	Description
eventInProgress	The third-party application sets the status of a gateway event to In Progress when it has started processing an event.
eventCompleted	The third-party application sets the status of a gateway event to Completed when it has successfully finished processing an event.
eventErrored	The third-party application sets the status of a gateway event to Error when an error has occurred while processing an event.

WDINotification Interface (Callback Mechanism)

Most operations implemented within the APIs require a WDINotification object reference as the first input parameter. The third-party application instantiates a WDINotification object.

The WDINotification interface enables a callback mechanism to notify the third-party application of the result of an operation invoked against it. The callback mechanism is used to communicate the results of an asychronous operation.

Note:

Operations of the WDINotification interface vary according to the application.

MetaSolv Solution uses JacOrb 3.8 to support the CORBA API. This software supports the 2.4 CORBA Standard. This software is shipped as part of the MetaSolv Solution product line and does not require you to purchase anything from a third party. This ORB inter operates with all the available ORBs.

The WDINotification interface has operations defined indicating the success or failure of an invoked operation. The parameters of the WDINotification interface include a reference (which varies by application, for example a document number for LSR-related callbacks) and an error structure where appropriate. The third-party application is responsible for implementing the operations in the WDINotification interface.

If an error is encountered during the processing of an API object implementation, a callback is performed to the third-party application indicating that the operation has failed and why the operation failed. The reasons for the failure are communicated by an error structure (WDIErrSeq), which may contain multiple, detailed error messages. Different errors can be encountered while attempting to process a given request, as shown in Figure 3-9.

Figure 3-9 Sample Flow for Successful and Error Conditions

Description of ''Figure 3-9 Sample Flow for Successful and Error Conditions''

Displaying errors is the responsibility of the third-party application because the third-party application functionality and error processing differs among software package. The API provides a mechanism for errors to be communicated back to the Work Management subsystem through the eventErrored operation of the WDISignal interface.

For example, with a third-party application importing a local service request confirmation (LSC) to the LSR API, the following processes can occur:

The third-party application invokes the importLSC operation with the appropriate data.
The importLSC operation processes the LSC data.
- During the processing, the LSC is validated against the MetaSolv Solution database business rules for the LSC.
- If all data is valid, it is inserted into the MetaSolv Solution database, and the successful operation is invoked on the notification interface.
- No detail error messages are generated.

If the import LSC process encounters an error or errors, the LSC is not inserted into the MetaSolv Solution database. The error code structure is populated with detailed error message information. Examples of these include location code not in the database and NC/NCI codes are invalid. MetaSolv Solution invokes the failed operation of the WDINotification interface.

The third-party application is responsible for logging the errors and making them available to the user. Typically, this means the data displays to the user. The third-party application may optionally communicate this error information back to MetaSolv Solution through the error status update for an event.