1 "CRUD" Request Types
- 1.1 Read
- 1.2 Create
- 1.3 Update (Single Record Only)
- 1.4 Delete (Single Record Only)
- 1.5 Batch Delete
2 Local SQL Queries
- 2.1 Select (Read-Only Local Query)
- 2.2 Update (Local Update Query)

"CRUD" Request Types

Read

Description

The Read API retrieves object data from the database based on specified field-value pairs. The API filters objects using the fields and values provided in the data portion of the request.

The API performs an exact match on the fields values. Supplying fields that do not exist on the SObject will result in failures.

This API always returns full object data for matching records. There is currently no way to limit the fields returned.

Request Parameters

type (string, required) – Must be set to "read" to indicate a read operation.
object (string, required) – The name of the Salesforce SObject to query (e.g., "Account", "Contact").
data (object, required) – A key-value mapping where:
- Keys represent field names of the specified object.
- Values represent the filter criteria. Only objects matching all field-value pairs will be returned.

Example Request

The following request retrieves all Account objects where the Name field is "John Doe Industries":

var request = {
  "type" : "read",
  "object" : "Account",
  "data" : { "Name" : "John Doe Industries" }
};
bridge.send(request, function (responseData) {
  if (responseData.type === 'error') {
    // when there is an error, the responseData will contain the error message
    alert('There was an error submitting your read request to Pulsar. ' + responseData.data);
  } else {
    // when the request succeeds, the responseData will contain an array of the matching objects
    const records = responseData.data;
    if (records.length > 0) {
      alert(`We found ${records.length} records matching Name = John Doe Industries`);
      alert(`The Id of the first record is ${records[0]['Id']}`);
    }
  }
});

Response Structure

If the request fails, responseData will contain an error message:
{ "type": "error", "object": "Account", "data": "Error message here" }
If the request succeeds, responseData.data will contain an array of matching objects:
{ "type": "readResponse", "object": "Account", "data": [ { "Id": "001XYZ123456789", "Name": "John Doe Industries", "Industry": "Technology", ... (remaining field: value pairs) }, ... (other matched SObjects) ] }

Create

Description

The Create API allows you to create a new Salesforce object by specifying field names and values in the data portion of the request. This is functionally equivalent to saving a new record via the Pulsar native user interface.

By default:

If a field validation or record creation error occurs, Pulsar’s record creation screen will be displayed to allow user intervention.
You can override this behavior using optional arguments. (see below)

Request Parameters

type (string, required) – Must be set to "create" to indicate a create operation.
object (string, required) – The name of the Salesforce SObject to create (e.g., "Account", "Contact").
data (object, required) – A key-value mapping where:
- Keys represent field names on the specified object.
- Values represent the field values to be assigned.
args (object, optional) – Additional options to control the behavior of the API:
- allowEditOnFailure (string, optional, default "TRUE")
  - If "TRUE" (default), Pulsar’s record creation screen is displayed when errors occur.
  - If "FALSE", errors will prevent creation without user intervention.
- skipLayoutRequiredFieldCheck (string, optional, default "FALSE")
  - If "TRUE", the API skips checking for fields marked as required in the Salesforce layout.

Concurrency Restrictions and Side Effects

Create, update, or delete requests must NOT run concurrently. These operations should be executed sequentially to avoid conflicts.

Furthermore, this API will have the following effects (if these features are enabled):

Run PSL Object Triggers for the created record(s).
Process Salesforce Validation Rules applicable to the record.
Recalculate and save formula fields for the created record.
Recalculate roll-up summary fields on parent records.

Example Request

The following request creates an Account record with a Name and Phone, while preventing user intervention in case of failure:

var request = {
    "type": "create",
    "object": "Account",
    "data": { "Name": "John Doe Industries", "Phone": "867-5309" },
    "args": { 
        "allowEditOnFailure": "FALSE", // Prevents UI intervention if an error occurs
        "skipLayoutRequiredFieldCheck": "FALSE" // Ensures all layout-required fields are validated
    }
};

bridge.send(request, function (responseData) { 
    alert('Received create response: ' + JSON.stringify(responseData)); 
});

Response Structure

If the request fails, responseData will contain an error message:
{ "type": "error", "object": "Account", "data": "Error message here" }
If the request succeeds, responseData.data will contain the Id of the newly created object:
{ "type": "createResponse", "object": "Account", "data": "001XYZ123456789", }

Update (Single Record Only)

Description

The Update API modifies an existing Salesforce object using field names and values specified in the data portion of the request. This is equivalent to updating a record via the Pulsar native user interface.

Only one record can be updated per request.
The Id field is required to identify the record to update.
By default, if the update violates Salesforce layout-required fields, the request may fail unless overridden (see below).

Request Parameters

type (string, required) – Must be set to "update" to indicate an update operation.
object (string, required) – The name of the Salesforce SObject to update (e.g., "Account", "Contact").
data (object, required) – A key-value mapping where:
- Id (string, required) – The unique Salesforce ID of the record to update.
- Other fields represent the values to update.
args (object, optional) – Additional options to control update behavior:
- skipLayoutRequiredFieldCheck (string, optional, default "FALSE")
  - If "TRUE", the API skips checking for fields marked as required in the Salesforce layout.

Concurrency Restrictions

Create, update, or delete requests must NOT run concurrently. These operations should be executed sequentially to prevent conflicts.

Additional Effects

If the following features are enabled, updating a record will also:

Trigger PSL Object Triggers for the updated record.
Process Salesforce Validation Rules applicable to the record.
Recalculate and save formula fields for the updated record.
Recalculate roll-up summary fields on parent records.

Example Request

The following request updates an Account record, modifying its Name and Phone:

var request = { 
    "type": "update",
    "object": "Account",
    "data": { 
        "Id": "001234567891234",  // Required: Specifies which record to update
        "Name": "John Doe Industries, Inc",
        "Phone": "(555) 867-5309"
    },
    "args": {
        "skipLayoutRequiredFieldCheck": "FALSE" // Ensures all layout-required fields are validated
    }
};

bridge.send(request, function (responseData) {
    alert('Received update response: ' + JSON.stringify(responseData));
});

Response Structure

If the request fails, responseData will contain an error message:
{ "type": "error", "object": "Account", "data": "Error message here" }
If the request succeeds, responseData.data will contain the Id of the updated record:
{ "type": "updateResponse", "object": "Account", "data": "001XYZ123456789" }

Delete (Single Record Only)

Description

The Delete API removes an existing Salesforce object using the Id field to identify the record. This is equivalent to deleting a record via the Pulsar native user interface.

Only one record can be deleted per request.
If the record does not exist or the Id is invalid, the request will fail.

Concurrency Restrictions

Create, update, or delete requests must NOT run concurrently. These operations should be executed sequentially to prevent conflicts.

Additional Effects

If the following features are enabled, deleting a record will also:

Trigger PSL Object Triggers for the deleted record.
Process Salesforce Validation Rules applicable to the record.
Recalculate and save formula fields for related records.
Recalculate roll-up summary fields on parent records.

Example Request

The following request deletes an Account record with the specified Id:

var request = { 
    "type": "delete",
    "object": "Account",
    "data": { "Id": "001234567891234" } // Required: Specifies which record to delete
};

bridge.send(request, function (responseData) {
    alert('Received delete response: ' + JSON.stringify(responseData));
});

Response Structure

If the request fails, responseData will contain an error message:
{ "type": "error", "object": "Account", "data": "Error message here" }
If the request succeeds, responseData.data will contain the Id of the now deleted object:
{ "type": "deleteResponse", "object": "Account", "data": "001234567891234", }

Batch Delete

Description

The Batch Delete API allows you to delete multiple Salesforce records in a single request using an array of object IDs. This is equivalent to sequentially deleting records via the Pulsar native user interface, but with improved efficiency.

Only records specified in the objectIdList array will be deleted.
The response provides a success status for each individual record.
If some deletions fail, the response will include error details.

Concurrency Restrictions

Delete requests, including batch deletes, must NOT run concurrently. These operations should be executed sequentially to prevent conflicts.

Additional Effects

If the following features are enabled, deleting records will also:

Trigger PSL Object Triggers for the deleted records.
Process Salesforce Validation Rules applicable to the records.
Recalculate and save formula fields for related records.
Recalculate roll-up summary fields on parent records.

Some records may be deleted while others fail. The API returns results for each attempted deletion.
If a record has dependent child records, Salesforce rules may prevent deletion unless cascading delete is enabled.
The summary success flag (summary.success) will be "TRUE" only if all deletions succeeded.

Example Request

The following request attempts to delete three Account records:

var request = { 
    "type": "deletebatch",
    "object": "Account",
    "data": { 
        "objectIdList": [ "001234567891234", "001234567891235", "001234567891236" ] // Required: List of record IDs to delete
    }
};

bridge.send(request, function (responseData) {
    console.log('Received batch delete response:', responseData);

    if (responseData.type === "deletebatchResponse") {
        var resultObject = responseData.data;
        var wasSuccessful = resultObject.summary.success; // "TRUE" if all deletions succeeded, "FALSE" otherwise
        var resultIds = Object.keys(resultObject.results);

        resultIds.forEach(function(objId) {
            var objectResult = resultObject.results[objId];
            if (objectResult.success === "FALSE") { // Check if deletion failed
                alert(`Failed to delete record: ${objectResult.objectId}. Error: ${objectResult.error}`);
            }
        });
        if (wasSuccessful) {
          console.log('Batch delete successful!');
        }
    } else if (responseData.type === "error") {
        alert('A problem occurred:\n' + responseData.data);
    }
});

Response Structure

If the request fails completely, responseData will contain an error message:
{ "type": "error", "object": "Account", "data": "Error message here" }
If the request succeeds partially or fully, responseData.data will contain a summary success flag and individual results for each record:
{ "type": "deletebatchResponse", "object": "Account", "data": { "summary": { "success": "FALSE" // "TRUE" if all deletions succeeded, "FALSE" if any failed }, "results": { "001234567891234": { "objectId": "001234567891234", "success": "TRUE", "error": "" }, "001234567891235": { "objectId": "001234567891235", "success": "FALSE", "error": "delete failed - Error occurred during object delete" }, "001234567891236": { "objectId": "001234567891236", "success": "TRUE", "error": "" } } } }

Local SQL Queries

Select (Read-Only Local Query)

Description

The Select API allows advanced users to execute custom read-only queries using Pulsar's built-in database engine. This API provides flexibility for querying data using a raw SQL-like syntax, enabling more complex filtering conditions than the standard Read API.

Supports fully custom SELECT statements within the Pulsar environment.
Executes locally, meaning results are derived from Pulsar’s database cache.
Read-only operation—no data modification is performed.

Request Parameters

type (string, required) – Must be set to "select" to indicate a selection query.
object (string, required) – The name of the Salesforce SObject to query (e.g., "Account", "Contact").
data (object, required) – Contains:
- query (string, required) – A raw SQL-like query string to execute.

Example Request

The following request selects all Account records where the Name field contains "hello":

var request = { 
    "type": "select",
    "object": "Account",
    "data": { 
        "query": "SELECT Id FROM Account WHERE Name LIKE '%hello%'" 
    }
};

bridge.send(request, function (responseData) {
    if (responseData.type === "error") {
        alert("An error occurred: " + responseData.data);
    } else {
        var records = responseData.data;
        console.log(`Retrieved ${records.length} records.`);
        if (records.length > 0) {
            alert(`First record Id: ${records[0].Id}`);
        }
    }
});

Response Structure

If the request fails, responseData will contain an error message:
{ "type": "error", "object": "Account", "data": "Error message here" }
If the request succeeds, responseData.data will contain an array of matching records:
{ "type": "selectResponse", "object": "Account", "data": [ { "Id": "001XYZ123456789" }, { "Id": "001XYZ987654321" } ] }

Update (Local Update Query)

Warning: Use with Caution

We strongly recommend using the standard CRUD Update API (see above) whenever possible. The updateQuery API allows developers to issue a raw UPDATE query directly to the local database, which can have significant risks if not used carefully.

Caveat Programmer!

Using updateQuery bypasses important Salesforce and Pulsar processing safeguards:

Test carefully in a sandbox environment before using in production.

❌ No validation rules are enforced for updated records.
❌ Formula fields are not recalculated after updates.
❌ Roll-up summary fields on parent records are not recalculated.
❌ Data may become unsynchronized with Salesforce, potentially causing issues when syncing.
❌ Incorrect updates can break Pulsar app functionality or damage Salesforce data integrity.

Description

The Update Query API performs a direct batch update on the local Pulsar database using a raw SQL-like query.

Bypasses standard Salesforce validation and field recalculations.
Offline mode: Updates are stored locally and synced later.
Online mode: Changes are pushed to Salesforce, but Salesforce errors are not immediately reflected in the API response.
Response always indicates local database success or failure, even if the sync to Salesforce fails.

Request Parameters

type (string, required) – Must be set to "updateQuery" to indicate a raw update query.
object (string, required) – The name of the Salesforce SObject being updated (e.g., "Account", "Contact").
data (object, required) – Contains:
- query (string, required) – A raw UPDATE SQL-like statement to execute.

Example Request

The following request updates all Account records where OpportunityCount__c > 0, setting ActiveCustomer__c to "TRUE":

var request = { 
    "type": "updateQuery",
    "object": "Account",
    "data": { 
        "query": "UPDATE Account SET ActiveCustomer__c = 'TRUE' WHERE OpportunityCount__c > 0;" 
    }
};

bridge.send(request, function (responseData) { 
    alert('Received update query response: ' + JSON.stringify(responseData)); 
});

Response Structure

If the local update succeeds, responseData will indicate "success", even if syncing to Salesforce later fails.
If Salesforce sync fails, errors will be reported separately inside the success response.

Example: Successful Local Update with Salesforce Error

{
  "type": "updateQueryResponse",
  "object": "Account",
  "data": "success",
  "errors": [
    {
      "errorCode": "ENTITY_IS_LOCKED",
      "message": "This record is locked. If you need to edit it, contact your admin."
    }
  ]
}

Local Database API (CRUD requests)

"CRUD" Request Types

Read

Description

Request Parameters

Example Request

Response Structure

Create

Description

Request Parameters

Concurrency Restrictions and Side Effects

Example Request

Response Structure

Update (Single Record Only)

Description

Request Parameters

Concurrency Restrictions

Additional Effects

Example Request

Response Structure

Delete (Single Record Only)

Description

Concurrency Restrictions

Additional Effects

Example Request

Response Structure

Batch Delete

Description

Concurrency Restrictions

Additional Effects

Example Request

Response Structure

Local SQL Queries

Select (Read-Only Local Query)

Description

Request Parameters

Example Request

Response Structure

Update (Local Update Query)

Warning: Use with Caution

Caveat Programmer!

Description

Request Parameters

Example Request

Response Structure

Example: Successful Local Update with Salesforce Error