Learn how to connect Paligo to Zendesk multibrand by using the integration settings in Paligo.
Zendesk enterprise plans have a multibrand feature where you can have a main Zendesk domain and also subdomains for different brands. For example, you could have acme.zendesk.com as your main domain, and then acme100.zendesk.com as a subdomain and acme200.zendesk.com as another subdomain. Paligo can publish to the top-level categories in the main Zendesk domain or those in a subdomain.
Note
Paligo can publish to top-level categories in a brand. You cannot publish Paligo content to lower-level categories.
Before you set up Paligo to publish to multiple subdomains (brands), make sure that:
-
Your Paligo plan includes multibrand support. It is included in the Paligo enterprise plan. On other Paligo plans, you can only publish to the main domain (or you could set up a Zendesk subdomain as the main domain in Paligo).
-
You have made the necessary preparation for connecting Paligo to Zendesk.
-
You have set up the various brands you want to use (in Zendesk). They all need to have a URL for their subdomain.
For details, see the official Zendesk documentation.
With these prerequisites in place, complete the following steps (1-4).
To connect to Zendesk, Paligo needs an API key. You can generate the API key in Zendesk and then copy it to Paligo.
-
Log in to your Zendesk account.
-
Display the Zendesk Admin Center. (Select the Zendesk Products icon and then select Admin Center).
-
In the Apps and Integrations section, select Zendesk API.
-
On the Settings tab, set Token Access to Enabled. This allows you to create API tokens.
-
Select Add API Token.
-
Enter a name for the API token in the API Token Description field.
-
Select Copy to copy the API token to your computer's clipboard.
When you have an API token from your Zendesk account, you can set up an integration in Paligo. The integration allows Paligo to connect to your Zendesk and:
-
Import content when you first migrate from Zendesk to Paligo
-
Publish content from Paligo to Zendesk.
If your Paligo plan includes multibrand support and you have Zendesk multibrand, you can publish to a top-level category in any of your brands. You can choose which brand and category to use for publishing in Paligo's integration settings.
To connect Paligo to Zendesk:
-
Log in to Paligo via a user account that has administrator permissions.
-
Sign in to Paligo using a user account that has administrator permissions.
-
Select the avatar in the top-right corner.
-
Select Settings from the menu.
-
In the Zendesk box, select Change.
If the Zendesk integration has not been set up in your Paligo instance previously, select Add instead of Change.
-
In the Account #1 section, enter the connection details for your main Zendesk brand:
-
Your Zendesk url: Enter the web address of your main Zendesk brand. This is the primary domain in your Zendesk.
-
E-mail: Enter the email address of a user with "Manager" permissions for the domain in Zendesk.
-
API key: Paste the API key into this field. Paligo and Zendesk use the API key to authorize the connection.
-
-
Select Save.
-
Select Change to re-open the Zendesk integration settings again. If Paligo was able to connect to your Zendesk instance, it will detect the categories and permissions automatically. You will be able to select them in the remaining steps of this procedure.
-
Select the Default category. This is the category that Paligo will publish to by default, unless you choose a different category when you publish.
Paligo automatically detects the categories that are available for the chosen account. Select the category you want from the list.
-
In the Permission Settings section, choose who can control and view the articles published to the selected account.
-
Use the Managed by setting to choose which group of Zendesk users can edit and publish articles that Paligo creates/updates in Zendesk.
Choose Admins or Editors and Publishers.
-
Use the Visible to setting to control who can see the articles that Paligo creates/updates in Zendesk.
Choose Everyone, Signed-in users, or Agents and admins.
-
-
Use Set as default to define whether Paligo should use the account as the default for publishing:
-
Select the Set as default radio button to use this account as the default account for publishing. When you publish, the publishing settings will automatically have this account in place, as the default setting. You can choose to publish to a different account if you wish.
-
Deselect (clear) the Set as default radio button if you don't want Paligo to use this account as the default account for publishing.
-
-
Select Save and then select Test settings.
Paligo attempts to connect to Zendesk. If the connection attempt fails, check the URL, email, API key, and default category ID carefully for errors and make sure the API key is valid.
-
To change an existing account or add another account, select the Choose account drop-down and either:
-
Select another account that has already been created.
-
Select Add account to create a new account.
-
-
Edit the settings for the account you selected or added in the previous step.
Set the:
-
Your Zendesk url - The URL of your Zendesk brand. This is the address of the subdomain for the brand.
-
E-mail - The email address of a Zendesk user who has "manager" permissions for the brand.
Note
The API Key is the same as the API Key for the primary domain, by default. For multibrand, this is usually appropriate. However, if you wanted to publish to separate Zendesk instances, instead of brands on the same account, you could add an account for each Zendesk instance and then set the different API key for each instance.
Use the other settings to configure the subdomain. The settings work in the same way as on the main brand. The values you put in place are stored separately for each account, so you can have accounts with the same, similar, or completely different settings, depending on what you need.
-
-
Select Save and then select Test settings.
This works in the same way as the test on the main brand.
You have now set Paligo to connect to your Zendesk(s).
Tip
To delete an account, see Remove a Zendesk Multibrand Account.
Now let's publish your content to Zendesk.
-
Select the dotted menu (...) for the topic or publication in the Content Manager.
-
Select Publish.
-
On the Settings tab, select HTML.
-
Choose the Zendesk layout that you want your publication to use.
The different types of Zendesk layout map content to Zendesk differently, so it is important that you choose a layout that meets your requirements. To find out how each layout maps content to Zendesk, see Zendesk Layouts.
-
Choose the Zendesk category that will receive your selected Paligo content.
-
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.
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.
-
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.
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.
-
Select the languages to be published.
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.
-
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.
Select OK to add your chosen profiling attribute(s).
-
Use the Output filename section to control the filename.
By default, Paligo will use the filename syntax that is defined in the System Settings.
To change the information included in the filename, enter your preferred format in the publishing settings. Default is:
ID-Title-Format
.You can use:
-
ID - The ID of the document.
-
Title - The title of the publication or topic that you are publishing.
-
Format - The name of the output format, for example, PDF or HTML5.
-
Edit date - The date that the publication or topic was last edited.
-
Branch label - The text from the branch label for the publication or topic. This only applies if your content has been branched and it has a branch label. For details, see Add or Edit Branch Labels.
-
Unique value - A random string of characters, generated by Paligo, that is added to the filename to make it unique. This can stop the file from being overwritten by later publishes of the same document.
-
-
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.
-
-
Select the Zendesk Preflight tab to View the Paligo-to-Zendesk Mapping.
If you are happy with the existing mapping, you can proceed to the next step.
To change the mapping, use the various settings on the Zendesk Preflight tab. You can map the Paligo topics to different sections and articles, change the Managed By and Visible To status, set the topics to be draft or publish, and promote them as needed. To find out more, see Customize Paligo-to-Zendesk Mapping.
-
Select Publish Document.
Paligo starts processing your content and applies your layout and publishing settings. The time that this takes varies depending on how much content you are publishing (the more content, the longer it takes).
The published output appears as:
-
A ZIP file with the published output appears in the downloads folder on your computer.
If you have altered your browser's settings to store downloaded files somewhere else, the zip file will be found there instead.
If you are using a publishing integration, the zip file will also be sent to the relevant service.
-
A link in the Activity Feed Panel to download the published content.
Note
To make the content available online, first unzip the file. You can then use the file locally or you can use an FTP client, such as Filezilla, to upload the unzipped content to a web server.
Tip
You can save your publishing settings and reuse them to achieve a smoother publishing process, see Publishing Settings. Any settings you save can also be used for Batch Publishing.
-
When Paligo publishes to Zendesk, a compressed file downloads in your browser. The first time you publish to Zendesk, you will need to add some of the downloaded files to your Zendesk.
When you publish to Zendesk, Paligo downloads a package in your web browser. The package contains CSS and javascript files, which are used to provide certain functionality and styles in Zendesk. You can add some or all of these assets to your Zendesk, depending on what functionality you want to include.
The CSS and JS files are:
-
JS
-
paligo-zd.js
Provides a range of functionality, including "accordion" collapsible sections, syntax highlighting for code, and checklists.
-
paligo-zd-lightbox.js and lightbox-min.js
These provide the "lightbox" feature, where you can select an image to view a larger version of the image
-
paligo-zd-glossary.js
Provides a popup on the glossary terms in your content. The popup contains the glossary term definition.
-
paligo-swagger.js
Allows swagger/Open API content to be embedded in Zendesk articles.
-
paligo-stickymenu.js
Adds a sub-navigation menu in the sidebar. This contains links to the sections inside an article. It also makes the menu "sticky" - it stays in view on the page even when you scroll down, and will scroll separately for long articles.
-
paligo-anchorlinks.js
Adds a "Click to copy" option to each heading, so that you can quickly copy the URL for that heading.
-
bootstrap-min.js
Provides the bootstrap framework that is needed for some of the javascript features, such as the glossary popups.
-
-
CSS
-
paligo-zd.css
Includes some basic styling to improve the overall look and feel of your articles, and also supports the functionality in the javascript files.
You can use this as a starting point for your styling. But you should check that the paligo-zd.css styles do not clash with any base styles you already have in Zendesk. If the styles do clash, you will need to make some overrides in your CSS or choose which styles you want to include/exclude.
-
paligo-stickymenu.css
Contains the styling for the "sticky menu" feature that's provided by paligo-stickymenu.js
-
lightbox.min.css
Contains the styling for the "lightbox" feature that's provided by paligo-zd-lightbox.js and lightbox.min.js.
-
You can find these files in the css and js folders in the zip file that is downloaded in your browser when you publish to Zendesk.
The first time that Paligo publishes to your Zendesk, you should add the CS and JS files to the Zendesk Assets :
-
Open the zip file that is downloaded when you publish.
-
Log in to your Zendesk help center.
-
Click the Guide Admin icon at the top right.
-
Select the Customize Design feature, and then choose the active theme and select Edit Code.
-
Select the Assets folder.
-
Find the JS > Zendesk folder and the CSS > Zendesk folder in the downloaded package. These contain the CSS and javascript files you need to add to your Zendesk assets. You can ignore the other files in the downloaded package.
-
Decide on which JavaScript and CSS files you want to use and then add them to the Assets in Zendesk.
We recommend that you include references to: paligo-zd.js, paligo-zd.css, and bootstrap.min.js. You should also include a reference to the jquery.min.js script.
-
paligo-zd.js
-
paligo-zd.css
-
bootstrap.min.js
-
jquery.min.js (this is a script that is provided externally, and the details for this reference are included in step 9).
The other references are optional. But if you decide to use a feature, remember to include all of the files that are needed for it, for example, glossary popups require paligo.zd-glossary.js and bootstrap.min.js, and the lightbox feature needs paligo-zd-lightbox, lightbox.min.js and lightbox.min.css as well as the jquery reference.
-
-
In the Zendesk theme, open the Templates folder and then select document_head.hbs.
-
Add a reference to each file, and also to the "Font Awesome" stylesheet (it is hosted, so there is no need to upload it to the Zendesk assets).
The following example shows the syntax for the references (and assumes that you have not renamed the package files). We have separated the references with comments so that you can see which references you need to include for the features you want.
<! -- reference for jquery script --> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script> <! -- reference for bootstrap script --> <script src="{{asset 'bootstrap.min.js'}}"></script> <! -- reference for fontawesome --> <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet"/> <! -- reference for "copy to copy" anchorlinks --> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js"></script> <! -- reference for paligo-zd scripts and css. Note that the first two references are for code syntax highlighting and they must come before the reference to the paligo-zd.js file. You can leave those out if you do not want to use syntax highlighting --> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.5.0/styles/androidstudio.min.css"/> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.5.0/highlight.min.js"></script> <script src="{{asset 'paligo-zd.js'}}"></script> <link href="{{asset 'paligo-zd.css'}}" rel="stylesheet" type="text/css" /> <! -- references for lightbox scripts and css --><script src="{{asset 'lightbox.min.js'}}"></script> <script src="{{asset 'paligo-zd-lightbox.js'}}"></script> <link href="{{asset 'lightbox.min.css'}}" rel="stylesheet"/> <! -- references for stickymenu scripts and css --> <script src="{{asset 'paligo-stickymenu.js'}}"></script> <link href="{{asset 'paligo-stickymenu.css'}}" rel="stylesheet" type="text/css" /> <! -- reference for glossary scripts and css --> <script src="{{asset 'paligo-zd-glossary.js'}}"></script>
-
Select Publish to save the settings in Zendesk.
You have now uploaded the relevant packaged files from Paligo into Zendesk, and set your Zendesk article pages to reference the files.
Comments
0 comments
Article is closed for comments.