Documentation Center

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 Settings > XML Background task Settings

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

  1. 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.
  2. The DITACheckLinks and DITACheckHyperlinks validation works quite similar: All link-start elements from the report are processed and the ref, keyref and scope attributes are used to determine validity in this way:
    1. When the link-start element does not have a keyref attribute:
      1. When the scope attribute is external or peer, the target-valid attribute is set to unknown.
      2. When the target of the ref attribute exists in the current publication, the target-valid attribute of the element is set to yes.
      3. When the target of the ref attribute does NOT exist in the current publication, the target-valid attribute of the element is set to no.
    2. When the link-start element has a keyref attribute, the system looks for the corresponding key definition:
      1. If no key definition is found, the keyref is ignored and validation is done as if no keyref was present
      2. If a key definition exists, the system uses the target and scope of the key definition target ref to determine validity, so:
        1. When the key definition scope attribute is external or peer, the target-valid attribute is set to unknown.
        2. When the key definition target ref attribute exists in the current publication, the target-valid attribute of the element is set to yes.
        3. When the key definition target ref attribute does not exists in the current publication, the original href is used as a fallback mechanism and validation of the original ref and scope is done.
  3. The DITACheckConrefs works similar as Links or Hyperlinks, except that is uses the conkeyref attribute instead of the keyref attribute, and that it validates and uses the conref and conrefend attributes.

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.