Skip to main content

Import from Zendesk

Abstract

You can import your Zendesk articles directly into Paligo. As part of the import, Paligo creates new topics to match your articles. You can then map the topics back to the articles, so that you can make updates in Paligo and publish the changes to Zendesk.

You can import content directly from your Zendesk Guide help center into Paligo. During the import, Paligo converts your Zendesk content into structured content, so that you can use it in Paligo. You can also set up Paligo so that you can make changes to your imported topics and publish them back into Zendesk.

To import from Zendesk, use the Paligo-Zendesk integration. If you have not already set this up, go ahead and do it now by following the instructions in Connect Paligo to Zendesk.

When you have connected Paligo to Zendesk, you can start the import process. We have broken this down into three parts:

Important

If you have the Zendesk multibrand feature, put the Zendesk account you want to import from at the top of the multibrand list. Paligo will import from the first account in the multibrand list. To change the order in the list, see Connect Paligo to Zendesk.

Note

The Paligo import does not support the Zendesk enterprise multi-section architecture. Please contact customer support for advice if you need to import multi-section architecture.

Import Zendesk Categories into Paligo

Paligo can import one Zendesk category (and its articles) at a time. In Paligo, the category becomes a publication and the articles inside the category become topics.

To import a category:

  1. In the Content Manager, create a folder for your import content. Alternatively, you can use an existing folder.

    You can create a folder from the dotted menu ( ... ) of any existing folder or from the Create content button.

    create-icon-new-folder.png

  2. Select the dotted menu ( ... ) for the folder and then select Import content.

    import-content-option.png

  3. Select Zendesk (via Zendesk integration) on the Import content dialog.

    import-content-zendesk-option.png

  4. Ignore the Select the archive file setting. It is not needed for Zendesk imports.

  5. Select the Category that you want to import. Paligo is able to detect the categories in your Zendesk help center as long as you have set up the Paligo-to-Zendesk connection correctly.

  6. Use the General options tab to set your preferences for the import:

    • Try to match components with existing components

      Check this box if you want Paligo to recognize components that are identical to components that already exist in Paligo. Paligo will not import content that already exists and will reuse the existing content instead. We recommend that you check the box so that your imports are more efficient and take advantage of Paligo's content reuse capabilities.

    • Import admonitions as separate components

      Paligo recommends that you check this box if you know you have many identical admonitions (notes, warnings and more). But if most are unique, leave it unchecked.

    • Ignore warnings on import validation

      In most cases, Paligo recommends that you check this box unless you have problems when trying the import. Paligo will usually fix minor problems automatically during the import process. If you disable this feature, Paligo will reject any invalid XML, display a warning message and stop the import process.

      Note

      This option is not shown for Paligo export file (PEF) imports.

    • Import missing images

      When enabled, placeholders for missing images will be added to your Media folder. This is the default setting. Disable this option to disregard missing images.

  7. Use the Custom options tab to set your preferences for the titles, numbering, folder levels, and variables:

    Custom options tab on the Import dialog. There are options for title prefix, folder numbering, max folder levels, and match with existing variable set.

    • Title prefix

      Use this setting if you want to mark your imported topics with a prefix. Enter the prefix in the field. If you do not want a prefix, leave the field blank.

    • Folder numbering

      Enable this setting to add sequential numbering to the folders for your imported content. Disable it if you don't want numbering.

    • Max folder levels

      Use to control the maximum number of folder levels Paligo will create for your imported content. The default value is 1. It means that each group of topics will be in one folder. If you set the value to 2, the content would be organized so that each topic is in its own folder.

      You can increase the number of folder levels to whatever number you need for your content. Paligo will create a new folder for each level as long as there is content at that level in the import.

    Note

    Ignore Match with existing variable set as it only applies to DITA, MadCap Flare, Paligo Export File (PEF), and DocBook imports.

  8. Select OK.

    Paligo imports the content from Zendesk (as long as the Paligo-to-Zendesk connection is set up correctly).

  9. Repeat this process for each category in your Zendesk help center.

During the import, Paligo converts your Zendesk category into a publication and its articles into topics. You now have the import in Paligo, but at this point, it is just regular content. Paligo does not understand that it has a relationship with your category and articles in Zendesk.

To create that relationship, you need to Map your Imported Content to your Zendesk Content.

Note

The Paligo import does not support the Zendesk enterprise multi-section architecture. Please contact customer support for advice if you need to import multi-section architecture.

Note

Once you have imported from Zendesk, you cannot update the content in Zendesk and re-import into the same topics. The import will create new topics in Paligo.

The import feature is only for migrating content from Zendesk to Paligo. Once the import is complete, you should make any updates in Paligo and publish from there back into Zendesk.

Choose your Publishing Preferences

Before you use Preflight to map your content, you need to set Paligo to publish to Zendesk. You can also set your publishing preferences.

  1. In the Content Manager, select the dotted menu ( ... ) for the import publication. It should have the same name as the category you chose to import from Zendesk.

  2. Select Publish.

  3. On the Publish document dialog, select HTML and then choose a Zendesk layout.

    Close-up of top of Publish document dialog. It shows HTML has been selected as the publishing type. Zendesk Enterprise has been chosen as the Zendesk layout.

  4. Use Select account to choose the account to use for publishing. This setting is only shown if there are multiple accounts set up for the Paligo-to-Zendesk integration.

  5. Choose the Zendesk category that will receive your selected Paligo content.

    zendesk-category.png

    Note

    Paligo detects the categories automatically if the Paligo-to-Zendesk integration is set up correctly. If you do not see any categories, check that Paligo can connect to Zendesk (see Connect Paligo to Zendesk or Connect Paligo to Zendesk Multibrand).

  6. Use the Managed by setting to choose which types of user can edit and publish the articles that Paligo creates or updates in Zendesk. The Managed by setting is sometimes called Permission Group in Zendesk.

    managed-by-zendesk.jpg

    This setting is applied as the default for all articles that Paligo publishes to Zendesk, but you can have different settings for individual articles as well. The individual settings take priority over the default settings. You set Managed By for individual articles on the Zendesk Preflight tab.

  7. Use the Visible to setting to choose who can see the articles that Paligo creates or updates in Zendesk. The Visible to group is sometimes called the User Segment Group in Zendesk.

    visible-to-zendesk.jpg

    Note

    Paligo uses the Visible to setting as the default for all articles when you publish to Zendesk. But you can also have different settings for individual articles.

    The Zendesk Preflight feature has Visible To settings for each article. The article settings take priority over the default settings.

  8. Select the languages to be published.

    Languages section of Publish document dialog. There are options for each language. English UK and Swedish are selected.

    Note

    If no translations are available, only the Source Language will show. If you have multiple languages translated and approved, you can select which ones to include. Paligo will publish each language as a separate output.

    For PDF output you can publish them as one multilingual publication, check the Combine selected languages box.

  9. If your content is set up to use Filtering / Profiling, use the Profiling attributes section to apply them. [Optional]. If you do not use filtering, ignore this setting.

    Select Edit and then choose the value for each filter that you want Paligo to use. For example, for Audience, choose Expert to include content that is marked as for expert users.

    If you do not want to apply a filter, leave the field blank.

    Profiling attributes dialog. Outputformat is set to include HTML.

    Select OK to add your chosen profiling attribute(s).

    Profiling attributes section of Publish document dialog. Shows Outputformat: HTML selected.

  11. Ignore the Upload output and Output filename sections as these are not needed for publishing to Zendesk.

  12. Set the Optional Parameters (leave unchecked if you do not want these features):

    • Save the output in Paligo - Check the box to save the zip file that Paligo creates when you publish. The zip file will be available from the Resource View and you can download it from the Saved Outputs tab. Clear the box if you don't want Paligo to store the zip file.

    • Notify me - Check this box if you want Paligo to send you an email when the publication is ready. This is useful if you have very large publications that can take a longer time to process and publish.

    • Make debug build - Check this box if you want Paligo to include a log file and link report. If there is an issue with your content, Paligo support may ask you to enable this feature so that they can use the log files to investigate.

For the next step, you will Map your Imported Content to your Zendesk Content.

Map your Imported Content to your Zendesk Content

To associate content that you imported with the corresponding content in Zendesk, you need to "map" it. Mapping tells Paligo about the relationships between:

  • Imported publications and categories in Zendesk

  • Imported topics and articles in Zendesk.

Use Zendesk Preflight to map your imported content:

  1. On the Publish document dialog, select the Zendesk Preflight tab.

    The Publish document dialog should still be on display from when you chose your publishing preferences.

    Zendesk Preflight shows your publication, it is collapsed by default.

  2. Select the chevron > to open the publication structure.

    You will see that the sections are duplicated. There are sections with a green and white plus icon and then the same sections but grayed out.

    Zendesk preflight. The structure shows a Cybersecurity publication, expanded to reveal its sections. There are plus icons next to the first three sections. The second three sections have no icon and are grayed out. They have the same titles as the first three sections.

    The sections with the plus icons are what Paligo will add to your Zendesk when you publish.

    The grayed out sections are the sections that already exist in Zendesk.

    But you don't want to duplicate the sections in Zendesk. Instead, you want to map the sections in Paligo to the sections in Zendesk (see next step).

  3. Select the cog icon Cog icon. for a section that has a plus icon. Paligo displays a Properties dialog that has a Mapping setting.

    Zendesk Preflight. Properties dialog for a section. It has a link to the topic in Paligo, and a Mapping setting. It also shows it will be a Section in Zendesk.

  4. In the Mapping dropdown, select the section that has the same name as the current section and a blue reuse icon. Select Confirm to remap and close the dialog.

    Section properties dialog in Zendesk Preflight. The Mapping dropdown options are revealed. A callout box highlights the option that has a blue reuse symbol and the same title as the selected section.

    This mapping tells Paligo to publish the section to the existing section in Zendesk rather than create a new section.

  5. Repeat steps 3 and 4 for the other sections. When you have finished, Zendesk Preflight should show only sections that are going to be updated. There should be no grayed out sections.

    Close up of Zendesk preflight publication structure. It shows that all sections have a reuse symbol and are set to map to existing sections in Zendesk.

  6. Expand a section to reveal the topics that are going to become articles in Zendesk. You should see that Paligo is going to add new articles and these are shown with plus icons. The existing articles are also listed and these are grayed out. Just like you did with the sections, you are going to map the new articles to the existing articles (see next step).

    Close up of Zendesk preflight publication structure. It shows a section has a reuse symbol and is set to map to an existing section in Zendesk. Inside the section, there are six articles. Three are going to be added and three with the same name already exist in Zendesk.

  7. Select the cog icon for an article that has a plus icon. Paligo displays a Properties dialog that has a Mapping setting.

    Zendesk preflight, article properties dialog. It has settings for mapping, labels, managed by, visible to, and status.

  8. In the Mapping dropdown, select the article that has the same name as the current article and a blue reuse icon.

    Zendesk preflight, article properties dialog. The mapping dropdown is shown and a callout box highlights the option that has a blue reuse symbol and the same title as the current article.

  9. [Optional] Add any labels and set the status for the article:

    • Labels

      Enter any labels that you want to include for the article. Labels are a Zendesk concept and you can find out about them in the official Zendesk documentation.

    • Managed by

      Choose who can edit and publish the article, for example, Agents and Managers. The Managed by setting is sometimes called Permission Group in Zendesk.

    • Visible to

      Choose who can see the article when it is published to your Zendesk help center. The Visible to group is sometimes called a User Segment Group in Zendesk.

    • Status

      Choose to either:

      • Publish the article in your Zendesk help center

      • Store the article as a Draft in your Zendesk help center.

  10. Select Confirm.

    You have now mapped a topic in Paligo to update an existing article in Zendesk rather than create a new article.

  11. Repeat the steps for mapping articles for all of the articles in your publication. You will need to expand each section, and for each article that Paligo is going to add (plus sign), map it to update an existing article instead.

    When you have finished, the structure in Zendesk Preflight should show that Paligo is going to update the sections and articles in Zendesk. It should not be set to add or duplicate any sections or articles.

    Zendesk preflight, publication structure. All sections and all articles have blue reuse icons. They have been set to map to sections and articles that already exist in Zendesk.

    Note

    Use the blue checkboxes on the left of the list to choose which categories, sections, and articles are going to be published.

  12. Select Publish Document.

Paligo will publish the sections and articles to Zendesk. If you have set the mapping correctly, it should update the existing sections and articles.

You have now imported and mapped a category. Next, you should repeat the import and mapping process for any other categories in your Zendesk help center.

From now on, if you need to update your articles, you should make the changes in Paligo and then publish to Zendesk. You should not need to map the topics to articles again. However, in some cases the mapping can be lost. This is usually due to an article being deleted in Zendesk and then restored. If this happens, use Zendesk Preflight to remap the topic and article.