Using the Setup Audit Trail API - the best kept secret of Winter '16

The Setup Audit Trail has been around for a long time. It's part of the Salesforce trust platform and is built into every edition. It tracks changes in setup by administrators such as adding new users, activation of users, changes in permissions including escalations of privilege, and changes to metadata like the creation of fields or deletion of objects. 

Until very recently, Setup Audit Trail was only available to manually download to a CSV (comma separated values) file using a link on a page in setup. I kept hearing how customers hated putting manual processes in place to click the link once a month as well as merge newly downloaded CSV files into previous exports. It made audit and compliance use cases much harder than what anyone wanted. Everyone was asking to integrate the Setup Audit Trail using the API so they could schedule regular, automated downloads of audit trail data to analytics and SIEM tools.

Starting with Winter '16, we added the Setup Audit Trail to the API as the SetupAuditTrail sObject. There are a couple key use cases that you might want to try out using a tool like Workbench.

1. I want to know everyone who logged in as a particular end-user:
SELECT Action, CreatedById, CreatedDate, DelegateUser, Display, Id, Section 
FROM SetupAuditTrail 
WHERE CreatedBy.Name = 'Jim Rivera' 
ORDER BY CreatedDate DESC NULLS FIRST LIMIT 10

2. I want to know everyone an admin user logged in as:

SELECT Action, CreatedBy.Name, CreatedDate, DelegateUser, Display, Id, Section 
FROM SetupAuditTrail 
WHERE DelegateUser = 'at@xx.com' 
ORDER BY CreatedDate DESC NULLS FIRST LIMIT 10

3. I want to know everything that any users with a specific profile (or role) did in setup:

SELECT Action, CreatedBy.Profile.Name, CreatedDate, DelegateUser, Display, Id, Section 
FROM SetupAuditTrail 
WHERE CreatedBy.Profile.Name = 'EMEA VP' 
ORDER BY CreatedDate DESC NULLS FIRST LIMIT 10

4. I want to know every user who was 'frozen' in the last week

SELECT Action, CreatedById, CreatedDate, DelegateUser, Display, Id, Section 
FROM SetupAuditTrail 
WHERE Action = 'frozeuser' AND CreatedDate = Last_n_Days:7 
ORDER BY CreatedDate DESC NULLS FIRST LIMIT 10

5. I want to know everything a specific user did last week

SELECT Action, CreatedById, CreatedDate, DelegateUser, Display, Id, Section 
FROM SetupAuditTrail 
WHERE CreatedBy.Name = 'Adrian Kunzle' AND CreatedDate = Last_n_Days:7 
ORDER BY CreatedDate DESC NULLS FIRST LIMIT 10

I use 'Limit 10' to just test the queries and keep them from taking a long time to return which is a good idea when experimenting with new queries.

Once you know what kind of queries you can write, you can create incredible apps that combine the SetupAuditTrail API with an app building platform like Node.js on Heroku:

The application above was created by the incredible Alessandro. You can download the source code from his Github repository or try it out with this free Heroku app.

You can also explore Setup Audit Trail data using an analytics platform like Wave:

The Setup Audit Trail is a powerful way of tracking important administrative audit events and now it's even more accessible through the API.