6 Creating Outbound Web Service Calls

This section explains how to create outbound web service calls using the Oracle Sales Cloud interface.

The Oracle Sales Cloud SalesParty object is used to provide an example of an outbound web service call and endpoint. The Opportunity object is used to provide examples of both an outbound only and a round-trip web service call (both outbound and inbound).

Topics:

Creating a SalesParty Object Outbound Web Service Call and Endpoint

This section explains how to create an externally hosted custom web service based on the Oracle Sales Cloud SalesParty object, and how to create an outbound web service call to that custom service.

Oracle Sales Cloud Object Workflows are used to send outbound messages to the this service's endpoint URL. In the scenario used in this section, the object workflow will be configured to call the web service when a particular field in the SalesAccount object is updated. The updated SalesAccount object provides the payload that is used by the web service.

Three files are required for this task flow:

  • SalesParty.xsd

  • OutboundMessageService.wsdl

  • OutboundMessageService.xsd

Task 1   Edit a sample OutboundMessageService WSDL

The following is a sample OutboundMessageService WSDL:

//Sample OutboundMessageService.wsdl 
<wsdl:definitions
     name="OutboundMessageService"
     targetNamespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/"
     xmlns:errors="http://xmlns.oracle.com/adf/svc/errors/"
     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns:types="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
    >
    <wsdl:import namespace="http://xmlns.oracle.com/adf/svc/errors/" location="ServiceException.wsdl"/>
    <wsdl:types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
                 schemaLocation="OutboundMessageService.xsd"/>
        </schema>
    </wsdl:types>
    <wsdl:message name="OutboundMessageService_processOutboundMessage">
        <wsdl:part name="parameters" element="types:processOutboundMessage"/>
    </wsdl:message>
    <wsdl:message name="OutboundMessageService_processOutboundMessageResponse">
        <wsdl:part name="parameters" element="types:processOutboundMessageResponse"/>
    </wsdl:message>
    <wsdl:portType name="OutboundMessageService">
        <wsdl:documentation/>
        <wsdl:operation name="processOutboundMessage">
            <wsdl:input message="tns:OutboundMessageService_processOutboundMessage"/>
            <wsdl:output message="tns:OutboundMessageService_processOutboundMessageResponse"/>
            <wsdl:fault name="ServiceException" message="errors:ServiceException"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="OutboundMessageServiceSoapHttp" type="tns:OutboundMessageService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="processOutboundMessage">
            <soap:operation soapAction="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/processOutboundMessage"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ServiceException">
                <soap:fault name="ServiceException" use="literal" encodingStyle=""/>
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="OutboundMessageService">
        <wsdl:port name="OutboundMessageServiceSoapHttpPort" binding="tns:OutboundMessageServiceSoapHttp">
            <soap:address location="http://adc2111013:7101/OMInterface/OutboundMessageService"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

You are required to adjust the following values to suit your specific environment:

  • ServiceException.wsdl

  • http://adc2111013:7101/OMInterface/OutboundMessageService

Task 2   Edit the OutboundMessageService.xsd and SalesParty.xsd Files

Search for the OutboundMessageService.xsd file in the Oracle Enterprise Repository.

You will need to value for schemaLocation to suit your environment. For example, schemaLocation="https:yourFCRM:443/crmCommonSalesParties/SalesPartyService?XSD=/META-INF/wsdl/BC4JService.xsd where yourFCRM is the location of your Oracle Sales Cloud.

The SalesParty.xsd file can be found at http://yourFCRMHost/crmCommonSalesParties/SalesPartyService?XSD=/oracle/apps/crmCommon/salesParties/salesPartiesService/SalesParty.xsd where yourFCRM is the location of your Oracle Sales Cloud. Make sure to save the SalesParty.xsd file locally under the same name.

Task 3   Create the Web Service in JDeveloper

This section explains how to create the web service in JDeveloper, as follows:

  1. Create a new custom app in JDeveloper.

  2. Import the following three files. All three files contain external references which must be amended to suit your specific environment:

    • SalesParty.xsd

    • OutboundMessageService.wsdl

    • OutboundMessageService.xsd

Task 4   Validate the OutboundMessageService WSDL

In this section, you will create the Java web service from the OutboundMessageService WSDL and deploy it to the embedded WebLogic service that is running with your instance of JDeveloper. Therefore, the location pointer in the WSDL below must point to your local machine:

<?xml version="1.0" encoding="UTF-8" ?>    
    <wsdl:definitions
     name="OutboundMessageService"
     targetNamespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/"
     xmlns:errors="http://xmlns.oracle.com/adf/svc/errors/" 
     xmlns:tns="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/"
     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns:types="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
    >
 
    <wsdl:documentation>
        <name>Sales Account Outbound Message Service</name>
        <docCategories>
            <category>None</category>
        </docCategories>
    </wsdl:documentation>    
<wsdl:import namespace="http://xmlns.oracle.com/adf/svc/errors/" 
location="https://isv25-crm-crm-ext.oracle.com/crmCommonSalesParties/SalesPartyService?WSDL=/META-INF/wsdl/ServiceException.wsdl"/>
    <wsdl:types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
                 schemaLocation="OutboundMessageService.xsd"/>
        </schema>
    </wsdl:types>
    <wsdl:message name="OutboundMessageService_processOutboundMessage">
        <wsdl:part name="parameters" element="types:processOutboundMessage"/>
    </wsdl:message>
    <wsdl:message name="OutboundMessageService_processOutboundMessageResponse">
        <wsdl:part name="parameters" element="types:processOutboundMessageResponse"/>
    </wsdl:message>
    <wsdl:portType name="OutboundMessageService">
        <wsdl:documentation/>
        <wsdl:operation name="processOutboundMessage">
            <wsdl:input message="tns:OutboundMessageService_processOutboundMessage"/>
            <wsdl:output message="tns:OutboundMessageService_processOutboundMessageResponse"/>
            <wsdl:fault name="ServiceException" message="errors:ServiceException"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="OutboundMessageServiceSoapHttp" type="tns:OutboundMessageService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="processOutboundMessage">
            <soap:operation soapAction="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/processOutboundMessage"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ServiceException">
                <soap:fault name="ServiceException" use="literal" encodingStyle=""/>
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="OutboundMessageService">
        <wsdl:port name="OutboundMessageServiceSoapHttpPort" binding="tns:OutboundMessageServiceSoapHttp">
            <soap:address location="http://192.168.2.107:7101/crmCommonSalesParties/OutboundMessageService"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>
Task 5   Validate the OutboundMessageService.xsd

This section explains how to validate the OutboundMessageService.xsd. In order to do so, you need to import the BC4JService.xsd file from your instance of Oracle Sales Cloud. The OutboundMessageService.xsd, where yourFCRM is the location of your Oracle Sales Cloud, as follows:

<schema elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
     xmlns:ns0="http://xmlns.oracle.com/adf/svc/errors/" xmlns:ns1="http://xmlns.oracle.com/apps/crmCommon/salesParties/salesPartiesService/"
     xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/" xmlns:tns="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
     xmlns="http://www.w3.org/2001/XMLSchema">
    <import namespace="http://xmlns.oracle.com/adf/svc/types/" schemaLocation="https://yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/META-INF/wsdl/BC4JService.xsd"/>
    <import namespace="http://xmlns.oracle.com/apps/crmCommon/salesParties/salesPartiesService/" schemaLocation="SalesParty.xsd"/>
    <element name="processOutboundMessage">
        <complexType>
            <sequence>
                <element name="object" type="ns1:SalesParty"/>
            </sequence>
        </complexType>
    </element>
    <element name="processOutboundMessageResponse">
        <complexType>
            <sequence/>
        </complexType>
    </element>
</schema>
Task 6   Validate the SalesParty.xsd

In order to validate the SalesParty.xsd, adjust the value for yourFCRM, where yourFCRM is the location of your Oracle Sales Cloud, as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/crmCommon/salesParties/salesPartiesService/"
     sdoJava:package="oracle.apps.crmCommon.salesParties.salesPartiesService" xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/"
     xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/organizationService/"
     xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/personService/" xmlns:sdoJava="commonj.sdo/java"
     xmlns:sdoXML="commonj.sdo/xml" xmlns="http://xmlns.oracle.com/apps/crmCommon/salesParties/salesPartiesService/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:annotation>
        <xsd:documentation>Sales Party SDO</xsd:documentation>
    </xsd:annotation>
    <xsd:import namespace="http://xmlns.oracle.com/adf/svc/types/" schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/META-INF/wsdl/BC4JService.xsd"/>
    <xsd:import namespace="http://xmlns.oracle.com/apps/cdm/foundation/parties/organizationService/"
         schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/oracle/apps/cdm/foundation/parties/organizationService/OrganizationParty.xsd"/>
    <xsd:import namespace="http://xmlns.oracle.com/apps/cdm/foundation/parties/personService/"
         schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/oracle/apps/cdm/foundation/parties/personService/Person.xsd"/>
    <xsd:import namespace="commonj.sdo/java" schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/xml/sdoJava.xsd"/>
    <xsd:import namespace="commonj.sdo/xml" schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/xml/sdoXML.xsd"/>
    <xsd:include schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/oracle/apps/crmCommon/salesParties/salesPartiesService/SalesAccount.xsd"/>
    <xsd:include schemaLocation="https:// yourFCRMInstance:443/crmCommonSalesParties/SalesPartyService?XSD=/oracle/apps/crmCommon/salesParties/salesPartiesService/SalesAccountResource.xsd"/>
    <xsd:complexType name="SalesParty">
        <xsd:annotation>
            <xsd:appinfo source="http://xmlns.oracle.com/adf/svc/metadata/">
                <key xmlns="http://xmlns.oracle.com/adf/svc/metadata/">
                    <attribute>PartyId</attribute>
                    <attribute>SalesAccountId</attribute>
                </key>
            </xsd:appinfo>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element minOccurs="0" name="AccountDirectorId" type="xsd:long" sdoXML:dataType="sdoJava:LongObject"/>
            <xsd:element minOccurs="0" name="CpdrfLastUpd" nillable="true" type="xsd:string"/>
            <xsd:element minOccurs="0" name="CpdrfVerPillar" nillable="true" type="xsd:int"/>
            <xsd:element minOccurs="0" name="CpdrfVerSor" nillable="true" type="xsd:int"/>
            <xsd:element minOccurs="0" name="CreatedBy" type="xsd:string"/>
            <xsd:element minOccurs="0" name="CreationDate" type="ns0:dateTime-Timestamp"/>
            <xsd:element minOccurs="0" name="LastAssignedDate" nillable="true" type="ns0:date-Date"/>
            <xsd:element minOccurs="0" name="LastUpdateDate" type="ns0:dateTime-Timestamp"/>
            <xsd:element minOccurs="0" name="LastUpdateLogin" type="xsd:string"/>
            <xsd:element minOccurs="0" name="LastUpdatedBy" type="xsd:string"/>
            <xsd:element minOccurs="0" name="NamedAccountFlag" type="xsd:boolean" sdoXML:dataType="sdoJava:BooleanObject"/>
            <xsd:element minOccurs="0" name="ObjectVersionNumber" type="xsd:int" sdoXML:dataType="sdoJava:IntObject"/>
            <xsd:element minOccurs="0" name="SalesAccountPartyId" type="xsd:long" sdoXML:dataType="sdoJava:LongObject"/>
            <xsd:element minOccurs="0" name="ExistingFlag" nillable="true" type="xsd:boolean"/>
            <xsd:element minOccurs="0" name="ExistingFlgLastUpdDate" nillable="true" type="ns0:date-Date"/>
            <xsd:element minOccurs="0" name="UserLastUpdateDate" nillable="true" type="ns0:dateTime-Timestamp"/>
            <xsd:element minOccurs="0" name="AttributeCategory" nillable="true" type="xsd:string"/>
            <xsd:element minOccurs="0" name="PartyId" type="xsd:long" sdoXML:dataType="sdoJava:LongObject"/>
            <xsd:element minOccurs="0" name="ObjectVersionNumber1" type="xsd:int" sdoXML:dataType="sdoJava:IntObject"/>
            <xsd:element minOccurs="0" name="PartyName" type="xsd:string"/>
            <xsd:element minOccurs="0" name="PartyNumber" type="xsd:string"/>
            <xsd:element minOccurs="0" name="PartyType" type="xsd:string"/>
            <xsd:element minOccurs="0" name="Status" type="xsd:string"/>
            <xsd:element minOccurs="0" name="AssgnExceptionFlag" nillable="true" type="xsd:boolean"/>
            <xsd:element default="ZCA_SALES_PARTY" minOccurs="0" name="AttachmentEntityName" nillable="true"
                 type="xsd:string"/>
            <xsd:element minOccurs="0" name="PartyUniqueName" type="xsd:string"/>
            <xsd:element minOccurs="0" name="SalesAccountId" type="xsd:long" sdoXML:dataType="sdoJava:LongObject"/>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="OrganizationParty" type="ns1:OrganizationParty"/>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="SalesAccount" type="SalesAccount"/>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="SalesAccountResource" type="SalesAccountResource"/>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="PersonParty" type="ns2:Person"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:element name="salesParty" type="SalesParty"/>
</xsd:schema>
Task 7   Create the Java Web Service

This section explains creating the Java Web Service using the OutboundMessageService.wsdl file, as follows:

  1. In JDeveloper, right-click OutboundMessageservice.wsdl in the Application Developer pane and select Create Web Service.

  2. In the Select Deployment Platform dialog, select the Java EE 1.5, with support for JAX-WS Annotations radio button and click Next.

  3. In the Select Web Service Description dialog, select the Java radio button, check the Copy WSDL Locally check box, and verify that the folder location selected in the WSDL Location field is correct. JDeveloper fetches your WSDL file.

  4. In the Specify Default Mapping Options dialog, apply the security token oracle/wss_saml_or_username_token.

  5. In the Configure Policies dialog, select the OWSM Policies radio button, verify that the policy contents in the Policies section, and click Next.

  6. In the Provide Handler Details dialog, no fields need to be modified. Click Next. The Finish dialog appears, notifying you that you have finished creating your Java web service. Click Finish.

  7. In the Select Web Service Artifact Root dialog, make sure to select the folder where the web service artifacts will be stored. The web service is generated.

  8. After JDeveloper has generated your web service, verify that the WSDL file contains the correct IP address for your local machine in the JDeveloper interface.

Task 8   Add Functionality to the Web Service

You can add functionality to your Java web service by editing the OutboundMessageServiceImpl.java file. The following sample code provides an example of simple and useful added functionality:

System.out.println("OutboundMessageService ...");
               try {
                   System.out.println("Request PartyId = " + object.getPartyId());
                   } catch (Exception ex) {
                       ex.printStackTrace();
                   }
               System.out.println("Service Complete");
Task 9   Configure Security for the WebLogic Service

This section explains how to configure security for your instance of the WebLogic service. Configuration of security for the service is required because OWSM Policies were specified during the creation of the web service. The steps required to configure security settings are as follows:

  1. Login to the console for your instance of the WebLogic Service.

  2. Navigate in the Security Realms menu to myreal > Users and Groups.

  3. In the Users tab of the Settings for myrealm section, click New to add a new user name. This user name will be used to trigger the Oracle Sales Cloud object workflow.

  4. Assign a password for that user name and click OK. The Settings for myrealm section displays the information for each user that has been created for your security realm.

  5. Return to your JDeveloper interface and deploy the web service to your embedded WebLogic service instance.

Task 10   Configure Port Forwarding for Your Web Service

In some cases, port forwarding for your web service may be necessary. This section explains how to configure port forwarding, if necessary. In this scenario, Oracle Sales Cloud web service calls are running locally:

  1. Determine your current WAN IP address. You can download a third-party tool such as MyWANiP to perform this step.

  2. Login to your local router and configure port forwarding for HTTP traffic on port 7101 to your WAN IP address.

Task 11   Call a Web Service from a Oracle Sales Cloud Object Workflow

This section explains how to call a web service from a Oracle Sales Cloud Object Workflow. Oracle Sales Cloud will contact this endpoint: http://87.151.236.27:7101/FCRM_SecureOutboundSalesPartyApp-FCRM_SecureOutboundSalesParty-context-root/OutboundMessageServiceSoapHttpPort. Take note of your WAN IP for the web service.

  1. Launch Application Composer.

  2. Select Customer Center from the Application navigation pane

  3. Create an Object Workflow in the Customer Center application.

  4. In the Edit Object Workflow section, edit the Condition section to call the web service when the NamedAccountFlag value changes.

  5. In the Edit Action: Outbound Message dialog, edit the Endpoint URL field in the Outbound Message Details section and click Save.

  6. Check the embedded WebLogic service log in JDeveloper.