3 Performing Operations Using the RightNow Cx Adapter

This chapter describes common configuration steps for the RightNow adapter using 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 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 a Oracle RightNow adapter project using JDeveloper. While you can use JDeveloper to configure a RightNow adapter and create a BPEL project, you can also configure the adapter for use with other service engines, such as Service Bus.

This section is referenced in other chapters in this Guide.

3.1.1 Configuring an Oracle RightNow Adapter Component

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

  1. In the File menu of JDeveloper, click New and select Application.

    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 Composite with BPEL Process from Standard Composite

    Figure 3-5 Configuring SOA Settings

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

  7. Click Finish.

  8. Drag and drop the RightNow adapter component from the Components in JDeveloper to the references swimlane.

  9. Click the RightNow adapter icon in the swimlane. The RightNow adapter Welcome screen appears.

    Figure 3-6 Oracle RightNow Adapter Reference Screen

    Description of Figure 3-6 follows
    Description of ''Figure 3-6 Oracle RightNow Adapter Reference Screen''

  10. On the RightNow Adapter Connection Screen, enter connection information to connect to Oracle RightNow Cx. This includes the WSDL URL, the name of the Authentication key, and options to run in Offline Configuration mode and to Clear Cache. You can leave options both unchecked, as needed.
    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''

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

    Figure 3-8 Test Connection

    Description of Figure 3-8 follows
    Description of ''Figure 3-8 Test Connection''

  12. 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 operations.

    • Any operation-specific configurations.

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

    • Configure Cloud Operation - This option is for working with a single operation.

    • Configure Multiple Operations in a Batch - Select this operation enables to work with multiple operations. This becomes unselected when you choose Configure Cloud Operation option.

      See the Operation Configuration screen, where you do the large part of your work related to selecting operations.

      Figure 3-9 Oracle RightNow Adapter Operation Configuration Screen

      Description of Figure 3-9 follows
      Description of ''Figure 3-9 Oracle RightNow Adapter Operation Configuration Screen''

3.2 Understanding Create, Read, Update, and Delete Operations

The operations available with the Oracle RightNow Adapter include basic 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.

In the following screenshot taken from the Oracle RightNow adapter Operation Configuration screen, Organization, Contact and Incident objects are all created as part of one request.

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

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

In the following screenshot, one object, an Organization object is created.

Figure 3-11 Creating One Object

Description of Figure 3-11 follows
Description of ''Figure 3-11 Creating One Object''

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.

In the following screenshot, you retrieve data from just Organization, by specifying the Get operation in Oracle RightNow adapter Cloud Operation Configuration screen and selecting the Organization object.

  1. Choose the Get operation from the list of Cloud Operations.

  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''

In the following screenshot, you use the Oracle RightNow adapter Cloud Operation Configuration screen to obtain data from multiple objects using one Get request and by selecting Organization, Contact and Incident.

Figure 3-13 Retrieving Multiple Objects

Description of Figure 3-13 follows
Description of ''Figure 3-13 Retrieving Multiple Objects''

3.2.1.1.3 Updating One or Multiple Business Objects

Use the Update operation to update any primary object and associated sub-objects. 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.

The following screenshot shows the Organization, Contact and Incident objects updated as part of a single Update request on the Oracle RightNow adapter Cloud Operation Configuration screen.

To perform an Update operation:

  1. Select Update from the list of Cloud Operations.

  2. Select one or more Business Objects from the Available list.

  3. Use the arrows to move it to the Selected list.

  4. Click Next.

Figure 3-14 Updating Multiple Objects with One Request

Description of Figure 3-14 follows
Description of ''Figure 3-14 Updating Multiple Objects with One Request''

The following screenshot shows Updating one object as part of a series of updates to three objects. In this example, the Organization object is updated.

Figure 3-15 Updating a Single Business Object

Description of Figure 3-15 follows
Description of ''Figure 3-15 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 Cloud Operation Configuration screen to delete Organization, Contact and Incident objects.

To delete multiple business objects:

  1. Choose the Destroy operation from the list of Cloud Operations.

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

  3. Click Next.

Figure 3-16 Deleting Multiple Objects

Description of Figure 3-16 follows
Description of ''Figure 3-16 Deleting Multiple Objects''

In the following screenshot, you use the Oracle RightNow adapter Cloud Operation Configurations screen to delete one business object.

Figure 3-17 Deleting One Business Object

Description of Figure 3-17 follows
Description of ''Figure 3-17 Deleting One Business Object''

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 Configure batch operation option from the Oracle RightNow adapter configuration wizard 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.

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 reference name. See Figure 3-18, "Oracle RightNow Adapter Configuration Wizard Reference Screen"

    Figure 3-18 Oracle RightNow Adapter Configuration Wizard Reference Screen

    Description of Figure 3-18 follows
    Description of ''Figure 3-18 Oracle RightNow Adapter Configuration Wizard Reference Screen''

  2. Provide connection details.

    Figure 3-19 Oracle RightNow Adapter Configuration Wizard Connection Screen

    Description of Figure 3-19 follows
    Description of ''Figure 3-19 Oracle RightNow Adapter Configuration Wizard Connection Screen''

  3. In the Cloud Operation Configuration page, select the option to configure a batch operation.

    Figure 3-20 RightNow Adapter Configuration Wizard Operation Page with Batch Selected

    Description of Figure 3-20 follows
    Description of ''Figure 3-20 RightNow Adapter Configuration Wizard Operation Page with Batch Selected''

  4. Selecting this option enables you to configure multiple operations in a batch. Select the Add operation icon, the plus sign. The adapter displays the Add an Operation dialog.

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

    Figure 3-21 RightNow Adapter Configuration Wizard Batch Add Operation Dialog

    Description of Figure 3-21 follows
    Description of ''Figure 3-21 RightNow Adapter Configuration Wizard Batch Add Operation Dialog''

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

    Figure 3-22 RightNow Adapter Configuration Wizard Operation Options

    Description of Figure 3-22 follows
    Description of ''Figure 3-22 RightNow Adapter Configuration Wizard Operation Options''

  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.

    Figure 3-23 Add Operation Dialog

    Description of Figure 3-23 follows
    Description of ''Figure 3-23 Add Operation Dialog''

  8. Select Next to complete the adapter wizard. The confirmation dialog will display 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 PortType 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 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, "Integration Response Payload":

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-24 Choosing a Substitute Element or Type in the XSLT Mapper

    Description of Figure 3-24 follows
    Description of ''Figure 3-24 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-25 Substitute Element or Type Dialog

    Description of Figure 3-25 follows
    Description of ''Figure 3-25 Substitute Element or Type Dialog''

    This substitution extends the Contact ID type.

    Figure 3-26 Contact ID Type Expanded

    Description of Figure 3-26 follows
    Description of ''Figure 3-26 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 Table 3-1, "CreateProcessing Options".

Table 3-1 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-2 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-3 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-4 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 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, a query editor opens. Type 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 will not be focusing 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 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. See Figure 3-27, "Sample ROQL Query" for an example.

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 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.3 Running the Query Test Tool

The Query Test tool helps to run and test the query. When you click the Test icon, a test dialogue box appears.

The Query Test dialogue 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

  • Refresh Bind Parameters. Use this button to refresh the Bind Parameters box, if you have made any change in the number of bind parameters in the query statement.

  • Execute Query. Use this button to execute the query.

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

See Figure 3-28, "Query Test Screen, with Specific Areas Highlighted", which highlights the areas of the screen.

Figure 3-28 Query Test Screen, with Specific Areas Highlighted

Description of Figure 3-28 follows
Description of ''Figure 3-28 Query Test Screen, with Specific Areas Highlighted''

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 Cloud API option on the Operation Configuration page.

  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 as shown in Figure 3-29, "Displaying 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.

    Figure 3-29 Displaying a List of Standard and Custom Objects Available on Oracle RightNow Cx

    Description of Figure 3-29 follows
    Description of ''Figure 3-29 Displaying a List of Standard and Custom Objects Available on Oracle RightNow Cx''

  3. Alternatively, you can provide a specific package to display all custom objects created in that package as shown in Figure 3-30, "Providing a Package to Display All Custom Objects Created in That Package".

    Figure 3-30 Providing a Package to Display All Custom Objects Created in That Package

    Description of Figure 3-30 follows
    Description of ''Figure 3-30 Providing a 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 Editor 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.

    Figure 3-31 Query in Context, Showing List of Fields in Contact Object

    Description of Figure 3-31 follows
    Description of ''Figure 3-31 Query in Context, Showing List of Fields in Contact Object''

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.

    Figure 3-32 Query Auto-Completion

    Description of Figure 3-32 follows
    Description of ''Figure 3-32 Query Auto-Completion''

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.

    Figure 3-34 Alias Support with All Relationships Displayed

    Description of Figure 3-34 follows
    Description of ''Figure 3-34 Alias Support with All Relationships 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.

    Figure 3-35 Alias Support Showing All Fields Associated with ServiceCategory Displayed

    Description of Figure 3-35 follows
    Description of ''Figure 3-35 Alias Support Showing All Fields Associated with ServiceCategory 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, as shown in Figure 3-36, "Suggesting Relationships Example".

Figure 3-36 Suggesting Relationships Example

Description of Figure 3-36 follows
Description of ''Figure 3-36 Suggesting Relationships Example''

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.

Figure 3-37 Query Validation Example

Description of Figure 3-37 follows
Description of ''Figure 3-37 Query Validation Example''

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, as shown in Figure 3-38, "Semantic Validation in Query Builder".

Figure 3-38 Semantic Validation in Query Builder

Description of Figure 3-38 follows
Description of ''Figure 3-38 Semantic Validation in Query Builder''

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.

This language is the RightNow Object Query Language (ROQL, pronounced "Rockwell"). The query language is based on a subset of 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. Hence, 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-39 Query Inputs in the Form of Bind Parameters

Description of Figure 3-39 follows
Description of ''Figure 3-39 Query Inputs in the Form of Bind Parameters''

See the following query example shown for the Oracle RightNow adapter user interface. The ampersand & symbol prefixed to contact_name and contact_address indicates that the ampersand is a bind parameter.

Figure 3-40 Query Example using BInd Parameters

Description of Figure 3-40 follows
Description of ''Figure 3-40 Query Example using BInd Parameters ''

You can run the Run Query Test tool to see how a query such as this works with bind parameters by clicking the Run Query Test Tool button on the right.

Figure 3-41 Running a Query Test

Description of Figure 3-41 follows
Description of ''Figure 3-41 Running a Query Test''

As shown above, the Run Query Test tool prompts you to provide a value for the bind parameter, here &contact_name and &contact_address.

Figure 3-42 Run Query Test Tool Prompting for Bind Parameters

Description of Figure 3-42 follows
Description of ''Figure 3-42 Run Query Test Tool Prompting for Bind Parameters''

After providing an appropriate value to the bind parameter and clicking the Execute Query button, you can view the result set for that particular query.

Figure 3-43 Query Test Tool Query Result, Using Bind Parameters

Description of Figure 3-43 follows
Description of ''Figure 3-43 Query Test Tool Query Result, Using Bind Parameters''

The WSDL generated for this particular Adapter query contains the bind parameter as part of input schema.

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

Description of Figure 3-44 follows
Description of ''Figure 3-44 Part of Generated Input Schema for WSDL Showing Bind Parameter''

The jca file generated for this particular Adapter query is:

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.