CaseSubjectParticle Metadata Type in SFDX

Architectural Overview#

When cases are generated automatically from social media channels via Social Customer Service, raw post content often makes poor Case subjects for Service Console agents. The CaseSubjectParticle metadata type allows architects to declaratively define an ordered sequence of tokens (“particles”) that Salesforce concatenates to build a structured, scannable Case.Subject string.

Each CaseSubjectParticle metadata component represents one segment in the subject template—such as the social network Source, the Author handle, a ProvidedString delimiter (like |), or the Message body—ordered by a zero-based index. Storing these particles in SFDX version control ensures uniform case subject formatting across all sandboxes and production.

Directory Location and File Suffix#

In Salesforce DX projects, CaseSubjectParticle files reside in the caseSubjectParticles folder.

Key Metadata Fields#

CaseSubjectParticle is a concise metadata type with three primary configuration fields:

Declarative Metadata Example#

Below are two CaseSubjectParticle files working together: the first inserts a custom prefix string ([SOCIAL] ) at index 0, and the second appends the inbound social Source at index 1.

<?xml version="1.0" encoding="UTF-8"?>
<CaseSubjectParticle xmlns="http://soap.sforce.com/2006/04/metadata">
    <index>0</index>
    <textField>[SOCIAL] </textField>
    <type>ProvidedString</type>
</CaseSubjectParticle>

<?xml version="1.0" encoding="UTF-8"?>
<CaseSubjectParticle xmlns="http://soap.sforce.com/2006/04/metadata">
    <index>1</index>
    <type>Source</type>
</CaseSubjectParticle>

Package Manifest (package.xml)#

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

SOQL Queries and SFDX CLI Commands#

You can query CaseSubjectParticle via SOQL to inspect the exact order in which inbound social Case subjects are assembled:

SELECT Id, DeveloperName, MasterLabel, Index, Type, TextField
FROM CaseSubjectParticle
ORDER BY Index ASC

Use the Salesforce CLI to retrieve and deploy all subject particles together:

# Retrieve all CaseSubjectParticle components
sf project retrieve start --metadata CaseSubjectParticle

# Deploy the full set of CaseSubjectParticle components
sf project deploy start --metadata CaseSubjectParticle

Architect Best Practices and Gotchas#

• 255-Character Case Subject Limit: The standard Case.Subject field has a maximum length of 255 characters. Place high-value routing tokens (Source, Sentiment, SocialHandle) at low index numbers (0–3) and place Message last so that long social posts are truncated cleanly without losing the channel or author identifier.
• Downstream Routing Dependencies: If EscalationRules or record-triggered Flow automations parse Case.Subject prefixes (such as [SOCIAL]), document that dependency inside the Flow description so admins do not inadvertently reorder CaseSubjectParticle indexes.

Frequently asked questions

What does CaseSubjectParticle control in Salesforce Service Cloud?

It controls how Salesforce Social Customer Service constructs the Subject field on newly created Case records from inbound social media posts by combining elements like source network, author, post content, and custom text.

What determines the order of components in the generated Case subject?

The index integer field on each CaseSubjectParticle record determines the exact sequence (0, 1, 2, and so on) in which the particles are concatenated into the Case Subject.

When is the textField element required on CaseSubjectParticle?

The textField element is required only when the type field is set to ProvidedString, allowing admins to insert custom separators such as pipes or hyphens between dynamic social fields.

Can I query CaseSubjectParticle records using SOQL?

Yes, CaseSubjectParticle is available in both standard SOQL and Tooling API, enabling architects to inspect the ordered subject generation rules directly.