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. Create methods that take a boolean parameter for this flag set it explicitly, whereas the remaining 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 Unified API provides the methods getBaselineReferrersWithDescriptor(...) and getBaselineReferrersWithDescriptorFulfilling(...). 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, the caller usually wants to retrieve a baseline content item in the desired site. Therefore, the methods getVariants() and getVariantsByLocale() of the ContentSiteAspect return only baselines. Note that in these method names "variants" refers to localization variants, not personalization variants. Use getAllVariants() and getAllVariantsByLocale() to include personalization variants in the result.

Both methods locate the variants by following the master property up to the topmost master of the content item. Since master is a weak link, the linked master is not necessarily published together with the content item that links to it. On a live server, such an unpublished master is represented by a destroyed content item, and the traversal stops there. The content item is then treated as its own topmost master, so variants that are only reachable through the unpublished master are not part of the result.

Site navigation is affected in the same way. Site.getMasterSite() returns null if the master site is not readable, which on a live server is the case for a master site that is not published, such as an abstract site. Note that null is also the regular result for a root site, which has no master site at all. See Section “Abstract Sites” in Multi-Site Manual for the background.

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 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 deprecated class ContentStringPropertyIndex might not be appropriate, because it includes variants in its results.