forcedotcom/sf-skills

dx-app-analytics-query

ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/forcedotcom/sf-skills --skill dx-app-analytics-query

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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):

FieldTypeDescription
DataTypestring (filterable)Type of analytics data. Values: PackageUsageSummary, PackageUsageLog, SubscriberSnapshot
RequestStatestring (filterable)Processing status. Values: New, Pending, Complete, Expired, Failed, NoData, Delivered
StartTimestringStart of time range for requested data
EndTimestringEnd of time range. Should be set on an hour boundary
AvailableSincestringLimits query to data indexed after this time (inclusive). Use for incremental retrieval
PackageIdsstringComma-delimited list of managed package IDs (033-prefix)
OrganizationIdsstringComma-delimited list of subscriber org IDs to filter results
DownloadUrlstringPresigned URL for downloading results. Populated when RequestState is Complete
DownloadSizelongSize in bytes of the result data file
DownloadExpirationTimestringTime at which the download URL expires
FileTypestring (filterable)Output format. Values: csv, parquet
FileCompressionstring (filterable)Compression. Values: none, gzip, snappy
QuerySubmittedTimestringTime the query was submitted to the Data Lake
ErrorMessagestringDiagnostic message for failed queries

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):

FieldTypeDescription
enableSimulationModeboolean (filterable)When true, allows querying sample usage logs for integration testing without real subscriber data
enableAppAnalyticsOptOutboolean (filterable)When true, opts this subscriber org out of AppExchange App Analytics data collection

Request Lifecycle

text
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:

bash
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

text
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>

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
forcedotcom
Community

design-systems-slds-apply

Apply SLDS-compliant UI using the correct blueprints, styling hooks, utility classes, and icons. Use when building any UI that needs SLDS, choosing between Lightning Base Components and SLDS Blueprints, applying styling hooks for theming, using utility classes for layout and spacing, or selecting icons. Triggers include \"build a modal\", \"create a form\", \"data table\", \"SLDS styling\", \"style with hooks\", \"add an icon\".

Installationen / 1h
1
GitHub Stars
1172
Aktualisiert
13. Nov.
forcedotcom
Community

dx-code-analyzer-run

Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. Also handles post-scan exploration: filtering results by engine/severity/category/file, and explaining what rules mean. TRIGGER when: user says 'scan my code', 'check security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulner

Installationen / 1h
1
GitHub Stars
1172
Aktualisiert
13. Nov.
forcedotcom
Community

experience-lwc-accessibility-jest-run

Use ALWAYS when running Sa11y accessibility Jest tests for an LWC — locally before pushing, producing the command(s), running one file vs a suite, selecting tests by naming convention, saving Sa11y-rendered HTML, or reproducing a Sa11y/A11yBug failure. Covers core (Bazel; bazel test // : ) and standalone npx jest (.accessibility.test.js, @sa11y/jest). REQUIRED for a run-plan.md, a failing a11y test's exit code, or SA11Y/A11yBug/core-Bazel test paths. DO NOT TRIGGER for functional Jest tests, a11

Installationen / 1h
1
GitHub Stars
1172
Aktualisiert
13. Nov.
forcedotcom
Community

experience-lwc-generate

Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc//.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use platform-apex-generate), Aura components, or Visualforce.

Installationen / 1h
1
GitHub Stars
1172
Aktualisiert
13. Nov.