AIUsecaseDefinition Metadata Type in SFDX

Architectural Overview#

Enterprise AI initiatives succeed when every machine learning model is anchored to a measurable business outcome and target entity. The AIUsecaseDefinition metadata type provides the declarative business wrapper for predictive and industry AI solutions—connecting the target CustomObject (such as Account, Asset, or Claim) with its underlying AIScoringModelDefinition and writeback fields.

Managing AIUsecaseDefinition in SFDX allows architects to package complete, domain-specific AI accelerators (e.g., Subscriber Churn Risk, Warranty Claim Fraud Detection, or Donor Lapsed Likelihood) and deploy them reproducibly across business units.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .aiUsecaseDefinition-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AIUsecaseDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Identifies B2B accounts at high risk of non-renewal 90 days prior to contract expiration.</description>
    <isActive>true</isActive>
    <masterLabel>Enterprise Contract Renewal Usecase</masterLabel>
</AIUsecaseDefinition>

Sample package.xml Manifest#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Enterprise_Contract_Renewal_Usecase</members>
        <name>AIUsecaseDefinition</name>
    </types>
    <types>
        <members>B2B_Renewal_Propensity_Model</members>
        <name>AIScoringModelDefinition</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval & Deployment#

Retrieve and deploy AIUsecaseDefinition components using the Salesforce CLI:

# Retrieve all AIUsecaseDefinition records from the org
sf project retrieve start --metadata "AIUsecaseDefinition:*"

# Deploy a specific AIUsecaseDefinition
sf project deploy start --metadata "AIUsecaseDefinition:Enterprise_Contract_Renewal_Usecase"

Senior Architect Best Practices & Gotchas#

• Bundle Schema, Model, and Automation: An AIUsecaseDefinition is only valuable when its predictions drive action. Package the target CustomField, AIScoringModelDefinition, AIUsecaseDefinition, and downstream Flow in the same SFDX package directory.
• License Verification in CI: Ensure your scratch org definition (project-scratch-def.json) includes the required Einstein or Industry Cloud add-on features before validating AIUsecaseDefinition deployments in automated pipelines.

Frequently asked questions

What is AIUsecaseDefinition in Salesforce?

AIUsecaseDefinition is a metadata type that encapsulates a specific AI business use case, linking the target Salesforce object, prediction goal, and AIScoringModelDefinition.

Where are AIUsecaseDefinition files stored in SFDX?

They are stored in the force-app/main/default/aiUsecaseDefinitions directory with the .aiUsecaseDefinition-meta.xml file suffix.

What dependencies are required when deploying AIUsecaseDefinition?

Any referenced custom objects, custom fields, and associated AIScoringModelDefinition components must exist in the target org or be included in the deployment.

How do I retrieve AIUsecaseDefinition metadata with Salesforce CLI?

Run sf project retrieve start --metadata AIUsecaseDefinition to download all configured AI use case definitions into your local workspace.