DiscoveryStory Metadata Type in SFDX

Overview#

The DiscoveryStory metadata type represents an Einstein Discovery story definition in CRM Analytics (formerly Tableau CRM / Wave Analytics). Architecturally, a DiscoveryStory bridges curated analytical datasets (WaveDataset) and deployable predictive models (DiscoveryAIModel). It defines the target outcome variable (outcome), optimization direction (goal such as Maximize or Minimize), model algorithm preferences, and explanatory variables analyzed during automated machine learning.

In Salesforce DX projects, DiscoveryStory is stored as a paired metadata component inside the force-app/main/default/discovery/ directory: a .story-meta.xml descriptor file and a companion .story file containing the raw JSON analytical specification.

Directory and File Suffix Reference#

Key Metadata Fields#

The .story-meta.xml file defines the high-level container, dataset reference, and outcome variable, while the .story file holds the JSON body (content).

DiscoveryStoryOutcome Subfields#

Declarative XML and Source Examples#

1. Metadata Descriptor (Customer_Churn_Story.story-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DiscoveryStory xmlns="http://soap.sforce.com/2006/04/metadata">
    <application>Revenue_Intelligence_App</application>
    <autoselectColumns>false</autoselectColumns>
    <classificationThreshold>0.62</classificationThreshold>
    <masterLabel>Enterprise Customer Churn Story</masterLabel>
    <outcome>
        <failureValue>Retained</failureValue>
        <field>Churn_Status</field>
        <goal>Minimize</goal>
        <label>Customer Churn Status</label>
        <successValue>Churned</successValue>
        <type>Binary</type>
    </outcome>
    <sourceContainer>Enterprise_Account_Health_DS</sourceContainer>
    <sourceType>AnalyticsDataset</sourceType>
    <validationType>CrossValidation</validationType>
</DiscoveryStory>

2. Companion Story Payload (Customer_Churn_Story.story)#

{
  "setup": {
    "algorithmType": "Xgboost",
    "maxCorrelation": 0.85,
    "fields": [
      {
        "name": "Annual_Contract_Value",
        "type": "Continuous"
      },
      {
        "name": "Support_Escalations_90d",
        "type": "Continuous"
      },
      {
        "name": "Executive_Sponsor_Present",
        "type": "Categorical"
      },
      {
        "name": "Product_Adoption_Tier",
        "type": "Categorical"
      }
    ]
  }
}

3. Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Revenue_Intelligence_App</members>
        <name>WaveApplication</name>
    </types>
    <types>
        <members>Enterprise_Account_Health_DS</members>
        <name>WaveDataset</name>
    </types>
    <types>
        <members>Customer_Churn_Story</members>
        <name>DiscoveryStory</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Deployment Commands#

Use the Salesforce CLI (sf) to retrieve and deploy DiscoveryStory metadata across environments:

# Retrieve a specific Einstein Discovery story and its JSON payload
sf project retrieve start --metadata DiscoveryStory:Customer_Churn_Story

# Retrieve all Einstein Discovery stories in the org
sf project retrieve start --metadata "DiscoveryStory:*"

# Validate deployment of the story alongside its parent WaveApplication
sf project deploy start \
  --source-dir force-app/main/default/discovery/Customer_Churn_Story.story-meta.xml \
  --dry-run

Architect Best Practices and Deployment Gotchas#

• Dataset Data vs. Metadata Dependency: Deploying a WaveDataset via Metadata API only deploys the dataset container, not the underlying parquet/edgemart rows. If you deploy a DiscoveryStory to a freshly provisioned sandbox before running the CRM Analytics Dataflow or Recipe (WaveRecipe) that populates sourceContainer, the story will open in Analytics Studio with an unpopulated dataset warning.
• Avoid Hardcoded Dataset Version IDs in .story JSON: When exporting a .story file from a sandbox, inspect the JSON payload to ensure it does not contain org-specific 0Fb (WaveDataset) or 0Fc version record IDs. Rely on sourceContainer in .story-meta.xml so the platform resolves the dataset by developer name.
• Decouple Story Exploration from Model Deployment: In enterprise CI/CD pipelines, data scientists iterate on DiscoveryStory in a dedicated Analytics Staging sandbox with masked production data, while production deployments promote the resulting DiscoveryAIModel and DiscoveryGoal (Prediction Definition) used by Flow and Apex scoring.

Frequently asked questions

What files make up a DiscoveryStory component in Salesforce DX?

A DiscoveryStory component consists of a pair of files in the discovery directory: a .story file containing the JSON story configuration payload and a .story-meta.xml file containing the outer metadata properties such as application, masterLabel, and outcome.

Does deploying a DiscoveryStory automatically train the predictive model in the target org?

Deploying DiscoveryStory creates the story configuration and metadata bindings, but the target org must already contain the referenced WaveDataset with populated data before Einstein Discovery can execute story analysis and generate a DiscoveryAIModel.

How does DiscoveryStory relate to WaveApplication in Metadata API?

Every DiscoveryStory must belong to a CRM Analytics folder represented by a WaveApplication developer name in the application field. If the target WaveApplication does not exist, the deployment fails with a missing dependency error.

What outcome types are supported in the DiscoveryStory outcome element?

The DiscoveryStory outcome element supports Count,Binary,Continuous,and Multiclass classification types,corresponding to regression,two-class classification,and multi-class predictive modeling use cases.