Connect Web Services for SOAP: Create a Contact

After retrieving the WSDL and be aware of the API Operations you are ready to get, create, update and delete RightNow records through Web Services.

In this post an example will be presented on how to create a Contact. On the documentation available (Connect Web Services for SOAP) we can see the sample code and then adapt to our case.

To create a Contact we shall use the “Create” API Operation. The request message shall have:

  • An Envelope;
  • A Header;
  • A Body;

Envelope

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/&#8221; xmlns:v1=“urn:messages.ws.rightnow.com/v1_2” xmlns:v11=“urn:base.ws.rightnow.com/v1_2”>
[Include here the Header and the Body]
</soapenv:Envelope>

Header

Notice the AppID tag with the Operation name “Basic Create”

<soapenv:Header>
  <ns7:ClientInfoHeader xmlns:ns7=“urn:messages.ws.rightnow.com/v1_2” soapenv:mustUnderstand=“0”>
     <ns7:AppID>Basic Create</ns7:AppID>
  </ns7:ClientInfoHeader>
  <wsse:Security xmlns:wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd&#8221; mustUnderstand=“1”>
     <wsse:UsernameToken>
        <wsse:Username>Username</wsse:Username>
        <wsse:Password Type=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText&#8221;>Password</wsse:Password>
     </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

Body

Notice the Create tag and the RNObjects tag with the xsi:type = “Contact”

<soapenv:Body>
<ns7:Create xmlns:ns7=“urn:messages.ws.rightnow.com/v1_2”>
——<ns7:RNObjects xmlns:ns4=“urn:objects.ws.rightnow.com/v1_2” xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance&#8221; xsi:type=“ns4:Contact”>
———<ns4:Emails>
————<ns4:EmailList action=“add”>
—————<ns4:Address>example.email@rightnow.com</ns4:Address>
—————<ns4:AddressType>
——————<ID xmlns=“urn:base.ws.rightnow.com/v1_2” id=“0” />
—————</ns4:AddressType>
————</ns4:EmailList>
———</ns4:Emails>
———<ns4:Name>
————<ns4:First>FirstName</ns4:First>
————<ns4:Last>LastName</ns4:Last>
———</ns4:Name>
——</ns7:RNObjects>
</ns7:Create>
</soapenv:Body>

Connect Web Services for SOAP: API Operations

Operations represent specific calls invoked to perform specific tasks on the RightNow CX platform. Connect Web Services defines a number of operations which either accept or return one or more instances of RNObject.

CRUD – Create, Read, Update and Destroy

CRUD operations allow for the creation, reading, updating and deleting of objects contained in the RightNow CX system.

Return values:

  • Create and Get (Read) operations return a list containing 1 to N RNObjects.
  • Update and Destroy operations do not return a value upon success.
  • If a CRUD operation fails, a SOAP fault is returned.

API Operations

Listed bellow are the supported operations in Connect Web Services (that are included in the WSDL).

  • Batch: Sends a set of operations to the server in a single request.
  • ConvertGenericToObject: Converts a generic object to a typed object.
  • ConvertObjectToGeneric: Converts a typed object to a generic object.
  • Create: Creates one or more instances of objects which inherit from RNObject.
  • Destroy: Destroys one or more instances of objects which inherit from RNObject.
  • ExecuteMarketingFlow: Initiates a marketing campaign flow.
  • Get: Reads one ore more instances of objects which inherit from RNObject.
  • GetFileData: Obtains the binary data for a file attachment.
  • GetMetaData: Obtains all meta-data information for all classes.
  • GetMetaDataForClass: Obtains meta-data information for the specified class.
  • GetMetaDataLastChangeTime: Obtains the date and time of the last change to the meta-data.
  • GetValuesForNamedID: Obtains a list of ID-Name pairs for a specific NamedID field.
  • GetValuesForNamedIDHierarchy: Obtains a list of ID-Name pairs for a specific NamedIDHierarchy field.
  • QueryCSV: Processes a ROQL query string and returns data in a CSV result.
  • QueryObjects: Processes a ROQL query string and returns one or more objects.
  • ResetContactPassword: Invalidates a contacts password and emails a link to the contact that can be used to reset the password.
  • RunAnalyticsReport: Executes a RightNow Analytics report reurnning the data in a CSV result.
  • SendMailingToContact: Sends a transactional mailing to a contact.
  • Update: Updates one or more instance of objects which inherit from RNObject.

Connect Web Services for SOAP: WSDL Retrieval

Connect Web Services for SOAP is an open and standards-based integration API enabling developers to build integration solutions with RightNow CX that leverage industry leading standards such as WSDL 1.1 and SOAP 1.1.

Connect Web Services for SOAP is RightNow’s leading data integration API, providing broad out-of-the-box tooling support for a wide variety of languages, platforms, and tools.

Connect Web Services should be used to extend the functionality offered by RightNow CX and the ability to access data stored in the RightNow CX platform.

WSDL Retrieval

There are two WSDL files that provide access to Connect Web Services:

  • Standard WSDL – This WSDL should be used by application developers building integrations specific to their Oracle RightNow CX instance. The typed WSDL is a strongly typed representation of the Connect Common Object Model. The strongly typed WSDL can be accessed from the following URL:

http://<host_name>/cgi-bin/<interface>.cfg/services/soap?wsdl=typed

  • Partner WSDL – This WSDL should be used by application developers building integrations that function across multiple instances of Oracle RightNow CX. It provides the ability to work with Generic Objects that can be used across multiple instances of Oracle RightNow CX. The generic WSDL can be accessed from the following URL:

http://<host_name>/cgi-bin/<interface>.cfg/services/soap?wsdl=generic

(e.g. host name: interfacename.rightnowdemo.com)
(e.g. interface: interfacename)