All generated Salesforce objects—such as Contact, Case, and Lead—have access to typed utility functions for interacting with Salesforce, for example:
let contact = await SalesforceRequests.Contact.createAndGetObject(newContactData);
let case = await SalesforceRequests.Case.getObjectByField(Case.Email, email);
Retrieves a Salesforce object of the specified type by its unique ID.
• Parameters:
id – The unique Salesforce record ID. Must be a non-empty string.
• Returns:
A promise resolving to the Salesforce object of the appropriate type.
• Throws Error:
If the ID is invalid or the request fails.
const contact = await SalesforceRequests.Contact.getObjectById('0031t00000XXXXXAAA')
Retrieves a Salesforce object of the specified type where the given field matches the provided value.
• Parameters:
field – The name of the Salesforce field to query. Must be a non-empty string.
value – The value to match for the specified field.
• Returns:
A promise resolving to the matched Salesforce object of the appropriate type.
• Throws Error:
If the query fails or the parameters are invalid.
const contact = await SalesforceRequests.Contact.getObjectByField<Contact>('Email', 'user@example.com');
Retrieves a single Salesforce object of the specified type matching a SOQL WHERE clause.
• Parameters:
whereClause – The SOQL WHERE clause (without the WHERE keyword). Must be a valid SOQL filter expression.
• Returns:
A promise resolving to the Salesforce object of the appropriate type.
• Throws Error:
If no records or multiple matching records are found, or if the request fails.
const lead = await SalesforceRequests.Lead.getObjectByWhere<Lead>("Email = 'a@example.com'");
Retrieves an array of Salesforce objects of the specified type where the given field matches the provided value.
• Parameters:
field – The name of the Salesforce field to filter by (e.g., 'Email'). Must be a non-empty string.
value – The value the field must match. Can be a string, number, or boolean.
• Returns:
A promise resolving to an array of matching Salesforce objects of the appropriate type.
• Throws Error:
If the query fails or parameters are invalid.
const contacts = await SalesforceRequests.Contact.getObjectArrayByField<Contact>('Email', 'a@example.com');
Retrieves an array of Salesforce objects of the specified type matching the given SOQL WHERE clause.
Fetches the record IDs first, then retrieves each full object by ID.
• Parameters:
whereClause – The SOQL WHERE clause (without the WHERE keyword). Must be a valid SOQL filter expression.
• Returns:
A promise resolving to an array of Salesforce objects of the appropriate type.
• Throws Error:
If the query fails or parameters are invalid.
const contacts = await SalesforceRequests.Contact.getObjectArrayByWhere<Contact>("LastName = 'Keller'");
Creates a Salesforce object record.
• Parameters:
data – The object data to create.
autoAssign – Optional; whether to auto-assign required fields. Defaults to true.
When set to false, adds the Salesforce header Sforce-Auto-Assign: FALSE to the request.
• Returns:
A promise resolving to the ID of the created Salesforce record.
• Throws Error:
If the creation fails due to Salesforce API errors.
await SalesforceRequests.Contact.createObject({ LastName: 'Wells', FirstName: 'Rene' });
Creates a Salesforce object record and retrieves the full object by its ID.
• Parameters:
data – The data to create the object with.
autoAssign – Optional; whether to auto-assign required fields. Defaults to true.
When set to false, adds the Salesforce header Sforce-Auto-Assign: FALSE to the request.
• Returns:
A promise resolving to the full Salesforce object record of the specified type.
• Throws Error:
If object creation or retrieval fails.
const contact = await SalesforceRequests.Contact.createAndGetObject({ LastName: 'Wells', FirstName: 'Rene' });
Updates a Salesforce object record by its ID.
• Parameters:
id – The Salesforce record ID to update. Must be a non-empty string.
data – The fields and values to update (partial object).
autoAssign – Optional; whether to auto-assign required fields. Defaults to true.
When set to false, adds the header Sforce-Auto-Assign: FALSE.
• Returns:
A promise that resolves when the update completes successfully.
• Throws Error:
If the update operation fails.
await SalesforceRequests.Contact.updateObject('0031t00000XXXXXAAA', { LastName: 'Holland' }, false);
Updates a Salesforce object by ID and retrieves the updated record.
• Parameters:
id – The ID of the object to update. Must be a non-empty string.
data – The data to update on the object (partial fields).
autoAssign – Optional; whether Salesforce should auto-assign default fields. Defaults to true.
When set to false, adds header Sforce-Auto-Assign: FALSE.
• Returns:
A promise resolving to the updated Salesforce object.
• Throws Error:
If the update or retrieval fails.
contact = await SalesforceRequests.Contact.updateAndGetObject('0031t00000XXXXXAAA', { LastName: 'Holland' });
Deletes a Salesforce object by its type and ID.
• Parameters:
id – The Salesforce ID of the object to delete. Must be a non-empty string.
• Returns:
A promise that resolves when the object is successfully deleted.
• Throws Error:
If the deletion fails.
await SalesforceRequests.Contact.deleteObjectById(contact.Id);
Deletes a Salesforce object using its type and the ID field from the given object.
• Parameters:
record – The object containing an Id field, which will be used to perform the deletion.
• Returns:
A promise that resolves when the object is successfully deleted.
• Throws Error:
If the deletion fails.
await SalesforceRequests.Contact.deleteObject(contactTwo);
Attempts to update a Salesforce object and expects the update to fail.
Used in negative test scenarios where an update should be rejected by the system.
• Parameters:
id – The ID of the object to update. Must be a non-empty string.
data – The update payload expected to cause a failure.
autoAssign – Optional; whether to allow Salesforce auto-assignment. Defaults to true.
When set to false, adds header Sforce-Auto-Assign: FALSE.
• Throws Error:
If the update unexpectedly succeeds.
await SalesforceRequests.Contact.updateObjectExpectFailure(contact.Id, { Birthdate: "Invaliddate" });
Waits until a specific field on a record has the expected value. Only one record must match.
Polls repeatedly for up to totalDurationMs milliseconds (default: 30000).
• Parameters:
field – The field name to check.
value – The expected value for the field.
totalDurationMs – Optional; total polling duration in milliseconds. Defaults to 30000.
• Returns:
A promise resolving to the updated object record when the field matches the required value.
• Throws Error:
Throws if zero or multiple matching records are not found within the timeout.
await SalesforceRequests.Contact.getObjectWhenField('Email', 'user@example.com');
Waits until the specified field on the given object record equals the required value.
Polls repeatedly for up to totalDurationMs milliseconds (default is 30000 ms).
• Parameters:
record – The existing object record (must have an Id).
field – The field name to check.
requiredValue – The expected value for the field (string | number | boolean | undefined | null)
totalDurationMs – Optional; total polling duration in milliseconds. Defaults to 30000.
• Returns:
A promise resolving to the updated object record when the field matches the required value.
• Throws Error:
If the polling times out or an error occurs.
await SalesforceRequests.Contact.getThisObjectWhenField(contact, 'Email', 'user@example.com');
Retrieves a single Salesforce object of the specified type matching the given SOQL WHERE clause,
retrying until exactly one record is found or the timeout expires.
Uses SOQLQueryWhenExactlyOneValue to poll the query repeatedly up to totalDurationMs.
• Parameters:
whereClause – The SOQL WHERE clause (without the ‘WHERE’ keyword).
totalDurationMs – Optional; maximum time in milliseconds to retry. Defaults to 30000.
• Returns:
A promise resolving to the object of type T.
• Throws Error:
If zero or multiple matching records are not found within the timeout.
const contact = await SalesforceRequests.Contact.getObjectWhenWhere('Contact', "Email = 'a@example.com'", 60000);
Waits until the specified field on the given object record is not null or undefined.
Polls repeatedly for up to totalDurationMs milliseconds (default: 30000).
• Parameters:
record – The existing object record (must have an Id).
field – The field name to check.
totalDurationMs – Optional; total polling duration in milliseconds. Defaults to 30000.
• Returns:
A promise resolving to the updated object record when the field is non-null.
• Throws Error:
If polling times out or an error occurs.
contact = await SalesforceRequests.Contact.getThisObjectWhenFieldNOTNull(contact, 'Phone');
Waits until the specified field on the given object record is null or undefined.
Polls repeatedly for up to totalDurationMs milliseconds (default: 30000).
• Parameters:
record – The existing object record (must have an Id).
field – The field name to check.
totalDurationMs – Optional; total polling duration in milliseconds. Defaults to 30000.
• Returns:
A promise resolving to the updated object record when the field is null or undefined.
• Throws Error:
If polling times out or an error occurs.
contact = await SalesforceRequests.Contact.getThisObjectWhenFieldNull(contact, 'Phone');
Waits until the specified field on the given object record is NOT equal to the unrequiredValue.
Polls repeatedly for up to totalDurationMs milliseconds (default: 30000).
• Parameters:
record – The existing object record (must have an Id).
field – The field name to check.
unrequiredValue – The value that the field should NOT equal (string | number | boolean | undefined | null).
totalDurationMs – Optional; total polling duration in milliseconds. Defaults to 30000.
• Returns:
A promise resolving to the updated object record when the field is different from the unrequiredValue.
• Throws Error:
If polling times out or an error occurs.
contact = await SalesforceRequests.Contact.getThisObjectWhenFieldNOTEqualsValue(contact, 'Status', 'Pending');
Ensures that a Salesforce object of the specified type does not exist.
• Parameters:
id – The ID of the Salesforce object to check for non-existence.
• Returns:
A promise that resolves if no object exists with the given ID.
• Throws Error:
Throws if an object with the given ID exists.
await SalesforceRequests.Contact.ensureNoObjectExistsById('0031t00000XXXXXAAA');
Ensures that no Salesforce object of the specified type exists with the given field-value pair.
• Parameters:
field – The field name to check (e.g., ‘Email’).
value – The value the field must NOT match (string | number | boolean | undefined | null).
totalDurationMs – Optional; duration in milliseconds to keep retrying. Defaults to 30000.
• Returns:
A promise that resolves if no matching object exists.
• Throws Error:
Throws if any matching record is found.
await SalesforceRequests.Contact.ensureNoObjectExistsByField('Email', 'no-reply@example.com', 60000);
Ensures that no Salesforce object of the specified type exists matching the given SOQL WHERE clause.
• Parameters:
whereClause – The SOQL WHERE clause (without the ‘WHERE’ keyword).
totalDurationMs – Optional; total duration in milliseconds to keep retrying. Default is 30000.
• Returns:
A promise that resolves if no matching objects exist.
• Throws Error:
Throws if any matching objects are found or if a query error occurs.
await SalesforceRequests.Contact.ensureNoObjectExistsByWhere(`email = 'notgoingtobefound@example.com'`, 10000);
Ensures that a Salesforce object of the specified type does not exist.
• Parameters:
data – The data object containing an ‘Id’ property.
• Returns:
A promise that resolves if no object with the given ID exists.
• Throws Error:
Throws if an object with the extracted ID exists or if the check fails.
await SalesforceRequests.Contact.ensureNoObjectExists({ Id: '0031t00000XXXXXAAA' });