Async SOQL Async SOQL Use Cases
"targetFieldMap" : {
"String__c" : "String__c"
},
"targetObject" : "test__b",
"targetValueMap" : { }
}, {
"jobId": "08PD000000000001",
"message": "Complete",
"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",
"status": "Complete",
"targetObject": "TargetObject__c",
}
}
"targetFieldMap": {"firstField__c":"firstFieldTarget__c",
"secondField__c":"secondFieldTarget__c" }
Canceling a Query
You can cancel a query using an HTTP DELETE request by specifying its jobId.
https://yourInstance.salesforce.com/services/data/v38.0/async-queries/jobId
Note: Canceling a query that has already completed has no effect.
Handling Errors in Async SOQL Queries
Two different types of errors can occur during the execution of an Async SOQL query.
•
An error in the query execution
•
One or more errors writing the results into the target object
Problems in executing the job cause some errors. For example, an invalid query was submitted, one of the Async SOQL limits was exceeded, or the query caused a problem with the underlying infrastructure. For these errors, the response body includes a status of
Failed. The message parameter provides more information on the cause of the failure.
Other times, the query executes successfully but encounters an error while attempting to write the results to the target object. Because of the volume of data involved, capturing every error is inefficient. Instead, subsets of the errors generated are captured and made available. Those errors are captured in the BackgroundOperationResult object and retained for seven days. You can query this object with the Async SOQL query jobID to filter the errors for the specific Async SOQL query. Async SOQL job info is retained for a year.
Async SOQL Use Cases
Understand some of the common Async SOQL use cases.
Customer 360 Degree and Filtering
In this use case, administrators load various customer engagement data from external sources into Salesforce big objects and then process the data to enrich customer profiles in Salesforce. The goal is to store customer transactions and interactions, such as point-of-sale data, orders, and line items in big objects and then process and correlate that data with your core CRM data. Anchoring customer
20
Async SOQL Async SOQL Use Cases transactions and interactions with core master data provides a richer 360-degree view that translates into an enhanced customer experience.
The following example analyzes the customer data stored in the Rider record of a car-sharing service. The source big object, Rider_Record_b, has a lookup relationship with the Contact object, allowing for an enriched view of the contact’s riding history. You can see that the query includes Rider__r.FirstName, Rider__r.LastName, Rider__r.Email as part of the
SELECT
clause. This example demonstrates the ability to join big object data (Rider_Record__b) with Contact data (FirstName, LastName, Email) in a single Async SOQL query.
Example URI
https://yourInstance—api.salesforce.com/services/data/v38.0/async-queries/
Example POST request body
{
"query": "SELECT End_Location_Lat__c, End_Location_Lon__c, End_Time__c,
Start_Location_Lat__c, Start_Location_Lon__c, Start_Time__c,
Car_Type__c, Rider__r.FirstName, Rider__r.LastName,
Rider__r.Email
FROM Rider_Record__b WHERE Star_Rating__c = '5'",
"targetObject": "Rider_Reduced__b",
"targetFieldMap": {"End_Location_Lat__c":"End_Lat__c",
"End_Location_Lon__c":"End_Long__c",
"Start_Location_Lat__c": "Start_Lat__c",
"Start_Location_Lon__c": "Start_Long__c",
"End_Time__c": "End_Time__c",
"Start_Time__c": "Start_Time__c",
"Car_Type__c": "Car_Type__c",
"Rider__r.FirstName": "First_Name__c",
}
"Rider__r.LastName": "Last_Name__c",
"Rider__r.Email": "Rider_Email__c"
}
Example POST response body
{
"jobId": "08PB000000000NA",
"message": "",
"query": "SELECT End_Location_Lat__c, End_Location_Lon__c, End_Time__c,
Start_Location_Lat__c, Start_Location_Lon__c, Start_Time__c,
Car_Type__c, Rider__r.FirstName, Rider__r.LastName,
Rider__r.Email
FROM Rider_Record__b WHERE Star_Rating__c = '5'",
"status": "New",
"targetFieldMap": {"End_Location_Lat__c":"End_Lat__c",
"End_Location_Lon__c":"End_Long__c",
"Start_Location_Lat__c": "Start_Lat__c",
"Start_Location_Lon__c": "Start_Long__c",
"End_Time__c": "End_Time__c",
21
Async SOQL Async SOQL Use Cases
}
"Start_Time__c": "Start_Time__c",
"Car_Type__c": "Car_Type__c",
"Rider__r.FirstName": "First_Name__c",
"Rider__r.LastName": "Last_Name__c",
"Rider__r.Email": "Rider_Email__c"
},
"targetObject": "Rider_Reduced__b"
Field Audit Trail
Field Audit Trail lets you define a policy to retain archived field history data up to 10 years, independent of field history tracking. This feature helps you comply with industry regulations related to audit capability and data retention.
You define a Field Audit Trail policy using the
HistoryRetentionPolicy
object for each object you want to archive. The field history data for that object is then moved from the History related list into the
FieldHistoryArchive
object at periodic intervals, as specified by the policy. For more information, see the Field Audit Trail Implementation Guide .
You can use Async SOQL to query archived fields stored in the
FieldHistoryArchive
object. You can use the
WHERE
clause to filter the query by specifying comparison expressions for the
FieldHistoryType
,
ParentId
, and
CreatedDate
fields, as long as you specify them in that order.
This example queries archived accounts created within the last month.
Example URI
https://yourInstance.salesforce.com/services/data/v38.0/async-queries/
Example POST request body
{
"query": "SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue
FROM FieldHistoryArchive WHERE FieldHistoryType = ‘Account’
AND CreatedDate > LAST_MONTH”,
"targetObject": "ArchivedAccounts__b",
"targetFieldMap": {"ParentId": "ParentId__c",
"FieldHistoryType": "FieldHistoryType__c",
"Field": "Field__c",
"Id": "Id__c",
"NewValue": "NewValue__c",
}
"OldValue": "OldValue__c"
}
Example POST response body
{
"jobId": "07PB000000006PN",
"message": "",
"query": "SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue
FROM FieldHistoryArchive WHERE FieldHistoryType = ‘Account’ AND CreatedDate
> LAST_MONTH”,
22
Async SOQL Async SOQL Use Cases
"status": "New",
"targetObject": "ArchivedAccounts__b",
"targetFieldMap": {"ParentId": "ParentId__c",
"targetObject": "Rider_Reduced__b" }
}
Note: All number fields returned from a SOQL query of archived objects are in standard notation, not scientific notation, as in the number fields in the entity history of standard objects.
Event Monitoring
Login Forensics and Data Leakage Detection, currently in pilot, enable you to track who is accessing confidential and sensitive data in your Salesforce org. You can view information about individual events or track trends in events to swiftly identify unusual behavior and safeguard your company’s data. This feature is useful for compliance with regulatory and audit requirements.
Note: These features are available to select customers through a pilot program. To be nominated to join this pilot program, contact salesforce.com.
In the current pilot, you can monitor data accessed through API calls, which covers many common scenarios because more than 50% of SOQL queries occur using the SOAP, REST, or Bulk APIs. Key information about each query, such as the Username, UserId, UserAgent, and SourceIP, is stored in the ApiEvent object. You can then run SOQL queries on this object to find out details of user activity in your org.
For example, let’s say you want to know everyone who viewed the contact record of your company’s CEO, Jane Doe. The key to this query is the CEO’s contact record ID: 003D000000QYVZ5. (You can also query the ID using SOQL:
SELECT Id FROM Contact
WHERE Name = 'Jane Doe'
). You can use the following Async SOQL query to determine all users who saw their contact information, including when, how, and where they saw it.
Example URI
https://yourInstance—api.salesforce.com/services/data/v38.0/async-queries/
Example POST request body
{
"query": "SELECT Soql, SourceIp, Username, EventTime FROM ApiEvent
WHERE RecordInfo Like '%003D000000QYVZ5%'",
"targetObject": "QueryEvents__c",
"targetFieldMap": {"Soql":"QueryString__c","SourceIp":"IPAddress__c",
"Username":"User__c", "EventTime":"EventTime__c",
"UserAgent":"UserAgent__c"
}
}
Example POST response body
{
"jobId": "05PB000000001PQ",
"message": "",
"query": "SELECT Soql, SourceIp, Username, EventTime
FROM ApiEvent WHERE RecordInfo Like '%003D000000QYVZ5%'",
23
Async SOQL Async SOQL Use Cases
"status": "Complete",
"targetObject": "QueryEvents__c",
"targetFieldMap": {"Soql":"QueryString__c","SourceIp":"IPAddress__c",
"Username":"User__c", "EventTime":"EventTime__c", "UserAgent":"UserAgent__c"
}
}
Note: All number fields returned from a SOQL query of archived objects are in standard notation, not scientific notation, as in the number fields in the entity history of standard objects.
If you ask this question on a repeated basis for audit purposes, you can automate the query using a cURL script.
curl -H "Content-Type: application/json" -X POST -d
'{"query": "SELECT Soql, SourceIp, UserAgent, Username, EventTime FROM ApiEvent WHERE
RecordInfo Like'%003D000000QYVZ5%'","targetObject": "QueryEvents__c",
"targetFieldMap": {"Soql":"QueryString__c", "SourceIp":"IPAddress__c", "Username":"User__c",
"EventTime":"EventTime__c",UserAgent}}'
"https://
yourInstance
.salesforce.com/services/data/v35.0/async-queries" -H
"Authorization: Bearer 00D30000000V88A!ARYAQCZOCeABy29c3dNxRVtv433znH15gLWhLOUv7DVu.
uAGFhW9WMtGXCul6q.4xVQymfh4Cjxw4APbazT8bnIfxlRvUjDg"
Another event monitoring use case is to identify all users who accessed a sensitive field, such as Social Security Number or Email. For example, you can use the following Async SOQL query to determine the users who saw social security numbers and the records in which those numbers were exposed.
Example URI
https://yourInstance—api.salesforce.com/services/data/v38.0/async-queries/
Example POST request body
{
"query": "SELECT Soql, Username, RecordIds, EventTime FROM ApiEvent
WHERE Soql Like '%SSN__c%'",
"targetObject": "QueryEvents__c",
"targetFieldMap": {"Soql":"QueryString__c", "Username":"User__c",
}
"EventTime":"EventTime__c", "RecordIds":"Records_Seen__c"
}
Example POST response body
{
"jobId": "08PB000000001RS",
"message": "",
"query": "SELECT Soql, Username, RecordIds, EventTime FROM ApiEvent
WHERE Soql Like '%SSN__c%'",
"status": "Complete",
"targetFieldMap": {"Soql":"QueryString__c", "Username":"User__c",
24
