3.14.1.12. Validate Multi-Site

The tool validate-multisite helps you to manage multiple localized variants of contents in CoreMedia Digital Experience Platform 8 as described in chapter "CoreMedia Digital Experience Platform 8 Website and Content Structure/Localized Content Management" of the [CoreMedia Digital Experience Platform 8 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] [other...]

Example 3.18. 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.

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.
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. 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).
File Output
  1. name of property
Option(s)

Set the required/recommended property value.

MS-VALIDATION-3000 - Missing Site Indicator Content Type
Severity ERROR
Description Content type defined in property siteIndicatorDocumentType of site model does not exist.
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.
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.
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. If you do not fix this issue, you always have to publish the master content before its derived contents.
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.

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.

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-4000 - Invalid Property Value
Severity WARN
Description Property value is invalid.
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.
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.
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
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.
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.

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.

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.

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.
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 document referenced by site indicator is outside the site folder. This will cause problems when deriving a new site.
File Output
  1. referencing site indicator's id
  2. site's id the site indicator belongs to
  3. root document's id not in site
Option(s)

Move root document somewhere into the site folder.

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

A content inside a site is not of a localizable content type. This might cause issues in translation process.

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.
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. In this case, the locale defaults 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.

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.

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.

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 document 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.

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.

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 document 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.

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 that belongs neither to the master site nor the content's site.

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.

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.

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.

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.

File Output
  1. affected content id
  2. master content id
  3. 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.

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-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.

File Output
  1. affected content id
  2. 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.

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
Description

A content links to a deleted content.

File Output
  1. affected content id
  2. link property containing link to deleted content
Option(s)

Adjust the link.

Table 3.20. 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.