Content Server Manual / Version 2204
Table Of Contents
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
Parameter | Description |
---|---|
{ -b | --below }
|
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 }
| 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 |
|
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 <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 <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
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 documents got linked, retrieving the site root document may cause arbitrary results. |
File Output |
|
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 |
|
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. |
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 |
|
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 |
|
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 |
|
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 |
|
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. |
Symptom(s) | When deriving a site, the site root document will not be derived. Instead, the site indicator of the derived site will direct to the same site root document as its master site. |
File Output |
|
Option(s) |
Move root document 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 |
|
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 |
|
MS-VALIDATION-4021 - Missing Translation Settings Property Value | |
Severity | ERROR |
Description | The denoted property value of a translation settings document is empty or unset but is required. |
Symptom(s) | Content synchronization will not work. |
File Output |
|
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 document is invalid. |
Symptom(s) | Content synchronization will not work. |
File Output |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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. |
Symptom(s) | none |
File Output |
|
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 |
|
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. |
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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
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.