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 varies, depending on the type of Zendesk Layouts you use, the layout's settings, and whether you customize the mapping by using the Zendesk Preflight feature.
To set up the mapping for your content:
-
Choose the appropriate type of layout for the mapping you want to achieve, see Zendesk Layouts
-
Edit the layout settings to:
-
Control how many levels of sections can be used in Zendesk. This is only available on Zendesk Enterprise Layouts.
-
Use Customize Paligo-to-Zendesk Mapping to control how Paligo maps to sections and articles in Zendesk.
When you publish to Zendesk, Paligo maps the topics in your publication to Zendesk articles (see Map Content from Paligo to Zendesk. If there are links in your topics, Paligo can map those to your articles too:
-
Topics with internal links: These are mapped and resolved automatically when you publish to Zendesk.
-
Links to topics in the same publication: These are mapped and resolved automatically when you publish to Zendesk.
-
Links to topics in a different publication: These do not map to articles in Zendesk (by default). But Paligo can map these links if you enable the Fix cross-links outside of publication scope setting on the Zendesk Layout. You may also need to publish twice. For more information, see Resolve Cross-References between Zendesk Categories.
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 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:
-
In the Content Manager, find the Publication you want to publish to Zendesk.
-
Open the publication so that you can see the links to the topics.
-
Display the options menu for the linked topic that you want to branch.
-
Select Branching.
-
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:
-
Create new branches inside the publication. Then In Zendesk, delete the articles that were created for the "outside the publication" branches.
-
Copy the content from your "outside the publication" branches into your "inside the publication" branches.
-
Remove the "outside the publication" topics from the publication and delete them.
-
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 8. 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.
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.
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.
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 Merge 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.
When you merge a topic, the topic that receives the merged content continues to use its own fork ID.
Example 9. 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.
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.
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.
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).
Zendesk Preflight allows you to map your topics in Paligo to Zendesk Guide articles with full control over what gets updated, deleted, or added.
When you publish from Paligo to Zendesk, you choose a Zendesk layout to use and a category to publish to. At that stage, Paligo is able to show you how your Paligo content will be published to Zendesk sections and articles. You can see a preview on the Zendesk Preflight tab.
The Zendesk Preflight tab can show you how Paligo is going to:
-
Create new articles in Zendesk that map to topics in Paligo.
-
Update existing sections and articles in Zendesk.
-
Delete articles in Zendesk.
Note
"Mapping" is the term we use for how Paligo matches a Paligo topic to a Zendesk section or article.
To access the Zendesk Preflight tab:
-
In the Content Explorer, select the option menu ( ...) for your publication and then select Publish.
-
On the Publish document dialog, select HTML. Then select the Zendesk layout you want to use and choose the Zendesk Category you are going to publish to.
You will need a Zendesk Layouts for publishing. You can use one of the built-in Zendesk layouts or create one of your own. They are special types of HTML layout.
-
Select the Zendesk Preflight tab to see how Paligo is going to map the topics in your publication to your Zendesk when you publish.
Note
If you use saved publishing settings, there is a different way to access the Zendesk Preflight tab (see Saved Settings and Paligo-to-Zendesk Mapping).
The Zendesk Preflight tab provides you with a preview of how Paligo will map your content to Zendesk. You can also use the Zendesk Preflight to Customize Paligo-to-Zendesk Mapping.
At the top of the tab, Paligo provides you with information about the number of "resources" that are going to be created, updated, or deleted. "Resources" is the term we use for Zendesk content and it can include sections and articles.
On the left, there is a hierarchical mapping list. This is where you can see how Paligo is going to publish your Paligo topics to Zendesk. It matches each topic to an existing section or article or will create a new section or article. The process of matching topics to sections and articles is called "mapping".
The list can show:
-
Topics that are going to be mapped to new sections or articles in Zendesk. These are shown with a plus icon.
-
Topics that are going to be used to update existing sections or articles in Zendesk. These are shown with an update icon.
-
Articles that Paligo is going to delete from your Zendesk. These are shown with a cross icon.
-
Articles that Paligo published to Zendesk previously, but they have since been moved in Zendesk. These are shown with a red copy icon.
By default, Paligo will create a new article at the location that Paligo expects the article to exist. You can control this behavior by using the Strict Mapping feature in the integration settings. For single brand Zendesk instances, see Connect Paligo to Zendesk. For multibrand Zendesk, see Connect Paligo to Multiple Zendesk Brands.
-
Articles that exist in Zendesk, but are not mapped to any topics in Paligo. These are shown as "grayed out" entries.
The "grayed out" articles could be articles that were created in Zendesk and have no matching topic in Paligo.
They could also be articles that were previously mapped to Paligo topics, but the mapping has since been broken, so now the articles are unmapped.
The structure of the mapping comes from the type of Zendesk layout you are using (Multi-Section Zendesk Layouts or Single-Section Zendesk Layouts).
Each mapped "resource" in the list has a checkbox that you can use to control whether the resource is published to Zendesk.
On the right, there are settings for controlling the status of new articles. These apply to all new articles, but it is also possible to change the status for individual topics. To find out more see Set the Status of Content that is Published to Zendesk.
If you are happy with the existing mapping settings, you can Publish to Zendesk.
But you can also use the Zendesk Preflight tab to change the way content is mapped to Zendesk. To find out how to make changes, see Customize Paligo-to-Zendesk Mapping.
You can save your publishing settings so that you do not have to re-enter the same settings each time you publish (see Publishing Settings). When you publish to Zendesk, you can select the saved settings and then use the Zendesk Preflight tab to see how your content is going to be "mapped". Your topics will either be mapped to new sections or articles in Zendesk or used to update existing sections and articles.
To use the Zendesk Preflight tab with saved settings:
-
In the Content Manager, select the options menu ( ... ) for the publication you want to publish to Zendesk, and select Publish.
-
On the Publish Document dialog, select the Saved Settings tab.
-
Check the box next to the publishing settings you want to use. When you check the box, the Zendesk Preflight tab appears.
-
Select the Zendesk Preflight tab to see how your Paligo content will be mapped to Zendesk.
You can use the Zendesk Preflight tab to view or change the mapping as described in:
Zendesk Preflight lets you control how your topics in Paligo are mapped to Zendesk Guide articles and sectons.
With Paligo's Zendesk Preflight feature, you can control how your Paligo content is mapped to Zendesk. It is available on Single-Section Zendesk Layouts and Multi-Section Zendesk Layouts Zendesk layouts. For details on how to display it, see View the Paligo-to-Zendesk Mapping.
Note
If you use saved publishing settings, there is a different way to access the Zendesk Preflight tab (see Saved Settings and Paligo-to-Zendesk Mapping).
When you display the Zendesk Preflight tab, it shows the mapping that will take place if you publish to Zendesk. You can customize the mapping to meet your own requirements or you can leave the existing mapping in place.
Before you make changes to the mapping, we recommend that you familiarize yourself with the Zendesk structure. You will also need to know which type of Zendesk layout you are going to use for publishing. There are two different types, multi-section and single-section, and they map the top-level content differently.
Note
The Zendesk layout also has some settings that you can use to control certain parts of the mapping. For example, you can control how the titles of Paligo topics are mapped to heading levels in the Zendesk articles. To find out more, see Edit a Zendesk Layout.
The Zendesk Preflight feature gives you control over which topics are published to Zendesk. You can choose to publish an entire publication, just a selection of its topics, or even a single topic if you prefer.
-
Look at the list of categories, sections, and articles. Each of them has a checkbox.
If you want to publish the content to Zendesk, check its box.
If you want to exclude the content from publishing, so that it is not added to Zendesk or used to update Zendesk articles, clear the box.
-
If you have made all of the mapping changes you need and have set the languages, filters, etc. on the tab, select Publish document to start the publishing process.
When you publish your content, Paligo will only publish those topics that have their boxes checked.
You can use the Zendesk Preflight feature to change the mapping between a Paligo topic and a Zendesk section or article. The changes you can make vary, depending on the existing mapping in place.
If you are mapping a topic that is not currently mapped to an article or section, you can map it to:
-
A new article or section. This is the default setting for a new topic.
-
An existing unmapped article that is in the same section as the topic you are mapping
-
An existing unmapped section that is in the same category that you are publishing to
If you are mapping a topic that is currently mapped to an article or section, you can remap it to:
-
An existing unmapped article or unmapped section.
To map a topic to a different section or article:
-
Browse the list to find the Paligo topic that you want to map, and select its cog icon to display a dialog.
On the dialog, use the Mapping setting to choose the section or article that you want to map to.
-
This step only applies if you are mapping a topic to an article.
Use the other settings on the dialog to define the publishing status and promoted status to control who can view and edit the article or section. To find out more about these settings, see Set the Status of Content that is Published to Zendesk.
-
Select Confirm.
-
If you have made all of the mapping changes you need and have set the languages, filters, etc. on the tab, select Publish document to start the publishing process.
When you publish your content to Zendesk, the Paligo topic will map to the section or article you selected.
Typically, when you map a topic in Paligo to an article in Zendesk, you will want the topic and article to keep their relationship. But it's possible that at some point, you may want to replace the topic with a different topic, but map to the same article and URL in Zendesk. To do this, complete the following steps:
-
In the Content Manager, find the publication that you publish to Zendesk and select it to display it in the structure view.
-
In the publication structure, remove the topic that you want to replace.
In the Publication structure, remove the topic that you want to replace. In this example, we are removing "Troubleshooting".
-
Add the replacement topic to the publication structure.
Add the replacement topic to the Publication structure.
-
Use the arrow buttons to arrange your topics and reused publications into the order you want. You can set them to display as a flat structure or you can "nest" topics and publications so they have a more complex structure, with multiple levels of content, see Organize a Publication.
-
In the Content Manager, find the publication and select its option menu ( ... ) and then select Publish.
-
Set the publication to produce an HTML output and choose a Zendesk layout.
-
Select the Zendesk Preflight tab.
For multi-section Zendesk layouts, the mapping shows:
-
The new topic is mapped to a new section and a new article.
-
The article that was mapped to the topic you removed is now unmapped. Its section is also unmapped. These are both shown as gray listings.
For single-section Zendesk layouts, the mapping shows:
-
The new topic is mapped to a new article.
-
The article that was mapped to the removed topic is now unmapped. This is shown as a gray listing.
The new replacement topic has a green plus icon, which shows that it is a new article that will be created in Zendesk.
-
-
This step varies depending on whether you are using a multi-section or single-section Zendesk layout.
If you are using a multi-section Zendesk layout:
-
Select the cog icon for the new section. On the dialog, use Mapping to select an unmapped Zendesk section. Select Confirm.
-
Select the cog icon for the new article. On the dialog, use Mapping to select an unmapped Zendesk article. Select Confirm.
If you are using a single-section Zendesk layout:
-
Select the cog icon for the new article. On the dialog, use Mapping to select an unmapped Zendesk article. Select Confirm.
-
-
If you have made all of the mapping changes you need and have set the languages, filters, etc. on the tab, select Publish document to start the publishing process.
In Zendesk, there are several settings that control who can see the articles and where the articles appear:
-
Draft/Publish status
If an article is in the Draft state, it exists in Zendesk but is not shown in the help center. In the Publish state, it is "live" and appears in the help center.
-
Managed by
This lets you choose which types of user can edit and publish an article, for example, Agents and Managers. The Managed by setting is sometimes called Permission Group in Zendesk.
-
Visible to
This lets you choose who can see this article when it is published in the help center. The Visible to group is sometimes called the User Segment Group in Zendesk.
-
Promoted
In Zendesk, articles can be promoted so that they appear at the top of a section and have a star icon next to them. They can also appear on the home page, depending on what theme you are using. You can set the promoted status in Paligo instead of having to set it in Zendesk.
When you publish content from Paligo to Zendesk, you can set the statuses of the content.
-
Display the Publish document dialog for your publication and set it to use a Zendesk layout and choose a Zendesk category, as described in View the Paligo-to-Zendesk Mapping.
-
On the Settings tab, use Managed by to define what user group can edit and publish your articles.
Note
Each article has its own Managed by setting, and if that is set, it will be used instead of the Managed by on the Settings tab.
-
Select the Zendesk Preflight tab.
-
To set the status for all new articles, use the new article settings on the right.
Note
You cannot set the promoted state for all new articles. You can only set the promoted state for individual articles, see step Step 5.
-
To set the status for an individual article, browse to the article in the list and select its cog icon to display a dialog.
On the dialog, you can set the draft/publish Status, Visible to, Managed by, and Promoted statuses. Select Confirm when you have made your choices.
Tip
You can also use this dialog to control the mapping.
-
If you have made all of the mapping changes you need and have set the languages, filters, etc. on the tab, select Publish document to start the publishing process.
When you publish your content to Zendesk, the content will use the statuses that you have set.
In Zendesk, each article can have labels that categorize the content, similar to how Taxonomies work in Paligo (Business and Enterprise plans only). For example, you could have some introductory training articles with labels for "Onboarding" and "Tutorial". When you map Paligo topics to Zendesk, you can set the Paligo articles to have labels too.
-
Display the Publish document dialog for your publication and set it to use a Zendesk layout and choose a Zendesk category, as described in View the Paligo-to-Zendesk Mapping.
-
Select the Zendesk Preflight tab.
-
Expand the sections to reveal the topics that will become articles in Zendesk. Select the cog icon for the article you want to edit.
-
Use the Labels setting to define the labels for the article.
The Labels field shows the names of any labels and taxonomy tags that are already applied to the article. Taxonomy tags are converted into labels in Zendesk.
Note
Existing labels are only shown (and kept) if Preserve Zendesk Labels is enabled in the Zendesk integration settings.
Taxonomies are only shown as labels if Publish taxonomies as labels is enabled in the Zendesk integration settings.
You can:
-
Enter the name of a new label and press Enter. When you publish, Paligo will create that label in Zendesk and associate it with the article.
-
Enter the name of a label that already exists in your Zendesk and press Enter. Be careful when typing as the text you enter must match the existing label name exactly. If it is different, Paligo will create a new label with that name rather than associate the article with the existing Zendesk label.
-
Delete a label name to prevent the article from being associated with that label.
-
-
Select Confirm.
-
If you have made all of the mapping changes you need and have set the languages, filters, etc. on the tab, select Publish document to start the publishing process.
Paligo will publish the content to Zendesk and apply the labels you have set.
To remotely delete sections and articles from Zendesk, use the Zendesk Preflight tab on the Publish document dialog.
-
Find the article that you want to remove in the list. You can delete articles and sections that are not mapped to Paligo content.
You cannot delete new articles or sections from the list. If you do not want Paligo to create them, clear their checkboxes or remove the matching topics from the publication instead.
If you want to remove a mapped section or article, you first need to "unmap" it. To do this, remove the mapped topic from Paligo's publication and then publish. When the publish is complete, the article in Zendesk becomes unmapped. You can then delete it remotely as described in Step 3.
-
Select the delete icon next to the section or article that you want to remove.
You can cancel a deletion by selecting the restore icon (plus icon).
-
If you have made all of the mapping changes you need and have set the languages, filters, etc. on the tab, select Publish document to start the publishing process.
The deletion will take place when you publish to Zendesk.
Comments
0 comments
Article is closed for comments.