Skip to main content

ServiceNow Integration

With Paligo's ServiceNow integration, you can publish content you create in Paligo directly to your ServiceNow help center. So you can use Paligo's powerful authoring features for content creation, and use your ServiceNow help center to present that content to your customers.

Your Paligo topics are "mapped" to become 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 Content to ServiceNow and there are also examples to show you how the mapping works.

paligo-plus-servicenow.png

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

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

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. Select your profile name in the upper right corner to display a menu, and then select Settings.

  4. In the Settings view, select the Integrations tab.

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

  6. Enter the URL for your ServiceNow subdomain. If you are copying and pasting the URL into the field, note that the https:// prefix and .service-now.com suffix are already included, so you will need to remove those from your entry.

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

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

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

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

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

  12. Select Save.

To test your Paligo to ServiceNow connection, access the ServiceNow integration settings again and select the Test Settings button. Paligo runs the test and displays a success or failure message. If the connection fails, check that the information you have provided is correct and also that your ServiceNow is not in hibernation. If you still have problems, contact Paligo support for assistance.

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

Publish Content to ServiceNow

To publish content from Paligo to ServiceNow, you first need to set up the Paligo to ServiceNow connection. 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 order 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 work around is to number your top-level topics.

  1. Edit the MS Word layout.

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

  2. Select HTML as the output format.

  3. Select a ServiceNow Knowledge layout. You can use the built-in ServiceNow Knowledge layout or you can create a new one (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.

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

    The ServiceNow Knowledgebase is set to "IT"

  5. Choose the ServiceNow category that will receive your Paligo content. This is optional - you do not have to publish to a category.

    The ServiceNow Category is set to "Applications"

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

    Note

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

    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 then 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 use.

  6. If you want to add some basic styles to your content check the Use Paligo CSS box.

    A Use Paligo CSS checkbox.

    This gives each piece of content that you publish from Paligo a reference to a Paligo stylesheet (CSS). The Paligo CSS contains styling rules to give your articles appropriate font sizes, spacing etc.

    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.

  7. Choose the Languages to publish to. If you do not have any translations, you can only select the original/source language.

  8. If you have set filters (Profiling attributes) on topics or elements, and/or have used variables, choose which values to use for the publication. See Filtering / Profiling and Variables to learn how to use these features.

  9. You can use the Upload output settings to upload a zip of the content you are publishing to a repository, for example, GitHub. To find out more, see the integrations documentation for the type of repository you want to use.

  10. Use the Optional parameters to choose whether Paligo will save the output zip file in Paligo, send you a notification when the publication is complete, and generate a log file for debugging.

  11. If you think you will need to use these same settings again, select Save Settings. Enter a name for the saved settings and select OK. These settings are then stored in the Saved Settings tab, so that the next time you publish, you can select the settings profile from there instead of having to re-enter the settings again.

    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.

  12. Select Publish Document.

    Paligo applies the publishing settings to your content (variables, filters, etc), generates the HTML, and "pushes" it to ServiceNow. Your topics are now articles in ServiceNow.

    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.

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.


In this section: