Expand my Community achievements bar.

Registration for the AEM Guides User conference on 24th and 25th March 2024 is open.

Using a custom DITA-OT for publishing | Things to remember

Avatar

Employee

Background

You are using AEM Guides and you publish the DITA content using DITA-OT.

 

Requirement

When using DITA-OT, sometimes you need to use your own version of DITA-OT. The product supplies a specific version of DITA-OT in its release (the latest one when the product version gets released, e.g. version 3.8 of AEM Guides includes DITA-OT version 3.3.2)

There are scenarios in which you may want to customize the DITA-OT supplied with product, those scenarios can be:

  • Using/Adding a custom plugin (to generate a style/branded output or a custom built plugin to get output in desired format, or integrating existing plugins)
  • Using a different version of DITA-OT (may be using the latest version, or using a legacy version on which your plugins were built)

 

Things to Remember when adding such customization

There are few things to keep in mind to make sure the integration of customized DITA-OT works successfully in AEM Guides. These pointers are scenario dependent, which are listed below

Scenario 1: Integrating a new plugin to out-of-the-box DITA-OT

  • The steps are documented in section "Use custom DITA-OT plug-ins" of Installation and Configuration Guide
  • When creating package and uploading it back to AEM server, do make sure you have done following:
Firstly, the zip file you created should have folder named "DITA-OT" in it containing the plugins folder, it is important as system is internally dependent on this, refer screenshot below:
DivrajSingh_0-1620722165864.png


Secondly, when you run the integrator to install custom plugin, recommendation is to do this on a Mac/Linux OS to avoid file separator issues during publishing. The plugin integrated on mac/linux OS is compatible to both Windows and Unix setup

Thirdly, the updated zip file should be of type "nt:file" (this should be the primary type of zip file when uploaded to AEM). To elaborate, do not use this zip file to install as AEM package (using package manager) rather upload this zip to desired path in AEM (e.g. /apps/test/dita_resources/DITA-OT) using a webdav tool or through code deployment

 

Scenario 2: Using a different DITA-OT version than out-of-the-box

Generally this is required because either the implementation team desires to use the latest features in newly released DITA-OT version, or the implementation team already uses another version of DITA-OT that has their custom plugins implemented on, and moving to different version requires refactoring. Hence, in those scenarios the implementation team generally will have their own copy of DITA-OT. Following points should be considered when uploading a custom DITA-OT into the system:

  • The general steps to upload custom DITA-OT are documented in section "Use custom DITA-OT plug-ins" of Installation and Configuration Guide
  • When creating package and uploading it to AEM server, do make sure you have done following:
Firstly, the environment variables within DITA-OT base plugin are updated, as AEM uses a temporary path that is different than what is configured in DITA-OT supplied on open source or use in other systems. So, make sure following environment variables within the DITA-OT are aligned to AEM Guides working paths, e.g. for versions 3.5.1+ of AEM Guides you will have to make following changes to the custom DITA-OT:
DivrajSingh_2-1620723451837.png


You will notice these paths are also printed in the DITA-OT error log, for e.g. following snippet from DITA-OT log prints the values of temporary path that you can validate before changing these variables
DivrajSingh_3-1620724943431.png

Secondly, in DITA-OT version 3.x and above, you may notice that the PDF output generation throws an error like "taskdef class org.dita.index.IndexPreprocessorTask cannot be found using the classloader AntClassLoader[]". This is generally because of the CLASSPATH issues with the custom plugins. To fix this, update the DITA Profile in AEM to add library paths containing the jars "ant-launcher.jar" and "index.jar", refer screenshot below:
DivrajSingh_0-1621362655560.png

Thirdly, update the xerces.jar file as per instructions given in section "Patch Xerces Jar while using custom DITA-OT for publishing" of Best Practices Guide. This is for performance improvement on DITA-OT publishing.

 

 

Some additional references

13 Replies

Avatar

Employee

Hi @DivrajSingh - Can you also share the high level steps to integrate the custom DITA-OT plugin with the product provided DITA-OT on local?

Avatar

Employee

@Kiran_Mohan : I think what you are asking is documented here. Let me know if you were looking for somethin else.

Avatar

Employee

Hi @DivrajSingh, While modifying the out-of-the-box DITA-OT.zip (AEM), there are some permissions (chmod) that need to be changed in order to make it work. Else the plugin will not work upon upload into AEM environments (running linux kernel) 

Can you please document those steps as well?

Avatar

Employee

Hi @Vijendra_HS 

 

The modified DITA-OT has to be uploaded to AEM repository. Extraction of the DITA-OT is done by AEM process so it should get write permissions for the AEM user (using which AEM java process is running).

Were you trying to upload the custom DITA-OT directly into the AEM extracted path? (/crx-quickstart/profiles/dita-ot...)

Avatar

Level 1

Hi @DivrajSingh 
we are followed the steps what you given for DITA-OT customized dita-ot version but we are getting this error while generating PDF output (attached the screenshot ). Can please give the solution to this.

MicrosoftTeams-image (6).png

 

Avatar

Employee

@kondisrinivasu : please share:

  • DITA-OT zip that you are using
  • Are you using custom DITA schema, if so - share the catalog package (and a screenshot of the DITA Profile that you have setup)
  • What version of AEM Guides and AEM are you using on the setup?
  • If this is for a customer - request you to raise a support ticket as well

Avatar

Level 1

Thankyou for the reply @DivrajSingh 

 

  • we are try to using DITA-OT version is 3.7.4 (we have sensitive information in that I am sending DITA-OT.zip in personal message )
  • I am new to AEM guides I am not sure about custom DITA schema Please tell where I need to check? I am attaching screenshot of DITA profile of my setup.(Attached in word document)
  • We are using AEM as cloud service version of  (2023.4.11873.20230421T153841Z) and FMDITA version is (com.adobe.fmdita-aemaacs-2023.4.249).

    Can please provide solution to this.

Avatar

Employee

@kondisrinivasu : I have replied to your message in inbox but here is the summary:
- The DITA-OT.zip is missing the DITA-OT folder (you need to zip the folder itself)

- Also the DITA profile you mentioned in the word document, I observed that you did not assign any path to the profile

DivrajSingh_0-1685104096563.png

 

Avatar

Level 1

Thankyou for the reply @DivrajSingh 

We are followed the steps what you are provided We are able to generate output  in other formats like (HTML etc) but we are not getting MathML equations in final output and we are getting error while generating Pdf output.

kondisrinivasu_0-1685113001136.png

 

Can please provide solution to this.

Avatar

Employee

@kondisrinivasu : The error indicates that the PDF plugin itself is not configured in DITA-OT properly so MathML is secondary issue for you as of this state.

The steps defined in this post are all complete. For the plugin you shared: the configurations done are not correct in the DITA-OT plugin and the output presets.

 

You are already in connection directly with us - recommend you to continue this conversation offline as the issue you are facing is more in your setup which has to be debugged!

Avatar

Level 3

Hi @DivrajSingh , @kondisrinivasu ,

I am also new to the AEM and working on DITA-OT. Its throwing same error that @kondisrinivasu mentioned in the above comment. 

Beaula123_0-1693288129367.png

Can you please suggest me, how you fixed this issue. Attached the Profile details below.

 

Thanks

Avatar

Employee

@Beaula123 : it seems you are trying to publish the PDF using default settings which uses the plugin "fm-pdf" which is not available in the custom DITA-OT that you have configured in AEM.

The error you shared indicates the supported output formats/plugin names like "bcpdf" or "sym_bcpdf"

You can configure this on the output preset in the field "Transformation name", refer image below:

 

DivrajSingh_0-1693342570274.png

 

I hope this helps.

 

Avatar

Employee

@kondisrinivasu : The error reported above is indicating that the transtype(plugin name) that you are using to generate the output is not available in the DITA-OT you have ocnfigured.