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:
Section 3.1, "Performing Common JDeveloper Configuration Steps"
Section 3.2, "Understanding Create, Read, Update, and Delete Operations"
Many of the sections summarize the operation or option and point to other chapters where the information is discussed in more depth.
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.
To configure an Oracle RightNow adapter for use an outbound service using JDeveloper:
In the File menu of JDeveloper, click New and select Application.
The New Gallery page is displayed. Select SOA Application from the Items list.
Provide a suitable name to your application.
Click Next and provide a suitable name to your project.
Figure 3-4 Providing a Name for Your Project
Click Next.
Select Composite with BPEL Process from Standard Composite
Click Finish.
Drag and drop the RightNow adapter component from the Components in JDeveloper to the references swimlane.
Click the RightNow adapter icon in the swimlane. The RightNow adapter Welcome screen appears.
Figure 3-6 Oracle RightNow Adapter Reference Screen
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
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.
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
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.
The following sections discuss the list of features supported by Oracle RightNow adapter.
The Oracle RightNow adapter supports CRUD, or Create, Read, Update, and Destroy Operations. The basic operations supported include the following:
Section 3.2.1.1.1, "Creating One or Multiple Business Objects"
Section 3.2.1.1.2, "Retrieving Data from One or Multiple Objects"
Section 3.2.1.1.3, "Updating One or Multiple Business Objects"
Section 3.2.1.1.4, "Deleting 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
In the following screenshot, one object, an Organization
object is created.
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.
Choose the Get operation from the list of Cloud Operations.
Use the arrow to move the Organization
object from the Available list to the Selected list.
Click Next.
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
.
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:
Select Update from the list of Cloud Operations.
Select one or more Business Objects from the Available list.
Use the arrows to move it to the Selected list.
Click Next.
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
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:
Choose the Destroy operation from the list of Cloud Operations.
Use the arrow to move the Organization, Contact and Incident objects from the Available list to the Selected list.
Click Next.
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
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.
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:
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
Provide connection details.
Figure 3-19 Oracle RightNow Adapter Configuration Wizard Connection Screen
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
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.
You can then select and add an operation in the batch operation.
Figure 3-21 RightNow Adapter Configuration Wizard Batch Add Operation Dialog
Once added, the operations appear listed with the appropriate business object.
Figure 3-22 RightNow Adapter Configuration Wizard Operation Options
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.
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.
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>
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.
Create a Contact
.
Create Incident
(the primary Contact
for this Incident is the one you created in the first step.)
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.
<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>
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.
In the Oracle XSLT mapper, load the Oracle RightNow adapter Reference/business Service request type as the target type.
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
Expand the Contact
object.
Right-click the ID element and select Substitute Element or Type from the popup.
The opens the Substitute Element or Type dialog. In the dialog, select ChainSourceID
.
Figure 3-25 Substitute Element or Type Dialog
This substitution extends the Contact ID type.
Set the variableName
property with a unique string (for example: MyContact
) that uniquely identifies this chain head.
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>
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
).
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).
Map other types as appropriate.
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:
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 |
---|---|
|
Used to indicate that external events should not run after the |
|
RightNow adapter-specific option. This property, which takes boolean values, indicates if an ID must be returned for a |
|
Used to indicate that business rules should not run after the |
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 |
---|---|
|
Used to indicate that external events should not run after the |
|
Used to indicate that business rules should not run after the |
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 |
---|---|
|
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 |
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 |
---|---|
|
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. |
|
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. |
The ROQL facility enables you to make queries against the RightNow Cx database.
This section includes the following information:
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.
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.
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.
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
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:
Section 3.3.4.1, "Simplifying the Discovery of Standard and Custom Business Objects"
Section 3.3.4.2, "Suggesting Query Constructs Based on the Context"
Section 3.3.4.4, "Providing Alias Support to Improve Readability"
Section 3.3.4.6, "Using the Query Builder to Obtain Inline and Semantic Validation"
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:
Select ROQL
as the Cloud API option on the Operation Configuration page.
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 optionClear 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
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
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:
When you enter Select in the ROQL Editor Text area and press Ctrl+Space, the Query Builder displays all standard and business objects.
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
The auto-completion feature facilitates building complex ROQL queries in a quick and efficient manner. To see this feature:
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.
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.
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.
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
.
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
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
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
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, as shown in Figure 3-38, "Semantic Validation in Query Builder".
Figure 3-38 Semantic Validation in Query Builder
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.
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.
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
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
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.
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
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
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
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.