Retrieve and Automate App Analytics Data

Learning Objectives

After completing this unit, you’ll be able to:

• Set up your License Management Org (LMO) to use App Analytics.
• Create an App Analytics query request and retrieve data.
• Automate App Analytics query requests using Apex.

Get Ready to Use App Analytics

Now that Robert has a good understanding of App Analytics data types, he retrieves App Analytics data using Salesforce CLI. To get started, he completes a few necessary setup tasks. You can follow along in your own LMO.

Complete Prerequisites

Like Robert, you’re an established AppExchange partner with solutions on AppExchange, so it’s likely that your org is ready to go. Still, it’s a good idea to review this list of prerequisites. If you need to set up your LMO, this is the process to follow. 

1. Use your License Management Org (LMO) to track all Salesforce users who install your managed package. Typically, as an AppExchange partner, you use your Partner Business Org (PBO) as your LMO.
2. Install the LMA in your LMO. If you’re using your PBO as your LMO, you’re all set—the LMA is automatically installed for you. If you need to install the LMA, read Get Started with the License Management App.
3. Register your security-reviewed managed package with the LMA. If you haven’t done this yet, follow the directions in Associate a Package with the License Management App.
4. In your LMO, create an App Analytics Admin permission set that includes create and read access on the AppAnalyticsQueryRequest object. Assign this permission set to non-Admin users who need to create App Analytics requests. Read Create Permission Sets if you need instructions.
5. Set up the CLI using the Salesforce CLI Setup Guide.

Request and Retrieve App Analytics Data

To retrieve and visualize App Analytics data, you follow this sequence.

1. Use Salesforce CLI to create an App Analytics query request and retrieve your CSV file.
2. Automate requests using Apex triggers.
3. Integrate your App Analytics and LMA data in CRM Analytics.
4. Create a dashboard and lenses in CRM Analytics.

We walk through steps 1 and 2 in this unit, and steps 3 and 4 in the next unit.

First, the request. Robert needs package usage summary data for 3 months. He uses these query specifications.

Here’s the step-by-step process that Robert uses—and you can, too.

1. Log in to your LMO using this Salesforce CLI command.

sf org login web -a YourPBO
You see output like:

Successfully authorized robert.bullard@getcloudyconsulting.com with org ID 00DXXXXXXXXXXXXXXX

2. Insert a query request record using the AppAnalyticsQueryRequest SOAP API object. If you’re working in your LMO, use one of your own package IDs. If you’re working in your hands-on org, use this package ID: 033xx00SIMsmall.

sf data create record -s AppAnalyticsQueryRequest -v "StartTime=2021-01-01T00:00:00Z EndTime=2021-04-01T00:00:00Z DataType=PackageUsageSummary PackageIds=033xx00SIMsmall" -o YourPBO

3. Save the AppAnalyticsQueryRequest ID that’s returned by the CLI.

Successfully created record: 0XI1U000000XdrAWAS

4. Monitor the status of your query.

sf data get record -s AppAnalyticsQueryRequest -i 0XI1U000000XdrAWAS -o YourPBO

You see output like:

Getting Record... done
attributes:
  type: "AppAnalyticsQueryRequest"
  url:
"https://pa-production-pickup..../c72c98bb-70fb-42f7-ad01-2863a6984aef_results.csv?/services/data/v50.0/sobjects/AppAnalyticsQueryRequest/0XI1U000000XdrAWAS"
Id: "0XI1U000000Xe3zWAC"
IsDeleted: null
Name: "AAQR-53754"
CreatedDate: "2021-04-15T20:36:05.000+0000"
CreatedById: "0051U0000089WFkQAM"
LastModifiedDate: "2021-04-15T20:36:36.000+0000"
LastModifiedById: "0051U000000yUSJQA2"
SystemModstamp: "2021-04-15T20:36:36.000+0000"
LastViewedDate: "2021-04-15T20:36:05.000+0000"
LastReferencedDate: "2021-04-15T20:36:05.000+0000"
DataType: "PackageUsageSummary"
StartTime: "2021-01-01T00:00:00.000+0000"
EndTime: "2021-04-01T00:00:00.000+0000"
RequestState: "Pending"
DownloadUrl: null
DownloadExpirationTime: null
ErrorMessage: null
PackageIds: "033xx00SIMsmall"
OrganizationIds: null
DownloadSize: null

The DownloadUrl field is null while the query is processing. It’s populated within a couple of minutes when the query is complete. The DownloadUrl field is unique to your request and provides a secure way to retrieve your data, but it expires after 60 minutes, so retrieve it in a timely manner.

5. Copy and paste the DownloadUrl into any browser to download your CSV file. The DownloadUrl is many lines of code long so make sure you copy the whole thing.

6. Rename the file PackageSummaries3Months.csv and save it on your local drive.

Automate App Analytics Requests with Apex

To visualize his data, Robert could upload his CSV file into CRM Analytics. That’s one way to get data into an org, but manual processing is so outdated. Let’s create some code that automatically handles the whole process. 

Robert has a variety of automation options, including but not limited to:

• Custom API integrations using REST or SOAP API calls
• Salesforce DX automation using the CLI
• Salesforce flows
• Apex triggers

Robert chooses Apex because it integrates well into CRM Analytics. Apex also keeps Cloudy Health’s LMA and App Analytics data in the Salesforce ecosystem where it can be accessed by all Salesforce state-of-the-art tools. Plus, Apex works well with the summarized data Robert needs. Later, if he wants to access other data types or sees an increase in log data volume, Robert can define a different type of custom integration that adapts to his evolving query needs.

The Apex code Robert builds looks for new query request records, monitors them, retrieves the data, and stores the data in a custom object in his LMO. Pretty slick! Plus, this code frees up his time so he can focus on data analysis and visualization instead of data retrieval. Here are the high-level steps Robert follows to automate his App Analytics requests. You can follow along in your own LMO.

Our Apex code joins your App Analytics data to your LMA package data, but for various technical reasons doesn’t join the LMA license information. However, a sample dataflow is available in this GitHub repo. To learn more about how to integrate LMA data with App Analytics data, read Get App Smart: How to Use AppExchange App Analytics—Part 2.

1. Create an Apex trigger that fires when the request is complete and the file is ready to download.
2. Create a remote site setting to enable your LMO to use Apex to retrieve the data.
3. Create a custom object and custom fields to hold the package usage summary data.
4. Write Apex code to retrieve the CSV file and insert the data.

Nice! Robert automated the downloading of his App Analytics query requests. Now he needs one last bit of Apex code to automatically submit the request for each package in his LMO using Scheduled Apex. You can follow along in your own LMO.

1. Click and then click Setup.
2. In the Quick Find box, search for and select Apex Classes.
3. Click New.
4. Copy and paste this code into the code editor.

   global with sharing class ScheduledRequestSubmitter Implements Schedulable { global void execute(SchedulableContext ctx) { List<AppAnalyticsQueryRequest> aaqrList = new List<AppAnalyticsQueryRequest>(); Date s = Date.today().addMonths(-1).toStartOfMonth(); Date e = Date.today().toStartOfMonth().addDays(-1); for (sfLma__Package__c p: [select sfLma__Package_ID__c from sfLma__Package__c]) { AppAnalyticsQueryRequest aaqr = new AppAnalyticsQueryRequest(); aaqr.DataType = 'PackageUsageSummary'; aaqr.StartTime = (Datetime) s; aaqr.EndTime = (DateTime) e; aaqr.PackageIds = p.sfLma__Package_ID__c; aaqrList.add(aaqr); } insert aaqrList; }

5. Click Save.
6. Click Apex Classes.
7. Click Schedule Apex.
8. For the job name, enter ThirdDaySummaries.
9. Click the lookup button next to Apex class and enter Scheduled. In the search results, click ScheduledRequestSubmitter.
10. Select Monthly for the frequency and set On day to 3.
11. Select the start and end dates, and a preferred start time.
12. Click Save.

Fantastic! Now, on the third day of each month, the previous month’s logs are automatically downloaded and stored in a custom object.

In this unit you learned how to use the CLI to create an App Analytics query request and retrieve data. You also learned how to automate your data requests and retrieval with Apex code. Whew! But wait, there’s more. Continue to the next unit to learn how to integrate App Analytics and LMA data in CRM Analytics, and create lenses and dashboards.

Resources

• Developer Documentation: Salesforce CLI Setup Guide
• Developer Documentation: Apex Developer Guide
• Blog Post: Get App Smart: How to Use AppExchange App Analytics
• Blog Post: Get App Smart: How to Use AppExchange App Analytics Part 2
• Blog Post: Automate AppAnalytics—AWS Stack
• Salesforce Help: Upload a CSV File to Create a Dataset