Content items can be marked as variants during creation. It is not possible to change the variant flag later on. Variants are used for A/B testing or user segmentation. Content items that are not variants are called baselines. Variants are created with the same content type as their baseline and provide all properties that are available for baselines.

The Unified API itself does not prescribe how variants are associated to their baselines or how they are chosen when presenting a content to a viewer. This is done by the ContentVariantModel and the ContentVariantService. Basically, variants link to their baselines and define conditions through content properties.

Unified Handling of Variants and Baselines

Typically, there is no need to handle variants and baselines in different ways. Because they are based on the same document type model and because variants include all properties that are available for baselines, they support the same operations.

However, there are three main tasks that become more complex: the analysis of content structures using referrers, the access to content items using observed properties, and the navigation between sites in a multi-site setup. For these tasks, the Unified API provides dedicated methods that return only baseline content items, allowing an efficient traversal of the content repository in the presence of variants, especially for complex content item hierarchies.

Variant Flag

Content items are permanently flagged as either baselines or variants during creation. The new create methods support a boolean parameter for this flag, whereas the old create methods always create baselines. The methods Content.isVariant() and Content.isBaseline() allow you to inspect the variant flag.

Referrers

When you inspect referrers of content items using the methods getReferrers(), getReferrersWithDescriptor(...), and so on, the Unified API returns both variants and baselines. However, most of the time, only the baselines are of interest. This is because baselines define the general outline of the content structure and variants only come into play when overriding specific content during delivery. For example, referrers might be used to build hierarchies of pages, categories, topics, or the like. This is done solely with baseline content items, so that variants do not have to be considered when traversing the hierarchies.

To this end, the methods getBaselineReferrersWithDescriptor(...) and getBaselineReferrersWithDescriptorFulfilling(...) have been added to the Unified API. They retrieve only baselines and do so in a very efficient way in the sense that they do not load variants or collect dependencies on them.

Observed Properties

Similar to referrers, variants are often not relevant when retrieving content items through observed properties. Observed properties typically help to identify content items that represent specific external entities. In this case, too, a representing content item should be the baseline, not a variant that has inherited the same value for the observed property.

The methods getBaselineContentsWithValue(...) and getBaselineContentsWithValueAndFulfilling(...) take care of this need, returning only the baseline content items with the desired string value. See Section 5.7, “Observed Property Service” for more information on observed properties.

Multi-Site

When navigating from a content item to the equivalent content items in a different site, it is also plausible that the caller wants to retrieve a baseline content item in the desired site. To this end, the methods getVariants() and getVariantsByLocale() of the ContentSiteAspect have been adjusted to return only baselines. Note that in these method names "variants" refers to localization variants, not personalization variants. The new methods getAllVariants() and getAllVariantsByLocale() exist, in case personalization variants should be included in the result.

Migrating Custom Code

Check whether variants that are returned from methods like getReferrersWithDescriptor(...) break the analysis of complex content structures. In such cases, you can use the new methods getBaselineReferrersWithDescriptor(...) to avoid reaching variants accidentally, as these methods efficiently limit the returned collection to baseline content items. Similarly, instead of using getContentsWithValue(...) it might be more robust to access observed properties using getBaselineContentsWithValue(...). Similarly, the already deprecated class ContentStringPropertyIndex might not be appropriate, because it includes variants in its results.