Considerations and requirements
You'll need a Teams or Enterprise Automation license to use this feature.
What is the Audit API?
The Audit API is one of three Gearset APIs, along with the Automation API and the Reporting API. It can provide the following information:
Deployment information:
Standard deployment information (e.g. who ran the deployment, when they did it, and the deployment status).
More granular deployment information, including:
all the objects that were deployed
why they were deployed (PA, change, deletion, etc.)
the modified information
relevant source and target information
the
SalesforceFinalDeploymentIdSalesforce Connections and if they are user owned or Team Shared
The linked work items (Jira, ADO, etc.)
Team Shared items auditing
Connected Services auditing
Anonymous Apex execution auditing
Note: This information is available for every deployment done through Gearset, including automation CI jobs and Compare and deploy.
Making your first Audit API requests
To use the Audit API, you'll need an API access token, which you can generate by following our tutorial: Creating a Gearset API access token. Once you have that, you're ready to start making API requests.
The Audit API is a REST API that returns JSON messages over HTTPS, and we'll be using the Audit API's dynamic documentation to query it.
First, log in with your access token by clicking on the
Authorizebutton:
Enter the authorization token that you got earlier, prefixed with the word
token:
Go to the Deployment audit section, and click on the
Try it outbutton:
To perform the query, fill in the time frame, enter any optional parameters for JiraTickets / AsanaTasks/ AzureDevOpsWorkItems (if required), and click
Execute.Note: The response can be pretty large, so we recommend that you make your time range as small as possible.
This will send off a request to the Audit API. Once executed, it presents the curl command used (so you can use it elsewhere) and the response. This can be copied or downloaded:
And here in the Response object is some of the deployment data that can be accessed:
What can I use the Audit API for?
An ideal question that can be answered using the Audit API would be: "which deployments in the time frame involved X metadata items?", where X represents some particularly restrictive metadata types that you want to keep a close eye on.
It can also be very useful for various auditing/compliance activities you may have to undertake, such as a SOX Compliance audit, where you need to prove a particular audit trail throughout your systems.
The answers to these questions can then be displayed in a spreadsheet (or an alternative visualization and/or graphing application that takes JSON), as with the following example:
FAQs
Q: Do customers need to be running Pipelines for the Audit API to work?
A: No. Audit API works for the whole Gearset app.
Q: Could this API be used to create a report showing which users deployed most often over a given period (e.g. a year)?
A: Yes, although the Reporting API can do that, too (its Deployment Frequency end-point is built specifically for that purpose).
Q: Can the results be filtered for deployments made to Production orgs? We have a few teams who would like to identify their power users.
A: Yes, TargetMetadataLocationType, found in both the Audit and the Deployment Frequency end-point (Reporting API), defines the target and says whether it's production or another target.
Q: Can I download the results in a different format?
A: The Audit API gives you a downloadable JSON format, but the Audit Reports capability does expose the 'Deployments' endpoint and allows downloading as CSV (note: this won't give you the exact component breakdown as part of the deployment though, so you'd need to use the API for that)