Skip to main content

ServiceNow Integration

With Paligo's ServiceNow integration, you can enjoy the benefits of Paligo's powerful authoring features, while using ServiceNow to present your content to your customers. The integration allows Paligo to publish directly to a ServiceNow "Studio IDE" knowledge base.

When you publish in Paligo, your topics are "mapped" to articles in ServiceNow. The way this is done varies, depending on whether you choose to publish to a category or directly to the root of a ServiceNow knowledge base. But in both cases, Paligo will create an article for each top-level Paligo topic.

You can find out more in Publish to ServiceNow and there are also examples to show you how the mapping works.

paligo-plus-servicenow.png

Preparations for ServiceNow Integration

To publish from Paligo to ServiceNow, you will need:

  • ServiceNow account

  • ServiceNow user account that has these roles:

    • knowledge

    • knowledge_admin

    • knowledge_manager

    • content_admin (this role is needed to be able to apply Paligo CSS file to uploaded articles).

  • ServiceNow knowledge base, set up in the developer oriented IDE experience.

  • To have set up OAuth 2.0 in ServiceNow (only if you want Paligo to log in via OAuth 2.0).

  • Paligo user account with admin permissions. You need admin permissions to access the integration settings, see User Accounts.

  • Paligo publication with content to be published to ServiceNow.

  • ServiceNow Knowledge layout in Paligo. You can use the built-in ServiceNow Knowledge layout or Create a Layout based on the default ServiceNow Knowledge layout.

  • To disable MIME type checking for uploads in ServiceNow. In ServiceNow, access System Properties and then Security. Clear the checkbox for MIME type checking for uploads. This feature needs to be disabled so that Paligo can publish images to ServiceNow.

Tip

You can find out how to create a user account, apply user roles and set up OAuth 2.0 in ServiceNow's own documentation.

Connect Paligo to ServiceNow

To connect Paligo to ServiceNow, you need to have set up a user account with the appropriate roles in ServiceNow. For details, see the prerequisites in ServiceNow Integration.

When you have a suitable ServiceNow user account, you can set up Paligo to connect to ServiceNow.

Note

Paligo can log in to ServiceNow using OAuth 2.0. If you want to use this more secure form of logging in, you must first set up OAuth 2.0 in ServiceNow. You can find out how to do that in ServiceNow's documentation.

  1. Log in to your ServiceNow. This is only required if your ServiceNow has not been used for some time and has entered "hibernation". By logging in, you end the hibernation period. Paligo cannot connect to ServiceNow if it is in hibernation.

  2. Log in to Paligo via a user account that has administrator permissions.

  3. Sign in to Paligo using a user account that has administrator permissions.

  4. Select the avatar in the top-right corner. User avatar. It shows the user's image and their name. Next to the name is a downward pointing arrow, which when selected, reveals a menu.

  5. Select Settings from the menu. Cog icon.

  6. Select the Integrations tab. Jigsaw piece icon.

    Paligo settings. The Integrations tab is highlighted.

  7. Find the ServiceNow settings and select Add.

    Note

    Add is only available the first time you set up an integration. After that, Add is replaced by Change.

    Paligo displays the ServiceNow integration settings:

    ServiceNow integration dialog with settings for URL, authentication type, username, password, default knowledgebase and publishing status.

  8. Enter the URL for your ServiceNow subdomain. If you are copying and pasting the URL into the field, note that the https:// prefix is already included.

  9. Select the Authentication type. You can choose from:

    • Basic

      This is a simple login where Paligo logs in to ServiceNowby providing the Username and Password for a ServiceNow user account. This is less secure than OAuth 2.0 as it requires the user credentials to be provided each time.

      If you choose Basic, continue from step 8.

    • OAuth 2.0

      OAuth 2.0 can improve system security by reducing the amount of times user credentials have to be provided. To use OAuth 2.0, you will need to set it up in ServiceNow first, and then enter a Client ID, Client secret, and an Access Token in Paligo.

      If you choose OAuth 2.0, ignore step 8 and continue from step 9.

  10. If you chose the Basic authentication, enter the Username and Password for a ServiceNow user account. Paligo will use these credentials to log in to ServiceNow when publishing.

    ServiceNow integration settings show authentication type is set to Basic. There is a field for username and a field for password.

    Ignore step 9 and continue from step 10.

  11. If you chose the OAuth 2.0 authentication, enter the Client ID and Client secret. These are generated in ServiceNow when you set up OAuth 2.0. You also need an Access Token, which you can generate in Paligo.

    ServiceNow integration settings show Authentication Type is set to OAuth 2.0. There is are fields for Client ID, Client secret, and Access token.

    To generate an Access Token in Paligo, select the New button at the right of the Access Token field. If you do not currently have an Access Token or the existing token has expired, Paligo prompts you to enter the Basic ServiceNow login credentials (Username and Password ). These must be for a ServiceNow user account that has the required roles.

    Get access token dialog for ServiceNow integration. There are fields for Username, Password, and a Remember Me checkbox. There is also a Get token button.

    By default, the access token expires after 30 minutes. But if you check the Remember me box, Paligo will be able to automatically renew the token during a 100 day period. These times can be changed in ServiceNow's OAuth 2.0 settings.

    Select Get token to generate the access token.

  12. Set the Default Knowledge Base. This is the ServiceNow knowledgebase that Paligo will publish to, by default. You can choose from any of the ServiceNow knowledgebases that Paligo has detected, and you can update the list by selecting the button at the right of the field.

  13. Set the status for articles that Paligo publishes to ServiceNow. Choose from:

    • Published - The Paligo content is used as "live" published articles in ServiceNow.

    • Draft - The Paligo content is stored as draft articles. These are not publicly available in ServiceNow. They will only be shown to your readers when you change them to the Published status (in ServiceNow).

  14. Select Save.

  15. Select the Change button for the integration.

  16. Select Test Settings to run a connection test.

    Test_Reset_Settings_Integrations_small.jpg

  17. If the settings are:

    • Correct, Paligo shows a green success notification.

    • Incorrect, Paligo shows a red failure notification.

      Check each connection setting carefully, to make sure you have not made any mistakes and try again.

      If the connection test continues to fail, contact Paligo support for assistance.

When the Paligo to ServiceNow connection is successful, you can Publish to ServiceNow.

Publish to ServiceNow

To publish content from Paligo to ServiceNow, you first need to Connect Paligo to ServiceNow. With that in place, you can publish your Paligo content so that it appears in your ServiceNow knowledge base.

Note

ServiceNow only allows Paligo to publish categories in alphabetical or numerical order.

This means that the order of categories is unlikely to match the order of the top-level topics in your Paligo publication. One possible workaround is to number your top-level topics.

  1. Select the dotted menu (...) for the topic or publication in the Content Manager.

    selectpublish.png

  2. Select Publish.

    publish-document-jan23.png

    Paligo displays the Publish document dialog.

  3. Select HTML as the output format.

    Publish document dialog. It has settings for defining the type of output, the language, filtering, variables, and uploading output to repositories.

  4. Select a built-in ServiceNow Knowledge layout or Create a Layout (based on the built-in one).

    Publish document dialog has HTML selected as the output type and a ServiceKnowledge layout is selected.

    Note

    ServiceNow Knowledge Layouts are a type of HTML layout and may contain settings that are not used for ServiceNow, but are relevant to other HTML outputs, such as Zendesk.

  5. Choose the ServiceNow Knowledge Base that will receive your selected Paligo content.

    The ServiceNow Knowledgebase is set to "IT"

  6. Choose the ServiceNow category that will receive your Paligo content (Optional).

    When you publish to the selected category, Paligo will create a subcategory for each top-level topic in the publication. Inside each subcategory, it will create articles for the topics (see Example 1, “Publishing to a ServiceNow Category”). You do not have to publish to a category.

    The ServiceNow Category is set to "Applications"

    Tip

    We recommend that you use categories to group your articles in ServiceNow, and then set Paligo to publish to a category. This helps to make sure your articles are organized logically and are easier for readers to find.

    Note

    If you do not choose a category, Paligo will publish directly to the root of the selected knowledge base. It will create a category for each top-level topic in your publication and articles inside those categories, see Example 2, “Publishing to a ServiceNow Knowledge Base (no Category selected)”. If you publish a large amount of content in this way, your ServiceNow articles can become disorganized and more difficult to find.

  7. Choose whether you want Paligo to add some basic CSS styling to your published articles.

    • Check the Use Paligo CSS box to include a set of basic styles developed by the Paligo team. We created the styles as an improvement on the article styles that already exist in ServiceNow. You cannot edit the Paligo styles.

    • Clear the Use Paligo CSS box to prevent Paligo from adding any styles. The articles will continue to use the ServiceNow styles. These could be the default styles for knowledge articles or custom styles that admins have set up in ServiceNow.

    A Use Paligo CSS checkbox.

    When you publish, Paligo will save the CSS as a special object in ServiceNow and add a link to it from every article.

    Tip

    You can set all of your ServiceNow content (including articles that were not created in Paligo) to use the Paligo CSS. To do this, in ServiceNow, edit the HTML of the articles and add the reference to the Paligo CSS file. Similarly, you could also edit the articles Paligo creates and add a link to a CSS that you already have in ServiceNow.

  8. Define how Paligo responds to broken mapping to the category in ServiceNow.

    By default, when Paligo first publishes to ServiceNow, it creates a category in ServiceNow automatically. It adds your Paligo content to the category and keeps a record of the category ID. When you next publish, Paligo identifies the ID of the category and updates the content there. This is called "mapping".

    If you delete a category in ServiceNow, you can break the mapping, even if you replace it with a new category with the same name.

    By using the Match categories based on name setting, you can control what Paligo does in this situation.

    • Check the box to get Paligo to map content to a category that matches by name.

      Paligo will look for a category with a matching name.

      If it finds one, it will publish to that category, even if that category was created in ServiceNow. It also updates the mapping. Each time you publish your content, Paligo will update this category.

      If it cannot find a matching category, Paligo will create a category and map to that.

    • Clear the box to prevent Paligo from publishing to a category that it cannot identify.

      If Paligo cannot find the category by its ID, it will cancel the publishing and generate an error message. It will not map to a different category, even if that category has the same name.

  9. 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.

  10. 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.

  12. Use the Upload output settings to upload a zip file of the content to a repository, see Integrations.

  13. Use the Output filename section to control the filename.

    By default, Paligo will use the filename syntax that is defined in the System Settings.

    Output filename section. There is a Template field that contains the values ID, Title, and Format. In the top-right corner is a preview of the filename that Paligo will generate if the current settings are used.

    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.

    Tip

    If you type @ into the field, Paligo displays a list of the available values and you can select from the list. To remove a value, click in it and use the delete key or backspace key to remove all of its characters.

    Note

    The filename shown in the top-right corner is a preview of the filename that Paligo will use when you publish.

  14. 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.

  15. 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).

    Publish_Progress_Bar_small.jpg

    A progress bar appears. Select the arrow to hide the progress bar and reopen it by selecting the progress clock in the top menu. To abort the publish, select the X.

    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.

    Publish document dialog has a Save Settings option and a Saved Settings tab. The option saves the currently shown settings and these can then be selected in a single action on the tab.

Note

If you have cross-references between different categories, you will need to publish your content twice. This is because when you first publish, the topic with the link (the "source") may link to an article that has not been published yet (the "target"). So the link does not work. Links between articles in different categories will only work if the "target" exists in ServiceNow when the "source" is published.

Examples of ServiceNow Publishing
Example 1. Publishing to a ServiceNow Category

Let's say you have an "IT" knowledge base in ServiceNow. It has a Category called "Learning".

In Paligo, you have a publication with "Getting Started" as a top-level topic and "Installation", "Backups", and "Performance Test" as second-level topics. There is a single "Engineering Test" third-level topic, and two fourth-level topics: "Fan Speed Test" and "Cooling Test". They are organized in a hierarchy like this:

  • Getting Started (publication)

    • Installation

    • Backups

    • Performance Test

      • Engineering Test

        • Fan Speed Test

        • Cooling Test

You publish to ServiceNow and choose "IT" as the knowledge base and "Learning" as the category. In ServiceNow, you will get:

  • IT (knowledge base)

    • Learning (category)

      • Installation (subcategory)

        • Installation (article)

      • Backups (subcategory)

        • Backups (article)

      • Performance Test (subcategory)

        • Performance Test (article)

        • Engineering Test (article)

The fourth-level "Fan Speed Test" and "Cooling Test" topics become subsections inside the "Engineering Test" article.


Example 2. Publishing to a ServiceNow Knowledge Base (no Category selected)

Let's say you have an "IT" knowledge base in ServiceNow.

In Paligo, you have a publication with "Getting Started" as a top-level topic and "Installation", "Backups", and "Performance Test" as second-level topics. There is a single "Engineering Test" third-level topic, and two fourth-level topics: "Fan Speed Test" and "Cooling Test". They are organized in a hierarchy like this:

  • Getting Started (publication)

    • Installation

    • Backups

    • Performance Test

      • Engineering Test

        • Fan Speed Test

        • Cooling Test

You publish to ServiceNow and choose "IT" as the knowledge base. You do not select a category. In ServiceNow, you will get:

  • IT (knowledge base)

    • Installation (category)

      • Installation (article)

    • Backups (category)

      • Backups (article)

    • Performance Test (category)

      • Performance Test (article)

      • Engineering Test (article)

The fourth-level "Fan Speed Test" and "Cooling Test" topics become subsections inside the "Engineering Test" article.