Platform Events Developer Guide
jApiEvent
Supported Calls
describeSObjects(), query()
Special Access Rules
Accessing this object requires either the Salesforce Shield or Salesforce Event Monitoring add-on subscription and the View Real-Time Event Monitoring Data user permission.
Fields
| Field | Details |
|---|---|
| ActionName |
|
| AdditionalInfo |
|
| ApiType |
|
| ApiVersion |
|
| Application |
|
| BotId |
|
| BotSessionIdentifier |
|
| Client |
|
| ConnectedAppId |
|
| ElapsedTime |
|
| EvaluationTime |
|
| EventDate |
|
| EventIdentifier |
|
| LoginHistoryId |
|
| LoginKey |
|
| Operation |
|
| PlannerId |
|
| Platform |
|
| PolicyId |
|
| PolicyOutcome |
|
| QueriedEntities |
|
| Query |
|
| Records |
|
| RelatedEventIdentifier |
|
| RequestIdentifier |
|
| RowsProcessed |
|
| RowsReturned |
|
| SessionKey |
|
| SessionLevel |
|
| SourceIp |
|
| UserAgent |
|
| UserId |
|
| Username |
|
Working With the AdditionalInfo Field
AdditionalInfo enables you to extend the API event with custom data that can be queried later. For example, you can capture a correlation ID when a user executes a SOQL query from an external system that shares that unique ID. This process enables tracking API calls across systems. To store data with ApiEvent, begin all AdditionalInfo field names with x-sfdc-addinfo-{field name}. For example, a valid field assignment is x-sfdc-addinfo-correlation_id = ABC123 where x-sfdc-addinfo-correlation_id is the field name and ABC123 is the field value.
When defining field names, note the following:
- x-sfdc-addinfo- is case-insensitive; x-sfdc-addinfo-{field name} is the same as X-SFDC-ADDINFO-{field name} and x-SfDc-AdDiNfO-{field name}.
- Fields can contain only alphanumeric and "_" (underscore) characters.
- Field names must be from 2 through 29 characters in length, excluding x-sfdc-addinfo-.
- Field names that don’t start with x-sfdc-addinfo- are ignored.
- Names that contain invalid characters after x-sfdc-addinfo- are ignored, and nothing is stored. For example, a valid field name is x-sfdc-addinfo-correlation_id but x-sfdc-addinfo-correlation->id isn’t valid.
- Only the first 30 valid field names are stored in AdditionalInfo. If you store two valid field names—for example, x-sfdc-addinfo-correlation_id and x-sfdc-addinfo-correlation_number— you can store 28 extra field names. Field names aren’t necessarily stored in the same order in which they were passed to authentication.
- You can’t use existing API field names as AdditionalInfo names in the HTTP header. If the AdditionalInfo name conflicts with an object’s API name, the field value isn’t stored. For example, the HTTP header X-SFDC-ADDINFO-UserId='abc123' doesn’t get stored in AdditionalInfo.
- Extra field values can contain only alphanumeric, "_," and "-" characters.
- Field values must be 255 characters in length or fewer. If a field value exceeds 255 characters, only the first 255 characters are stored, and the rest are truncated.
- Field values that contain invalid characters are saved with a field header of Empty String ("").
- Only the first 30 valid field names are stored in the AdditionalInfo field. They aren’t guaranteed to be stored in the same order that they were passed into the authentication.
- When AggregationFieldName or PlatformEventMetrics is SourceIp, you can’t filter on AggregationFieldValue if its value is Salesforce.com IP.
How to Pass Additional Information by Using HTTP with cURL
1curl https://yourInstance.salesforce.com/services/data/v34.0/query?q=SELECT+Name+From+Account -H "X-PrettyPrint:1" -H "x-sfdc-addinfo-correlationid:
2d18c5a3f-4fba-47bd-bbf8-6bb9a1786624"Example of Using Java
1//adding additional info headers ..
2Map<String, String> httpHeaders = new HashMap<String,String>();
3httpHeaders.put("x-sfdc-addinfo-fieldname1" /* additional info field*/ , "d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);
4httpHeaders.put("x-sfdc-addinfo-fieldname2" /* additional info field*/ , "d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);
5
6ConnectorConfig config = new ConnectorConfig();
7config.setUsername(userId);
8config.setPassword(passwd);
9config.setAuthEndpoint(authEndPoint);
10config.setProxy(proxyHost, proxyPort);
11
12//setting additional info headers
13for (Map.Entry<String, String> entry : httpHeaders.entrySet()) {
14 config.setRequestHeader(entry.getKey(), entry.getValue());
15}
16// Set the username and password if your proxy must be authenticated
17 config.setProxyUsername(proxyUsername);
18 config.setProxyPassword(proxyPassword);
19 try {
20 QueryResult queryResult = connection.query("SELECT Id, Name FROM Account");
21 // etc.
22 } catch (ConnectionException ce) {
23 ce.printStackTrace();
24 }Standard SOQL Usage
ApiEvent allows filtering over two fields: EventDate and EventIdentifier. The only supported SOQL functions on the ApiEvent object are WHERE, ORDER BY, and LIMIT. In the WHERE clause, you can only use comparison operators (<, >, <=, and >=). The != operator isn’t supported. In the ORDER BY clause, you can only use EventDate DESC. Ascending order isn’t supported with EventDate, and EventIdentifier sorting isn’t supported.
Example of an Unfiltered Query
This query is valid because it doesn’t contain a WHERE clause. No special rules apply.
1SELECT ApiType, Client, ElapsedTime, QueriedEntities, Username
2FROM ApiEventExample of a Filtered Query
You can filter solely on EventDate, but single filters on other fields fail. You can also use a comparison operator in this query type.
1SELECT ApiType, Client, ElapsedTime, QueriedEntities, Username
2FROM ApiEvent
3WHERE EventDate>=2014-11-27T14:54:16.000Z