Use dynamic fragments dynamic-fragments

On this page: Learn how to use dynamic fragment resolution in Adobe Journey Optimizer to select which published fragment is injected into a message at runtime, based on profile attributes, dataset lookups, or context data passed at send time.

Adobe Journey Optimizer supports dynamic fragment resolution at runtime, allowing you to select which published fragment is injected into a message based on profile attributes, dataset lookups, or context data passed at send time. This enables highly personalized content without duplicating campaign or journey logic.

Overview overview

Static fragments are embedded in a message at design time — the same fragment is used for every recipient. Dynamic fragments resolve the fragment ID at runtime per recipient, meaning different profiles can receive entirely different content blocks within the same campaign or journey.

Dynamic fragment IDs can come from three sources:

Prerequisites prerequisites

Before using dynamic fragments, ensure the following are in place:

Step 1: Create and publish the fragment create-fragment

Before referencing a fragment dynamically, it must be published in Journey Optimizer.

Step 2: Author the message with a dynamic fragment reference author-message

In the personalization editor, insert the dynamic fragment placeholder using the following syntax:

{{fragment id=dynamic_fragment_id}}

The identifier dynamic_fragment_id is a variable name. Its value must be resolved before the fragment lookup occurs. You resolve it using a dataset lookup expression, a profile attribute, or context data.

Resolve from a dataset lookup resolve-from-dataset

If the fragment ID is stored in an AEP dataset (for example, a style-to-fragment mapping table), use the datasetLookup helper function to resolve it:

{{
  {datasetLookup datasetId="<your-dataset-id>" key=profile.style attribute="fragmentId"}
}}

{{fragment id=dynamic_fragment_id}}

In this example, the dataset contains rows keyed by a style value (such as style1). For a given profile, the lookup retrieves the corresponding fragmentId column value and assigns it to dynamic_fragment_id, which is then used to resolve the fragment.

Resolve from context data resolve-from-context

If the fragment ID is supplied at send time as part of the API request context, reference it using the context namespace:

{{fragment id=context.audiencePayload.fragmentId}}

The path context.audiencePayload is the required prefix for all attributes sourced from a CSV audience file or passed via the API request context. The column name from the CSV (for example, fragmentId) follows the prefix.

Resolve from a profile attribute resolve-from-profile

If the fragment ID is stored as a profile attribute in Adobe Experience Platform, reference it directly:

{{fragment id=profile.mi.fragmentId}}

Step 3: Configure your dataset for the lookup approach configure-dataset

If you are using the dataset lookup approach, update your dataset schema and data to carry the fragment ID.

Example dataset structure:

Step 4: Pass context data at send time pass-context-data

If you are resolving the fragment ID from context data (for example, from a CSV audience recommendation file), pass the fragment ID in the API request under the required context prefix.

When using the campaign proofing API, include the fragment ID in the context object:

{
  "recipients": [
    {
      "userId": "<profile-email>",
      "namespace": "email"
    }
  ],
  "inChannelData": {
    "channel": "email",
    "emailAddresses": ["<delivery-address>"]
  },
  "context": {
    "audiencePayload": {
      "fragmentId": "<published-fragment-id>",
      "systemSource": "<optional-system-value>"
    }
  }
}

The prefix context.audiencePayload is required. Attributes nested under this key map directly to columns in the CSV audience file when running the live campaign.

Step 5: Proof and validate proof-validate

Before activating the campaign, use the campaign proofing API to verify that the dynamic fragment resolves correctly and that the rendered email output is as expected.

For more on the campaign API, refer to the Journey Optimizer APIs documentation.

Guardrails and limitations guardrails

The following limitations apply when using dynamic fragments:

More guardrails applying to fragments are available in this section.

Error handling error-handling

If a dynamic fragment fails to resolve at runtime, an exclusion event is generated for the affected profile. Currently, all fragment rendering failures are categorized as a single blanket error type.

To debug fragment resolution failures: