3 Walkthrough of the Oracle RightNow Adapter Configuration Wizard

This chapter describes common configuration steps for the Oracle RightNow adapter using Oracle JDeveloper, various operations available with the adapter that are related to create, read, update and delete, features available with those operations, and use of the RightNow Object Query Language (ROQL) query language.

The chapter includes the following sections:

Many of the sections summarize the operation or option and point to other chapters where the information is discussed in more depth.

3.1 Performing Common JDeveloper Configuration Steps

This section provides a summary of the common configuration steps for beginning an Oracle RightNow adapter project using Oracle JDeveloper. While you can use Oracle JDeveloper to configure an Oracle RightNow adapter and create a BPEL project, you can also configure the adapter for use with other service engines, such as Oracle Service Bus.

3.1.1 Create SOA Application Project in JDeveloper

To configure an Oracle RightNow adapter for use as an outbound or inbound service using Oracle JDeveloper, first create the SOA application project.

  1. Click New and select Application from the File menu of Oracle JDeveloper.

    Figure 3-1 Navigation

    Description of Figure 3-1 follows
    Description of "Figure 3-1 Navigation"

  2. The New Gallery page is displayed. Select SOA Application from the Items list.

    Figure 3-2 Create SOA Application

    Description of Figure 3-2 follows
    Description of "Figure 3-2 Create SOA Application"

  3. Provide a suitable name to your application.

    Figure 3-3 Name Your Application

    Description of Figure 3-3 follows
    Description of "Figure 3-3 Name Your Application"

  4. Click Next and provide a suitable name to your project.

    Figure 3-4 Providing a Name for Your Project

    Description of Figure 3-4 follows
    Description of "Figure 3-4 Providing a Name for Your Project"

  5. Click Next.

  6. Select Standard Composite.

  7. Select Composite with BPEL Process.

    Figure 3-5 Configuring SOA Settings

    Description of Figure 3-5 follows
    Description of "Figure 3-5 Configuring SOA Settings "

  8. Click Finish.

3.1.2 Configuring an Oracle RightNow Adapter for Outbound Services

To configure an Oracle RightNow adapter for use as an outbound service using Oracle JDeveloper:

  1. Drag and drop the Oracle RightNow adapter component from the Components list in Oracle JDeveloper to the references swimlane.

  2. Click the RightNow adapter icon in the swimlane. The Basic Info screen appears.

  3. Enter a meaningful name for the Oracle RightNow adapter and an optional description.

    Figure 3-6 Oracle RightNow Adapter Basic Info Screen

    Description of Figure 3-6 follows
    Description of "Figure 3-6 Oracle RightNow Adapter Basic Info Screen"

  4. On the RightNow Cloud adapter Connection screen, enter connection information to connect to Oracle RightNow Cx. This includes the WSDL URL, the security policy, and the name of the authentication key.
    You can obtain the WSDL and the authentication key from your RightNow administrator.

    Figure 3-7 Oracle RightNow Adapter Connection Screen

    Description of Figure 3-7 follows
    Description of "Figure 3-7 Oracle RightNow Adapter Connection Screen"

  5. You are provided with an option to test the connection in the initial screen itself to validate the credentials. To test the connection, select the Test option.

  6. Next, the RightNow adapter configuration wizard displays additional information for you to select:

    • The operation you want to perform.

    • The objects against which you perform the operation.

    • Any operation-specific configurations.

    At this point, you can indicate to either perform single CRUD operations or perform operations in a batch:

3.1.3 Configuring an Oracle RightNow Adapter for Inbound Services

To configure an Oracle RightNow adapter for use as an outbound or inbound service using Oracle JDeveloper, first create the SOA application project.

  1. Drag and drop the Oracle RightNow adapter component from the Components in Oracle JDeveloper to the Exposed Services swimlane.

  2. Click the Oracle RightNow adapter icon in the swimlane. The Oracle RightNow adapter Basic Info screen appears.

    Figure 3-9 Oracle RightNow Adapter Basic Info Screen

    Description of Figure 3-9 follows
    Description of "Figure 3-9 Oracle RightNow Adapter Basic Info Screen "

  3. Enter basic information to connect to the Oracle RightNow adapter.

    Table 3-1 RightNow Configuration Wizard

    Configure Example/Information

    What do you want to call your connection?

    Enter a meaningful name.

    What does your connection do?

    Enter a description.

    Figure 3-10 Oracle RightNow Connection Screen

    Description of Figure 3-10 follows
    Description of "Figure 3-10 Oracle RightNow Connection Screen"

    Table 3-2 Connection Page

    Configure Example/Information

    WSDL URL


    Obtain the WSDL from your RightNow administrator.

    Security Policy

    Select a policy.

    Authentication Key


    You can obtain the authentication key from your RightNow administrator.

  4. Test the connection to validate the credentials by clicking Test.

  5. Select the business object that you want to receive from Oracle RightNow Cx as a request document to start this integration, then select Next.

    Description of 5request.PNG follows
    Description of the illustration 5request.PNG

  6. Select a response type and optional business object for the response.

    • Deselect the Send checkbox if a response is not required. This action disables the list of business objects from being selected.

    • Select Immediate, then select a business object that you want the integration to send as a response document to Oracle RightNow Cx. You can also optionally select Also Send Faults to send faults if they are encountered by the integration.

      Note:

      The Response list includes an option called Delayed. This option does not work and should not be selected.

    Description of 6response.PNG follows
    Description of the illustration 6response.PNG

  7. Click Next.

    The Summary page is displayed.

  8. Click Finish.

3.2 Understanding Create, Read, Update, and Delete Operations

The operations available with the Oracle RightNow adapter include create, read, update, and delete, or CRUD operations.

The CRUD operations enable the creation, reading, updating and deleting of objects contained in the Oracle RightNow Cx system.

All CRUD operations behave in a polymorphic manner as defined in the Polymorphic Behavior section. Therefore, any CRUD operation can accept as input parameters 1 to N heterogeneous primary objects, which means a mix of object types can be supplied to any CRUD operation in a single request.

For example, a Contact, Incident, and Organization object can be supplied to a single invocation of the Create method.

There is a hard limit of 1000 objects that may be supplied in a single CRUD request – however, due to operational constraints, supplying the maximum objects might result in an error.

The return value of Create and Get (Read) is a list containing 1 to N RNObjects. The size of the list will match the size of the list provided in the operation request. The Update and Destroy methods do not return a value upon success. If a CRUD operation fails, a SOAP fault is returned to the client.

However, the Create operation returns the ID of the created business object if you have disabled suppressResponse but the Get operation returns the entire business object.

When a client of Oracle Cloud Connect Web Services for SOAP invokes a Create operation, an object or list of objects will be returned. If you require the rest of the data associated with the object, a Get operation must be performed.

The Create operation can be performed directly on all primary objects.

When a client of the Oracle Cloud Connect Web Services invokes a Get operation, an object or list of objects is returned.

The Destroy operation destroys primary objects and sub-objects.

3.2.1 Supported Features

The following sections discuss the list of features supported by Oracle RightNow adapter.

3.2.1.1 Using CRUD Operations

The Oracle RightNow adapter supports CRUD, or create, read, update, and destroy operations. The basic operations supported include the following:

3.2.1.1.1 Creating One or Multiple Business Objects

You create one or multiple business objects (standard or custom) on RightNow Cx using the Oracle RightNow adapter. For example, you create Organization, Contact and Incident objects all as part of a single request or as three independent requests.

For example, on the Operation screen, you can select the Organization, Contact, and Incident objects as part of one request.

Figure 3-11 Creating Organization, Contact, and Incident Objects in One Request

Description of Figure 3-11 follows
Description of "Figure 3-11 Creating Organization, Contact, and Incident Objects in One Request"

3.2.1.1.2 Retrieving Data from One or Multiple Objects

You can retrieve data either from one or multiple objects available on the RightNow CX cloud platform using the Oracle RightNow adapter. For example, you can use the Oracle RightNow adapter to retrieve data just related to just organizations or the information could be a combination of organizations, contacts and incidents in one request.

For example, you can retrieve data from just Organization, by specifying the Get operation in Oracle RightNow adapter Operations screen and selecting the Organization object.

  1. Choose the Get operation from the Select an Operation Type list.

  2. Use the arrow to move the Organization object from the Available list to the Selected list.

  3. Click Next.

Figure 3-12 Retrieving Data from One Object

Description of Figure 3-12 follows
Description of "Figure 3-12 Retrieving Data from One Object"

3.2.1.1.3 Updating One or Multiple Business Objects

Use the Update operation to update any primary object and associated subobjects. You can update one or multiple business objects (standard or custom) on the RightNow CX cloud platform using the Oracle RightNow adapter. For example, you can update Organization, Contact and Incident objects as part of a single request or as three independent requests.

For example, you can update the Organization, Contact and Incident objects as part of a single Update request on the Oracle RightNow adapter Operation screen.

To perform an Update operation:

  1. Select Update from the Select an Operation Type list.

  2. Select one or more business objects from the Available list.

  3. Use the arrows to move the business objects to the Selected list.

  4. Click Next.

You can update one object as part of a series of updates to three objects.

Figure 3-13 Updating a Single Business Object

Description of Figure 3-13 follows
Description of "Figure 3-13 Updating a Single Business Object "

3.2.1.1.4 Deleting one or Multiple Business Objects

You can delete one or multiple business objects (standard or custom) on the RightNow Cx cloud platform using the Oracle RightNow adapter. For example, you can delete Organization, Contact and Incident objects all as part of a single request or as three independent requests.

In the following screenshot, you use the Oracle RightNow adapter Operation screen to delete Organization, Contact and Incident objects.

To delete multiple business objects:

  1. Choose the Destroy operation from the Select an Operation Type list.

  2. Use the arrow to move the Organization, Contact and Incident objects from the Available list to the Selected list.

  3. Click Next.

3.2.1.2 Using the Batching Feature

Batching is a unique feature of the Oracle RightNow adapter that enables one or more heterogeneous operations to be sent to RightNow Cx server through a single operation. This feature enables the integration developer to update an existing organization, create a contact for an existing organization, delete a note for an existing incident, or create a new incident. Using batching, all these instructions can be consolidated and sent to Oracle RightNow Cx server as a single operation The Oracle RightNow adapter extends this capability by providing the necessary tooling to configure batch operations and batching options.

The adapter also provides an integration-friendly interface for batch operations and processing options. You can select the Batch Operation option to configure this option.

Other features of batching include:

  • Each operation in a batch has separate processing options. The adapter configuration wizard provides a graphical and intuitive way for users to configure the processing options.

  • Operations within a batch are normally executed in a single transaction, but these operations can be grouped into different units of work using the commitAfter property. This property groups multiple operations in a single transaction. At runtime, when a set of operations in a batch are defined as part of a single operation, this action is sent after the last operation in that transaction boundary.

3.2.1.2.1 Oracle RightNow Adapter User Interface Support for Batching

Batching is a unique feature of the Oracle RightNow adapter that allows one or more operations to be sent to Oracle RightNow Cx through a single operation.

The Oracle RightNow adapter extends batching capability by providing the necessary tooling to configure batch operations and batching options. It also provides an integration-friendly interface for batch operations and processing options.

The following section describes how you can use the adapter configuration wizard to model the Oracle RightNow adapter for batch operations:

  1. In a SOA project or a service bus project, drag and drop the Oracle RightNow adapter from Components to the composite swim lane. Provide a valid connection name. See Section 3.2.1.2.1, "Oracle RightNow Adapter Configuration Wizard Basic Info Screen."

    Figure 3-14 Oracle RightNow Adapter Configuration Wizard Basic Info Screen

    Description of Figure 3-14 follows
    Description of "Figure 3-14 Oracle RightNow Adapter Configuration Wizard Basic Info Screen"

  2. Provide connection details.

    Figure 3-15 Oracle RightNow Adapter Connection Screen

    Description of Figure 3-15 follows
    Description of "Figure 3-15 Oracle RightNow Adapter Connection Screen"

  3. In the Operations page, select the Batch Operation option to configure a batch operation.

    Figure 3-16 RightNow Adapter Configuration Wizard Operations Screen with the Batch Operation

    Description of Figure 3-16 follows
    Description of "Figure 3-16 RightNow Adapter Configuration Wizard Operations Screen with the Batch Operation"

  4. Selecting this option enables you to configure multiple operations in a batch.

  5. You can then select and add an operation in the batch operation.

  6. Once added, the operations appear listed with the appropriate business object.

  7. Each operation in a batch process has separate processing options that can be specified in the Properties tab. For example, the Add Operation has three properties you can specify: Suppress External Events, Suppress Rules, and Commit After.

  8. Select Next to complete the adapter wizard. The confirmation dialog shows the generated artifacts.

Operations within a batch are normally executed in a single transaction; however, these operations can be grouped into separate units of work using the commitAfter property.

3.2.1.2.2 Batch Process WSDL

The following examples represent different parts of a sample WSDL from a batch process. The first example shows the port type and operation defined within the integration WSDL for the batch operation:

Example 3-1 PortType and Operation

<wsdl:portType name="rightnowReferencePortType">
        <wsdl:operation name="Batch">
            <cloud:CloudOperation xmlns:cloud="http://xml.oracle.com/types" targetOperation="Batch"/>
            <wsdl:input message="ns0:BatchRequestMessage"/>
            <wsdl:output message="ns0:BatchResponseMessage"/>
            <wsdl:fault name="ServerErrorFault" 
                     message="ns0:ServerErrorFault"/>
            <wsdl:fault name="RequestErrorFault" 
                     message="ns0:RequestErrorFault"/>
            <wsdl:fault name="UnexpectedErrorFault" message="ns0:UnexpectedErrorFault"/>
        </wsdl:operation>
</wsdl:portType>

The second example shows the input message type defined in the Integration WSDL Batch operation.

Example 3-2 Input Message Type Defined in Integration WSDL Batch Operation:

<xs:element name="Batch" type="ns2:BatchRequestType"/>
<xs:complexType name="BatchRequestType">
                <xs:sequence>
                    <xs:element name="Create" 
                             type="ns2:CreateRequestType"/>
                    <xs:element name="Update" 
                            type="ns2:UpdateRequestType"/>
                    <xs:element name="Get"
                            type="ns2:GetRequestType"/>
      </xs:sequence>
</xs:complexType>
 
<xs:complexType name="CreateRequestType">
        <xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" type="ns7:Account" name="Account"/>
</xs:sequence>
</xs:complexType>

The next example shows the output message type defined in the integration WSDL Batch operation.

Example 3-3 Output Message Type Defined in Integration WSDL Batch Operation:

<xs:element name="BatchResponse" type="ns2:BatchResponseType"/>
    <xs:complexType name="BatchResponseType">
     <xs:sequence>
        <xs:element name="Create" type="ns2:CreateResponseType"/>
      <xs:element name="Update" type="ns2:UpdateResponseType"/>
      <xs:element name="Get" type="ns2:GetResponseType"/>
     </xs:sequence>
</xs:complexType>
 
<xs:complexType name="CreateResponseType">
    <xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0"
                        type="ns7:Account" name="Account"/>
      <xs:element name="RequestErrorFault" maxOccurs="1"
                 minOccurs="0" 
                   type="ns9:RequestErrorFaultType"/>
      <xs:element name="UnexpectedErrorFault" 
                maxOccurs="1" minOccurs="0" 
                type="ns9:UnexpectedErrorFaultType"/>
      <xs:element name="ServerErrorFault"
                 maxOccurs="1" minOccurs="0" 
                 type="ns9:ServerErrorFaultType"/>
    </xs:sequence>
</xs:complexType>

3.2.1.3 Chaining

Chaining is an Oracle RightNow adapter feature that you can use to correlate multiple operations within a single batch request. Specifically, you use chaining together with batching to execute related operations. For operations to be chained together, the source and target operations of a chain must be in the same unit of work.

For example, the following request has three operations which are all part of the same sample batch request.

  1. Create a Contact.

  2. Create an Incident (the primary Contact for this Incident is the one you created in the first step).

  3. Get the Incident (you must return the Incident just created).

Using the attributes highlighted in the example in Section 3.2.1.3, "XML for Chaining," provide a look at how this is accomplished in code.

Example 3-4 XML for Chaining

  <Batch
xmlns="http://xmlns.oracle.com/pcbpel/adapter/
             rightnow/RNDemo01/RNBatchDemo01/rightnowReference"
xmlns:rna_v1_2="urn:metadata.ws.rightnow.com/v1_2" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:rnm_v1_2="urn:messages.ws.rightnow.com/v1_2" 
    xmlns:rnn_v1_2="urn:nullfields.ws.rightnow.com/v1_2"
    xmlns:rnf_v1_2="urn:faults.ws.rightnow.com/v1_2" xmlns:ns1="urn:base.ws.rightnow.com/v1_2"
    xmlns:rno_v1_2="urn:objects.ws.rightnow.com/v1_2" xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype"
    xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:rng_v1_2="urn:generic.ws.rightnow.com/v1_2"
         xmlns:rnw_v1_2="urn:wsdl.ws.rightnow.com/v1_2"
   xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/
        rightnow/RNDemo01/RNBatchDemo01/rightnowReference"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tns:CreateContact>
        <tns:Contact>
            <ns1:ID xsi:type="ns1:ChainSourceID"
                         variableName="MyContact" />
            <rno_v1_2:Name>
                <rno_v1_2:First>John</rno_v1_2:First>
                <rno_v1_2:Last>Doe</rno_v1_2:Last>
            </rno_v1_2:Name>
        </tns:Contact>
    </tns:CreateContact>
    <tns:CreateIncident>
        <tns:Incident>
            <ns1:ID xsi:type="ns1:ChainSourceID" 
                       variableName="MyIncident" />
            <rno_v1_2:PrimaryContact>
                <rno_v1_2:Contact>
                    <ns1:ID xsi:type="ns1:ChainDestinationID" variableName="MyContact" />
                </rno_v1_2:Contact>
            </rno_v1_2:PrimaryContact>
            <rno_v1_2:Subject>This is a test subject.
                         </rno_v1_2:Subject>
        </tns:Incident>
    </tns:CreateIncident>
    <tns:GetIncident>
        <tns:Incident>
            <ns1:ID xsi:type="ns1:ChainDestinationID" 
                      variableName="MyIncident" />
        </tns:Incident>
    </tns:GetIncident>
</Batch>

There are request and response payloads associated with Section 3.2.1.3, "Integration Request Payload" provides an example of an integration request payload.

Example 3-5 Integration Request Payload

<Batch
   xmlns="http://xmlns.oracle.com/pcbpel/adapter/
     rightnow/RNDemo01/RNBatchDemo01/rightnowReference"
    xmlns:rna_v1_2="urn:metadata.ws.rightnow.com/v1_2" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:rnm_v1_2="urn:messages.ws.rightnow.com/v1_2" 
             xmlns:rnn_v1_2="urn:nullfields.ws.rightnow.com/v1_2"
    xmlns:rnf_v1_2="urn:faults.ws.rightnow.com/v1_2" xmlns:ns1="urn:base.ws.rightnow.com/v1_2"
    xmlns:rno_v1_2="urn:objects.ws.rightnow.com/v1_2" xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype"
    xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:rng_v1_2="urn:generic.ws.rightnow.com/v1_2" xmlns:rnw_v1_2="urn:wsdl.ws.rightnow.com/v1_2"
    xmlns:tns="http://xmlns.oracle.com/pcbpel/
        adapter/rightnow/RNDemo01/RNBatchDemo01/rightnowReference"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tns:CreateContact>
        <tns:Contact>
            <ns1:ID xsi:type="ns1:ChainSourceID" variableName="MyContact" />
            <rno_v1_2:Name>
                <rno_v1_2:First>John</rno_v1_2:First>
                <rno_v1_2:Last>Doe</rno_v1_2:Last>
            </rno_v1_2:Name>
        </tns:Contact>
    </tns:CreateContact>
    <tns:CreateIncident>
        <tns:Incident>
            <ns1:ID xsi:type="ns1:ChainSourceID" 
                               variableName="MyIncident" />
            <rno_v1_2:PrimaryContact>
                <rno_v1_2:Contact>
                    <ns1:ID xsi:type="ns1:ChainDestinationID" variableName="MyContact" />
                </rno_v1_2:Contact>
            </rno_v1_2:PrimaryContact>
            <rno_v1_2:Subject>This is a test 
                              subject.</rno_v1_2:Subject>
        </tns:Incident>
    </tns:CreateIncident>
    <tns:GetIncident>
        <tns:Incident>
            <ns1:ID xsi:type="ns1:ChainDestinationID" 
                          variableName="MyIncident" />
        </tns:Incident>
    </tns:GetIncident>
</Batch>

The response payload is shown in Example 3-6:

Example 3-6 Integration Response Payload

<itns:BatchResponse xmlns:n0=
                  "urn:messages.ws.rightnow.com/v1_2"
    xmlns:n2="urn:base.ws.rightnow.com/v1_2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:n1="urn:objects.ws.rightnow.com/v1_2" xmlns:itns="urn:oracle.cloud.adapter.rightnow/1214">
    <itns:Create>
 
        <itns:Contact>
            <n2:ID id="1903" />
        </itns:Contact>
    </itns:Create>
    <itns:Create>
 
        <itns:Incident>
            <n2:ID id="455" />
        </itns:Incident>
    </itns:Create>
    <itns:Get>
 
        <itns:Incident>
            <n2:ID id="455" />
            <n2:LookupName>140623-000003</n2:LookupName>
            <n2:CreatedTime>2014-06-23T14:44:03.000Z</n2:CreatedTime>
            <n2:UpdatedTime>2014-06-23T14:44:03.000Z</n2:UpdatedTime>
            <n1:CreatedByAccount>
                <n2:ID id="2" />
            </n1:CreatedByAccount>
            <n1:InitialResponseDueTime>2014-06-24T00:00:00.000Z
            </n1:InitialResponseDueTime>
            <n1:Interface>
                <n2:ID id="1" />
            </n1:Interface>
            <n1:Language>
                <n2:ID id="1" />
            </n1:Language>
            <n1:PrimaryContact>
                <n1:Contact>
                    <n2:ID id="1903" />
                </n1:Contact>
            </n1:PrimaryContact>
            <n1:Queue>
                <n2:ID id="2" />
            </n1:Queue>
            <n1:ReferenceNumber>140623-000003</n1:ReferenceNumber>
            <n1:Source>
                <n2:ID id="6006" />
                <n2:Parents xsi:type="n2:NamedReadOnlyID">
                    <n2:ID id="32007" />
                </n2:Parents>
            </n1:Source>
            <n1:StatusWithType>
                <n1:Status>
                    <n2:ID id="1" />
                </n1:Status>
                <n1:StatusType>
                    <n2:ID id="1" />
                </n1:StatusType>
            </n1:StatusWithType>
            <n1:Subject>This is a test subject.</n1:Subject>
        </itns:Incident>
    </itns:Get>
</itns:BatchResponse>

3.2.1.4 Using Chaining

Chaining is always used together with batching and does not require any extra step in the Oracle RightNow adapter batch configuration wizard.

However, to use chaining, you must link the right chain source and destination in the adapter request, as illustrated in the sample request above.

The following steps illustrate how you can achieve chaining during transformation with the Oracle XSLT mapper.

  1. In the Oracle XSLT Mapper, load the Oracle RightNow adapter reference/business service request type as the target type.

  2. When creating a contact object which must be chained to a different object example, Incident), substitute the Contact ID with the extension ChainSourceID.

    Figure 3-17 Choosing a Substitute Element or Type in the XSLT Mapper

    Description of Figure 3-17 follows
    Description of "Figure 3-17 Choosing a Substitute Element or Type in the XSLT Mapper"

  3. Expand the Contact object.

  4. Right-click the ID element and select Substitute Element or Type from the popup.

  5. The opens the Substitute Element or Type dialog. In the dialog, select ChainSourceID.

    Figure 3-18 Substitute Element or Type Dialog

    Description of Figure 3-18 follows
    Description of "Figure 3-18 Substitute Element or Type Dialog"

    This substitution extends the Contact ID type.

    Figure 3-19 Contact ID Type Expanded

    Description of Figure 3-19 follows
    Description of "Figure 3-19 Contact ID Type Expanded"

    Set the variableName property with a unique string (for example: MyContact) that uniquely identifies this chain head.

  6. During the Create Incident operation, set the following: in the PrimaryContact field of Incident, set the ChainDestinationID so the Incident is created for the Contact as they are Chained.

    In other words, ChainDestinationID of MyContact is set on the PrimaryContact field.

    <rno_v1_2:PrimaryContact>
                                <rno_v1_2:Contact>
                        <ns1:ID xsi:type="ns1:ChainDestinationID" 
           variableName="{string ('MyContact' )}"/>
                </rno_v1_2:Contact>
</rno_v1_2:PrimaryContact>

  7. Similarly, to create Incident and subsequently perform a Get on this incident, substitute the Incident ID with the chainSourceID. Set the variableName property with a unique string (example: MyIncident).

  8. Next, in the Get operation, substitute the Incident ID with the extension ChainDestinationID and set the variableName property to the variable name of the chainSourceID (that is, MyIncident).

  9. Map other types as appropriate.

3.2.2 Supported Processing Options

Use processing options to enable and disable certain aspects of server-side processing when performing a a RightNow cloud operation. Processing options are created and supplied to the various WSDL operations that use processing options. Following is a list of all supported processing options, along with their usage and default values. This section includes the following subsections:

3.2.2.1 CreateProcessingOptions

You can use CreateProcessingOptions together with the Create operation, by specifying them on the Create Properties Tab. CreateProcessingOptions contain properties listed in Section 3.2.2.1, "CreateProcessing Options."

Table 3-3 CreateProcessing Options

Field Description

SuppressExternalEvents

Used to indicate that external events should not run after the Create operation completes. The default value is language specific, refer to your documentation and generated client code for more information on the default value.

SuppressResponse

RightNow adapter-specific option. This property, which takes boolean values, indicates if an ID must be returned for a Create operation.

SuppressRules

Used to indicate that business rules should not run after the Create operation completes. Refer to your documentation and generated client code for more information on the default value

3.2.2.2 DestroyProcessingOptions

You can use DestroyProcessiongOptions together with the Delete operation, by specifying them on the Delete Operation Properties tab. DestroyProcessingOptions contain the following properties.

Table 3-4 Destroy Processing Options

Field Description

SuppressExternalEvents

Used to indicate that external events should not run after the Destroy operation completes. Refer to your documentation and generated client code for more information on the default value.

SuppressRules

Used to indicate that business rules should not run after the Destroy operation completes. Refer to your documentation and generated client code for more information on the default value

3.2.2.3 GetProcessingOptions

You can use GetProcessiongOptions together with the Get operation by specifying them on the Get Operation Properties Tab. GetProcessingOptions contain the following properties.

Table 3-5 GetProcessing Options

Field Description

FetchAllNames

Signals to the server that all NamedID types should include both the Name and the ID for that field. Note the use of this if very inefficient and should only be used when all Name and ID fields are required. If all Name and ID fields are not require, this option should not be used, for more information, see the Get operation

3.2.2.4 UpdateProcessingOptions

You can use UpdateProcessingOptions together with the Update operation by specifying them on the Update Operation Properties Tab. UpdateProcessingOptions contain the following properties:

Table 3-6 UpdateProcessingOptions

Field Description

SuppressExternalEvents

Used to indicate that external events should not run after the Update operation completes. The default value is language specific, refer to your language documentation and generated client code for more information on the default value.

SuppressRules

Used to indicate that business rules should not run after the Update operation completes. The default value is language specific, refer to your language documentation and generated client code for more information on the default value.

3.3 Working with ROQL

The RightNow Object Query Language (ROQL) facility enables you to make queries against the RightNow Cx database.

This section includes the following information:

3.3.1 Using ROQL

If you select the ROQL operation category on the Operations screen, a field for entering an ROQL query is displayed. Enter the ROQL statement depending on the operation you selected.

ROQL enables you to search your organization's RightNow Cx data for specific information.

This chapter does not focus on discussing ROQL at length. Refer to Oracle Service Cloud Connect Web Services for SOAP.

3.3.1.1 ROQL Query Statement

The ROQL query statement queries data from Oracle RightNow Cx. The Query statement text box consists of ROQL statements according to Oracle RightNow CX.

Refer to the section on ROQL Operations for more information on the query operation. For detailed information on ROQL, see the Oracle RightNow Connect Web Services for SOAP Developer's Guide and navigate to the ROQL section.

3.3.2 ROQL Query Statement

Use the ROQL query statement to query data from RightNow Cx. The Query statement text box consists of ROQL statements according to RightNow Cx. Refer to the section in ROQL Operations for additional information on query operations. For detailed information on ROQL, see the Oracle RightNow Connect Web Services for SOAP Developer's Guide and navigate to the ROQL section.

3.3.3 Running the ROQL Query Statement

You can run and test the query. When you click the Test icon, a test dialogue box appears.

The Query Test dialog that appears contains the following areas:

  • Query Statement and Results. The Query Statement text box is for the query itself and the Results box shows the result of the query executed. If the query has one or more bind parameters in it, one or more input boxes will appear to provide values for these

  • Parameter Bindings. Enter values for any parameter bindings that appear in the query statement.

  • Test My Query. Click to execute the query.

  • Results. After the successful execution of the query, the text area is filled with results from RightNow Cx.

See Figure 3-20, which highlights the areas of the screen.

Figure 3-20 Query Test Screen

Description of Figure 3-20 follows
Description of "Figure 3-20 Query Test Screen"

3.3.4 Using the ROQL Query Builder

This section discusses how to use the ROQL query builder. The ROQL query builder addresses several areas that are often problematic for the integration developer.

This approach helps you in writing complex, error-free queries with greater ease. To accomplish writing such queries, the ROQL Query Builder provides the following features, described in these subsections:

3.3.4.1 Simplifying the Discovery of Standard and Custom Business Objects

The ROQL Query Builder identifies for you potential standard and custom objects that you can use in constructing the queries. To see an example of this feature:

  1. Select ROQL as the operation type on the Operations screen.

  2. Enter Select in the ROQL Editor Text area and enter Ctrl+Space. The Query Builder displays a list of standard and custom objects available on Oracle RightNow Cx.

    Note:

    If the custom objects you create do not appear in the list of objects shown in the operations page, check the option Clear Cache in the connection page, then connect again to obtain the latest metadata from the RightNow Cx system.

  3. Alternatively, you can provide a specific package to display all custom objects created in that package.

3.3.4.2 Suggesting Query Constructs Based on the Context

ROQL Query Builder automatically identifies the context, based on the position of the cursor, for the query string. Using this context, the Query Builder provides recommendations, enabling you to write efficient ROQL queries. This feature operates in the following manner:

  1. When you enter Select in the ROQL query text area and press Ctrl+Space, the Query Builder displays all standard and business objects.

  2. Similarly, if you perform the query Select Contact from Contact where and enter Ctrl+Space after the where clause, you are provided with the list of fields of the Contact object that you can use in fine-tuning the query, and applicable keywords and functions.

3.3.4.3 Providing Auto-Completion

The auto-completion feature facilitates building complex ROQL queries in a quick and efficient manner. To see this feature:

  1. Using the query string Select Se, if you perform Ctrl+Space after the term, Se, the Query Builder displays all objects that start with Se.

3.3.4.4 Providing Alias Support to Improve Readability

The ROQL Query Builder features support for aliasing. It recognizes when aliasing of the RightNow Object (Base class for all primary objects in the Oracle RightNow adapter) is being queried and treats the alias name as the actual object name.

All operations associated with the object can then be performed on the alias.

  1. In the query string Select from ServiceCategory S where, S is set as an alias for object ServiceCategory. Thus, you can perform all operations associated with ServiceCategory on the alias 'S'. Some of the operations you can perform on the alias include the following.

  2. If you perform Ctrl+Space between Select and from in the query above, the query builder will display S, suggesting that the S should come in between Select and From, as shown here - Select S from ServiceCategory S where.

  3. If you enter a dot after the first S, all relationships associated with Service Category are displayed.

  4. Similarly in this query, Select S from ServiceCategory S where S, if you enter a dot after the last S, all fields associated with ServiceCategory will be displayed.

3.3.4.5 Using ROQL to Suggest Relationships

ROQL has support for the relationship feature. With this feature you can reach from one primary object to other primary objects through a relationship.

The ROQL Query Builder identifies and lists all reachable relationships from the identified object. It can list relationships of relationships.

For more details see Oracle RightNow Connect Web Services for SOAP Developer's Guide

If you must find the parent organization of a particular Contact, enter Select Contact in the ROQL text area and enter "." which displays all relationships possible on the Contact object.

3.3.4.6 Using the Query Builder to Obtain Inline and Semantic Validation

The Query Builder has a built-in inline validator that highlights problematic text by drawing a red curved line underneath it and also provides suggestions to correct the error in a tooltip message.

The Query Builder validator performs spelling checks on keywords, object names, relationship names, field names and names of functions. All the keywords that are typed correctly will automatically be colored blue, indicating the validity of these keywords.

The ROQL Query builder also has support for semantic validation of the query. It can recognize that the specified relationship or field name is invalid for the currently selected object.

3.3.5 Adapter Support for ROQL

The Oracle RightNow adapter provides a query subsystem that enables you to perform SQL-like queries against the RightNow CX platform using the object query language.

The ROQL query language is based on a subset of the Object Query Language (OQL) and a SQL-like query language that has been extended to handle object notation.

ROQL currently supports only the Query Objects Feature and not Query CS.

3.3.5.1 Query Arguments

Using the following query as an example:

Use query arguments to fine-tune queries. Therefore, in the above example, Lin and CA are query arguments.

Select Contact from Contact where Contact.Name.First = 'Lin' AND Contact.Address.City = 'CA'

Query parameters are a unique concept through you can parameterize the query arguments, which the adapter substitutes with actual values during query execution.

Much like SQL, the query language has a provision to fine-tune the search by passing in filters in the WHERE clause. This fine-tuning is made possible by use of the concept of bind parameters.

3.3.5.2 Support for Bind Parameters

The Oracle RightNow adapter provides you an option to give inputs to your query statement in the form of bind parameters.

Figure 3-21 Query Inputs in the Form of Bind Parameters

Description of Figure 3-21 follows
Description of "Figure 3-21 Query Inputs in the Form of Bind Parameters"

See the following query example for the Oracle RightNow adapter. The ampersand & symbol prefixed to orgid indicates that the ampersand is a bind parameter.

Figure 3-22 Query Example using Bind Parameters

Description of Figure 3-22 follows
Description of "Figure 3-22 Query Example using Bind Parameters "

You can run the query to see how it works with bind parameters by clicking Test My Query.

Figure 3-23 ROQL Query Results

Description of Figure 3-23 follows
Description of "Figure 3-23 ROQL Query Results"

As shown above, the query prompts you to provide a value for the bind parameter.

The WSDL generated for an adapter query contains the bind parameter as part of input schema.

Figure 3-24 Part of Generated Input Schema for WSDL Showing Bind Parameter

Description of Figure 3-24 follows
Description of "Figure 3-24 Part of Generated Input Schema for WSDL Showing Bind Parameter"

The JCA file generated for an adapter query can look as follows:

Example 3-7 JCA File Generated when Bind Parameters are Used in Query

<adapter-config name="rightnowReferencePortType" adapter="rightnow" wsdlLocation="../WSDLs/rightnowReference.wsdl" xmlns="http://platform.integration.oracle/blocks
          /adapter/fw/metadata">
                 <connection-factory location=
                         "cloud/CloudAdapter">
    <non-managed-connection managedConnectionFactoryClassName="oracle.cloud.connector.
                            rightnow.
              RightNowConnectionFactory">
      <property name="targetWSDLURL" 
                           value="../WSDLs/soap.wsdl"/>
      <property name="csfkey" value="csf21"/>
      <property name="appID" 
                  value=
                "removeWhenAppIdIsHardcodedByRNPlugin"/>
      <property name="applicationVersion" value="1_2"/>
    </non-managed-connection>
  </connection-factory>
  <endpoint-interaction
                      portType="rightnowReferencePortType" 
                             operation="Get">
    <interaction-spec className="oracle.tip.adapter.cloud.
                          CloudInteractionSpec">
      <property name="targetOperation" value="Get"/>
      <property name="operationPath" value="Get"/>
      <property name="gpo.fetchAllNames" value="false"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

Once queries are parameterized, the Oracle RightNow adapter enables its consumers to pass in the query parameters as part of the request payload.

The adapter dynamically substitutes the query parameter from the request payload to reconstruct the ROQL query with arguments during service invocation.

Thus, by using the adapter to easily define query parameters, you can parameterize query arguments and dynamically inject these parameters at runtime.