Outputs Supported
Note This feature is supported in HTML5 skinless output, but not in HTML5 Side Navigation, Top Navigation, or Tripane outputs.
Following are some steps you should complete and information you should know before you publish from Flare to Zendesk. For example, these guidelines can help when structuring the table of contents (TOC), and configuring the destination file for Zendesk.
Note This documentation assumes you have a Zendesk account set up and a working knowledge of the Zendesk dashboard.
[Menu Proxy — Headings — Online — Depth3 ]
Zendesk Side
Following are settings and considerations on the Zendesk side of this process.
Administrator or Team Leader
To publish output from Flare to Zendesk, you must be set as either an Administrator or Team Leader on Zendesk. In Zendesk's Admin Center, you can view and set team members and their roles.
Categories and Sections
You have different options when it comes to publishing Flare output to your Zendesk categories and sections. Depending on your situation, you might even be using a combination of these options when you publish to Zendesk.
- You can publish output to the initial categories and sections in your Zendesk Help Center, designating which ones to use as defaults in your Flare destination file.
- You can create other categories and sections in Zendesk to better align with your Flare TOC. Flare populates those categories and sections with articles if it finds they match your TOC, but Flare does not change the order of the categories and sections as you create them in Zendesk. Only newly created categories and sections resulting from the Flare publishing process are added in the order dictated by the Flare TOC.
- You can create categories and sections on the fly during the publishing process from Flare. New categories and sections are automatically added to Zendesk based on your settings and the structure of the Flare TOC.
Note When structuring your files to publish to Zendesk, keep in mind that Flare has no limit to the number of levels (i.e., nested books) supported in the TOC, but Zendesk may have limitations. For example, files nested deeper than six sections are routed to the default category in Zendesk, and display as a list since there are no more levels to store those articles. In a situation like this, you might consider rearranging the TOC in Flare or the files in Zendesk. Refer to the Zendesk documentation for current maximum nesting levels.
For more information and examples, see Configuring the TOC for Zendesk.
Topics and Articles
If you are using the same topic multiple times in the TOC, that topic is published only once in Zendesk.
If you remove topics from a TOC and republish that target to Zendesk, those corresponding articles are removed from the dashboard. However, an empty section might remain on the dashboard if all underlying articles have been removed. The empty section needs to be manually removed through your Zendesk dashboard.
Search
Although some Flare targets, such as HTML5, let you choose a search engine, you are not using Flare's search for output published to Zendesk. Instead, the search provided on Zendesk is used for that content.
Attachment Limits
Zendesk limits you to 20 MB per attachment for images and other files (e.g., videos).
Multilingual Targets and Language Settings
Multilingual targets in Flare can be published to Zendesk. Users in Zendesk can switch between languages in the interface to see the categories, sections, and articles in a particular language.
Whether you are publishing multilingual output or just content in a single language, it is a good idea to make sure the language that is set in the Zendesk Help Center matches the language set in the user's profile. For example, English (United States) is not the same thing as English (United Kingdom). The two should match exactly. Otherwise, you might not be able to see the list of categories and sections from the Flare destination file.
Note For each language used to publish your project, you need to set up the default categories and sections for each language in Zendesk.
Brands
Keep in mind that you can publish to alternate brands in a multi-brand account.
Example — Publishing to Alternate Brands in Multi-Brand Account
In Zendesk you have a subdomain called “MadCap Software,” the name of your company.
Instead of publishing everything to that subdomain, you want to publish specific content to each or your company’s products: Product A, Product B, and Product C. Therefore, you create brands for each of those products.
In Flare, you have a target, destination file, and TOC dedicated to Product A. The target points to both that destination file and the TOC.
When you enter your credentials in the Destination Editor, you provide the URL for that brand.
After you publish the target, the content for Product A displays within the Product A brand on Zendesk.
Flare Side
Following are settings and considerations on the Flare side of this process.
Clean XHTML or HTML5 Skinless
In order to publish to Zendesk, you must use either Clean XHTML or skinless HTML5 as the target format. So if you choose HTML5, make sure you open the target, select the Skin tab, and from the Skin drop-down choose (none). In addition, do not include skin components (e.g., for search bars, menus) in your output, because anything having to do with a skin is not supported.
Targets, TOCs, and Destination Files
If you want to publish multiple groups of content to Zendesk, it is best not to do so from the same target (e.g., switching the TOC in the target file each time you want to publish different content). Otherwise, the most recently published content replaces the content published earlier. It is best to use a different target, destination file, and TOC for each distinct group of content.
Flare to Zendesk Only
Importing Zendesk Content
Flare supports sending output to Zendesk, but not importing content from it. After publishing topics from Flare, you should not edit the resulting articles in Zendesk if you plan to republish from Flare in the future. Otherwise, any changes you make in Zendesk will be overwritten by the newly published topics.
Limiting Content Published
You have different options when it comes to limiting the content that is published to Zendesk:
- There is an Exclusions field in the Destination Editor where you can enter specific files to be held back from the publishing process. This is particularly useful to exclude files such as Default.htm, which is the main entry file for HTML5 formats.
- You can use conditions on topic files in Flare, then include or exclude them appropriately in the Target Editor.
- In the Target Editor, you can select the Advanced tab and choose an option in the Content to include drop-down. You can include files linked directly or indirectly from the target, or you can include only files linked directly from the TOC.
Duplicate Headings
When you view a published article in Zendesk, you might notice a title at the top of the article with the identical text in the heading from the Flare topic. The text at the top is populated automatically based on the <title> tag found for that topic in Flare. Often, the author doesn't provide a separate set of text for that tag, so the main heading text is used.
If you want to have a different title for your articles in Zendesk, you need to open the properties for the topic file in Flare, then on the Topic Properties tab, enter text in the Topic Title field.
If you don't want to change the topic titles, but just don't want to see the same text duplicated in the heading after it, you can use conditions or styles (or even both) in Flare to hide that heading in the published article in Zendesk.
API Rate Limitations
You should avoid publishing multiple targets to Zendesk from a batch at the same time in order to avoid any API rate limitations during the upload process. You can still publish targets in a batch, but you probably want to open the Options dialog (File > Options), select the Build tab, and set the Maximum Concurrent Builds to 1.
For more information about API rate limitations, see the following:
https://develop.zendesk.com/hc/en-us/articles/360001074328-Best-practices-for-avoiding-rate-limiting
Practice Publishing
Since you have many options for publishing content to Zendesk, you might find it helpful to practice publishing output using different settings in Flare. If your Zendesk account supports a Sandbox, it is recommended you use that. Once you identify results that you like in Zendesk, you can than publish output to your production environment.
