Map Content from Paligo to Zendesk

When you publish content to Zendesk, Paligo has to "push" the content from your topics into Zendesk. To do this, it "maps" topics to the Zendesk structure, which consists of categories, sections, and articles.

The mapping that takes place when you publish depends on:

  • The type of Zendesk layout you use

  • The mapping settings you choose for the layout

  • Whether you use the Zendesk Preflight feature to customize the mapping to meet your own requirements.

To learn about mapping, we recommend that you:

  1. Make sure that you understand the Zendesk structure.

  2. Learn about the differences between the multi-section Zendesk layout and the single-section Zendesk layout, see Zendesk Layouts.

  3. Learn how to View the Existing Paligo-to-Zendesk Mapping.

    When you view the mapping, you may decide that you want to make changes. For more information, see Customize Paligo-to-Zendesk Mapping.

Note

For information on mapping Paligo links and cross-references to Zendesk articles, see Map Links to Zendesk.

Note

If you have branched content and want to find out about how it is mapped to Zendesk, see Map Branched Content to Zendesk.

Note

In this section, we explain how branched content is mapped to Zendesk. We assume that you already understand and use the branching feature to create concurrent versions of your publications and topics. To learn about branching, see Version Branching.

When you publish to Zendesk, Paligo maps the content in your publication, including branched topics, to articles in Zendesk. For regular, unbranched topics, Paligo will map each topic to an existing article or will create a new article (see Map Content from Paligo to Zendesk). But if you have branched topics, they will map to articles differently, depending on how you create the branched topics:

  • If you create branches from inside the publication, the branched topics will map directly to corresponding articles in Zendesk. This is because branches made in the publication use the same fork ID as the original version of the topic (see Fork IDs and Mapping).

  • If you create branches of topics outside of the publication, and then add them to the publication, the branched topics will map to new articles in Zendesk. They will not update the existing articles.

Typically, you will want your branched versions of topics to map to Zendesk and update your existing articles. For this type of mapping, you need to make sure you branch your topics from inside the publication:

  1. In the Content Manager, find the Publication you want to publish to Zendesk.

  2. Open the publication so that you can see the links to the topics.

    links-to-topics.png
  3. Display the options menu for the linked topic that you want to branch.

    pub-link-context-menu.png
  4. Select Branching.

  5. Select New Branch.

    Paligo creates a new branched version of the topic, and because you created it in the publication, the branched version will map to the same Zendesk article as the original version of the topic.

Tip

If your branched topics are mapping to new articles instead of updating existing articles, it is likely because they have been branched outside the publication. To resolve this situation:

  1. Create new branches inside the publication. Then In Zendesk, delete the articles that were created for the "outside the publication" branches.

  2. Copy the content from your "outside the publication" branches into your "inside the publication" branches.

  3. Remove the "outside the publication" topics from the publication and delete them.

  4. In Zendesk, delete the articles that were created for the "outside the publication" topics.

In this section, we explain how Paligo uses the "fork ID" to map topics to Zendesk articles. It will help you to understand why Paligo maps branched topics differently, depending on whether they are branched inside the publication or outside of the publication.

Let's say you have a Paligo publication and you want to publish to Zendesk for the first time. There are no articles in Zendesk at the moment.

  • unbranched topics

  • topics that are branched from inside a publication

  • topics that are branched outside a publication.

Note

If your branched topics are mapped to new articles instead of updating your existing articles, it is probably because the branches were created outside of the publication.

Example 1. Branching from the Publication will Update Articles in Zendesk

You can branch your content in two ways: in a publication or outside a publication. This example shows how Paligo maps content to Zendesk when you branch from inside a publication so that the branched versions and original topic all use the same fork ID.

Let's start with a publication and a topic. When you add a topic to a publication, Paligo creates a fork ID. It uses the fork ID as a record of the relationship between the publication and the topic.

FORKID.png

You decide to publish to Zendesk for the first time. Paligo checks its internal record to see if the topic's fork ID has been used to map to any articles in Zendesk. It has not, as there are no articles yet, and so Paligo maps the topic to a new article. It also keeps a record so that it knows the fork ID of your topic maps to that specific article in Zendesk.

You make some changes to the topic and publish to Zendesk again. Paligo checks its internal record and finds that the fork ID of your topic maps to the article in Zendesk. Paligo writes the content of the topic to the article in Zendesk.

map-to-zendesk1.png

If Paligo has a record of the fork ID (1) mapping to an existing article (2), it will transfer the topic content to the article.

The product you work on is being updated, and you need to add new content to the topic. But you also need to have the original version available. To make this possible, you create a branch of the topic. You make the branch in the publication, so that the branched version of the topic uses the same fork ID as the original topic.

You write new content in the branched version of the topic. When the new product is ready, you publish your content to Zendesk. Paligo checks its internal record and finds the fork IDs of your original topic and branched version topic has been used to map to an article before. Paligo ignores the original topic and maps the latest version (the branched version) of the topic to the article. So the article in Zendesk is updated with content from your branched topic.

map-to-zendesk2.png

The branched topic has the same fork ID (1) as the original topic and so is mapped to the same Zendesk article (2) as the original topic.

You could also merge the branched version of the topic with the original topic. This gives you the option to add all or some of the branched version to the original topic (you can choose which elements are copied to the original topic, see Merging Branches). When you publish to Zendesk, the original/merged topic is written to the article, as it is the most recent version and its fork ID maps to the article.

map-merge-to-zendesk.png

When you merge a topic, the topic that receives the merged content continues to use its own fork ID.


Example 2. Branching Outside the Publication will Create New Articles in Zendesk

This example shows how Paligo maps content to Zendesk when you branch a topic outside a publication so that the branched version and original topic use different fork IDs.

Let's start with a publication and a topic. When you add a topic to a publication, Paligo creates a fork ID. It uses the fork ID as a record of the relationship between the publication and the topic.

FORKID.png

You decide to publish to Zendesk for the first time. Paligo checks its internal record to see if the topic's fork ID has been used to map to any articles in Zendesk. It has not, as there are no articles yet, and so Paligo maps the topic to a new article. It also keeps a record so that it knows the fork ID of your topic maps to that specific article in Zendesk.

You make some changes to the topic and publish to Zendesk again. Paligo checks its internal record and finds that the fork ID of your topic maps to the article in Zendesk. Paligo writes the content of the topic to the article in Zendesk.

map-to-zendesk1.png

If Paligo has a record of the fork ID (1) mapping to an existing article (2), it will transfer the topic content to the article.

The product you work on is being updated, and you need to add new content to the topic. But you also need to have the original version available. To make this possible, you create a branch of the topic. You make the branch in the publication, so that the branched version of the topic uses the same fork ID as the original topic.

You write new content in the branched version of the topic. When the new product is ready, you publish your content to Zendesk. Paligo checks its internal record and finds the fork IDs of your original topic and branched version topic has been used to map to an article before. Paligo ignores the original topic and maps the latest version (the branched version) of the topic to the article. So the article in Zendesk is updated with content from your branched topic.

Paligo also checks its internal record for the fork ID of your branched version. The fork ID has not been used to map to an article before. So Paligo creates a new article in Zendesk and writes the content of the branched topic to the new article.

map-to-zendesk3.png

The branched topic has a different fork ID (3) to the original topic (1). So the original topic maps to one article in Zendesk (2) and the branched topic maps to a different Zendesk article (4).