DITA Map Zendesk Publishing

Oxygen XML Author Eclipse plugin includes a built-in transformation scenario that provides the ability to publish DITA topics to XHTML output and upload them directly as articles to the Zendesk Help Center.

Attention: This feature is only available in the Enterprise edition of Oxygen XML Author Eclipse plugin.

To run the transformation, follow these steps:

Start Oxygen XML Author Eclipse plugin and open a DITA map in the DITA Maps Manager view.
Click the Configure Transformation Scenario(s) button.
Create a new DITA-OT transformation scenario and choose the Zendesk Help Center transformation type.
Go to Parameters tab and set the following parameters:

Host

The URL reference to the Zendesk Help Center (for example, https://your-domain.zendesk.com).

Username

The username (e-mail address) for the account used to upload the content.

API Token

An API token, generated in the Zendesk admin pages, necessary for authentication to the server: https://support.zendesk.com/hc/en-us/articles/226022787-Generating-a-new-API-token-.

Article category

The name of the category where the articles are uploaded. The category needs to be created in the Zendesk admin pages: https://support.zendesk.com/hc/en-us/articles/218222877-Organizing-knowledge-base-content-in-categories-and-sections#topic_hjs_tl4_kk.

Article section

The name of the section (inside the parent category) where articles are uploaded. The section needs to be created in the Zendesk admin pages: https://support.zendesk.com/hc/en-us/articles/218222877-Organizing-knowledge-base-content-in-categories-and-sections#topic_ysj_wtt_zz.
Note: When publishing to a subsection, a path of section names separated by '///' can be passed (for example: Main section///Subsection 1///Subsection 1.1).

Create article draft

This setting controls whether the articles should be published (if the value is false) or saved as drafts (if the value is true). The default value is false.

Visible to

The name of the user segment that can view the articles.

Permission group name

The name of the Zendesk permission group that controls who edits and publishes articles: https://support.zendesk.com/hc/en-us/articles/203661966-Creating-managing-and-using-groups.

Create table of contents

When the zendesk.create.toc parameter is set to true (default value), a table of contents is published as the first article in the Zendesk section and this initial article references all other articles. The title of the TOC article is the title of the DITA map.

Specify a prefix title for the table of contents

Set the zendesk.toc.title.prefix parameter to specify a prefix to use for the title of the table of contents article.

Specify a suffix title for the table of contents

Set the zendesk.toc.title.suffix parameter to specify a suffix to use for the title of the table of contents article.
Save the changes and run the transformation.

Important:

There may be cases when the publishing breaks, presenting an error related to HTTPS certificates, similar to this one:

Error: org.zendesk.client.v2.ZendeskException: java.net.ConnectException: PKIX path building failed: 
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path 
to requested target

This usually occurs if an HTTPS proxy server is installed in your company's network. In this case, if running on Windows, you can edit the transformation scenario you are using to publish DITA to Zendesk and in the Advanced tab, go to the JVM Arguments field and set this value:

-Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=C:\\Windows\\win.ini

Resources

For more information about publishing content to the Zendesk Help Center, watch the following video demonstration:

https://www.youtube.com/embed/QZ_9Fk_LOk8