Documentation Center

IPublishPostProcessPlugin - DitaDeliveryPrepareOverallPackage

Moves the files that need to be transported for Dynamic Delivery to a certain folder based on the configured file patterns and creates an XML file listing all the files that need to be send.

Plugin Input

Plugin configuration parameters
ParameterRequiredDefault valueAllowed valuesDescription
DITAOTOutDirectoryContextItemKeyYesThe name of key of input parameter to get the full directory name of the out directory generated by DITA-OTThe input value with the full directory name of the out directory generated by DITA-OT will be obtained from the context.Items collection.
PackageContentYesConfiguration must comply with the Package Content SchemaThe configuration that describes the folder names (defined by the group name) to use, which type of files are in the folder and the file patterns that define which files need to go into the folder.
ContentObjectIdLevelNoIf parameter is not present, default value is lnglng, logicalLevel which identifies whether LANGUAGECARDID or LOGICALCARDID will be used in place of CARDID for file names of the form [PUBLICATIONOUTPUTID]-[CARDID]-[TYPE].[FILEEXTENSION].
Input expected in the context.Items collection
Item KeyRequiredDefault valueItem Value TypeDescription
MetadataExtensionNo.jsonstringExtension to use to find the metadata file next to the file to transport.
The name of key is specified in the parameter DITAOTOutDirectoryContextItemKeyyesstringThe out folder of DITA-OT

The files that need to go into the transport package should be present in the folder provided in the item associated with DITAOTOutDirectoryContextItemKey in the context.

The accompanying metadata files should be in a JSON format.

Plugin Outcome

Changes made to the file system:
  • All files (and accompanying metadata files) that need to be sent for Dynamic Delivery will be moved to subfolders with the configured group names inside the Data\Publish\Data\[RANDOMFOLDERNAME]\work\TP\ALL folder and are given new filenames of the form [PUBLICATIONOUTPUTID]-[CARDID]-[TYPE].[FILEEXTENSION], where CARDID might be LOGICALCARDID or LANGUAGECARDID depending on parameter ContentObjectIdLevel. For some files, a CARDID might not be present, so a unique number for that type will be generated by the plugin.
  • A package.xml file is created in the TP/ALL folder. That file contains a list of all the files that need to be sent.
  • A __packages.xml file is created in the TP folder which is similar than the package.xml, but holds some extra information of the files to send.
Values set in the context.Items collection as a result
Item KeyTypical ValueItem Value TypeDescription
TransportPackageRootDirectory...\Data\Publish\Data\[RANDOMFOLDERNAME]\work\TPstringThe root transport package folder.
ExtendedOverallPackageObjectFilePath...\Data\Publish\Data\[RANDOMFOLDERNAME]\work\TP\__packages.xmlstringFile path of the XML that contains an overview of all the files that need to be transported to Dynamic Delivery.
TransportPackageDirectoriesA string list with one entry: "Data\Publish\Data\[RANDOMFOLDERNAME]\work\TP\ALL"List<string>A list of Folder paths were the Transport Packages content that needs to be sent can be found. When this plugin has completed its process, the list only contains one value: The location of the ALL folder.

plugin name="ISHDITADELIVERYCREATEOVERALLPACKAGE" example


<!-- Created with Liquid Technologies Online Tools 1.0 (https://www.liquid-technologies.com) -->
<plugin name="ISHDITADELIVERYCREATEOVERALLPACKAGE" handler="DITADeliveryCreateOverallPackage">
  <description>Moves the files needed to be transported to DITA Delivery into a folder structure under the "Data\Publish\Data\[RANDOMFOLDERNAME]\work\TP\ALL"</description>
  <initialize>
    <parameters>
      <parameter name="DITAOTOutDirectoryContextItemKey">DITAOTOutDirectory</parameter>
      <parameter name="ContentObjectIdLevel">logical</parameter>
      <parameter name="PackageContent">
        <groups>
          <group name="pub">
            <objects type="publication">
              <includefiles>Publication.json</includefiles>
            </objects>
          </group>
          <group name="nav">
            <objects type="toc">
              <includefiles>toc.html</includefiles>
            </objects>
            <objects type="index">
              <includefiles>index.xml</includefiles>
            </objects>
          </group>
          <group name="page">
            <objects type="page">
              <includefiles>*.html</includefiles>
            </objects>
          </group>
          <group name="schema">
            <objects type="publication_schema">
              <includefiles>publication_metadata_schema.json</includefiles>
            </objects>
            <objects type="page_schema">
              <includefiles>page_metadata_schema.json</includefiles>
            </objects>
            <objects type="binary_schema">
              <includefiles>binary_metadata_schema.json</includefiles>
            </objects>
          </group>
          <group name="bin">
            <objects type="binary">
              <includefiles>*.*</includefiles>
              <excludefiles>commonltr.css</excludefiles>
              <excludefiles>commonrtl.css</excludefiles>
              <!-- exclude any metadata file that did not have a content file -->
              <excludefiles>*.json</excludefiles>
              <excludefiles>*.ditamap_ishditadelivery.log</excludefiles>
            </objects>
          </group>
        </groups>
      </parameter>
    </parameters>
  </initialize>
</plugin>

Example of a resulting __packages.xml file


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<!-- Created with Liquid Technologies Online Tools 1.0 (https://www.liquid-technologies.com) -->
<Package>
  <Group Name="bin">
    <Object Id="ish:39137-6333-16" Type="binary" SubFolderName="ALL" OriginalFile="GUID-6292C9EB-CB58-46CC-8F14-471B2A80D839-low.jpg" Content="39137-6333-16.jpg" Metadata="39137-6333-16.json" LanguageCardId="6312" RevisionId="GUID-A4BCB0BD-325D-4804-BE75-724B2A7AA9CC" />
    <Object Id="ish:39137-6377-16" Type="binary" SubFolderName="ALL" OriginalFile="GUID-DEED112E-8856-46A3-ADA0-E911293DCF8E-low.jpg" Content="39137-6377-16.jpg" Metadata="39137-6377-16.json" LanguageCardId="6356" RevisionId="GUID-EF0BA5ED-B85C-410C-9E85-548875A1AD86" />
    <Object Id="ish:39137-2147483644-16" Type="binary" SubFolderName="ALL" OriginalFile="20160905012715316.MP330.zip" Content="39137-2147483644-16.zip" />
    <Object Id="ish:39137-6923-16" Type="binary" SubFolderName="ALL" OriginalFile="GUID-5F85AF33-F80B-43CA-9B91-502CE6D923B2-low.gif" Content="39137-6923-16.gif" Metadata="39137-6923-16.json" LanguageCardId="6902" RevisionId="GUID-9A15D73D-E624-44AC-9CF3-60C4BBC09387" />
    <Object Id="ish:39137-2147483645-16" Type="binary" SubFolderName="ALL" OriginalFile="GUID-Z.ditamap_ishditadelivery.log" Content="39137-2147483645-16.log" />
  </Group>
  <Group Name="pub">
    <Object Id="ish:39137-1-1" Type="publication" SubFolderName="ALL" OriginalFile="Publication.json" Metadata="39137-1-1.json" LanguageCardId="39137" />
  </Group>
  <Group Name="schema">
    <Object Id="ish:39137-1-8" Type="publication_schema" SubFolderName="ALL" OriginalFile="publication_metadata_schema.json" Content="39137-1-8.json" />
    <Object Id="ish:39137-3-8" Type="binary_schema" SubFolderName="ALL" OriginalFile="binary_metadata_schema.json" Content="39137-3-8.json" />
    <Object Id="ish:39137-2-8" Type="page_schema" SubFolderName="ALL" OriginalFile="page_metadata_schema.json" Content="39137-2-8.json" />
  </Group>
  <Group Name="page">
    <Object Id="ish:39137-6245-16" Type="page" SubFolderName="ALL" OriginalFile="GUID-54F20824-43B5-4CE1-8EA2-400F1CB13716.html" Content="39137-6245-16.html" Metadata="39137-6245-16.json" LanguageCardId="6228" RevisionId="GUID-CAB421B2-8759-4215-AACE-0B6A60C4896A" />
    <Object Id="ish:39137-6246-16" Type="page" SubFolderName="ALL" OriginalFile="GUID-67F1627E-FFBA-4E03-A62D-F70030C52596.html" Content="39137-6246-16.html" Metadata="39137-6246-16.json" LanguageCardId="6229" RevisionId="GUID-E17EDE47-A8D5-4072-9FB2-C79607D6C243" />
    <Object Id="ish:39137-6295-16" Type="page" SubFolderName="ALL" OriginalFile="GUID-E97722D1-514C-4FAE-A9BA-DB55C6CA04E0.html" Content="39137-6295-16.html" Metadata="39137-6295-16.json" LanguageCardId="6278" RevisionId="GUID-0C5CB0DD-395B-48A9-A694-C6DD1A564B6A" />
  </Group>
  <Group Name="nav">
    <Object Id="ish:39137-100000000-512" Type="index" SubFolderName="ALL" OriginalFile="index_index.xml" Content="39137-100000000-512.xml" />
    <Object Id="ish:39137-1-512" Type="toc" SubFolderName="ALL" OriginalFile="toc.html" Content="39137-1-512.html" />
  </Group>
</Package>

The packages.xml file in the TP\ALL folder looks similar, but does not have the SubFolderName, LanguageCardId and RevisionId attributes on Object.

Example of a resulting file structure

Package Content Schema


<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="groups">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="group" maxOccurs="unbounded" minOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="objects" maxOccurs="unbounded" minOccurs="1">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:string" name="includefiles" maxOccurs="unbounded" minOccurs="1"/>
                    <xs:element type="xs:string" name="excludefiles" maxOccurs="unbounded" minOccurs="0"/>
                  </xs:sequence>
                  <xs:attribute type="objecttype" name="type" use="required"/>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
            <xs:attribute type="limitedstring" name="name" use="required"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="objecttype">
    <xs:restriction base="xs:string">
      <xs:enumeration value="publication"/>  
      <xs:enumeration value="toc"/>  
      <xs:enumeration value="index"/>  
      <xs:enumeration value="page"/>  
      <xs:enumeration value="binary"/>  
      <xs:enumeration value="publication_schema"/>  
      <xs:enumeration value="page_schema"/>  
      <xs:enumeration value="binary_schema"/>  
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="limitedstring">
    <xs:restriction base="xs:string">
      <xs:maxLength value="10"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Plugin flow

The DitaDeliveryPrepareOverallPackage does the following:
  • The plugin creates a TP\ALL folder under the folder provided in the RootWorkDirectory property of the context (typically Data\Publish\Data\[RANDOMFOLDERNAME]\work) and subfolders for all configured group names.
  • The files in the folder provided in the item associated with DITAOTOutDirectoryContextItemKey of the context (typically Data\Publish\Data\[RANDOMFOLDERNAME]\work\out) that match all the given includefilepatterns and excludefilepatterns for the group are then moved to the corresponding subfolder.
  • When moved, the plugin looks for an accompanying metadata file, by looking for a file named [FileNameToMove].[MetadataExtension], and when a metadata file is found, it is moved as well.
  • The files moved are given a unique ID of the form ish:xxx-yyy-zzz and the ID together with some information of the file are kept in a list in memory. The files are moved to a xxx-yyy-zzz.[FileExtension] filename, where the xxx part is the publication output id, the yyy part is the logical card id or language card id of the topic or binary depending on parameter ContentObjectIdLevel (found by reading the value of the ishlogicalref.object.id property for logical card id or ishlngref.object.id property for language card id in the accompanying metadata file) and the zzz part is a type identifier of the Dynamic Delivery system.
  • The in memory list of ID together with some information of the file is saved in a package.xml file in the TP\ALL folder, in the Dynamic Delivery Transport Package format.
  • The in memory list of ID together with some information of the file is also saved to a __packages.xml file in the TP folder, and contains more detailed information than package.xml.
  • The values of the context and context Items that need to be changed are set.