Operations represent specific calls that your client applications invoke to perform specific tasks on the RightNow CX platform, for example:
The Connect Web Service for SOAP API defines a number of operations which either accept or return one or more instances of RNObject. This allows these operations to behave in a polymorphic manner in which the input and return values can actually be any instance of a derived class of RNObject. This behavior is accomplished by passing in subclass instances from program language bindings and 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 allows developers working with the Connect Web Services for SOAP API to work with any type of object that inherits from RNObject and 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 an example code snippet or XML that demonstrates using polymorphic behavior see the examples for the Create operation.
CRUD operations allow for the creation, reading, updating and deleting of objects contained in the 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, meaning a mix of object types can be supplied to any CRUD operation in a single request. For example, a Contact, Incident and Organization can all 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, it is possible supplying the maximum objects may result in an error. The number of items that may safely be sent in a single CRUD operation request will need to be weighed against the object complexity and size of data. In cases where too much data is supplied in a single request the server may fail to complete the transaction and the client will receive an unexpected exception from the SOAP toolkit (this may not be a SOAP Fault returned from the server).
The return value of Create and Get(read) is a list containing 1 to N RNObject’s, 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 were to fail a SOAP fault would be returned to the client.
All items supplied to a CRUD operation are treated as one transaction. Therefore, if any one object in the request cannot be processed, the entire request is rolled back and none of the data is committed. If there is need for different transactional behavior, Batching can be used as other ways to effectively provide commit operations when desired.
Many of the object fields are defined such that they are not required on Create or Update operations. This allows developers to only send in the required information when creating or updating object data. A number of these same optional fields are also nillable, meaning their values can be set to null. In some toolkits, particularly .NET, the handling of the optional field which is also nillable is not done correctly. To support the toolkits that do not work with optional fields which are nillable we have included null field classes for all objects which have optional fields which are also nullable. For clients developing integrations using one of those toolkits these objects must be used to signify to the RightNow server which fields should be set to null. For more information please see the NullFields documentation.
Due to the various types of objects and relationships in the RightNow CRM system each type of object has its own defined lifecycle. For more detail on the types of objects and the relationships please see Object Model Introduction. The following is a description of CRUD operations for RightNow objects which support CRUD operations.
When a client of the API invokes a Create operation an object or list of objects will be returned, however only the ID attribute will be set on this object. If clients require the rest of the data associated with the object a Get operation must be performed. Please see the Create operation for sample code and XML to create an object.
The Create operation can be preformed directly on all primary objects. Fields which are 'Available' on Create may be set on the primary object that is being created, 'Required' fields must be supplied. For more details on the available and required fields please refer to the object model documentation for the primary object you are creating.
The Create operation cannot be performed directly on sub-objects. To perform a create of a sub-object, the operation must be performed "in-line" with a Create or Update operation on a primary object. For example, when creating a Contact and a new Note needs to be created and added to the Contact, the developer must provide a Note object inside the NoteList associated with the Contact object. This will cause a Note to be created in the RightNow system and associated with the Contact object.
The Create operation can be used to set NamedID (and variants) values when the fields are 'Available' on Create. The NamedID fields can be set either by ID or by name, if both are supplied ID is used in favor of the name. It is important to note that it is not possible to create or update the referenced objects using the NamedID field. For example, you cannot create or update a Product while updating an Incident by using the Incident.Product NamedIDHierarchy.
When a client of the API invokes a Get operation an object or list of objects will be returned, however the attributes which are populated will vary based on the client request. Please see the Get operation documentation for sample code and XML to get object data.
The Get operation can be performed directly on primary objects. A primary object is obtained by instantiating an instance of the type of object and setting the ID property. Any other data that is specified on the object will be ignored and will result in inefficiencies when using the Get operation. When a primary object contains a relationship to another primary object, only the ID for the related primary object will be returned by the Get operation. All direct properties of the object will be populated when performing a Get operation.
Sub-objects are only returned when specifically requested in the Get operation. The list of sub-objects is supplied in line with the primary object. This is done by instantiating a new instance of the sub-object and assigning it to the member variable of the primary object. In cases where a sub-object contains another sub-object this secondary sub-object can be obtained through the same manner as first level sub-objects.
By default all NamedID, NamedIDDeltaList, NamedIDList and NamedIDHierarchyList fields are returned for a get operation; however, only the ID properties of the objects will be returned. To obtain the name string values of these objects clients must create instances of NamedID, NamedIDDeltaList, NamedIDList or NamedIDHierarchyList and send these in the request, doing so will cause the server to return both the ID and name string values. For NamedIDHierarchyList fields, both the name and the parent fields will be populated, the parent path includes only the ancestors, and not the leaf value that is in the name field. The order of the ancestor names is from root to the parent of the object.
The Update operation is used to update any primary object and associated sub-objects. Please see the Update operation documentation for sample code and XML to update object data.
Primary objects are updated directly through the Update operation. When updating a primary object the request is only required to set the field values for those fields requiring an update, this is the driving force behind every property in the schema being set to optional and nillable.
Sub-objects are updated in the same manner in which they are created, updates must be performed "in-line" with the primary object. Only the fields of the sub-object which require updates must be populated in the sub-object. The Update operation should also be used to destroy sub-objects when the primary object does not need to be destroyed.
The Update operation can be used to set NamedID (and variants) values when the fields are 'Available' on update. The NamedID fields can be updated either by ID or by name, if both are supplied ID is used in favor of the name. It is important to note that it is not possible to create or update the referenced objects using the NamedID field. For example, you cannot create or update a Product while updating an Incident by using the Incident.Product NamedIDHierarchy.
The Destroy operation is used to destroy primary objects and sub-objects. Please see the Destroy operation documentation for sample code and XML to destroy object data.
Primary objects are deleted directly through the Destory operation. To destroy a primary object an instance of the object must be instantiated and the ID property set, no other fields require population. When a primary object is deleted, this operation may also “cascade” to related primary objects. For instance, if an Organization is deleted, all Contact records associated with that Organization are also deleted. The deletion behavior is defined by the relationship type in the metadata. If the defined relationship behavior is not a cascading delete, the relationship fields in any child objects will be cleared out when a parent object is deleted. For example, if an Account is deleted, the AssignedAccount field in any incidents that were assigned to that account will be set to null.
The following is a list of aggregations that will cause a cascading delete:
| Object | Related Object |
|---|---|
| Contact | Incident |
| Contact | Task |
| Organization | Contact |
| Organization | Incident |
| Organization | Opportunity |
| Organization | Task |
Sub-objects which are related to a primary object will be destroyed when the primary object is destroyed. If a specific sub-object needs to be destroyed without destroying the primary object the Update operation should be used.
Object properties of this type are not destroyed when the primary object is destroyed. Where objects of this type extend RNObject the destroy method can be used to destroy these objects directly.
Each of the CRUD operations accept processing options as a parameter. For example, the Create operation takes a CreateProcessiongOptions object as a parameter to the operation. Processing options can be used to prevent external events or business rules from executing when the CRUD operation is invoked. For more information see Processing Options.
The Batch operation can be used to send multiple heterogeneous operation requests to the server in a single SOAP request. The Batch operation takes a list of all the basic SOAP request messages that are supported. For instance, a caller might call Batch with a Create for an Incident, an Update for three contacts, and a Get for an Answer. On each batch request item a ‘CommitAfter’ attribute can be set. Before the first message in the batch list is processed, a transaction is implicitly started. All operations in the list are considered part of this transaction until an operation in the list is encountered with the ‘CommitAfter’ attribute set or the end of the list. At this point, all changes are committed to the database. Following a commit, a new transaction is implicitly started.
Similar to the inputs of the Batch operation the output of the Batch operation can be a list of any of the defined SOAP responses. The items in the list will correspond to the return values of the standalone WSDL operation. Should an exception occur during the processing of a batch transaction, that exception will be included in the list of responses. If an operation in a transaction boundary fails, the operations prior to the boundary will contain valid responses, however the client is responsible for knowing these operations have been rolled back due to the transactional nature. All operations after the failed operation will return a not executed SOAP fault. If a new transaction is in the batch request after the failed transaction, this transaction will continue to run.
It is important to note that the server does impose restrictions on the number of operations that can be included in a batch as well as memory and CPU restrictions when processing a batch of operational requests. At most, the server will allow for 100 transactions in a batch request. However, do the various amounts of data and other factors in any given operation request it may be the case where the batch request will hit CPU and/or memory restrictions prior to processing all 100 batch operations. It is the responsibility of the client developer to partition batch requests into reasonable size to avoid these server side CPU & memory restrictions. In the event a client request hits the CPU &/or memory limit the client will receive an exception and the client may not be able to determine which operations in the batch request succeeded and which did not execute.
Please see the Batch operation documentation for code and XML samples of batching.
Creating related objects usually requires multiple requests to a server which can be very inefficient, especially for bulk operations. Chaining is a mechanism that allows for efficiently creating multiple related objects in a single server request via bulk or Batch operations. For instance, suppose a caller wants to create a new Organization, a Contact associated with that organization, and an Incident associated with that organization and contact. In order to associate the contact with the organization, the caller must know the id assigned to the new organization when it was created. Likewise, to create the incident, the caller must know the new organization id and the new contact id.
In order to allow these operations to be done in a single batch request, the ids must be “chained” together between the objects. That is, it must be possible to indicate that the organization id in the contact should be set to the value assigned to the newly created organization’s id.
All primary and foreign key fields are of type ID. To chain the id of a newly created object, a specialized ID (ChainSourceID) is passed to the create request using type extension. ChainSourceID defines a variableName attribute which is used as a unique variable name to ‘bind’ that newly created id value to that variable name for the scope of the SOAP request.
For any subsequent objects where you want to reference the source id, you similarly instantiate a ChainDestinationID subtype, set the variableName attribute to the same name, and assign that object to the ID field. The public SOAP service will handle placing the value that is assigned to the id in the ChainSourceID into any ChainDestinationID with a matching variable name.
The service will not handle forward references; that is, a ChainDestinationID with a particular variable name cannot precede the ChainSourceID with the same variable name. If there is ever a circular reference chain in the object model, it will be necessary to update the IDs in the same way that you would handle a circular foreign key reference in a database; create one of the objects with a null value for the reference to the second class, create the second object and set the reference using chaining, then update the first object to populate its reference to the second object using chaining.
The source ID may be the id of an object being created. The destination ID may be any id field that references the source object type. In addition to the Create operation, clients may also use chaining with a Get operation. An example of chaining with a Get operation is getting the primary Contact and the contact's Organization when you get an Incident.
Chaining can be used in both bulk creates or Batch operations. When used in a Batch operation the chaining cannot span transaction/commit boundaries, attempting to span transaction boundaries with chaining will result in a Request fault.
Please see the Batch operation documentation for code and XML samples of chaining.
Custom fields, or client defined fields, are of type GenericField. A GenericField type includes the properties DataType, DataValue and Name. Name is required and maps to the column name on the custom field. All custom fields are accessed by their column name (not an integer id). On any Get of an object that contains custom fields the server will fully populate the GenericField property for all custom fields on the object. When performing a Create or Update operation only the custom fields being created or updated are required in the request.
If an operation attempts to access a custom field that no longer exists a SOAP fault will be returned.
RightNow Connect Web Services for SOAP uses SOAP Message Transmission Optimization Mechanism (MTOM) for sending and receiving of file attachments over the size of 64 kilobytes(file attachments that are smaller than 64 kilobytes, data is sent and received using in-lined base64 encoded data). The MTOM specification relies on XML-Binary Optimized Packaging and Assigning Media Types to Binary Data in XML.
MTOM provides a mechanism to transfer binary data that is more efficient than in-lined base64 encoded data. MTOM requests must have a Content-Type: item in the HTTP header. This content-type item should take the form of:
Content-Type: Multipart/Related; boundary=MIME_Boundary; type=application/xop+xml; charset=UTF-8; start-info="application/soap+xml"
The value in boundary= will be used as the MIME boundary in the message. Mime boundaries are embedded in the message and are preceded by 2 dashes ‘--‘. There is an optional start=”MIME-CONTENT-ID” parameter that defines the Content-ID: value of the first MIME part which should contain the SOAP message. Otherwise the first MIME part is assumed to contain the SOAP message. The MIME part containing the SOAP message needs to have a Content-Type: set to application/xop+xml;charset=UTF-8;type="application/soap+xml" and a Content-Transfer-Encoding: set to binary.
The SOAP request element which contains binary data to be transferred using MTOM will contain a sub-element that looks like:
<xop:Include href=”cid:unique-content-id” xmlns="http://www.w3.org/2004/08/xop/include" />
The data in the href after the cid: is the content-id of the mime part containing the binary data, unique-content-id in this case.
A sample request Client-to-Server would look like this (example based off the MTOM Implementation Summary, Test 1b (Send MTOM, Receive XML), Canon->Microsoft):
==== Request ====
POST /dotnet/mtom/mtomecho.ashx HTTP/1.1
Content-Type: Multipart/Related;boundary=MIME_Boundary;type=application/xop+xml;charset=UTF-8;start-info="application/soap+xml";start="<mymainpart@crf.canon.fr>"
Mime-Version: 1.0
Host: martingudgin-2.dsl.easynet.co.uk
Content-Length: 16557
Cache-Control: no-cache
--MIME_Boundary
Content-ID: <mymainpart@crf.canon.fr>
Content-Type: application/xop+xml;charset=UTF-8;type="application/soap+xml"
Content-Transfer-Encoding: binary
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime" xmlns:xop="http://www.w3.org/2004/08/xop/include"><soap:Header></soap:Header><soap:Body><ns1:EchoTest xmlns:ns1="http://example.org/mtom/data"><ns1:Data><xop:Include href="cid:thismessage:/frog.jpg"></xop:Include></ns1:Data></ns1:EchoTest></soap:Body></soap:Envelope>
--MIME_Boundary
Content-ID: <thismessage:/frog.jpg>
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
***BINARY DATA***
--MIME_Boundary--
A sample request Server-to-Client would look like this (example based off the MTOM Implementation Summary, Test 1a (Send XML, Receive MTOM), White Mesa ->Canon):
==== Response ====
HTTP/1.1 200 OK
Date: Thu, 09 Sep 2004 09:28:10 GMT
Server: WhiteMesa SOAP Server/3.2
Content-Type: Multipart/Related; boundary="6DC2B87_XOP_6DC2B87"; type="application/xop+xml"; start="<uuid:B9399162-C9FA-46B8-9675-8EFBA861DAF5>"; start-info="application/soap+xml"
Content-Length: 16607
Connection: close
--6DC2B87_XOP_6DC2B87
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Id: <uuid:B9399162-C9FA-46B8-9675-8EFBA861DAF5>
Content-Transfer-Encoding: binary
<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"><SOAP-ENV:Body><test:EchoTest xmlns:test="http://example.org/mtom/data" xmlns:xop="http://www.w3.org/2004/08/xop/include"><test:Data><xop:Include href="cid:uuid:F7B90AC8-6DC3-42AD-B9A5-0A15C915CCCF" /></test:Data></test:EchoTest></SOAP-ENV:Body></SOAP-ENV:Envelope>
--6DC2B87_XOP_6DC2B87
Content-Type: application/octet-stream
Content-Id: <uuid:F7B90AC8-6DC3-42AD-B9A5-0A15C915CCCF>
Content-Transfer-Encoding: binary
***BINARY DATA***
--6DC2B87_XOP_6DC2B87--
Most toolkits support MTOM for sending and receiving binary data, for details refer to your toolkit documentation.
All date / time values exchanged via the Connect Web Services for SOAP use ISO 8601 encoding. The date /time values stored in the RightNow CX platform are normalized to UTC. When passing in times to RightNow CX platform it is your responsibility to ‘normalize’ times to UTC (adjust local time to UTC) and transmit the date / time on the wire with a trailing ‘Z’ which indicates the time is UTC time.The following is an example of a UTC formatted date:
20050110T04:00:00Z
Any date / time value supplied in a request that is not in UTC format will be rejected by the RightNow CX platform. If the time format is not valid a RequestFault will be returned.
For more information see http://www.w3.org/TR/xmlschema-2/#isoformats and http://www.iso.org/iso/date_and_time_format.
The Connect Web Services for SOAP API service endpoint is available on each interface configured for a site. When handling any strings that are localized (such as those in the NamedID fields), the API uses the language associated with the interface, both for looking up incoming strings and for generating outgoing strings. For strings that come from message bases, the message bases for the interface will be used to supply the values. In addition, language and interface fields on RightNow objects such as Incidents will automatically default to the interface and language of the interface the request was sent to. Setting the interface field will cause the language to default to that of the interface.