Admin.XMLPublishPluginConfiguration.xml
The Admin.XMLPublishPluginConfiguration.xml file contains the configuration for the plugins that are executed during the publish (post) process.
Changelog
| File version | Content Manager version | Notes |
|---|---|---|
| 1.0 | 13.0.0 | This is the first version of Admin.XMLPublishPluginConfiguration.xml. |
| 1.0 | 13.0.1 | The Admin.XMLPublishPluginConfiguration.xml is extended with the ability to configure the following:
|
Introduction
This configuration file is accessible from the Content Manager Web Client. Select .
This configuration file contains:
- The global parameters that can be used by the export and by any publish post process plugins.
- The configuration for the export.
- The sequence of plugins that will be executed within the post processing step of the publish process.
- A plugin definitions section that defines a number of plugins which can be referenced in the sequence of plugins.
Overview of the XML elements
| Node name | Description |
|---|---|
| infoSharePublishPluginConfig | Root node of the publish plugin XML configuration. |
| publish | Describes a sequence of plugins that will be executed within the publish process.
|
| publish @ishcondition | The condition that determines when the current publish sequence should be activated. |
| parameters | The global parameters that can be used by the export and by any publish post process plugin. |
| export | Contains the configuration (e.g. requested metadata) used during the export of the files. |
| postprocess | Describes a sequence of plugins that will be executed within the post processing step of the publish process.
|
| plugindefinitions | Specifies a number of plugin definitions that can be referenced from within the postprocess element. This provides an easy way to reuse the same plugin definition for different output formats. |
Global parameters
| Node name | Description |
|---|---|
| parameters | The global parameters which can be used by the export and by any publish post process plugin. |
| parameter |
The parameter that is passed to the export and the plugins.
|
| parameter @name | The name of the parameter. |
| parameter @ishcondition | The condition for which the parameter will be used. |
Example:
<parameters>
<parameter name="CatalogFolder">%ISHPROJECTWEBPATH%\Author\ASP\DocTypes</parameter>
<parameter name="CatalogFile">catalog.xml</parameter>
<parameter name="DraftWhenFallbackLanguageUsed">yes</parameter>
<parameter name="DraftWhenFallbackLanguageUsedForIllustration">no</parameter>
<parameter name="DraftWhenFallbackLanguageUsedForResource">yes</parameter>
<parameter name="VariableAssignedXPath">//*[@varid][not(ancestor-or-self::*[@varref])][not(ancestor::*[@conref])]</parameter>
<parameter name="VariableInUseXPath">//*[@varref][not(ancestor::*[@varref])][not(ancestor::*[@conref])]</parameter>
...
</parameters>
Export configuration
| Node name | Description |
|---|---|
| parameters | The global parameters that can be used by the export and by any publish post process plugin. |
| parameter |
The parameter that is passed to the export.
|
| parameter @name | The name of the parameter. |
| parameter @ishcondition | The condition for which the parameter will be used. |
The configuration for the export is used to pass the parameters with the requested metadata for the document objects (e.g. maps, topics...) and the publication output:
<export>
<parameters>
<parameter name="documentobjrequestedmetadata">
<ishfields>
<ishfield name="FTITLE" level="logical" />
<ishfield name="FDESCRIPTION" level="logical" />
<ishfield name="VERSION" level="version" />
<ishfield name="FCHANGES" level="version" />
<ishfield name="FAUTHOR" level="lng" />
<ishfield name="FSTATUS" level="lng" />
...
</ishfields>
</parameter>
<parameter name="publicationoutputrequestedmetadata">
<ishfields>
<ishfield name="FTITLE" level="logical"/>
<ishfield name="FDESCRIPTION" level="logical"/>
<ishfield name="VERSION" level="version"/>
...
<ishfield name="FPUBINCLUDECOMMENTS" level="lng"/>
<ishfield name="FPUBINCLUDEMETADATA" level="lng"/>
<ishfield name="FPUBWATERMARK" level="lng"/>
<ishfield name="FISHPUBREVIEWENDDATE" level="lng"/>
<ishfield name="FISHPUBLNGCOMBINATION" level="lng" ishvaluetype="value" />
<ishfield name="FISHPUBSTATUS" level="lng" ishvaluetype="element" />
...
<ishfield name="FISHDITADLVRREMOTESTATUS" level="lng" ishvaluetype="element" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishditadelivery'"/>
<ishfield name="FISHPRODUCTFAMILYNAME" level="logical" ishvaluetype="value" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishditadelivery'"/>
<ishfield name="FISHPRODUCTRELEASENAME" level="version" ishvaluetype="value" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishditadelivery'"/>
</ishfields>
</parameter>
</parameters>
</export>
Publish post process plugins
| Node name | Description |
|---|---|
| postprocess | Describes a sequence of plugins that will be executed within the post processing step of the publish process.
|
| @ishcondition | The ishcondition attribute can be set on most of the elements of the postprocess. As the configuration is conditionally filtered, this allows to remove some of the plugins depending on the output format, the type of object which is processed, ... |
| beforecompare currentversion sequence | The element that contains a sequence of publish post process plugins to run on the exported files of the current version before the compare is executed. |
| beforecompare compareversion sequence | The element that contains a sequence of publish post process plugins to run on the exported files of the compare version before the compare is executed. |
| compare | The element that describes the compare plugin to run. Note that this type of plugins will only execute when the publish contains a value for Differences from version. |
| compare @handler | The C# class that contains the implementation of the IPublishComparePlugin interface. |
| combinelanguages | The element that describes the combine languages plugin to run. Note that this type of plugins will only execute when the publish contains multiple languages. |
| combinelanguages @handler | The C# class that contains the implementation of the IPublishCombineLanguagesPlugin interface. |
| sequence | The element that contains a sequence of publish post process plugins. The sequence element can contain a mixture of plugin elements and/or pluginreference elements. |
| plugin | Describes one single publish plugin. |
| plugin @name | The name of the plugin. For custom plugin you should not start the name with ISH (which indicates an out-of-the-box plugin). |
| plugin @handler | The C# class that contains the implementation of the IPublishPostProcessPlugin interface. |
| pluginreference | Describes a reference to a plugindefinition that is defined in the plugindefinitions section |
| pluginreference @name | The name of the reference. This name should match exactly one name of a plugindefinition element in the plugindefinitions section. |
| description | The description of the plugin. |
| initialize | Describes the parameters that should be passed to the plugin instance upon initialization. |
| parameters | Contains parameter elements. |
| parameter |
The parameter that is passed to the plugin.
|
| parameter @name | The name of the parameter. |
Example:
...
<postprocess ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE in ('ishpdf')">
<beforecompare>
<currentversion>
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES"/>
<pluginreference ref="ISHCHECKREFERENCES"/>
</sequence>
</currentversion>
<compareversion>
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES"/>
<pluginreference ref="ISHCHECKREFERENCES"/>
</sequence>
</compareversion>
</beforecompare>
<compare handler="IshPublishCompare">
<parameters />
</compare>
<combinelanguages handler="IshPublishCombineLanguages">
<parameters/>
</combinelanguages>
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES" ishcondition="ISHCompare='FALSE'"/>
<pluginreference ref="ISHCHECKREFERENCES" ishcondition="ISHCompare='FALSE'"/>
<pluginreference ref="ISHSAVEFILESTORUNLEGACYSCRIPTS"/>
<pluginreference ref="ISHRESTOREDOCTYPE"/>
<pluginreference ref="ISHRUNDITAOT"/>
<pluginreference ref="ISHFINDDITAOTPDFRESULTFILE"/>
<pluginreference ref="ISHUPLOADDITAOTRESULTFILE"/>
</sequence>
</postprocess>
...
<postprocess ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE in ('htmlhelp', 'ishhtmlhelp')">
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES"/>
<pluginreference ref="ISHCHECKREFERENCES"/>
<pluginreference ref="ISHSAVEFILESTORUNLEGACYSCRIPTS" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE in ('ishhtmlhelp')"/>
<pluginreference ref="ISHRESTOREDOCTYPE"/>
<pluginreference ref="ISHRUNDITAOTWITHCOPYIMAGES"/>
<pluginreference ref="ISHFINDDITAOTCHMRESULTFILE"/>
<pluginreference ref="ISHUPLOADDITAOTRESULTFILE"/>
</sequence>
</postprocess>
...
Plugin definitions plugins
| Node name | Description |
|---|---|
| plugindefinitions | Specifies a number of plugin definitions that can be referenced from within the postprocess element. This provides an easy way to reuse the same plugin definition for different output formats. |
| plugindefinition @name | Defines one plugin definition. The name of the plugindefinition should be unique. For custom plugin you should not start the name with ISH (which indicates a out-of-the-box plugin). |
| plugindefinition @handler | The C# class that contains the implementation of the IPublishPostProcessPlugin interface. |
| description | The description of the plugin. |
| initialize | Describes the parameters that should be passed to the plugin instance upon initialization. |
| parameters | Contains parameter elements. |
| parameter |
The parameter that is passed to the plugin.
|
| parameter @name | The name of the parameter. |
Example:
...
<plugindefinitions>
<plugindefinition name="ISHREMOVENOTLOCKEDNAVTITLES" handler="IshRemoveNotLockedNavTitles">
<description>
Removes the "navtitle" elements and attributes from "topicref" elements (or specializations of the "topicref" element)
that do not have the "locktitle" attributes set to "yes" from DITA maps (or specializations of DITA maps), to avoid that
"DITA-OT" takes them into account.
</description>
<initialize />
</plugindefinition>
<plugindefinition name="ISHCHECKREFERENCES" handler="IshCheckReferences">
<description>Checks that the links, hyperlinks, conref, conrefend, keyrefs targets exist and updates the report items with the found status.</description>
<initialize>
<parameters>
<!-- When the CorrectLegacyHyperlinkSyntaxToDITA is set to yes, hyperlink reference values of the form LOGICALID#ELEMENTID will be corrected to the DITA -->
<!-- syntactically correct LOGICALID#LOGICALID/ELEMENTID. Note that this correction towards LOGICALID#LOGICALID/ELEMENTID might produce an incorrect result -->
<!-- if you have content files that contain more than one topic element and the reference value actually contained a LOGICALID#TOPICID. -->
<parameter name="CorrectLegacyHyperlinkSyntaxToDITA">yes</parameter>
<parameter name="DraftWhenInvalidHyperlink">yes</parameter>
</parameters>
</initialize>
</plugindefinition>
...
</plugindefinitions>
...
Supported conditions
The following condition names can be used for determining if the plugin must be executed:
| Condition name | Description |
|---|---|
| ISHType | This controls whether the plugin needs to execute depending on the type of the object to publish.
|
| ISHLevel | This controls whether the plugin needs to execute depending on the level of the object to publish. The allowed values are: |
| EDT | The element name of the EDT linked with the output format (e.g. EDTZIP). |
| ISHOutputFormat | The output format used for publishing. |
| ISHOutputFormat.* | All fields from the output format used for publishing. The condition name is the element name of the field prefixed by
For example:
|
| ISHCompare | This controls whether the plugin needs to execute when running in compare mode or not. You can use the values TRUE or FALSE. |
| ISHCombineLanguages | This controls whether the plugin needs to execute when publishing with multiple (combined) languages. You can use the values TRUE or FALSE. |
Out-of-the-box global parameters
| Parameter name | Description |
|---|---|
| CatalogFolder | The full path to the folder where the CatalogFile is located.
|
| CatalogFile | The file name of the catalog, in combination with CatalogFolder this should result in the full path to the catalog file.
|
| DraftWhenFallbackLanguageUsed | When some of the topics can only be retrieved in a fallback language but cannot be found in the requested language, this boolean indicate whether the publication output will be a Draft or still a Release candidate.
|
| DraftWhenFallbackLanguageUsedForIllustration | When some of the illustrations can only be retrieved in a fallback language but cannot be found in the requested language, this boolean indicate whether the publication output will be a Draft or still a Release candidate.
|
| DraftWhenFallbackLanguageUsedForResource | When some of the resources can only be retrieved in a fallback language but cannot be found in the requested language, this boolean indicate whether the publication output will be a Draft or still a Release candidate.
|
| CombineLanguageHeaderIshRef | Specifies the identifier of the language separator page in case you publish a publication output with multiple languages.
|
| UseDitaMapExtensionForMaps | Specifies whether the publish export will use a .ditamap file extension when exporting objects of type Map or will use the default .xml file extension.
|
| SkipPersistFixedAttributesList | Specifies which fixed attributes from the DTD should not be persisted in the XML during the publish export phase. As some of the fixed attributes are lengthy and not needed in the Out-Of-The-Box publish plugins, a list of unused attributes is provided to reduce the memory consumption of the publish.
|
| VariableAssignedXPath | XPATH expression used to extract the variable definitions.
|
| VariableInUseXPath | XPATH expression used to find the variable references.
|
| ExtractTargetIds | XPath information to extract the targets.
|
| ExtractLinks | XPath information to extract the links
|
| ExtractImagelinks | XPath information to extract the image links
|
| ExtractHyperlinks | XPath information to extract the hyper links
|
| ExtractConrefs | XPath information to extract the conrefs
|
| ExtractKeyDefinitions | XPath information to extract the key definitions
|
| MaxDegreeOfParallelism | Specifies the maximum number of threads that can be used per Publish background task. Setting this value higher could increase throughput, but will potentially use more database connections, so it should not be set too high.
|
Example
<infoSharePublishPluginConfig version="1.0">
<publish>
<parameters>
<parameter name="CatalogFolder">%ISHPROJECTWEBPATH%\Author\ASP\DocTypes</parameter>
<parameter name="CatalogFile">catalog.xml</parameter>
<parameter name="DraftWhenFallbackLanguageUsed">yes</parameter>
<parameter name="DraftWhenFallbackLanguageUsedForIllustration">no</parameter>
<parameter name="DraftWhenFallbackLanguageUsedForResource">yes</parameter>
<parameter name="VariableAssignedXPath">//*[@varid][not(ancestor-or-self::*[@varref])][not(ancestor::*[@conref])]</parameter>
<parameter name="VariableInUseXPath">//*[@varref][not(ancestor::*[@varref])][not(ancestor::*[@conref])]</parameter>
...
</parameters>
<export>
<parameters>
<parameter name="documentobjrequestedmetadata">
<ishfields>
<ishfield name="FTITLE" level="logical" />
<ishfield name="FDESCRIPTION" level="logical" />
<ishfield name="VERSION" level="version" />
<ishfield name="FCHANGES" level="version" />
<ishfield name="FAUTHOR" level="lng" />
<ishfield name="FSTATUS" level="lng" />
...
</ishfields>
</parameter>
<parameter name="publicationoutputrequestedmetadata">
<ishfields>
<ishfield name="FTITLE" level="logical"/>
<ishfield name="FDESCRIPTION" level="logical"/>
<ishfield name="VERSION" level="version"/>
...
<ishfield name="FPUBINCLUDECOMMENTS" level="lng"/>
<ishfield name="FPUBINCLUDEMETADATA" level="lng"/>
<ishfield name="FPUBWATERMARK" level="lng"/>
<ishfield name="FISHPUBREVIEWENDDATE" level="lng"/>
<ishfield name="FISHPUBLNGCOMBINATION" level="lng" ishvaluetype="value" />
<ishfield name="FISHPUBSTATUS" level="lng" ishvaluetype="element" />
...
<ishfield name="FISHDITADLVRREMOTESTATUS" level="lng" ishvaluetype="element" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishditadelivery'"/>
<ishfield name="FISHPRODUCTFAMILYNAME" level="logical" ishvaluetype="value" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishditadelivery'"/>
<ishfield name="FISHPRODUCTRELEASENAME" level="version" ishvaluetype="value" ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishditadelivery'"/>
</ishfields>
</parameter>
</parameters>
</export>
...
<postprocess ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE in ('ishpdf')">
<beforecompare>
<currentversion>
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES"/>
<pluginreference ref="ISHCHECKREFERENCES"/>
</sequence>
</currentversion>
<compareversion>
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES"/>
<pluginreference ref="ISHCHECKREFERENCES"/>
</sequence>
</compareversion>
</beforecompare>
<compare handler="IshPublishCompare">
<parameters />
</compare>
<combinelanguages handler="IshPublishCombineLanguages">
<parameters/>
</combinelanguages>
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES" ishcondition="ISHCompare='FALSE'"/>
<pluginreference ref="ISHCHECKREFERENCES" ishcondition="ISHCompare='FALSE'"/>
<pluginreference ref="ISHSAVEFILESTORUNLEGACYSCRIPTS"/>
<pluginreference ref="ISHRESTOREDOCTYPE"/>
<pluginreference ref="ISHRUNDITAOT"/>
<pluginreference ref="ISHFINDDITAOTPDFRESULTFILE"/>
<pluginreference ref="ISHUPLOADDITAOTRESULTFILE"/>
</sequence>
</postprocess>
...
<postprocess ishcondition="ISHOutputFormat.FDITAOTTRANSTYPE='ishxpp'">
<sequence>
<pluginreference ref="ISHREMOVENOTLOCKEDNAVTITLES"/>
<pluginreference ref="ISHCHECKREFERENCES"/>
<pluginreference ref="ISHSAVEFILESTORUNLEGACYSCRIPTS"/>
<pluginreference ref="ISHRESTOREDOCTYPE"/>
<pluginreference ref="ISHRUNDITAOT"/>
<plugin name="ISHRUNSDLXPP" handler="IshRunSDLXPP">
<description>
Uploads the merged xml file obtained from DITA-OT together with the images to SDL XPP and
runs the transformation to convert them to PDF
</description>
<initialize>
<parameters>
<parameter name="ScriptsFolder">%ISHPROJECTAPPPATH%\Utilities\PublishingService\Tools</parameter>
</parameters>
</initialize>
</plugin>
<pluginreference ref="ISHFINDDITAOTPDFRESULTFILE"/>
<pluginreference ref="ISHUPLOADDITAOTRESULTFILE"/>
</sequence>
</postprocess>
...
<plugindefinitions>
<plugindefinition name="ISHREMOVENOTLOCKEDNAVTITLES" handler="IshRemoveNotLockedNavTitles">
<description>
Removes the "navtitle" elements and attributes from "topicref" elements (or specializations of the "topicref" element)
that do not have the "locktitle" attributes set to "yes" from DITA maps (or specializations of DITA maps), to avoid that
"DITA-OT" takes them into account.
</description>
<initialize />
</plugindefinition>
<plugindefinition name="ISHCHECKREFERENCES" handler="IshCheckReferences">
<description>Checks that the links, hyperlinks, conref, conrefend, keyrefs targets exist and updates the report items with the found status.</description>
<initialize>
<parameters>
<!-- When the CorrectLegacyHyperlinkSyntaxToDITA is set to yes, hyperlink reference values of the form LOGICALID#ELEMENTID will be corrected to the DITA -->
<!-- syntactically correct LOGICALID#LOGICALID/ELEMENTID. Note that this correction towards LOGICALID#LOGICALID/ELEMENTID might produce an incorrect result -->
<!-- if you have content files that contain more than one topic element and the reference value actually contained a LOGICALID#TOPICID. -->
<parameter name="CorrectLegacyHyperlinkSyntaxToDITA">yes</parameter>
<parameter name="DraftWhenInvalidHyperlink">yes</parameter>
</parameters>
</initialize>
</plugindefinition>
...
</plugindefinitions>
</publish>
</infoSharePublishPluginConfig>