Documentation Center

IBackgroundTaskHandler - Publish

Exports the content of a publication to the file system and uses plugins to convert the content into the request output format

Input data

The publish can start from (1) a publication output or (2) the version of a map or topic. Depending on how the publish is started, the input data will be different.

  1. Input data for a publication output.

    The input data XML identifies a publication output:

    export-document-type
    The ishtype of the starting object. The value is always ISHPublication.
    • Required: yes
    export-document-level
    The level of the starting object. The value is always lng.
    • Required: yes
    export-ishlngref
    The numerical identifier of the publication output.
    • Required: yes
    creationdate
    Date time indicating when the publish was triggered.
    • Required: no
    This XML examples shows the typical input data:
    <data>
      <export-document-type>ISHPublication</export-document-type>
      <export-document-level>lng</export-document-level>
      <export-ishlngref>1004828</export-ishlngref>
      <creationdate>20170915162510159</creationdate>
    </data>
  2. Input data for the version of a map or topic

    Since all the information which is stored on the publication version and publication output must be passed as in the input data, the input data for a version of a map or topic is much bigger and complex.

    So, in order to trigger the Publish background task for the version of a map or topic, you should use DocumentObj25.RaisePublishEvent which will generate the following XML structure:
    <data>
      <ishref>GUID-C9CA7357-CBA3-43B3-A4B2-B977AD1B7D1E</ishref>
      <ishtype>ISHMasterDoc</ishtype>
      <ishlevel>version</ishlevel>
      <version>2</version>
      <!--publisher='admin'-->
      <publisher>VUSERADMIN</publisher>
      <!--outputformat='PDF (A4 Manual)'-->
      <outputformat>GUID-2A69335D-F025-4963-A142-5E49988C7C0C</outputformat>
      <!--languages= fr-->
      <languages>VLANGUAGEFR</languages>
      <rootdocumentobjectishref>GUID-C9CA7357-CBA3-43B3-A4B2-B977AD1B7D1E</rootdocumentobjectishref>
      <resources>GUID-8C023953-0F7C-4986-9DE2-568FF183FC25, GUID-9E48AEC2-2AF4-444A-85C2-A96EE537A340</resources>
      <!--fallbacklanguages= en-->
      <fallbacklanguages>VLANGUAGEEN</fallbacklanguages>
      <!--illustrationfallbacklanguages= en-->
      <illustrationfallbacklanguages>VLANGUAGEEN</illustrationfallbacklanguages>
      <!--resourcefallbacklanguages= en-->
      <resourcefallbacklanguages>VLANGUAGEEN</resourcefallbacklanguages>
      <baseline />
      <!--baselinecompletemode='Latest available'-->
      <baselinecompletemode>VBASELINECOMPLETEMODELATESTAVAILABLE</baselinecompletemode>
      <!--workinglanguage='en'-->
      <workinglanguage>VLANGUAGEEN</workinglanguage>
      <!--workingresolution='Low'-->
      <workingresolution>VRESLOW</workingresolution>
      <xmlproductdefinition>&lt;features&gt;
        &lt;feature name='BLUETOOTH' value='Y' /&gt;
        &lt;feature name='GAMES' value='DJ' /&gt;
        &lt;feature name='GAMES' value='SNAKE' /&gt;
        &lt;feature name='GAMES' value='WATERRAPIDS' /&gt;
        &lt;feature name='GPRS' value='Y' /&gt;
        &lt;feature name='HEADSET' value='Y' /&gt;
        &lt;feature name='LOUDSPEAKER' value='Y' /&gt;
        &lt;feature name='MODEL' value='330' /&gt;
    &lt;/features&gt;</xmlproductdefinition>
      <compareversion />
      <compareversionrootdocumentobjectishref />
      <compareversionresources />
      <compareversionbaseline />
      <compareversionxmlproductdefinition />
      <parameters>
        <parameter name="FPUBINCLUDECOMMENTS">true</parameter>
        <parameter name="FPUBINCLUDEMETADATA">true</parameter>
        <parameter name="FPUBWATERMARK">false</parameter>
      </parameters>
    </data>

Background task configuration

The list below describes the configurable parameters:
exportlocation
Full path to the folder where a sub folder is created into which all files will be exported
  • Required: yes
  • Default value: %ISHPROJECTDATAPATH%\Publish\Data
  • Allowed values: Any folder path which is valid on all application servers that might pick up the background task

Default background task configuration example

The following configuration handles the Publish background task for Dynamic Delivery:

<handler eventType="PUBLISHDITADELIVERY">
  <scheduler executeSynchronously="false"/>
  <authorization type="authenticationContext"/>
  <execution timeout="1.00:00:00" recoveryGracePeriod="00:30:00" isolationLevel="Process" useSingleThreadApartment="false"/>
  <activator>
    <net name="Publish">
      <parameters>
        <parameter name="exportlocation">%ISHPROJECTDATAPATH%\Publish\Data</parameter>
      </parameters>
    </net>
  </activator>
  <errorHandler maximumRetries="3">
    <actions>
      <!-- Retry on connection failures to the external system -->
      <add errorNumber="-111001" action="Retry" delay="00:10:00" />
      <!-- Retry on integration failures to the external system -->
      <add errorNumber="-111002" action="Retry" delay="00:10:00" />
      <!-- Retry on publication was locked by another user -->
      <add errorNumber="-140" action="Retry" delay="00:10:00" />
    </actions>
  </errorHandler>
</handler>

Flow

  1. Validate the input data and align the 2 types of input data by creating a generic context
  2. Autocomplete (if necessary) the baseline using the working language and resolution in order to determine the versions of the objects
  3. Determine the language objects which must be exported
  4. Enlist all variables with resolved values
  5. Create the export folder and a version folder underneath it
  6. Recursively export the content of all language objects starting from the root map to the export\version\language folder:
    • Xml content

      Before saving the file system the xml content is processed:

      • First pretranslation tags are removed (if necessary)
      • Validate xml against the DTD
      • In order to avoid loosing performance by unnecessary loading of the xml with DTD, the default attributes are added and the DOCTYPE definition is moved to a processing instruction
      • All content is conditionally filtered before exporting
      • All variables are resolved during export
    • Binary content

      Binary content is saved to the file system without extra processing

    Remarks:

    • Only the language objects which are not conditionally filtered out are exported
    • If the language object does not exist and cannot be found in a fallback language, a file with a matching missing object is referenced instead.
    • Illustrations are exported in all requested resolutions, although the first resolution is considered preferred.
    • If the illustration is not available in the language for one of the resolutions, the publish will use the illustration in the fallback language for that resolution or even use the missing illustration for that resolution.
    • If the publish contains multiple languages, the topic configured with the CombineLanguageHeaderIshRef parameter is exported for every language.
  7. Export the metadata for all exported language objects
  8. A IPublishPostProcessContext context is created for the current version
  9. If the compare option of the publish is enabled and the compare version is provided, all above steps starting from the baseline autocomplete are performed for the compare version as well, resulting in a compare version export folder with all the content and metadata files of that version as well, so that the export folder contains 2 subfolders, one with the files exported for the current version and one with the files exported for the compare version and a second IPublishPostProcessContext context is created for the compare version.
  10. Before starting any of the plugins, the contents of the export folder is copied to a work folder
  11. If the compare option of the publish is enabled and the compare version is provided:
    • A folder named compare is created in the work folder
    • A list is build with all the logical ids (and in case of images their resolution) and filenames of all the files that were exported to the compare version folder, the current version folder or both.
    • For every object in the list:
      • If the object is of typeImage or Template, the code of the Publish background task will copy the correct image or template files to the result folder and a PublishCompareResult result is calculated and stored in the list
      • If the object is of type Map, Topic or Library, the CompareXml method of the configured IPublishComparePlugin plugin is called and the PublishCompareResult result is stored in the list.
      • If there is a metadata file belonging to the object, the CompareMetadata method of the configured IPublishComparePlugin plugin is called and the PublishCompareResult result is stored in the list.
      • The resulting list with the compare results is saved to a file named PublishCompareReport.xml in the work folder
      • A new IPublishPostProcessContext context is created with a merger of all report items of the compare and current version. When the logical object is used in both versions, the links, image links, conrefs, ... and messages of the 2 report items will be merged.
  12. If the publish contains multiple languages, the configured IPublishCombineLanguagesPlugin plugin is executed
  13. The configured publish post process plugins are triggered with the created IPublishPostProcessContext context
  14. Finalize the publish
    • If one of the plugins has set FinishDeployingBackgroundTask:
      • When publishing a publication output, set the status to Deploying Draft or Deploying Release Candidate
      • Create a background task with the specific event data and event type inside the main event logging
    • Otherwise
      • When publishing a publication output, set the status to Draft or Release Candidate