4 Understanding RightNow Adapter Advanced Concepts

This chapter describes the design-time and runtime advanced capabilities of the Oracle RightNow Cloud adapter.

This chapter contains information on the following features:

4.1 Understanding the SOAP API

The Oracle RightNow adapter requires a connection to enable you to perform operations on business objects. In addition to operations on business objects, the RightNow API model also includes a definition of the types of transactions used when the Oracle RightNow adapter communicates with RightNow Cx.

4.1.1 Understanding Objects

There are two types of objects upon which the Oracle RightNow adapter enables you to perform actions:

  • Standard business objects. These are objects delivered by the Oracle RightNow SaaS application. Primary objects are objects with a unique ID (primary key) which can be directly created, read, updated, and deleted. All primary objects inherit from the RightNow RNObject. Primary objects have no set lifecycle in the Oracle RightNow Cx platform, meaning that once the objects are created, they exist in the system until they are deleted. While primary objects have their own life cycle, sub objects that could be anywhere between 0 to many for a single primary object, live within the context of primary objects. Hence, their life cycle is based on the life cycle of the primary object. The exact lifecycle behavior for objects can be obtained from the relationship information contained in the metadata or in the object model documentation.

  • Custom business objects. A custom business object is an object that has been created by a customer. It can be modeled after any standard object, or it can be entirely unique. When created, custom objects are treated and act just like standard, primary objects. The only difference between the standard objects and custom objects is in the name of the object that is used. For the primary objects, you can use the name of the class such as 'Contact'. For custom objects, you can use the combination of the package name and custom object name to uniquely identify the custom object. The package name and object name are joined by a '.'. For example, if there was a custom object package called 'CO' and a custom object named PurchasedProduct you would reference this object as CO$PurchasedProduct.

4.1.2 Understanding Transactions

The RightNow adapter supports the message exchange patterns supported by RightNow SaaS application. It is a synchronous request - response based message exchange pattern. The BPEL / OSB application makes a synchronous request to RightNow adapter and waits for a response. The adapter in turn does the necessary transformation on the same thread before making a synchronous request to RightNow Cx Server using the RightNow SOAP API.

The response returned by RightNow application after necessary processing is in turn received by the calling thread. The adapter performs the transformation before sending the response back to BPEL / OSB based client application.

Every operation that writes to RightNow Cx object, such as create or update is, by default, committed. Batch Operation does enable the integration developer to override the default. Refer to the section on Batch Support for more information.

4.2 Handling the Polymorphic Behavior of Oracle RightNow Cx Schema

Oracle Cloud Connect Web Services for SOAP defines a number of operations which either accept or return one or more instances of RNObject (which is the Base class for all primary RightNow object classes).

This feature enables the same operations to behave in a polymorphic manner, in which the input and return values can be any instance of a derived class of RNObject.

This feature accomplishes this behavior by passing in subclass instances from program language bindings, and also through the use of the xsi:type attribute in the serialized XML for the object. The xsi:type specifies the concrete type that is being substituted in the element with the type RNObject.This behavior enables developers working with Oracle Cloud Connect Web Services for SOAP to work with any type of object that inherits from the base class, RNObject and to pass this object into any operation that expects an instance of RNObject. In addition, developers can cast returned instances of RNObject to the appropriate subclass.For more information on polymorphic behavior, see Oracle Service Cloud Connect Web Services for SOAP.

Due to this polymorphic nature, mapping from source object to target object user experience is somewhat complex for standard objects that inherit RNObject. For custom objects and custom attributes, it is more complex.

The Oracle RightNow adapter elevates the element definitions as first-class citizens for standard objects, custom objects and custom fields, reducing the number of steps you must perform to create complex transformations and simplifying your experience mapping source to target definitions.

4.2.1 Example: Mapping A Custom Object

Following is a sample of a mapping experience of a custom object with and without Oracle RightNow adapter. The example might not be typical, but it helps you understand the mapping experience and the differences between doing so with and without the Oracle RightNow adapter.

One example shows mapping an Oracle RightNow custom object without using an Oracle RightNow adapter. The second example shows the same mapping, the difference being that the second example is greatly simplified; the adapter simplifies the process.

4.2.1.1 Example: Mapping an Object without Using an Oracle RightNow Adapter

This section provides information about creating a custom object instance without using the Oracle RightNow adapter. In this scenario, you create a SOA Composite and use the Web Service adapter to create a client for RightNow Service.The steps follow that are required when you create a data mapping using XSLT mapper from a client source schema to a custom object schema.

See Figure 4-1, "Using XSLT Mapper to Map a RightNow Custom Object for the Schema without Using the Oracle RightNow Adapter-Generated WSDL".

  1. In the XSLT editor, on the target schema node RNObject, right-click and select Substitution Type or Element then choose Generic Object.

  2. Set Object ObjectType->TypeName : Value of the RightNow CustomObject Name created in RightNow

  3. Set GenericFields->dataType: Data type value of the custom attribute. for example, STRING, or INTEGER

  4. Set GenericFields->name: name of the custom attribute.

  5. Set GenericFields->DataValute->StringValue : Value of the attribute

Figure 4-1 Using XSLT Mapper to Map a RightNow Custom Object for the Schema without Using the Oracle RightNow Adapter-Generated WSDL

Description of Figure 4-1 follows
Description of ''Figure 4-1 Using XSLT Mapper to Map a RightNow Custom Object for the Schema without Using the Oracle RightNow Adapter-Generated WSDL''

The source view is:

Figure 4-2 Sample XSL File in Source Mode

Description of Figure 4-2 follows
Description of ''Figure 4-2 Sample XSL File in Source Mode''

4.2.1.2 Example: Mapping an Object with the Oracle RightNow Adapter

This section provides information about creating a custom object instance with the Oracle RightNow adapter. You create a SOA Composite and use the Web Service adapter to create a client for an integration-friendly Oracle RightNow adapter-generated WSDL.

Use the following steps to create the data mapping using the XSLT mapper from a client source schema to a custom object schema (the schema is strongly typed and referred from the integration-friendly WSDL generated by the Oracle RightNow adapter). The custom object is a first class entity in generated Local WSDL Map the fields directly in the mapper as shown below.

4.3 Integrating with Custom Objects in the Cloud

A custom object is an object that has been created by a customer. It can be modeled after any standard object, or it can be entirely unique.It can either be a standalone object or it can be the child of an existing standard object.

4.3.1 Creating Custom Objects in the RightNow Cx Server

Follow these instructions to create custom objects in the RightNow Cx server.

  1. Login to the Oracle RightNow Cx client, and follow instructions in Section 4.6.2.1, "Configuring Restricted Access Permissions on RightNow Cx".

  2. Click Configuration on the navigation pane.

  3. Double-click Object Designer under Database. The object designer opens on the content pane.

  4. Select a package to which you want to add the custom object, or create a new package for the object by clicking New on the ribbon and selecting Package. Enter the name you want for the package. Package names must be between two and eleven characters in length.

  5. Click New on the ribbon and select Object. The Object Summary page displays.

    Figure 4-3 Object Summary Page

    Description of Figure 4-3 follows
    Description of ''Figure 4-3 Object Summary Page''

  6. Enter a name for the object in the Name field.

  7. Click Fields on the ribbon to add predefined or customized fields to the object and add custom fields. For additional information, see the Oracle RightNow Connect Web Services for SOAP documentation.

  8. Click the Save and Close button on the ribbon to save changes to the custom object. RightNow performs a validation when either the Save or Save and Close buttons are clicked. Any validation errors, such as a missing field name, display in a message and must be corrected before the object can be saved.

  9. Deploy the custom objects when you are ready.

4.3.2 Selecting Custom Objects to Perform Operations

Once a custom object has been created, you can select the object against which to perform operations.

  1. Figure 4-4 Selecting a Custom Object to Perform Operations

    Description of Figure 4-4 follows
    Description of ''Figure 4-4 Selecting a Custom Object to Perform Operations''

    Once you select the custom object, an Integration-friendly WSDL is generated with custom object schema in strongly typed format. A non-normative sample of the generated custom object schema is shown in Figure 4-5, "Example of a Custom Object Schema".

    Figure 4-5 Example of a Custom Object Schema

    Description of Figure 4-5 follows
    Description of ''Figure 4-5 Example of a Custom Object Schema''

4.4 About the Clear Cache User Interface Check Box Option

To minimize the number of calls to Oracle RightNow Cx for fetching metadata, the adapter maintains a cache where all metadata information is stored for future reference.

However, if any modification is done to objects on Oracle RightNow Cx, and the change must be reflected in the Oracle RightNow adapter, the clear cache option in the user interface deletes the old cache and fetches the latest metadata from Oracle RightNow Cx server.

4.5 About the Offline Mode User Interface Check Box Option

This option enables you to configure the Oracle RightNow adapter in offline mode. As soon as you select the offline configuration check box, the configuration wizard makes a call to Oracle RightNow Cx to fetch metadata information about the Oracle RightNow Cx objects. This is stored in the cache which is used when subsequent a adapter instance is created.This feature helps reduce the Oracle RightNow adapter operation calls an adapter would make use of the cache rather than the live Oracle RightNow adapter call. In this mode, the adapter does not support test functionalities which requires a direct call to Oracle RightNow Cx server.

Uncheck the Offline Mode check box to resume working in online mode.

4.5.1 Behaviors Expected When Using Offline Mode

Although the Offline Mode has numerous advantages, limitations include:

  • You are not able to run the Query Test tool if the Offline Configuration check box is checked. In that case, if you click the Query Test tool button, a warning message is displayed that Query Test is not available in Offline mode.

  • You will also not be aware of any new custom objects /custom attributes added by the organization while in offline mode. You must uncheck the Offline Configuration check box and either check the Clear cache or Offline configuration checkboxes to fetch the latest metadata.

4.6 Understanding Oracle RightNow Adapter Security Management

The Oracle RightNow adapter uses the Credentials Store Framework to store credentials captured during the configuration of connections within the Oracle RightNow adapter configuration wizard. This ensures that the credentials captured during configuration are stored in secured form and are not stored with the SOA Composite or Oracle Service Bus flow.

Currently, the CSF_KEY and the associated credentials are not automatically migrated to the WebLogic server domain in which the composites will be deployed for runtime execution.

Hence, the integration developer or administrator is expected to create and configure the CSF key using the Fusion Middleware Control console. For information on how to configure the CSF key, see Appendix A, "Credential Store Configuration for Managing RightNow Credentials".

At runtime, the adapter automatically retrieves the credentials from the Credentials Store Framework based on the CSF_KEY that was specified during design time. These credentials are injected into the SOAP header of the document that is sent to the RightNow Cx Server for authentication.

4.6.1 Authenticating on the Oracle RightNow Cx Server with Account Passwords

The following section provides information about authenticating on the Oracle RightNow Cx Server with account passwords. This section includes:

4.6.1.1 Understanding Access Control on the Oracle RightNow CX Server

When the Oracle Cloud Connect Web Services for SOAP API receives a request, a series of access control measures are enforced:

  1. The site configuration is checked to ensure the API has been enabled at a site level.

  2. The user credentials supplied in the request are validated.

  3. The profile for the supplied account is checked to ensure the correct profile bit is enabled. The profile is the mechanism for controlling access to administrative functions and for assigning staff members specific permissions, default workspaces, a default navigation set, and report access.

    Note:

    Server-side access control is enforced on all core API calls made by Oracle Cloud Connect Web Services for SOAP. The current permissions map to read, edit, delete, and move check boxes on the Profile Permissions editor in Oracle RightNow. Although server-side access is enabled by default on new May 2013 sites and later, it is disabled on upgraded sites before the May 2013 release. If you are an existing Oracle RightNow customer and plan to upgrade your site to a May 2013 or later build, contact customer care to have this security-enhancing functionality enabled.

    If you already have server-side access control enabled on your site, be careful of changes you make to Profile permissions. If an Oracle RightNow administrator changes the permissions on a profile for an Oracle Cloud Connect Web Services for SOAP integration, they might break that integration.

4.6.2 Oracle Cloud Connect Web Services for SOAP Site Configuration

Access to the Oracle Cloud Connect Web Services for SOAP is available only on those sites that have it enabled. If Oracle Cloud Connect Web Services for SOAP is not enabled, contact your Oracle account manager, as the API will not function and a request error will be returned.

Request errors are generated any time there is a validation failure or a data related error of the inbound request.The exception code will be ACCESS_DENIED and the message will be the message base string for SOAP_SERVER_DISABLED.

For complete information on request errors and exception codes, see Oracle Connect Web Services for SOAP.

Before staff accounts can be authenticated through Oracle RightNow Cx, their profile(s) must be updated on the Profile Permissions editor in Oracle RightNow Cx. The permissions check boxes are located at Staff Management > Profiles > Permissions.

Figure 4-6 Location of Permissions Checkboxes

Description of Figure 4-6 follows
Description of ''Figure 4-6 Location of Permissions Checkboxes ''

In addition, RightNow Cx administrators can restrict access to Oracle Cloud Connect Web Services for SOAP integrations by IP address using the configuration settings in the Oracle RightNow Cx platform. The following setting is located at Site Configuration > Configuration Setting

  • SEC_PAPI_INTEG_HOSTS_SOAP: Defines which hosts are allowed to access the SOAP interface. Valid entries include a comma-separated list of domain names with wildcards, specific IP addresses, or IP subnet masks (for example, *.rightnow.com,1.2.3.4, 10.11.12.0/255.255.255.0).

    Only users logging in from hosts matching entries in this list are allowed access to the SOAP interface. The default is blank.

4.6.2.1 Configuring Restricted Access Permissions on RightNow Cx

To configure restricted access permissions:

  1. Install the Oracle RightNow Cx client.

  2. Login to the Oracle RightNow Cx client installed on your workstation. You can immediately begin configuring and customizing the application.

    To access the same site in the future, you can launch the client by selecting Start menu > All Programs > RightNow > RightNow (<site_name>). The client application is site-based, meaning that a separate client must be deployed for each site you access.

    However, a single client application can be used to access all interfaces on a single site. Interfaces are added to the client in the same way the client is deployed.

    Access the interface's Launch page and click the Install Oracle RightNow CX Cloud Service button (as described in the Oracle RightNow Cx User's Guide), and the deployment tool adds the interface to the Interface drop-down menu on the client's Login window.

  3. Configure the SEC_PAPI_INTEG_HOSTS_SOAP setting. Refer to the Oracle RightNow Cx User's Guide.

4.6.3 Validating Account Credentials

When a request is sent to the API and the site configuration has been validated, the next step is to validate the account credentials. If the credentials do not verify, a request error is returned. The exception code will be INVALID_LOGIN, and the message will be the message base string LOGIN_ID_PASSWD_COMBINATION_INV_MSG.

4.6.4 Profile Configuration

The profile for the staff account which is used in the security header must have the Public SOAP API profile bit enabled. If this bit is not enabled, a request error is returned. The exception code will be ACCESS_DENIED, and the message will be the message base string PROFILE_NO_SOAP_ACCESS_MSG.

4.6.5 Password-based Authentication

Oracle Cloud Connect Web Service for SOAP utilizes Web Services Policy 1.2 is defined by http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf for client authentication.

The supporting XSD for the security policy is located at http://schemas.xmlsoap.org/ws/2004/09/policy/ws-policy.xsd

To authenticate with single sign-on, refer to Authenticating with SAML 2.0.

The WS-Security specification calls for a Security tag in the SOAP Header with a namespace of

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd.

Inside the Security tag is a UsernameToken tag (part of the WS-Security UsernameToken Profile 1.0 specification). The UsernameToken tag contains elements for Username, Password, Nonce, and Created. The Password element has a Type attribute which specifies if the content of the Password element is PasswordText. Oracle Cloud Connect Web Services for SOAP does not support PasswordDigest.

The Nonce and Created elements are not supported. If a request is received that contains the PasswordDigest type or the Created/Nonce elements, the server rejects the request as a malformed request.

The following is an example SOAP request with username and password credentials:

Example 4-1 Example SOAP Request with Username and Password Credentials

 soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004
             /01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                   soapenv:mustUnderstand="1">
            <wsse:UsernameToken
                xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                  oasis-200401-wss-wssecurity-utility-1.0.xsd" 
                      wsu:Id="UsernameToken-3902281">
                <wsse:Username>comland</wsse:Username>
                <wsse:Password Type=
                     "http://docs.oasis-open.org/wss/2004
                      /01/oasis-200401-wss-username-token-profile-1.0
                       #PasswordText">Connect1</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
</soapenv:Envelope>

4.7 Oracle RightNow Adapter Test Functionality

Test functionality is a distinctive feature of the Oracle RightNow adapter that is available in two forms.

One form enables you to test the connection parameters. The second form enables you to validate and execute a ROQL query.

The section below provides more information about these two features.

4.7.1 Design-Time Test Functionality Details

Design-time test functionality includes the following test functionalities:

  • Test Right Now CX Cloud Connection: There is a Test Connection button on Connection Configuration page of the Oracle RightNow adapter configuration wizard.

    By clicking on the Test Connection button you receive either of the following messages:

    • Success! - For successful connection

    • Failure! - For any exception during login

  • Query Test Tool: This tool helps to run and test your queries. When you click the Test icon on the Operation Configuration page of the Oracle RightNow adapter configuration wizard, a test dialogue box appears with a Query Statement text box and a Results box showing the query result,.

4.8 Oracle RightNow Adapter Limit and Restriction Handling

The following limits and restrictions apply to this adapter. They include:

4.8.1 Delete-Cascading Delete Effect

There is a cascading delete effect when using Oracle RightNow adapter for a Destroy Delete operation.

Primary objects are deleted directly through the Delete operation. To destroy a primary object, an instance of the object must be instantiated and the ID property set, but no other fields require population. When a primary object is deleted, this operation may also ”cascade” to related primary objects.

For additional information on cascading delete effects, and a summary of aggregations that will cause a cascading delete effect, see the Oracle RightNow Connect Web Services for SOAP Developer Guide.

4.8.2 API Limits Enforced by the RightNow Cx Server

While usage of Oracle Cloud Connect Web Services for SOAP is unlimited, there are practical limits which are enforced by the RightNow Cx server.

There are two important limits relevant to the use of the Oracle RightNow adapter:

  • 100 Batch items per SOAP request. The Batch operation enforces a hard limit of 100 items. If this limit is exceeded, a fault is returned before completing any operations. If the limit is exceeded, batch items are not processed.

  • Each individual Create, Get, Update, and Destroy operation is limited to 1000 items. RightNow Cx server checks the number of items in the request at the beginning and if the number of items is more than 1000, or if the number of items causes the combined summation of items to exceed the request maximum, RightNow Cx server throws an exception and does not process the request.

  • 10,000 total input objects per SOAP request. The combination of the multi-object Create, Get, Update and Destroy operations and the Batch operation is limited to 10,000 total input objects per SOAP request. RightNow Cx keeps a running total of objects which is managed by Create, Get, Update, and Destroy operations. Each time one of the bulk operations occurs, the number of items is added to the total number of objects processed in the request.

    The processing of the Batch operations will occur until the limit of 10,000 objects is reached. Once reached, the operation causing the 10,000 limit will be terminated and a fault returned. Operations contained within the Batch request that do not contain input objects will continue to execute.

    These three limits (100, 1000, 10000) are treated independently. Some operations affect both the bulk limits and the total operation limits (for example, Create, Get, Update, and Destroy).

For additional information, see the see the Oracle RightNow Connect Web Services for SOAP Developer Guide.