Salesforce Objects API

These SOQL query functions are for cases where the standard Salesforce Objects API doesn’t fit.

They let you run custom SOQL queries to retrieve data more flexibly and precisely.

---

SOQLQuery(queryString: string) : Promise<any>

Executes a SOQL query against Salesforce and returns the raw response.

• • Parameters:
  queryString – The SOQL query string to execute. Must be a valid SOQL statement.

• • Returns:
  A promise resolving to the query response object, or null if no matching records are found (NOT_FOUND error).

• • Throws Error:
  If any error other than NOT_FOUND is encountered during the request.

const response = await Playforce.SOQL.SOQLQuery(
  `SELECT Id FROM Contact WHERE Email = '${email}'`
);

if (response?.records?.[0]?.Id) {
    return await contactBase.getObjectById(response.records[0].Id);
}

throw new Error(`No contact found for email: ${email}`);

---

SOQLQueryExactlyOneValue(queryString: string) : Promise<string>

Executes a SOQL query expected to return exactly one record with exactly one field.

Throws an error if zero or multiple records are returned,
or if the record contains more than one field.

• • Parameters:
  queryString – The SOQL query string to execute.

• • Returns:
  A promise resolving to the single field’s value from the single record.

• • Throws Error:
  If the query returns zero records, multiple records, or records with multiple fields.

const id = await Playforce.SOQL.SOQLQueryExactlyOneValue(
  `SELECT Id FROM ${objectType} WHERE Email = '${email}'`
);
return await contactBase.getObjectById(id);

---

SOQLQueryWhenExactlyOneValue(queryString: string, totalDurationMs?: number) : Promise<string>

Repeatedly queries Salesforce with the given SOQL until exactly one record with one field is returned,
or until the timeout duration is reached.

• • Parameters:
  queryString – The SOQL query to execute.
  totalDurationMs – Maximum time in milliseconds to retry. Defaults to 30,000 ms.

• • Returns:
  A promise resolving to the single field’s value from the single record once found.

• • Throws Error:
  If the query does not return exactly one value within the timeout period.

const id = await Playforce.SOQL.SOQLQueryWhenExactlyOneValue(
  `SELECT Id FROM ${objectType} WHERE Email = '${email}'`
);
return await contactBase.getObjectById(id);