dx-app-analytics-query

name: dx-app-analytics-query description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use platform-soql-query)." metadata: cliTools: - tool: ["sf"] semver: ">=2.0.0" relatedSkills: - "platform-metadata-deploy" - "platform-soql-query" version: "1.0" domains: ["Developer Experience"] minApiVersion: "56.0"

App Analytics

When This Skill Owns the Task

Use dx-app-analytics-query when the work involves:

• Creating AppAnalyticsQueryRequest records via the REST/sObject API
• Configuring AppAnalyticsSettings via the Metadata API (simulation mode, opt-out)
• Understanding the query lifecycle: New → Pending → Complete → Expired → Failed
• Choosing between dataType values: PackageUsageSummary, PackageUsageLog, SubscriberSnapshot
• File format and compression options for analytics downloads
• Time-range filtering with startTime, endTime, availableSince
• Troubleshooting failed or expired analytics queries

Delegate elsewhere when the user is:

• Running standard CRM SOQL queries → platform-soql-query
• Building reports/dashboards on standard objects → reporting skills
• Deploying or retrieving generic metadata XML → platform-metadata-deploy / retrieving-metadata

Available Types

AppAnalyticsQueryRequest (REST/sObject API)

An asynchronous query request that ISV partners use to retrieve usage analytics data for their managed packages from the ISV Intelligence Data Lake. Records are created via POST /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest and polled via GET /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest/<id>. The system processes the query and provides a presigned download URL upon completion.

Fields (14 properties):

AppAnalyticsSettings (Metadata API)

Configuration settings for ISV App Analytics that control simulation mode and opt-out behavior. Deployed via the Metadata API (sf project deploy) or Tooling API.

Fields (2 properties):

Request Lifecycle

New → Pending → Complete → (download within expiration window)
                         → Expired (download URL no longer valid)
                         → Delivered (download confirmed received)
         → Failed (check errorMessage)
         → NoData (no matching records for the criteria)

Common Patterns

Query Package Usage Summary (last 7 days)

Create a record via the REST API:

POST /services/data/v60.0/sobjects/AppAnalyticsQueryRequest
Content-Type: application/json

{
  "DataType": "PackageUsageSummary",
  "StartTime": "<7-days-ago>T00:00:00Z",
  "EndTime": "<today-on-hour-boundary>T00:00:00Z",
  "PackageIds": "033XXXXXXXXXXXX",
  "FileType": "csv",
  "FileCompression": "gzip"
}

Poll the record via GET until RequestState reaches Complete, then download from DownloadUrl.

Incremental Data Retrieval

Set AvailableSince to the timestamp of your last successful query completion to avoid re-downloading data you already have.

Enable Simulation Mode for Testing

Deploy AppAnalyticsSettings via Metadata API with enableSimulationMode: true to query sample data without real subscribers.

High-Signal Gotchas

• AppAnalyticsQueryRequest is an sObject — create and poll records via the REST Data API (/sobjects/AppAnalyticsQueryRequest), NOT via Metadata API XML deployment.
• AppAnalyticsQueryRequest does NOT have Apex triggers and does NOT flow through custom objects or Flows.
• Download URLs expire — always check DownloadExpirationTime before attempting download.
• EndTime should be set on an hour boundary for consistent results.
• AvailableSince is inclusive — data indexed at exactly that timestamp will be included.
• PackageIds uses 033-prefix IDs, not 04t (package version) IDs.
• Data is processed asynchronously by the ISV Intelligence Data Lake infrastructure. There is no synchronous query option.
• FileType: parquet with FileCompression: snappy gives optimal performance for large datasets.

Output Format

Analytics task: <query / configure / troubleshoot>
Data type: <PackageUsageSummary / PackageUsageLog / SubscriberSnapshot>
Package IDs: <033-prefixed IDs>
Time range: <startTime> to <endTime>
File format: <csv|parquet> / <none|gzip|snappy>
Request state: <current state>
Next step: <poll for completion / download / investigate failure>