Understanding Create, Read, Update, and Delete Operations

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.

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 Operations screen and selecting the Organization object.

Choose the Get operation from the Select an Operation Type list.
Use the arrow to move the Organization object from the Available list to the Selected list.
Click Next.

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 . 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 Operation screen.

To perform an Update operation:

Select Update from the Select an Operation Type list.
Select one or more business objects from the Available list.
Use the arrows to move the business objects to the Selected list.
Click Next.

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

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:

Choose the Destroy operation from the Select an Operation Type list.
Use the arrow to move the Organization, Contact and Incident objects from the Available list to the Selected list.
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:

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.
Provide connection details.

Description of the illustration rightnow_connection.png
In the Operations page, select the Batch Operation option to configure a batch operation.
Selecting this option enables you to configure multiple operations in a batch.
You can then select and add an operation in the batch operation.
Once added, the operations appear listed with the appropriate business object.
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 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.

Note:

When configuring the Oracle RightNow Cloud Adapter in the outbound direction, do not select the Commit After processing option if you are using chaining. For information about configuring the outbound direction, see Oracle RightNow Adapter User Interface Support for Batching.

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

Create a Contact.
Create an 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 Example 3-4, 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 Example 3-5 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.

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

Description of "Figure 3-6 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.
This opens the Substitute Element or Type dialog. In the dialog, select ChainSourceID.

Figure 3-7 Substitute Element or Type Dialog

Description of "Figure 3-7 Substitute Element or Type Dialog"

This substitution extends the Contact ID type.

Figure 3-8 Contact ID Type Expanded

Description of "Figure 3-8 Contact ID Type Expanded"

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.

3.2.2 Supported Processing Options

Use processing options to enable and disable certain aspects of server-side processing when performing 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.

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.