Using the PDC Web Service

34 Using the PDC Web Service

Learn how to use the Oracle Communications Pricing Design Center (PDC) Web Service.

Topics in this document:

About the PDC Web Service API

The PDC Web service application programming interface (API) allows other Oracle applications as well as third-party applications to interact with PDC. Use the PDC Web service API to:

Create, modify, and export pricing components.
Create, modify, and export setup components.
Create and export metadata and custom data.

To use the PDC Web service API, the external application must call the PDC Web service API through a custom client application. You can use any language that supports Web services to access the API, for example, Java.

About Using the PDC Web Service

To use the PDC Web service, you must:

Ensure that the SSL port for the WebLogic Server domain is enabled. See "Configuring SSL for the WebLogic Server Domain" in PDC Installation Guide for more information.
Ensure that the following system properties are set in WebLogic Server:
- weblogic.security.TrustKeyStore
- weblogic.security.CustomTrustKeyStoreFileName
- weblogic.security.CustomTrustKeyStorePassPhrase
- weblogic.security.CustomTrustKeyStoreType
See the discussion about setting the system properties in the WebLogic Server Administration Console Help for more information.
Ensure that the following BindingProvider properties are set in WebLogic Server:
- BindingProvider.USERNAME_PROPERTY
- BindingProvider.PASSWORD_PROPERTY
See the discussion about setting the BindingProvider properties in the WebLogic Server Administration Console Help for more information.

Creating and Modifying Pricing Components

To create or modify components with the PDC Web service:

Create the XML file containing the components. See "About Creating the XML Files" for more information.
Use the PDC Web service to create or modify the components defined in the XML file. The PDC APIs are exposed as Web service operations through the PricingGateway.wsdl file. This file defines the Web service that can be called as well as the attributes required to call a specific operation.

You can use the PDC Web services for the tasks shown in Table 34-1.

Table 34-1 Create and Modify Components

Task	Operation
Create pricing components.	CreatePricing
Modify promoted pricing components.	ModifyPricing
Create pricing components and publish the components to the Oracle Communications Billing and Revenue Management (BRM) database.	CreatePricingAndSubmit
Modify promoted pricing components and publish the components to the BRM database.	ModifyPricingAndSubmit
Create setup components.	createBusinessConfig
Create setup components and publish the setup components to a billing system such as BRM.	createBusinessConfigAndSubmit
Modify setup components.	modifyBusinessConfig
Modify setup components and publish the setup components to a billing system such as BRM.	modifyBusinessConfigAndSubmit
Create metadata.	createMetadata
Create custom data.	createCustomFields

About Creating the XML Files

You need to create an XML file containing the components you want to use. You can create:

One consolidated XML file containing all the components
Separate XML files for each type of component (for example, charge offers, discount offers, packages, and so on)

The XML files that you create must conform to the format detailed in the XSD files for pricing components.

The PDC Web service uses the PricingGateway.xsd file for creating or modifying components in PDC. The XSD files describe the structure of the XML document. The XML file you create must comply with the structure defined in the XSD. The PricingGateway.xsd file is available at:

http://hostName:sslPortNumber/pdc/PricingGatewayPort?xsd=1

where:

hostName is the host name of the machine on which PDC is deployed.
sslPortNumber is the SSL port number of the domain on which PDC is deployed.

Sample Code to Call the PDC Web Service

Use the following sample code to call the PDC Web service:

PricingGatewayPortType pricingGatewayPortType =(PricingGatewayPortType)Service.getPort(new QName("urn:PricingGateWay","PricingGatewayPort"),
PricingGatewayPortType.class);

Map<String, Object> rc = ((BindingProvider)pricingGatewayPortType).getRequestContext();
rc. put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, http://hostName:sslPortNumber/pdc/PricingGatewayPort?WSDL));
rc.put(BindingProvider.USERNAME_PROPERTY,pdcUserName);
rc.put(BindingProvider.PASSWORD_PROPERTY,pdcUserPassword);

UserContextType userContext = new UserContextType();
userContext.setUserid("pdcUserName");

PricingInputXMLType pricingInputXMLType = new PricingInputXMLType();
pricingInputXMLType.setUserContext(userContext);
ByteArrayOutputStream bs = new ByteArrayOutputStream();
ZipOutputStream out = new ZipOutputStream(bs);
        FileInputStream fl = null;
        try {
            fl = new FileInputStream(new File(pricing.xml));
            // Set the compression ratio
            out.setLevel(Deflater.BEST_COMPRESSION);
            ZipEntry ze = new ZipEntry(PDC);
            out.putNextEntry(ze);
            byte[] data = new byte[BUFFER_SIZE];            int count = 0;
            BufferedInputStream in = new BufferedInputStream(fl);
            while ((count = in.read(data, 0, BUFFER_SIZE)) != -1){
                out.write(data, 0, count);
            }
        } catch (Exception e) {
            throw e;
        } finally {
            if (fl != null) {
                fl.close();
            }
            if (bs != null) {
                bs.flush();
            }
            if (out != null) {
                out.flush();
                out.close();
            }
        }
        byte[] bytesToRet = null;
        if (bs != null) {
            bytesToRet = bs.toByteArray();
        }
pricingInputXMLType.setXmlBinaryString(bytesToRet);

PDCResponseType pDCResponseType = pricingGatewayPortType.createPricingAndSubmit(pricingInputXMLType);

CreatePricing

This Web service operation validates the input XML by comparing the XML fields and values against the values in the PricingGateway.xsd file and the rules for each type of pricing component. If the validation is successful, it retrieves the data from the XML file and creates the pricing components in PDC.

The CreatePricing operation does not publish the pricing components to the BRM database.

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType createPricing(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

ModifyPricing

The ModifyPricing operation does not publish the pricing components to the BRM database.

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType modifyPricing(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

CreatePricingAndSubmit

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType createPricingAndSubmit(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

ModifyPricingAndSubmit

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType modifyPricingAndSubmit(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

createBusinessConfig

This Web service operation validates the input XML by comparing the XML fields and values against the values in the PricingGateway.xsd file and the rules for each type of business config component. If the validation is successful, it retrieves the data from the XML file and creates business config components in PDC.

The createBusinessConfig operation does not publish the business config components to the BRM database.

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType createBusinessConfig(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

createBusinessConfigAndSubmit

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType createBusinessConfigAndSubmit(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

modifyBusinessConfig

The modifyBusinessConfig operation does not publish the business config components to the BRM database.

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType modifyBusinessConfig(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

modifyBusinessConfigAndSubmit

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType modifyBusinessConfigAndSubmit(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

createMetadata

This Web service operation validates the input XML by comparing the XML fields and values against the values in the PricingGateway.xsd file and the rules for each type of metadata component. If the validation is successful, it retrieves the data from the XML file and creates metadata components in PDC.

The createMetadata operation does not publish the metadata components to the BRM database.

Syntax:

public oracle.communications.brm.pdc.server.service.types.PDCResponseType createMetadata(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

createCustomFields

This Web service operation validates the input XML by comparing the XML fields and values against the values in the PricingGateway.xsd file and the rules for each type of custom fields. If the validation is successful, it retrieves the data from the XML file and creates custom fields in PDC.

The createCustomFields operation does not publish the custom fields to the BRM database.

Syntax

public oracle.communications.brm.pdc.server.service.types.PDCResponseType createCustomFields(oracle.communications.brm.pdc.server.service.types.PricingInputXMLType param) throws oracle.communications.brm.pdc.server.service.PricingExceptionResponse;

Exporting Components

You can use the PDC Web services for the tasks shown in Table 34-2.

Table 34-2 Export Tasks

Task	Operation
Export pricing components.	getPricingObjects
Export setup components.	getBusinessConfigObjects
Export metadata components.	getMetadataObjects
Export BRM components.	getBRMObjects
Export custom fields.	getCustomFields

PDC Web services use the RetrieveInputXMLType object as input for exporting the PDC components. You can create the RetrieveInputXMLType object.

Using the Setter Method. See "Creating RetrieveInputXMLType Object Using Setter Method".
Using the XML. See "Creating RetrieveInputXMLType Object Using XML".

Creating RetrieveInputXMLType Object Using Setter Method

You can create the RetrieveInputXMLType object using setter methods (for example, pojos) with the required parameters to export components from PDC system.

For example, to export pricing components you can create the object as follows:

getPricingObjects() {
 RetrieveResponseType response = new RetrieveResponseType();
 RetrieveInputXMLType request = new RetrieveInputXMLType();
 ObjectType objectType = new ObjectType();
 WSPricingObject pricingObject = new WSPricingObject();
 pricingObject.getPricingObjectType().add(WSPricingObjectType.ALTERATION_EXCLUSION);
 objectType.setPricingObject(pricingObject);
 request.setObjectType(objectType);
 request.setAllReferences(false);
 request.setIncludeFailedObjects(false);
 request.setObsolete(false);
 request.setReferences(false);
 UserContextType userContext = new UserContextType();
 userContext.setUserid("pdcuser");
 request.setUserContext(userContext);
 response = pricingGatewayPortType.getPricingObjects(request);
 return response;
}

Creating RetrieveInputXMLType Object Using XML

The PDC Web services use the RetrievePricingGateway.xsd file for exporting components from PDC. The XSD file describes the structure of the XML file. The XML file you create must comply with the structure defined in the XSD. The RetrievePricingGateway.xsd file is available at:

http://hostName:sslPortNumber/pdc/PricingGatewayPort?xsd=2

where:

hostName is the host name of the machine on which PDC is deployed.
sslPortNumber is the SSL port number of the domain on which PDC is deployed.

You need to manually set the required parameters in the XML file for indicating the objects that you want to export from the PDC system. The RetrieveInputXMLType object is then created by parsing this XML.

Parameters for Exporting PDC Components

Table 34-3 describes the parameters used for exporting PDC components.

Table 34-3 Parameters for Exporting PDC Components

Parameter	Description
objectType	Specifies the object type to export. The valid values are pricingObject, businessConfigObject, brmObject, and metadataObject. You can specify the pricing object type for exporting. For example, ALTERATION_RATE_PLAN, USC_MAP and so on. If pricing object type is not specified, all the pricing components are considered for exporting. This parameter is also applicable for setup components, metadata, and cross-reference data.
references	Specifies whether to export data including references.
allReferences	Specifies whether to export data including all references. This is applicable only when exporting pricing objects. When allReferences is set to true for pricing objects, the response is written separately into pricingObjectResponse, configObjectResponse, and metadataObjectResponse fields. If the export allReferences is not set for pricing objects, the pricing object responses are written into response field.
obsolete	Specifies whether to export obsolete data.
includeFailedObjects	Specifies whether to export data including failed objects.
modifiedAfterDate	Specifies whether to export data based on modified date. ModifiedAfterDate supports the following formats: yyyy-mm-dd Example: 2010-01-05 yyyy-mm-dd'T'hh:mm:ss Example: 2010-01-05T23:59:59 yyyy-mm-dd'T'hh:mm:ssz Example: 2010-01-05T19:05:09GMT+05:30
modifiedByUser	Specifies whether to export data based on the user who modified the data.
objectName	Specifies whether to export data based on object name.
UserContext	Specifies whether to export data for a specific user.
productSpecName	Specifies whether to export data based on product specification. This is applicable only when exporting pricing components.

Web Service Response

The PDC Web service operation first validates the input XML by comparing the XML fields and its values against the values in the RetrievePricingGateway.xsd file. If the validation is successful, it retrieves the objects from PDC and returns the data in RetrieveResponseType object.

Here is the structure of the RetrieveResponseType object:

<xsd:complexType name="RetrieveResponseType">
 <xsd:annotation>
  <xsd:documentation>Get Object Webservice Response</xsd:documentation>
 </xsd:annotation>
 <xsd:sequence>
  <xsd:element name="status" type="xsd:string"/>
  <xsd:element name="errors" type="xsd:string" maxOccurs="unbounded" minOccurs="0"/>
  <xsd:element name="response" type="xsd:base64Binary"/>
  <xsd:element name="pricingObjectResponse" type="xsd:base64Binary"/>
  <xsd:element name="configObjectResponse" type="xsd:base64Binary"/>
  <xsd:element name="metadataObjectResponse" type="xsd:base64Binary"/>
 </xsd:sequence>
</xsd:complexType>

The RetrieveResponseType object contains the status of operation and the exported object fields in the XML binary format based on the input provided in RetrieveInputXml file. The status field value is either SUCCEEDED or FAILED. The RetrieveResponseType object also capture errors occurred during the operation.

Processing the Response from Export/GET API

When an export or GET operation is successful, you receive a response with the requested object data. You get the response as follows:

response = pricingGatewayPortType.getPricingObjects(request);

You can process the response object by using the following code in your application:

processResponse(RetrieveResponseType response) {
byte[] zippedBinaryStr = response.getResponse();
for (int i = 0; i < response.getErrors().size(); i++) {
  System.out.println("Cause : \n" + response.getErrors().get(i)+ "\n");
}
String status = response.getStatus(); //status values can be either SUCCEEDED or FAILED
}

Optionally, you can convert the response into the XML format by using the following code in your application:

private static void writeToFile(byte[] zippedBinaryStr, String filename) throws Exception {
        try {
            FileOutputStream fpStream = new FileOutputStream(filename);
            BufferedOutputStream bufferedStream = new BufferedOutputStream(fpStream);
            extractZippedContentAndWriteXMLStream(zippedBinaryStr, bufferedStream);
            bufferedStream.flush();
            bufferedStream.close();
            fpStream.flush();
            fpStream.close();
        } catch (IOException e) {
            System.out.println("Exception caught when writing data to file");
            throw e;
        }
    }
   private static void extractZippedContentAndWriteXMLStream(byte[] binaryXMLString,
BufferedOutputStream bufferedFileStream) throws Exception {
        try (ByteArrayInputStream byteStrm = new ByteArrayInputStream(binaryXMLString);
             ZipInputStream in = new ZipInputStream((byteStrm))) {
             ZipEntry entry = in.getNextEntry();
            //Transfer bytes from the ZIP file to the output file
            if (entry != null && in.available() > 0) {
                byte[] buf = new byte[BUFFER_SIZE];
                int len = in.read(buf);
                while (len > 0) {
                     bufferedFileStream.write(buf, 0, len);
                    len = in.read(buf);
                }
                bufferedFileStream.flush();
            }
        } catch (Exception e) {
            throw e;
        }
    }

where filename is the path to the XML file for storing the output.

getPricingObjects

This Web service operation validates the input XML by comparing the XML fields and values against the values in the RetrievePricingGateway.xsd file. If the validation is successful, it retrieves the pricing objects from PDC and returns the data in RetrieveResponseType object.

Syntax

public oracle.communications.brm.pdc.server.service.types.RetrieveResponseType getPricingObjects(oracle.communications.brm.pdc.server.service.types.RetrieveInputXMLType param) throws Exception;

getMetadataObjects

This Web service operation validates the input XML by comparing the XML fields and values against the values in the RetrievePricingGateway.xsd file. If the validation is successful, it retrieves the metadata object from PDC and returns the data in RetrieveResponseType object.

Syntax

public oracle.communications.brm.pdc.server.service.types.RetrieveResponseType getMetadataObjects(oracle.communications.brm.pdc.server.service.types.RetrieveInputXMLType param) throws Exception;

getCustomFields

This Web service operation validates the input XML by comparing the XML fields and values against the values in the RetrievePricingGateway.xsd file. If the validation is successful, it retrieves the custom fields from PDC and returns the data in RetrieveResponseType object.

Syntax

public oracle.communications.brm.pdc.server.service.types.RetrieveResponseType getCustomFields(oracle.communications.brm.pdc.server.service.types.RetrieveInputXMLType param) throws Exception;

getBusinessConfigObjects

This Web service operation validates the input XML by comparing the XML fields and values against the values in the RetrievePricingGateway.xsd file. If the validation is successful, it retrieves the business config from PDC and returns the data in RetrieveResponseType object.

Syntax

public oracle.communications.brm.pdc.server.service.types.RetrieveResponseType getBusinessConfigObjects(oracle.communications.brm.pdc.server.service.types.RetrieveInputXMLType param) throws Exception;

getBRMObjects

This Web service operation validates the input XML by comparing the XML fields and values against the values in the RetrievePricingGateway.xsd file. If the validation is successful, it retrieves the BRM object from PDC and returns the data in RetrieveResponseType object.

Syntax

public oracle.communications.brm.pdc.server.service.types.RetrieveResponseType getBRMObjects(oracle.communications.brm.pdc.server.service.types.RetrieveInputXMLType param) throws Exception;