IEventHandler - PublishService.cExport4Pub
Technical reference about the cExport4Pub procedure and configuration
Overview
cExport4Pub allows you to configure and perform publication exports in a background process task.
Algorithm / Process Flow
Provides the functionality to export all data for publishing.
Configuration options / Parameters
The background process to trigger the cExport4Pub is configured within the background task configuration which is accessible from the Content Manager web client using
<handler eventType="EXPORTFORPUBLICATION">
<scheduler executeSynchronously="false" />
<authorization type="authenticationContext" />
<execution timeout="1.00:00:00" recoveryGracePeriod="00:30:00" isolationLevel="Process" useSingleThreadApartment="true" />
<activator>
<comIEventHandler projectName="PublishServiceIso" className="CExport4Pub">
<configuration>
<parameters>
<parameter name="raiseevent" type="value">PUBLISHINGSERVICEPROCESS</parameter>
</parameters>
<checkhyperlinks>
<!-- hyperlinkseparator defines the separator between MAPID and ANCHOR inside the map e.g. GA100#CHAPTER2 -->
<hyperlinkseparator>#</hyperlinkseparator>
<!-- If the 'draftoninvalidhyperlink' parameter is set to 'yes' the status of the Publication Output will be set to 'Draft' when one or more hyperlinks within the publication is invalid;
when it is set to 'no' invalid hyperlinks will be reported in the 'Status Report' but ignored when determining if the Publication Output is a 'Release candidate'. -->
<draftoninvalidhyperlink>yes</draftoninvalidhyperlink>
<ditakeyrefredirectionconfiguration>
<parameters>
<parameter name="keysxpath" type="value">(//*[@keys][contains(@class,' map/topicref ')][not(ancestor-or-self::*[@varref])][not(ancestor::*[@conref])])</parameter>
<parameter name="keysextrainfonames" type="value">keys;ref;keyref;class;scope</parameter>
<parameter name="keysextrainfoxpaths" type="value">@keys;@href;@keyref;@class;ancestor-or-self::*[@scope][position()=1]/@scope</parameter>
<parameter name="linkxpath" type="value">(//*[contains(@class,' map/topicref ')][(@href and @href!='-dita-use-conref-target') or (@keyref)][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])])</parameter>
<parameter name="linkextrainfonames" type="value">ref;keyref;scope;processing-role;print;class</parameter>
<parameter name="linkextrainfoxpaths" type="value">@href;@keyref;ancestor-or-self::*[@scope][position()=1]/@scope;ancestor-or-self::*[@processing-role][position()=1]/@processing-role;ancestor-or-self::*[@print][position()=1]/@print;@class</parameter>
<parameter name="imagelinkxpath" type="value">(//*[contains(@class,' topic/image ')][(@href and @href!='-dita-use-conref-target') or (@keyref)][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])]) | (//*[contains(@class,' topic/object ')][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])][not(contains(@data,':'))]/@data) | (//*[contains(@class,' topic/param ') and (@name='movie' or @name='src' or @name='URL')][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])][not(contains(@value,':'))]/@value)</parameter>
<parameter name="imagelinkextrainfonames" type="value">ref;keyref;scope;class</parameter>
<parameter name="imagelinkextrainfoxpaths" type="value">@href | @data;@keyref;ancestor-or-self::*[@scope][position()=1]/@scope;@class</parameter>
<parameter name="hyperlinkxpath" type="value">(//*[contains(@class,' topic/xref ')][(@href and @href!='-dita-use-conref-target') or (@keyref)][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])]) | (//*[contains(@class,' topic/link ')][(@href and @href!='-dita-use-conref-target') or (@keyref)][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])]) | (//*[contains(@class,' map/reltable ')]//*[contains(@class,' map/topicref ')][(@href and @href!='-dita-use-conref-target') or (@keyref)][not(ancestor::*[@conref])][not(ancestor-or-self::*[@varref])])</parameter>
<parameter name="hyperlinkextrainfonames" type="value">ref;keyref;scope;class</parameter>
<parameter name="hyperlinkextrainfoxpaths" type="value">@href;@keyref;ancestor-or-self::*[@scope][position()=1]/@scope;@class</parameter>
<parameter name="conrefxpath" type="value">(//*[@conref or @conrefend or @conkeyref][not(ancestor-or-self::*[@varref])][not(ancestor::*[@conref])])</parameter>
<parameter name="conrefextrainfonames" type="value">conref;conkeyref;conrefend;class</parameter>
<parameter name="conrefextrainfoxpaths" type="value">@conref;@conkeyref;@conrefend;@class</parameter>
</parameters>
</ditakeyrefredirectionconfiguration>
</checkhyperlinks>
</configuration>
</comIEventHandler>
</activator>
<errorHandler maximumRetries="10">
<actions>
<add errorNumber="-1" action="Retry" delay="00:01:00" />
</actions>
</errorHandler>
</handler>
- hyperlinkseparator
- Defines the separator between the Logical Id and the Anchor inside the map e.g. GA100#CHAPTER2.
- draftoninvalidhyperlink
- If this parameter is set to 'yes' the status of the Publication Output will be set to 'Draft' when one or more hyperlinks within the publication is invalid; when it is set to 'no' invalid hyperlinks will be reported in the 'Status Report' but ignored when determining if the Publication Output is a 'Release candidate'.
- ditakeyrefredirectionconfiguration
- Extra configuration to support validation with DITA 1.2 keyref support. The idea is to extract the href, keyref, scope, keys, keyref and all other information that affects validation of links, hyperlinks, images, etc. for every xml document that is published. The gathered information is stored in the publish report xml below the "object-report" element of the xml document being published. When all the xml documents are published and all relevant information is gathered, the validation uses the gathered information from the report.
- keysxpath
- Defines the XPath expression to extract all the elements that define a key (via the keys attributes). Every returned element will become a "key-definition" element below the "object-report" element in the publish report. You might need to extend this parameter to support DITA specializations.
- keysextrainfonames
- A separated list of extra attribute names to add on a "key-definition" element in the publish report. The attributes will be then be used in the link, hyperlink, image and conref validation. Note that the number of items should match the number of items of keysextrainfoxpaths. Don't change the value of this parameter.
- keysextrainfoxpaths
-
A separated list of XPaths to execute on all the elements returned by keysxpath. The resulting string (when not empty) is then put in the publish report xml in the attribute name specified on the same position of keysextrainfonames. You might need to extend this parameter to support DITA specializations.
With the example configuration above the following pseudo code is executed, and 5 extra attributes are added to the publish result node to check hyperlink validation: for each element in xmldocument.selectnodes("(//*[contains(@class,' map/topicref ')][@keys])") keydefnode = publishreport.createElement("key-definition") if exists element.selectSingleNode("@keys") then keydefnode.attribute("keys") = element.selectSingleNode("@keys") end if if exists element.selectSingleNode("@href") then keydefnode.attribute("ref") = element.selectSingleNode("@href") end if if exists element.selectSingleNode("@keyref") then keydefnode.attribute("keyref") = element.selectSingleNode("@keyref") end if if exists element.selectSingleNode("@class") then keydefnode.attribute("class") = element.selectSingleNode("@class") end if if exists element.selectSingleNode("ancestor-or-self::*[@scope][position()=1]/@scope") then keydefnode.attribute("scope") = element.selectSingleNode("ancestor-or-self::*[@scope][position()=1]/@scope") end if next element - linkxpath
- Defines the XPath expression to extract all link elements that do not occur inside a conrefed part of the document. Every returned element will become a "link-start" element below the "object-report" element in the publish report. You might need to extend this parameter to support DITA specializations.
- linkextrainfonames
-
A separated list of extra attribute names to add on a "link-start" element in the publish report. The attributes will be used during link validation. Note that the number of items should match the number of items of linkextrainfoxpaths.
- linkextrainfoxpaths
- A separated list of XPaths to execute on all the elements returned by linkxpath. The resulting string (when not empty) is then put in the publish report xml in the attribute name specified on the same position of linkextrainfonames. You might need to extend this parameter to support DITA specializations.
- imagelinkxpath
- Defines the XPath expression to extract all image elements that do not occur inside a conrefed part of the document. Every returned element will become a "link-start" element below the "object-report" element in the publish report. You might need to extend this parameter to support DITA specializations.
- imagelinkextrainfonames
- A separated list of extra attribute names to add on a "link-start" element in the publish report. The attributes will be then be used in image validation. Note that the number of items should match the number of items of imagelinkextrainfoxpaths. Don't change the value of this parameter.
- imagelinkextrainfoxpaths
- A separated list of XPaths to execute on all the elements returned by imagelinkxpath. The resulting string (when not empty) is then put in the publish report xml in the attribute name specified on the same position of imagelinkextrainfonames. You might need to extend this parameter to support DITA specializations.
- hyperlinkxpath
- Defines the XPath expression to extract all hyperlink elements that do not occur inside a conrefed part of the document. Every returned element will become a "hyperlink-start" element below the "object-report" element in the publish report. You might need to extend this parameter to support DITA specializations.
- hyperlinkextrainfonames
-
A separated list of extra attribute names to add on a "hyperlink-start" element in the publish report. The attributes will be then be used in the hyperlink validation. Note that the number of items should match the number of items of hyperlinkextrainfoxpaths.
- hyperlinkextrainfoxpaths
- A separated list of XPaths to execute on all the elements returned by hyperlinkxpath. The resulting string (when not empty) is then put in the publish report xml in the attribute name specified on the same position of hyperlinkextrainfonames. You might need to extend this parameter to support DITA specializations.
- conrefxpath
- Defines the XPath expression to extract all conrefed elements that do not occur inside a conrefed part of the document. Every returned element will become a "conref-start" element below the "object-report" element in the publish report. You might need to extend this parameter to support DITA specializations.
- conrefextrainfonames
-
A separated list of extra attribute names to add on a "conref-start" element in the publish report. The attributes will be then be used in the conref and conrefend validation. Note that the number of items should match the number of items of conrefextrainfoxpaths.
- conrefextrainfoxpaths
- A separated list of XPaths to execute on all the elements returned by conrefxpath. The resulting string (when not empty) is then put in the publish report xml in the attribute name specified on the same position of conrefextrainfonames. You might need to extend this parameter to support DITA specializations.
Example Publish Report XML
<export-report language="en" start-document-id="EL-KEYREFTEST-MAINMAP">
...
<object-report ishtype="ISHMasterDoc" ishlogicalref="73743" ishversionref="73744" ishlngref="73745" ishref="EL-KEYREFTEST-SUBMAP" object-title="EL KEYREFTEST SUBMAP" lng="en" status="object-not-released" defined-in-baseline="no" doc-valid-against-dtd="yes" filename="EL-KEYREFTEST-SUBMAP.xml" version="1" objectstatus="Draft">
<key-definition keys="companyname" class="+ map/topicref mapgroup-d/keydef ">companyname</key-definition>
<key-definition keys="google" ref="http://www.google.com/HowToUse.htm" class="- map/topicref " scope="external">google</key-definition>
<key-definition keys="microsoft" ref="http://www.microsoft.com/duplicatekey" class="- map/topicref " scope="external">microsoft</key-definition>
<link-start target-valid="unknown" ref="http://www.google.com/HowToUse.htm" scope="external" class="- map/topicref " resolved-ref="http://www.google.com/HowToUse.htm" resolved-scope="external">http://www.google.com/HowToUse.htm</link-start>
<link-start target-valid="unknown" ref="http://www.microsoft.com/duplicatekey" scope="external" class="- map/topicref " resolved-ref="http://www.microsoft.com/duplicatekey" resolved-scope="external">http://www.microsoft.com/duplicatekey</link-start>
<targets>
<block id="EL-KEYREFTEST-SUBMAP"/>
</targets>
</object-report>
...
<object-report ishtype="ISHModule" ishlogicalref="73747" ishversionref="73748" ishlngref="73755" ishref="EL-KEYREFTEST-TESTHYPERLINKS" object-title="EL KEYREFTEST TESTHYPERLINKS" lng="en" status="object-not-released" defined-in-baseline="no" doc-valid-against-dtd="yes" filename="EL-KEYREFTEST-TESTHYPERLINKS.xml" version="1" objectstatus="Draft">
<link-start target-valid="yes" ref="GUID-C055DEF2-7983-4866-B368-0B9E913B4E67" class="- topic/image " resolved-ref="GUID-C055DEF2-7983-4866-B368-0B9E913B4E67">GUID-C055DEF2-7983-4866-B368-0B9E913B4E67</link-start>
<link-start target-valid="no" ref="ELUNEXIMAGE1" class="- topic/image " resolved-ref="ELUNEXIMAGE1">ELUNEXIMAGE1</link-start>
<hyperlink-start target-valid="no" ref="EL-KEYREFTEST-GUID-OOO#EL-KEYREFTEST-GUID-OOO/P1541" scope="local" class="- topic/xref " resolved-ref="EL-KEYREFTEST-GUID-OOO#EL-KEYREFTEST-GUID-OOO/P1541" resolved-scope="local">EL-KEYREFTEST-GUID-OOO#EL-KEYREFTEST-GUID-OOO/P1541</hyperlink-start>
<hyperlink-start target-valid="no" ref="EL-KEYREFTEST-GUID-PPP#EL-KEYREFTEST-GUID-PPP/P18232" keyref="unex" scope="local" class="- topic/xref " resolved-ref="EL-KEYREFTEST-GUID-PPP#EL-KEYREFTEST-GUID-PPP/P18232" resolved-scope="local">EL-KEYREFTEST-GUID-PPP#EL-KEYREFTEST-GUID-PPP/P18232</hyperlink-start>
<conref-start target-valid="yes" temporary-check-value="EL-KEYREFTEST-DEF#EL-KEYREFTEST-DEF/P411" conref="EL-KEYREFTEST-DEF#EL-KEYREFTEST-DEF/P411" conkeyref="abc/P411" conrefend="EL-KEYREFTEST-DEF#EL-KEYREFTEST-DEF/P412" class="- topic/p " resolved-conref="EL-KEYREFTEST-ABC#EL-KEYREFTEST-ABC/P411" resolved-conrefend="EL-KEYREFTEST-ABC#EL-KEYREFTEST-ABC/P412" resolved-scope="local">EL-KEYREFTEST-ABC#EL-KEYREFTEST-ABC/P411</conref-start>
<targets>
<block id="EL-KEYREFTEST-TESTHYPERLINKS">
<element id="GUID-B2C1B693-0E4E-41E2-B0BF-8EEA58CE2A61"/>
</block>
</targets>
</object-report>
...
</export-report>
How link, hyperlink and conref validation uses the extra information, gathered by configuring ditakeyrefredirectionconfiguration
- While the documents are being exported, the key definitions, key references, hrefs, scope, etc. are extracted and added to the publish report as described above. DITA Maps are exported and placed in the publish report in a breadth-first order. This order is important when there are keys that are defined twice. According to the OASIS DITA 1.2 specification the first key definition, found in breadth-first order should be taken.
- The DITACheckLinks and DITACheckHyperlinks validation works quite similar: All
link-startelements from the report are processed and theref,keyrefandscopeattributes are used to determine validity in this way:- When the
link-startelement does not have akeyrefattribute:- When the
scopeattribute isexternalorpeer, thetarget-validattribute is set tounknown. - When the target of the
refattribute exists in the current publication, thetarget-validattribute of the element is set toyes. - When the target of the
refattribute does NOT exist in the current publication, thetarget-validattribute of the element is set tono.
- When the
- When the
link-startelement has akeyrefattribute, the system looks for the corresponding key definition:- If no key definition is found, the
keyrefis ignored and validation is done as if nokeyrefwas present - If a key definition exists, the system uses the target and scope of the key definition target
refto determine validity, so:- When the key definition
scopeattribute isexternalorpeer, thetarget-validattribute is set tounknown. - When the key definition target
refattribute exists in the current publication, thetarget-validattribute of the element is set toyes. - When the key definition target
refattribute does not exists in the current publication, the originalhrefis used as a fallback mechanism and validation of the originalrefandscopeis done.
- When the key definition
- If no key definition is found, the
- When the
- The DITACheckConrefs works similar as Links or Hyperlinks, except that is uses the
conkeyrefattribute instead of thekeyrefattribute, and that it validates and uses theconrefandconrefendattributes.
The resulting target, after keyref resolving, etc. is also saved in a resolved-ref, resolved-conref or resolved-conkeyref attribute on the link-start, hyperlink-start and conref-start elements
Revision information
As of SDL Trisoft 2011 the checkhyperlinks was extended with an extra ditakeyrefredirectionconfigurationconfiguration to support validation with OASIS DITA 1.2 keyref support. In DITA 1.2 the keyref overrules the href on the same element if the key is defined in one of the DITA Maps of the Publication. In the case where the href is invalid but there is a keyref with a key defined, the hyperlink validation should not report the href as being invalid.
Since SDL LiveContent Architect 2014 (InfoShare 11.0.0), the configuration is moved from InfoShareConfig.xml to the background task configuration.