Web Services Overview

1 Web Services Overview

This chapter provides introductory information about the Oracle Communications MetaSolv Solution (MSS) Access Service Request (ASR) Web Services.

Overview

Web services support interoperable system-to-system interaction over a network. They are APIs that can be accessed over a network and run on a remote system hosting the requested services. Web services are described by the Web Service Definition Language (WSDL).

This document describes how to integrate MetaSolv Solution ASR with other Oracle products or with external applications using web services. In this book, you can find deployment information, and a reference chapter for each web service.

About the ASR Web Services

The ASR Web Services include two web services that address various ASR features such as importing and exporting different request types of ASR orders. These operations cover the operations that are offered by the CORBA APIs.

ASR Web Service

You can use the ASR Web Service operations to request the following:

Import and export various request types of ASR orders
Import and export a Confirmation Notice
Import and export a Clarification Request
Import and export a Provider Test Acceptance
Query ASRs by criteria
Import an External DLR

You can import or export the following types of ASR orders:

Transport
Trunking
SES
FGA
PIP
DIS
EUSA
Ring
WAL

Refer to ASR Web Service Reference for information about the ASR Web Service set of operations.

CABS Web Service

You use the CABS Web Service to export and query billing information for a given ASR. For example, you can request the following:

Export of CABS
Query CABS by various criteria

Refer to CABS Web Service Reference for information about the CABS Web Service set of operations.

About the ASR Web Services Framework

Figure 1-1 shows the path traveled by a call originating from the web service client.

Figure 1-1 ASR Web Services Framework

Description of "Figure 1-1 ASR Web Services Framework"

The path of the web service includes:

Web service client

This client represents the web service user. Web service operations are called by sending SOAP messages over HTTP or HTTPS.
Web service module

This module represents all the sub-modules required for implementing a web service, for instance, the web service framework, the WSDL interfaces, and the WSDL implementations. The web service module is deployed as a WAR file.

See "About the ASR Web Service Module" for more information.
Business logic

The business logic includes all the sub-modules required for implementing business functionality and includes the Java EJBs and the database.

About the ASR Web Service Module

The web service module is installed as part of the ASR installation. All web services are included in the following EAR files:

ASRrelease.ear file for a single server environment
cluster-ASRrelease.ear file for a clustered server environment

where release is the ASR release number. When the ASR installer copies the EAR file to the deploy directory, the following modules of the ASR Web Services are deployed and ready to use:

ASR Web Service
CABS Web Service

You can deploy two different ASR versions at the same time.

About ASR Web Service Standards and Specifications

See MSS Web Services Developer's Guide for information on the web service standards and specifications topic.

About Transaction Handling

Transactions are handled in the same way that MSS Web Services manages transactions. See MSS Web Services Developer's Guide for information on this topic.

About Exception Stacktraces

Exception stacktraces are available in the WebLogic server logs. The error messages are thrown by the operation when an exception occurs. This information is available in the following log files:

serverName.mss.log file where serverName is the server name of the ASR application installation.
AppServerLog_ASRrelease.xml file where release is the ASR release number.

These files are located in the MSS log directory.

ASR throws exceptions of type WSException_Exception from the web service. You must handle these exceptions from the client-side code.

Understanding ASR Web Services

Web services are defined by WAR, WSDL, and schema files. For web services, there is a WAR file. The WAR file includes a single WSDL file and numerous schema files. The WSDL files contain the actual web service definitions. The schema files include definitions of specific elements, complex types, and simple types.

About WAR and WSDL Files

The WAR files are in the root directory of the ASR EAR file. Within each WAR file, the WSDL file is located in the WEB-INF/wsdls directory. The schemas are also available in the asr_webservice_schemas.jar file. You find this JAR file as a deliverable with the ASR installer. Table 1-1 provides the WSDL and WAR file names for the web services.

Table 1-1 WAR and WSDL Files for Each Web Service

Web Service	WAR File Name	WSDL File Name
ASR Web Service	asrws.war	ASRWebService.wsdl
CABS Web Service	cabsws.war	CABSWebService.wsdl

About WSDL Definitions

The WSDL definitions at the beginning of the WSDL file define the web service as being deployed using the SOAP 1.1 protocol over HTTP.

See the following websites for more information about WSDL 1.1 and SOAP 1.1:

See "About ASR Web Service Standards and Specifications" for more information about the standards that apply to the ASR Web Service.

Example 1-1 shows the definitions section of the ASRWebService.wsdl file.

Example 1-1 WSDL Definitions Example

<definitions targetNamespace="http://www.openuri.org/" name="ASRWebService"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:tns="http://www.openuri.org/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">

About WSDL Locations

For the ASR Web Services, you can access the WSDL information with URL locations. Table 1-2 provides the URL locations for each web service.

Table 1-2 WSDL URL Location for each Web Service

Web Service	URL Location
ASR Web Service	http://asrHost:port/ASRreleaseWS/asr/ASRreleaseWebService?WSDL
CABS Web Service	http://asrHost:port/CabsreleaseWS/asr/CABSreleaseWebService?WSDL

where:

asrHost is the name of the host on which ASR is installed.
port is the port number of the system on which ASR is installed.
release is the ASR release number because two different versions of ASR can be deployed simultaneously.

About WSDL Bindings

In the WSDL file, the bindings define the protocol details and message formats for the web service operations. Example 1-2 shows a portion of the WSDL file with the binding definition of the exportASR operation.

Example 1-2 ASRSoap Binding Definition Example with exportASR

<binding name="ASRWSSoapBinding" type="tns:ASRImpl">
   <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
      style="document"/>
   <operation name="exportASR">
   <soap:operation soapAction="http://www.openuri.org/exportASR"
      style="document"/>
   <input>
      <soap:body use="literal"/>
   </input>
   <output>
       <soap:body use="literal"/>
   </output>
       <fault name="WSException">
           <soap:fault name="WSException" use="literal"/>
       </fault>
   </operation>
</binding>

About Namespaces

Each WSDL file defines a namespace to avoid naming conflicts. The namespace definition appears after the WSDL definitions section.

You use the namespace to determine the schema file location of the schema reference. Example 1-3 shows how a namespace defined in the WSDL correlates to the supporting schema files.

In this example, the ASR Web Service WSDL file named ASRWebService.wsdl defines and references the asr namespace. This excerpt shows exportASRReq has a namespace designation and how the namespace is defined:

Example 1-3 ASRWebService.wsdl Namespace Example

.
.
.
<xsd:schema xmlns:asr="http://xmlns.oracle.com/communications/asr">
     <!-- ============= Schema Imports ==================== -->
     <xsd:import namespace="http://xmlns.oracle.com/communications/asr"
                 schemaLocation="../schemas/ASRWebService_schema.xsd"/>
</xsd:schema>
.
.
.
<xsd:element name="exportASRReq">
     <xsd:complexType>
          <xsd:sequence>
              <xsd:element ref="asr:exportASR"/>
          </xsd:sequence>
     </xsd:complexType>
</xsd:element>

The exportASRReq element declaration tells you that exportASR is defined in the schema file that supports the specified namespace. A search for the specified namespace reveals that the asr namespace represents the ASRWebService_schema.xsd schema file.

After you determine that the ASRWebService_schema.xsd schema file defines the XML structure that the WSDL file references, you can navigate through the schema files to determine child XML structures.

Refer to the following website for more information on namespaces:

https://www.w3.org/TR/REC-xml-names/

Understanding ASR WSDL Operations

The WSDL file defines the web service and its operations. It also defines the input, output and fault messages of each operation. ASR WSDL operations follow the request-response or round-trip pattern. When the client sends a request message to the web service, the operation either sends a response message back or the operation sends a fault message back to the client for an error.

In the WSDL file, each service is bound to a port. For example, in the ASRWebService.wsdl file, the ASR Web Service is bound to the ASRreleaseWSSoap port, where release is the ASR release number. Example 1-4 shows the definition of the service and the port name.

Example 1-4 Service and Port Definition

<service name="ASRreleaseWebService">
    <port name="ASRreleaseWSSoap" binding="tns:ASRWSSoapBinding">
        <soap:address location="http://localhost:7001/ASRreleaseWS/ASR"/>
    </port>
</service>

In Example 1-4, the release placeholder is the ASR release number.

The service and port declaration reference the portType through the soap definition. The portType element combines multiple message elements to define the list of web service operations and their parameters.

Example 1-5 demonstrates the following aspects of the portType definition in the ASR Web Service:

The portType element definition of the name as ASRreleaseWSSoap where release is the ASR release number.
The definition of exportASRReq as a round-trip operation
The declaration of the input, output, and fault message types for exportASRReq

Example 1-5 The WSDL portType and exportASRReq Definition

<portType name="ASRImpl">
    <operation name="exportASR">
        <input message="tns:exportASR"/>
        <output message="tns:exportASRResponse"/>
        <fault message="tns:WSException" name="WSException"/>
    </operation>
.
.
.
</portType>

Message definitions determine the input and output parameters for the operation. Example 1-6 shows a WSDL excerpt with the message definitions and their respective elements.

Example 1-6 Web Service Message Definitions for exportASRReq Operation

<message name="exportASR">
    <part name="parameters" element="tns:exportASRReq"/>
</message>
<message name="exportASRResponse">
    <part name="parameters" element="tns:exportASRReqResponse"/>
</message>
<message name="WSException">
    <part name="fault" element="tns:WSExceptionRes"/>
</message>

Table 1-3 summarizes the definitions in Example 1-5 and Example 1-6 to list the message types, messages, and elements for the exportASRReq operation.

Table 1-3 exportASRReq Messages and Elements

Message Type	Message	Element
input	exportASR	exportASRReq
output	exportASRResponse	exportASRResponse
fault	WSException	WSExceptionRes

The details of the element for each message are defined in declarations in the WSDL file. For example, the input request, output response, and exception/fault elements listed in Table 1-3 are defined by the declarations shown in Example 1-7.

Example 1-7 Element Definitions for Input, Output, and Fault for exportASRReq

<xsd:element name="exportASRReq">
     <xsd:complexType>
          <xsd:sequence>
               <xsd:element ref="asr:exportASR"/>
          </xsd:sequence>
     </xsd:complexType>
</xsd:element>
<xsd:element name="exportASRReqResponse">
     <xsd:complexType>
         <xsd:sequence>
             <xsd:element ref="asr:exportASRResponse"/>
         </xsd:sequence>
    </xsd:complexType>
</xsd:element>
<xsd:element name="WSExceptionRes">
    <xsd:complexType>
         <xsd:sequence>
             <xsd:element ref="asr:WSException"/>
         </xsd:sequence>
    </xsd:complexType>
</xsd:element>

The elements include references to the locations in schema files where they are fully defined. The references include namespaces that you use to locate the schema file for each element. For example, the namespace asr was defined earlier to point to the ASRWebService_schema.xsd file.

The schema files can themselves include references to other schema files.

Refer to "About Namespaces" for more information on namespaces, and "About Schema Files" for more information on schema files.

About Schema Files

Numerous schema files support the ASR Web Services. Within a WAR file, you find the schema files located in the WEB-INF/wsdls directory. The schemas are also available in the asr_webservice_schemas.jar file. This JAR file is provided along with the ASR installer file. These schemas are categorized as ASR schemas, CABS schemas, External DLR schemas, and Query ASR schemas.

Refer to the individual web service chapter for more information about schema files.

Getting Information about ASR WSDL Operations

This guide contains high-level documentation about each web service and its operations.

There is a reference chapter dedicated to each web service. Each web service chapter includes an overview of the web service and a section for each operation. Each operation section contains the following:

An overview of the operation's purpose
High-level schema information for the input or request message payload
High-level schema information for the output or response message payload

You use the XSD schema files as reference for field-level information such as descriptions and field formatting guidance. Also, refer to "Using the Access Service Ordering Guidelines" for additional field-level documentation.

Using the Message Payload Documentation

The reference chapter for the web service includes sections for the request and response documentation. For each operation's request and response, a table describes the primary XSD elements and types. An operation can have multiple tables describe complex payloads.

These tables enable you to navigate the request or response in the following ways:

They provide an overall view of the payload.
They aid in locating the request or response definitions and their XSD file location.
They show you XSD definitions, for instance, whether they are elements or complex types.

The table describing a request contains the following information:

The input request element defined in the first row.
A row for each element, describing how the element or complexType is defined in the XSD, its type, and the file name where it is defined.
A row for each type listed in the table, placed following the row in which the type is first mentioned.

Table 1-4 is an example of the request elements and complex types for the exportASR operation.

Table 1-4 Elements and Types for the Request Example

Name	Defined As	Type Description	File Name
exportASRReq	element	exportASR	ASRWebService.wsdl
exportASR	element	exportASR	ASRWebService_schema.xsd
exportASR	complexType	documentNumber	ASRWebService_schema.xsd
documentNumber	int	The order number for export.	ASRWebService_schema.xsd

In this example, exportASRReq is the name value in first row. This exportASR element is defined as the input message element for the operation. It is defined as an element and is located in the ASRWebService.wsdl file. (See Example 1-6 for an excerpt of this input message definition.)

The type for the exportASRReq element is exportASR. This exportASR type is then listed in the second row and similarly described.

This pattern continues until one of the following is true:

The item referenced is list of form fields.
The item referenced is a series of fields where the series contains simple types or complex types that are located in the same schema file.

To get specific information about fields, you consult the XSD schema file itself. For example, you find the exportASR element in the ASRWebService_schema.xsd file.

Similarly, response messages are defined in tables that have the same format and layout as the request information. Refer to the Access Service Ordering Guidelines (ASOG) documentation for field level details and error message information.

Table 1-5 shows an example of the possible error messages for the exportASR operation.

Table 1-5 Error Messages for the exportASR Operation

Error Message	Cause	Resolution
5855 Failed: No Order Found for PON 123.	The document number passed in the input does not exist in database.	Populate a valid document number which needs to be exported.
The order for PON 123 is received not sent and cannot be exported.	The document number provided in the input is a received order and not a sent order.	For an export request, you must provide a sent order and not a received order.

Using the Access Service Ordering Guidelines

The ASR Web Services and its operations are defined based on the Access Service Ordering Guidelines (ASOG). Refer to the guidelines of the desired release to get more information on the field level validations and additional operation details. You can access this documentation at this website:

https://www.atis.org

How to Use Multiple Versions of ASR

Two different ASR versions can be deployed at the same time. To invoke the correct version of the ASR operation, use the release number within the WSDL. Refer to "About WSDL Locations" for more information on the WSDL location URLs.

Deploying, Testing, and Invoking Secure Web Services

This section provides information about deploying, testing, and invoking secure ASR Web Services.

About Deploying ASR Web Services

The ASR Web Services WAR file is part of the ASR EAR file. When the appropriate ASR EAR file is deployed the web services are also deployed. You can deploy ASR and the ASR Web Services in a single server or in a clustered server environment. If you already have the ASR and the ASR Web Services deployed then you will need to first undeploy them before you can deploy again.

See ASR Installation Guide for information on deploying and undeploying the ASR EAR file.

About Testing ASR Web Services

You can test the ASR Web Services in several ways, for instance by testing using SoapUI or by writing a Java test client. See MSS Web Services Developer's Guide for information on testing.

About Invoking Secure ASR Web Services

The ASR Web Service operations are secured in the same way that MSS Web Services are secured. See MSS Web Services Developer's Guide for information on this topic.

Troubleshooting

See MSS Web Services Developer's Guide for information on the troubleshooting topic.

Understanding the Differences in CORBA APIs and Web Services

If you currently use the CORBA APIs, this section helps you understand the differences in the CORBA APIs and the web services. Understanding these differences helps you move to the web services and convert from IDL definitions to schema definitions. Most of the APIs have alignment, but the following items detail a few differences:

The data type fields of MSVDate change to a string data type. The data type format for the date string fields is “yyyy-mm-dd" such as a “2017-07-20" format.

For the importExternalDLR operation, this change affects the following fields:
- ISS
- PTD
- DD
For the exportCABS operation, this change affects the following fields:
- lastModifiedDate
- inServiceDate
- serviceTermDate
- transferDate
- extractDate
- vtaTermDate
- dateOfAgencyAuthorization
- desiredDueDate
There are no blank structures for empty forms, except for the TQ form.

For example, in the CORBA API (not supported now) export of an ASR, the operation returns empty structures for empty forms. For the exportASR web service operation, no empty forms are returned. One exception is for the ASR Web Service where a TQ form returns an empty structure.
The handling of empty tags in the output data is different in the web services than it is for CORBA APIs (not supported now).

During an exportASR web service operation, the response structure has:
- either this definition
```
<tagName></tagName>
```
- or this type of definition
```
<tagName/>
```
  where tagName is an element or complex type in the schema.
The easbdw field (in the PIP, DIS and ACI forms) changes to have a unit of measure value included in the web service schemas. An example easbdw field value is “1.45K" which previously was “1.45" without a unit of measure.
All character data type fields change to a string data type with length of 1 in the schema files.