close

Filter

loading table of contents...

Content Server Manual / Version 2401

Table Of Contents

3.13.1.11 Validate Multi-Site

The tool validate-multisite helps you to manage multiple localized variants of contents in CoreMedia Content Cloud as described in chapter "CoreMedia Content Cloud Website and Content Structure/Localized Content Management" of the [Blueprint Developer Manual]. It validates your multi-site configuration as well as your content repository.

It is strongly recommended that you run this tool when introducing or migrating the multi-site feature to ensure that your system is valid. You can also use this tool to regularly check your content for possible mistakes during translation processes, checking global conditions that are not addressed by the validators that are available to your editors in CoreMedia Studio.

cm validate-multisite [ {-b folder} ...] [-f file] [-fow] [-t] [other...]

Example 3.15. Usage of validate-multisite


ParameterDescription

{ -b | --below } folder

Base folder for validating content. May be used multiple times to validate multiple folders. By default, all sites as located by their site indicator are validated.

If you include folder outside of any site, the analysis results will not be meaningful, because most conditions cannot be checked in such a case. As long as a site indicator is invalid, it cannot define a site, so that analyzing content in the site will not be possible.

{ -f | --file } file

Output file for writing the detected issues in tab-separated value format.

-fow | --fail-on-warning

Fail with a non-zero exit code when a warning is generated.

-t | --thorough

Disable fail early approach and search for failures more thorough.

Table 3.19. Parameters of validate-multisite


Severities

The multi-site issues come with different severities. It is recommended to fix all issues for best results when using multi-site.

INFO
denotes issues that oppose best practices
WARN
denotes recoverable issues which violate multi-site requirements and possibly cause unexpected results
ERROR
denotes unrecoverable issues which prohibit further analysis as well as using multi-site features will not work or produce corrupt results
File Output

The file output is meant to support automatic actions like for example adjusting wrong or missing property values. It contains relevant error parameters in tab separated columns, so that it becomes possible to identify the reported issues.

The first two columns are fixed: Issue Severity and Issue Error Code. The third is most of the time the id of the analyzed content. Additional parameters are mentioned in Table 3.20, “Issues of validate-multisite.

Issues
MS-VALIDATION-0000 - Internal Error
Severity ERROR
Description An exception occurred during validation. Please analyze the exception stack trace for further information.
File Output
  1. Exception Message
MS-VALIDATION-1000 - Missing Sites Service
Severity ERROR
Description SitesService is not defined. None of the multi-site features will work.
Symptom(s) None of the multi-site features will work.
File Output no additional columns
Option(s)

Validate your application contexts to contain a bean of type SitesService. Typically, by adding a dependency to com.coremedia.cms:cap-multisite and importing multisite-services.xml.

<import resource="classpath:/com/coremedia/cap/multisite/multisite-services.xml"/>
MS-VALIDATION-1001 - Missing Site Model
Severity ERROR
Description SiteModel is not available in SitesService.
Symptom(s) None of the multi-site features will work.
File Output no additional columns
Option(s)

Validate your application contexts to contain a bean of type SitesService with reference to a SiteModel. Typically, by adding a dependency to com.coremedia.cms:cap-multisite, importing multisite-services.xml and adding your configured SiteModel bean.

<import resource="classpath:/com/coremedia/cap/multisite/multisite-services.xml"/>
<customize:replace
  id="addYourSiteModel"
  bean="sitesService"
  property="siteModel"
  custom-ref="yourSiteModel"/>

It is recommended to create a bean of the type com.coremedia.cap.multisite.DefaultSiteModel or of a custom subtype.

MS-VALIDATION-2000 - Missing Required Property Value
Severity WARN, ERROR
Description Denoted property's value is empty or unset but is either required (error) or strongly recommended (warn).
Symptom(s) Some multi-site features may not work or may cause unexpected states depending on the affected property.
File Output
  1. name of property
Option(s)

Set the required/recommended property value.

MS-VALIDATION-2001 - Deprecated Property
Severity INFO
Description The property is deprecated.
Symptom(s) none
File Output
  1. deprecated property name
  2. current value of property
Option(s)

Consult deprecation notices for details and possible replacement.

MS-VALIDATION-3000 - Missing Site Indicator Content Type
Severity ERROR
Description Content type defined in property siteIndicatorDocumentType of site model does not exist.
Symptom(s) Sites will not be available.
File Output
  1. referenced non-existing content type
Option(s)

Either update site model configuration or extend your content type model by the given type.

MS-VALIDATION-3001 - Missing Property Descriptor
Severity ERROR
Description Property referenced from site model does not exist.
Symptom(s) Some, if not all multi-site features will not work or cause unexpected states.
File Output
  1. content type which does not serve defined property
  2. name of missing property
  3. site model property referencing missing property
Option(s)

Either update site model configuration or extend your content type model by the required property.

MS-VALIDATION-3002 - Invalid Property Descriptor Type
Severity ERROR
Description Property referenced from site model exists but is of invalid type. For example the denoted master property is not of type link.
Symptom(s) Some, if not all multi-site features will not work or cause unexpected states.
File Output
  1. content type which contains property
  2. name of property
  3. site model property referencing property
  4. expected property type
  5. actual property type
Option(s)

Either update site model configuration or change your content type model to match the required type.

MS-VALIDATION-3003 - Master Link not Weak
Severity WARN
Description The master property is not marked as weak.
Symptom(s) You will always have to publish the master content prior to its derived contents, and you cannot withdraw the master content without withdrawing all derived contents first.
File Output
  1. affected content type
  2. affected property
Option(s)

Adjust your content type model setting master property to weak.

<LinkListProperty
  Name="master"
  Max="1"
  LinkType="CMLocalized"
  extensions:weakLink="true"/>
MS-VALIDATION-3004 - Missing Localizable Content Type Property
Severity INFO
Description

A content type appears to be localizable but misses a recommended property.

Symptom(s) Most likely none, as a fallback exists. For example if the locale property is missing, the typical fallback is to the site indicator's locale.
File Output
  1. content type
  2. property
Option(s)

Adjust your content type model to match the required criteria.

MS-VALIDATION-3005 - Invalid Localizable Content Type Property
Severity WARN
Description

A content type appears to be localizable but one of its properties is of invalid type.

Symptom(s) Some, if not all multi-site features will not work or cause unexpected states.
File Output
  1. content type
  2. property
  3. expected type
  4. actual type
Option(s)

Adjust your content type model to match the required criteria.

MS-VALIDATION-3006 - Invalid Master Link Type
Severity WARN, INFO
Description

A content type having a master link property of wrong type. It is expected that the type of the master link is just the same as the content type defining it. If the link type is a parent type this issue is considered INFO level as it does not break processing. If the link type is of any other type, this issue is considered WARN level as it might cause severe problems during multi-site processing.

Symptom(s) Most likely none, if the link type is compatible to the current content type. May break multi-site features, though, if an editor sets a link to a content different to current type. If the link type is incompatible, multi-site feature may or will break, like translation processes may escalate.
File Output
  1. content type
  2. property
  3. actual link type
Option(s)

Adjust your content type model so that the master link is always of the same type as the current content type. For details, see Section 4.3.8.4, “Changing LinkType of LinkListProperty”.

MS-VALIDATION-4000 - Invalid Property Value
Severity WARN
Description Property value is invalid.
Symptom(s) Multi-site features may produce unexpected results. If, for example, the locale is not idempotent regarding Locale.forLanguageTag(locale).toLanguageTag() multi-site features may evaluate to different locales.
File Output
  1. site indicator's content id
  2. name of property
  3. actual value
  4. suggested value for fix
Option(s)

Fix the property value.

MS-VALIDATION-4001 - Ambiguous Property Value
Severity INFO
Description Property value is ambiguous and might lead to unexpected behavior.
Symptom(s) Multi-site features may produce unexpected results. If for example multiple site root content items got linked, retrieving the site root content item may cause arbitrary results.
File Output
  1. site indicator's content id
  2. name of property
Option(s)

Fix the property value.

MS-VALIDATION-4002 - Invalid Path
Severity WARN
Description A site indicator is located at a path that does not match the configured site root folder pattern.
Symptom(s) When deriving a site, the derived sites may not be created as sibling of the current site.
File Output
  1. content id
  2. expected path; might be some root folder rather than explicit path
Option(s)

Either fix the content location or adjust the site model to match the location of the content.

MS-VALIDATION-4003 - Invalid Path Depth
Severity ERROR
Description A site indicator is located a path that does not match the currently configured site root folder pattern and site indicator depth.
Symptom(s) The denoted site root folder may be wrong, and may result in unexpected contents to be contained or not to be contained in site. When deriving a site, the derived sites may not be created as sibling of the current site.
File Output
  1. content id
  2. configured depth
  3. actual depth
  4. folder content should be located below at configured depth
Option(s)

Either fix the content location or adjust the site model to match the location of the content.

MS-VALIDATION-4004 - No Site Indicators
Severity WARN
Description

No site indicators found. Either you need to adjust your site model, or your content needs to have site indicators.

Not detected when folder restriction is active.

Symptom(s) Sites will not be available.
File Output no additional columns
Option(s)

Either fix the content location or adjust the site model to match the location of the content.

MS-VALIDATION-4005 - Multiple Site Indicators at Site Root
Severity ERROR
Description

Multiple site indicators exist in the same site at the same depth as denoted by site indicator depth in site model. Selecting and deriving sites might cause problems.

Possibly not detected when folder restriction is active.

Symptom(s) Ambiguous results when determining site/site properties of a given content. Multi-site features such as translation may cause unexpected results.
File Output
  1. first site indicator's id
  2. second site indicator's id
  3. folder which both of them identify as site folder
Option(s)

Remove unnecessary site indicators.

MS-VALIDATION-4006 - Non-Unique Site-ID
Severity ERROR
Description

Multiple site indicators share the same site ID.

Possibly not detected when folder restriction is active.

Symptom(s) Some sites will not be available to be selected as preferred site. Ambiguous results when determining site/site properties of a given content. Multi-site features such as translation may cause unexpected results.
File Output
  1. first site indicator's id
  2. second site indicator's id
  3. id which both of them share
Option(s)

Create unique site IDs as administrative user.

MS-VALIDATION-4007 - Missing Site Indicator Property Value
Severity ERROR
Description The denoted property value of a site indicator is empty or unset but is required.
Symptom(s) Site represented by this site indicator will not be available (site will be considered destroyed).
File Output
  1. affected site indicator's id
  2. name of property
Option(s)

Set the required property value.

MS-VALIDATION-4008 - Root not in Site
Severity WARN
Description The root content item referenced by site indicator is outside the site folder.
Symptom(s) When deriving a site, the site root content item will not be derived. Instead, the site indicator of the derived site will direct to the same site root content item as its master site.
File Output
  1. referencing site indicator's id
  2. site's ID the site indicator belongs to
  3. root content item's ID not in site
Option(s)

Move root content item somewhere into the site folder.

MS-VALIDATION-4009 - Discouraged Property Value
Severity INFO
Description The value of the property is discouraged due to known disadvantages.
Symptom(s) none
File Output
  1. property name
  2. current value of property
Option(s)

Consult documentation and release notes for the recommended value and migration efforts.

MS-VALIDATION-4020 - Missing Translation Settings Content Type
Severity ERROR
Description Content type defined in property translationSettingsDocumentType of site model does not exist.
Symptom(s) Content synchronization will not work.
File Output
  1. referenced non-existing content type
MS-VALIDATION-4021 - Missing Translation Settings Property Value
Severity ERROR
Description The denoted property value of a translation settings content item is empty or unset but is required.
Symptom(s) Content synchronization will not work.
File Output
  1. affected translation settings content item's ID
  2. name of property
Option(s)

Set the required property value.

MS-VALIDATION-4022 - Invalid Translation Settings Property Value
Severity ERROR
Description The denoted property value of a translation settings content item is invalid.
Symptom(s) Content synchronization will not work.
File Output
  1. affected translation settings content item's ID
  2. name of property
Option(s)

Set the required property value.

MS-VALIDATION-5000 - Type not Localizable
Severity WARN
Description

A content inside a site is not of a localizable content type.

Symptom(s) This might cause issues in translation process, such as that contents cannot be marked having reached a new translation state.
File Output
  1. affected content id
  2. actual content type
Option(s)

Most likely adjust your content type model so that the content's type is localizable.

MS-VALIDATION-5001 - Not Site Locale
Severity WARN
Description A content has locale that differs from the site locale, but is not marked as derived from another content in the site.
Symptom(s) When deriving a site, or propagating the content to a derived site, the locale will not be adjusted. This behavior will break as soon as a site in the site hierarchy shares the same locale as the content. In lower levels the site locale will be adapted to the site locale which may be unexpected.
File Output
  1. affected content id
  2. locale of content
  3. expected site locale
Option(s)

Most likely adjust locale or set a master link.

MS-VALIDATION-5002 - Locale not Set
Severity INFO
Description

A content is localizable, but the locale property is not set.

Symptom(s) None, because the locale of the content will default to the site locale, but it is preferred to set the locale explicitly.
File Output
  1. affected content id
  2. suggested locale from site
Option(s)

Set the locale of the given content to the site locale.

MS-VALIDATION-5003 - Same Locale
Severity WARN
Description

A content is marked as derived from another content in the site, but still uses the site locale.

Symptom(s) There are no immediately visible symptoms. May cause problems on delivery though, for example when displaying language toggles.
File Output
  1. affected content id
  2. actual locale
Option(s)

Most likely adjust the locale of the derived content.

MS-VALIDATION-6000 - Content not Used in Derived Site
Severity INFO
Description

A content in the master site has no translated counterpart in the derived site. This might be a result of an unfinished translation process as well as intended as content is not required for the derived site.

Symptom(s) Most likely none, but content may be recreated unexpectedly during translation processes, if it gets linked in master content.
File Output
  1. affected content id
  2. content's site id
  3. locale of missing translation
Option(s)

Possibly nothing to do. Otherwise, start a translation process to get the content from master into derived site.

See Also
MS-VALIDATION-6001 - Content not Used in Derived Site but some Content Exists
Severity WARN
Description

A content in master site has no translated counterpart in the derived site regarding the value of master link. Nevertheless, a content with the very same name exists in derived site.

Symptom(s) Possible counterpart will not receive any translation results. Instead, if the master content gets translated, a new derived content will be created with a non-conflicting name.
File Output
  1. affected content id
  2. content's site id
  3. locale of missing translation
  4. content id of suggested counterpart to set current content as master
Option(s)

Most likely just set the master link or rename preferably the derived content item to prevent future collisions in translation process.

See Also
MS-VALIDATION-6002 - Content without Master
Severity INFO
Description

Counterpart to MS-VALIDATION-6000: In this case a content in the derived site exists which has no master. This might be intended if you have a content which is just relevant for your derived site.

Symptom(s) none
File Output
  1. affected content id
  2. content's site id
Option(s)

Possibly nothing to do. Otherwise, copy (and translate) content to master site and add a corresponding master link to the derived content.

See Also
MS-VALIDATION-6003 - Content without Master but some Content Exists
Severity INFO
Description

Counterpart to MS-VALIDATION-6001: In this case a content in the derived site exists which has no master link set, but a content with the same name exists in master site.

Symptom(s) Possible counterpart will not receive any translation results from master. Instead, if the master content gets translated, a new derived content will be created with a non-conflicting name.
File Output
  1. affected content id
  2. content's site id
  3. content id of suggested counterpart to as master
Option(s)

Most likely just set the master link or rename preferably the derived content item to prevent future collisions in translation process.

See Also
MS-VALIDATION-6004 - Root Content with Master
Severity INFO
Description

A content in a root site defines a master.

Symptom(s) Most likely none, but may signal that either the site indicator misses a master link. Otherwise, the master link is just ignored.
File Output
  1. affected content id
  2. current site id
  3. linked master content id
Option(s)

Possibly delete the master link or adjust site's master link.

MS-VALIDATION-6005 - Master not in Site
Severity WARN
Description

A content in a derived site is derived from a content belonging neither to the master site, nor the content's site.

Symptom(s) Content will never receive updates from the denoted master, as propagation of localization is organized by site, not content hierarchies.
File Output
  1. affected content id
  2. current site id
  3. linked master content id
  4. master site id
Option(s)

Adjust the master link to point to either to a content inside the site or in the master site.

MS-VALIDATION-6006 - Master has more than one derived variant in one site
Severity WARN
Description

A master content has more than one directly derived variant in one single site. This harms the translation process and leads to inconsistent translation results.

Symptom(s) Only one arbitrary derived content will receive updates from master. The algorithm may even choose different derived contents on each update process.
File Output
  1. affected content id
  2. current site id
  3. locale of the affected site with the two or more derived variants
Option(s)

Check if every derived variant has the correct master set. Reduce to only one content, which refers to the master.

MS-VALIDATION-7000 - Master Version Destroyed
Severity WARN
Description

A master version referenced by derived content does not exist any longer.

Symptom(s) Most obvious symptom is, that auto-merge properties will not receive any updates. Linklists for example will not receive newly inserted links in master content.
File Output
  1. affected content id
  2. master content id
  3. denoted destroyed master version
  4. the latest master version
Option(s)

Either adjust master version or start a translation process to update master version.

See Also
MS-VALIDATION-7001 - Master Version Invalid
Severity WARN
Description

A master version value is invalid regarding the available versions of the master. Number might be negative or greater than current version number.

Symptom(s) Most obvious symptom is, that auto-merge properties will not receive any updates. Linklists for example will not receive newly inserted links in master content.
File Output
  1. affected content id
  2. master content id
  3. denoted invalid master version
  4. the latest master version
Option(s)

Either adjust master version or start a translation process to update master version.

See Also
MS-VALIDATION-7002 - Master Version not Localized yet
Severity INFO
Description

Derived content has not been localized yet. Because this is a completely valid state, it is reported with severity INFO.

Symptom(s) Content will be marked as not localized yet.
File Output
  1. affected content id
  2. master content id
  3. denoted not yet localized master version
  4. the latest master version
Option(s)

Start a translation process to update master version.

See Also
MS-VALIDATION-7003 - Master Version not up to Date
Severity INFO
Description

Derived content has not been updated to most recent master version yet. Because this is a completely valid state, it is reported with severity INFO.

Symptom(s) Content will be marked as not being up-to-date.
File Output
  1. affected content id
  2. master content id
  3. denoted outdated master version
  4. the latest master version
Option(s)

Start a translation process to update master version.

See Also
MS-VALIDATION-7004 - Master Version not set
Severity WARN
Description

Derived content has no master version.

Symptom(s) Most obvious symptom is, that auto-merge properties will not receive any updates. Linklists for example will not receive newly inserted links in master content.
File Output
  1. affected content id
  2. master content id
  3. the latest master version
Option(s)

Set the master version of the derived content. If you choose a positive number, it signals, that the content received the latest translation from master (master and derived are up-to-date). If you choose a negative number, it signals, that the derived content got copied from the given master version and it is marked as not translated yet. Benefit of the positive number is, that there is nothing more to do. Benefit of the negative number is, that you may trigger an editorial review process for adjusted contents.

See Also
MS-VALIDATION-8000 - Link Spanning Sites
Severity WARN
Description

A content in a site links to a content in another site with a property other than the master property.

Symptom(s) Such external links will not be adjusted during localization processes (derive site, translation, ...). While this does no harm to the translation processes, it may be unexpected at delivery, as for example navigation contexts cannot be resolved.
File Output
  1. affected content id
  2. site id of the affected content
  3. site id of the link target
  4. link property name containing spanning links
Option(s)

Possibly adjust the links.

MS-VALIDATION-8001 - Link to Destroyed Content
Severity WARN
Description

A content links to a non-existing content.

Symptom(s) Most likely none regarding localization processes.
File Output
  1. affected content id
  2. link property containing link to destroyed content
Option(s)

Adjust the link.

MS-VALIDATION-8002 - Link to Deleted Content
Severity WARN for strong links, INFO for weak links
Description

A content links to a deleted content.

Symptom(s) Most likely none regarding localization processes. Note, though, that deleted links behave like external links (links to content outside of current site). I.e., the link will not be mapped upon localization processes. If for any reason the linked content is restored, you may end up with additional issues regarding multi-site validation and localization processes.
File Output
  1. affected content id
  2. link property containing link to deleted content
Option(s)

Adjust the link.

MS-VALIDATION-8003 - Link to Deleted Master
Severity WARN
Description

A content links to a deleted content in its master property.

Symptom(s) Most likely none regarding localization processes. It may signal, that a content should be deleted in derived sites, too.
File Output
  1. affected content id
Option(s)

Delete the derived content after deletion of the master content. Or adjust the link to point to the correct master content.

Table 3.20. Issues of validate-multisite


Commerce-related Issues
MS-VALIDATION-9000 - Augmenting content is missing in a derived site
Severity INFO
Description

An augmenting content of a master site has no equivalent in a derived site.

Symptom(s) It may signal that a commerce item should be also augmented in the derived site, at least if you follow a synchronous content approach. Some augmentations of the master site may not be available in the derived site (e.g. pictures or texts or even the navigation can vary).
File Output
  1. affected master content id
  2. master content's site id
  3. commerce reference of missing augmentation
  4. locale of missing augmentation
Option(s)

If it is intentional, then do not worry (it is just INFO level). If not, then go to the derived site (locale) and augment the equivalent commerce item as well. Do not forget to set the master link in the derived augmenting content.

MS-VALIDATION-9001 - Augmenting content is missing in a derived site but a candidate was found
Severity WARN
Description

An augmenting content of the master site has no equivalent in a derived site although a content with the same external id reference exists. But it is not linked to the master content.

Symptom(s) Traversing from a derived page (e.g. an augmented category in a derived locale) to the master page (in a master locale) and vice-versa could be broken, depending if such a functionality is available.
File Output
  1. affected master content id
  2. master content's site id
  3. commerce reference of missing augmentation
  4. locale of missing augmentation
  5. content id of suggested counterpart to set current content as master
Option(s)

Probably the master link was simply forgotten and should just be set in the derived augmenting content.

MS-VALIDATION-9002 - Augmenting content is missing in a master site
Severity INFO
Description

An augmenting content of a derived site has no equivalent in a master site.

Symptom(s) It may signal that a commerce item should be also augmented in the master site, at least if you follow a synchronous content approach. Some augmentation of the derived site are not available in the master site (e.g. pictures or texts or even the navigation can vary).
File Output
  1. affected derived content id
  2. derived content's site id
  3. commerce reference of missing augmentation
  4. locale of missing augmentation
Option(s)

If it is intentional, then do not worry (it is just INFO level). If not, then go to the master site (locale) and augment the equivalent commerce item as well. Do not forget to set the master link in the derived augmenting content.

MS-VALIDATION-9003 - Augmenting content is missing in a master site but a candidate was found
Severity WARN
Description

An augmenting content of a derived site has no equivalent in a master site although a content with the same external id reference exists. Of course it is also not linked to the master content.

Symptom(s) Traversing from a master page (e.g. an augmented category in a master locale) to the derived page (in a derived locale) and vice-versa could be broken, depending if such a functionality is available.
File Output
  1. affected derived content id
  2. derived content's site id
  3. commerce reference of missing augmentation
  4. locale of missing augmentation
  5. content id of suggested counterpart to set as master
Option(s)

Probably the master link was simply forgotten and should just be set in the derived augmenting content.

MS-VALIDATION-9004 - Augmenting content is invalid
Severity WARN
Description

The content of a type that is meant to hold a reference to a commerce item (to augment a commerce item) is missing the reference. This content item is not actually augmenting anything and would be useless. Note, it is not checked if an existing commerce reference points to a valid commerce item.

Symptom(s) Unless this content is not used or linked it is only useless data. But if it is used, then the page is definitely broken at this point.
File Output
  1. affected content id
  2. content's type
  3. content's site id
Option(s)

If this content is used or linked, the commerce reference should be quickly entered by assigning a commerce item.

MS-VALIDATION-9005 - Augmenting content is not unique
Severity WARN
Description

There are several contents within a site that point to the same commerce object.

Symptom(s) Although this situation does not pose a problem for operation because the content with the smallest content id is always selected, you may wonder why changes on an augmenting content are not displayed on the website. It is possible that another content with the same commerce reference (and a smaller content id) hides this content and is always favored.
File Output
  1. affected content id
  2. content's type
  3. content's site id
  4. commerce reference of affected augmentation
Option(s)

Augmenting content must be unique. Delete all other instances with the same commerce reference.

Table 3.21. Commerce-related Issues of validate-multisite


Exit Codes

The tool exits with the following codes:

Code 0
No issues other than severity INFO (or WARN if fail on warning is turned off) found.
Code 31
Errors found.
Code 32
Warnings found (if fail on warning is turned on).
other
Other exit code are standard to UAPI Client and denote exceptions, usage failure, etc.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.