Scripting - Record INSERT, UPDATE, UPSERT

iDialogue scripts may create or update Salesforce records from customer experience (CX) rooms.

Examples of common interactions including

• Recording a quote selection
• Updating context information

Record I/O Best Practices

It is generally best practice for a script to update a checkbox or DateTime field on a Salesforce record to record an interaction. Then let a record-trigger flow execute more detailed DML or record modification.

Scripts should implement AJAX and asynchronous handlers when POSTing to the /records API.

Scripts should handle exceptions gracefully, protecting the end user from experiencing full stack traces.

Records are created and updated on-behalf of the iDialogue OAUth user established under the iDialogue Admin “Quick Start” tab.

API

The script records API provides:

• API Endpoint
• One POST body request
• A JSON representation for records
• An API response body

Endpoint

https://api.i-dialogue.com/v1/orgs/{orgid}/rooms/{room_id}/records

The API endpoint can be constructed by concatenating the roomContext.url prperty and /records.

var apiUrl = context.url + 'records';

Method

The API supports only POST requests. The request method property determines the context of record INSERT, UPDATE, or UPSERT.

Request

The POST body contains the following properties.

var request          = {};
request.orgId;        // (Optional) Provided in REST URL path
request.roomId;        // (Optional) Provided in REST URL path
request.origin;        // (Reserved)
request.storedProcedure;  // Reference to a MDT develper_name with predefined DML rules.
request.method;        // (Required) Valid values: INSERT, UPDATE, UPSERT
request.type        // (Required) The SObject type. Opportunity, Contact, etc...
request.externalField;    // Required if method is UPSERT
request.records;       // (Required) An array collection of Salesforce records for DML.

Response

var response = JSON.parse( xmlhttp.response );
response.success    // (Boolean) true if operation was successful.
response.message    //  Contains high level error message if success === false
response.errors      //  Array collection of detailed error messages.
response.orgId      //  Reflects the provided request value.
response.roomId      //  Reflects the provided request value.
response.origin      //  Reflects the provided request value.
response.storedProcedure //Reflects the provided request value.
response.method      // Reflects the provided request value.
response.type      //  Reflects the provided request value.
response.records     // Array collection of records.
            // For INSERT method, the records contain their new ID.
            // The individual SRecords will also contain success and message
            // properties in the response.

SRecord

The records property in the API Request and Response defines the following properties:

var sRecord    = {};
sRecord.id;    // Required for UPDATE and UPSERT operations.
        // 18-char ID reference to a Salesforce record.
sRecord.type;  // The Salesforce record type. Example "Opportunity", "Contact"
sRecord.name;  // Required for INSERT. The record Name (if name is a required field).
sRecord.fields; // Map collection of key/values.
        // Key: API name of a field
        // Value: String field value.

API Examples

Query Quotes and Update Opportunity

The following example queries all quotes associated with an Opportunity, then updates a custom field on Opportunity to designate the customer selected Quote.

<script>
  function queryQuotes(){
    var queryURL = roomContext.url + '/query';
    var queryRequest = {};
    queryRequest.query = "SELECT Id, Name, TotalAmount FROM Quote WHERE OpportunityId='" + roomContext.masterRecordId + "' LIMIT 100";

    var xmlhttp = new XMLHttpRequest();
    xmlhttp.open("POST", queryURL );
    xmlhttp.setRequestHeader("Content-Type", "application/json" );
    xmlhttp.setRequestHeader("Authorization", roomContext.sessionId );
    xmlhttp.send(JSON.stringify( queryRequest ) );
    xmlhttp.onreadystatechange = function() {
      if ( xmlhttp.readyState === 4) {
        var data = JSON.parse( xmlhttp.response );
        // Render response
      }
    }
  }

  function updateSelectedQuote( selectedQuoteId ){
    var updateURL         = roomContext.url + '/records';

    var opportunityRecord     = {};
    opportunityRecord.id     = roomContext.masterRecordId;
    opportunityRecord.type     = "Opportunity";
    opportunityRecord.fields   = {};
    opportunityRecord.fields["CustomerSelectedQuote__c"] = selectedQuoteId;

    var updateRequest       = {};
    updateRequest.method     = "UPDATE";
    updateRequest.type       = "Opportunity";
    updateRequest.records     = [];
    updateRequest.records.push( opportunityRecord )

    var xmlhttp = new XMLHttpRequest();
    xmlhttp.open("POST", updateURL );
    xmlhttp.setRequestHeader("Content-Type", "application/json");
    xmlhttp.setRequestHeader("Authorization", roomContext.sessionId);
    xmlhttp.send(JSON.stringify( updateRequest ) );
    xmlhttp.onreadystatechange = function() {
      if ( xmlhttp.readyState === 4) {
        var response = JSON.parse( xmlhttp.response );
        if( response.success == false ){
          // Handle response.message and response.errors here
        }
        // Render response
      }
    }
  }
</script>