Object Reference for Salesforce and Force.com
jNewer Version Available
LoginEvent
Represents a trackable user login event in your
org. In the Real-Time Events pilot, only UI logins with username and password are
captured. This object is available in API version 36.0 and
later.
Supported Calls
describeSObjects(), query()
Special Access Rules
Accessing this object requires View Login Forensics Events and API Enabled user permissions.
Fields
Working with AdditionalInfo
AdditionalInfo enables you to extend the login event with custom data that can be queried later. For example, you can capture a correlation ID when a user logs in from an external system that shares that unique ID. This process enables tracking logins across systems. To store data with LoginEvent, begin all AdditionalInfo field names with x-sfdc-addinfo-{fieldname}. 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}.
- Fields can contain only alphanumeric and “_” (underscore) characters.
- Field names must be between 2 and 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.
- Only the first 30 valid field names are stored in AdditionalInfo. Field names are not necessarily stored in the same order in which they were passed to authentication.
When determining field values, keep the following in mind:
- 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.
- Additional 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 are not guaranteed to be stored in the same order that they were passed into the authentication.
- When AggregationFieldName 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
Here’s an example of passing additional information via the command
line.
1curl https://yourInstance.salesforce.com/services/oauth2/token -d "grant_type=password" -d
2"client_id=3MVG9PhR6g6B7ps4RF_kNPoWSxVQstrazijsE8njPtkpUzVPPffzy8
3jIoRE6q9rPznNtlsqbP9ob8kUfMjXXX" -d "client_secret=4180313776440635XXX" -d
4"username=user@company.com" -d "password=123456" -H "X-PrettyPrint:1" -H
5"x-sfdc-addinfo-correlationid:
6d18c5a3f-4fba-47bd-bbf8-6bb9a1786624"How to Pass Additional Information in Java
Here’s an example of passing additional information in
Java.
1//adding additional info headers ..
2Map<String, String> httpHeaders = new HashMap<String,String>();
3httpHeaders.put("x-sfdc-addinfo-fieldname1" /* additional info field*/ ,
4"d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);
5httpHeaders.put("x-sfdc-addinfo-fieldname2" /* additional info field*/ ,
6"d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);
7ConnectorConfig config = new ConnectorConfig();
8config.setUsername(userId);
9config.setPassword(passwd);
10config.setAuthEndpoint(authEndPoint);
11config.setProxy(proxyHost, proxyPort);
12//setting additional info headers
13for (Map.Entry<String, String> entry : httpHeaders.entrySet()) {
14config.setRequestHeader(entry.getKey(), entry.getValue());
15}
16// Set the username and password if your proxy must be authenticated
179
18LoginEvent
19config.setProxyUsername(proxyUsername);
20config.setProxyPassword(proxyPassword);
21try {
22EnterpriseConnection connection = new EnterpriseConnection(config);
23// etc.
24} catch (ConnectionException ce) {
25ce.printStackTrace();
26}Standard SOQL Usage
Currently, the only supported SOQL function on LoginEvent is WHERE, and you can only use comparison
operators (=, <, >, <=, and >=) on the final expression in a WHERE clause. The != operator isn’t supported.
LoginEvent allows filtering over two ordered fields: EventDate and
EventIdentifier. There’s a catch here; your query won’t work
unless you use the correct order and combination of these fields. The following list
provides some examples of valid and invalid queries:
-
Unfiltered
-
Valid—Contains no WHERE
clause, so no special rules
apply.
1SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId 2FROM LoginEvent
-
Valid—Contains no WHERE
clause, so no special rules
apply.
-
Filtered on EventDate
-
Valid—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 Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId 2FROM LoginEvent 3WHERE EventDate<=2014-11-27T14:54:16.000Z -
Valid—You can filter on EventDate using
date
literals.
1SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId 2FROM LoginEvent 3WHERE EventDate<=TODAY
-
Valid—You can filter solely on EventDate, but
single filters on other fields fail. You can also use a comparison operator
in this query
type.
-
Filtered on EventDate and EventIdentifier
-
Valid—Successful queries on LoginEvent filter over both
fields.
1SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId 2FROM LoginEvent 3WHERE EventDate=2014-11-27T14:54:16.000Z and EventIdentifier='f0b28782-1ec2-424c-8d37-8f783e0a3754' -
Invalid—Queries on LoginEvent with EventDate and standard date
literals.
1SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId 2FROM LoginEvent 3WHERE EventDate=TODAY and EventIdentifier='f0b28782-1ec2-424c-8d37-8f783e0a3754' -
Invalid—Filtering only on EventDate with <= or >= operator and
EventIdentifier field isn’t
supported.
1SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId 2FROM LoginEvent 3WHERE EventDate<=2014-11-27T14:54:16.000Z and EventIdentifier='f0b28782-1ec2-424c-8d37-8f783e0a3754'
-
Valid—Successful queries on LoginEvent filter over both
fields.
Async SOQL Usage
With Async SOQL, you can filter on any field in LoginEvent and use any comparison operator in your query.
Example: Get Yesterday’s Successful Logins
SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId FROM LoginEvent WHERE EventDate<Yesterday AND Status=’Success’