MadCap Flare is a powerful authoring tool that makes it easy for authors to reuse and repurpose source content for different deliverables. Its multi-channel publishing functionality allows writers to deliver content in a variety of formats for different types of audiences — all from a single source.
With the release of MadCap Flare 2020, a new MadCap Connect for ServiceNow® plugin makes it easy for users to publish Flare source content directly to a ServiceNow® knowledge base. The plug-in is the latest addition of plug-ins, adding to the Salesforce® and Zendesk integrations.
ServiceNow® is one of the most popular platforms that supports IT Service Management (ITSM) and is used by companies worldwide including many MadCap Software customers. With this new plug-in, you won’t have to worry about managing duplicate content, copy and paste updates, and have to reformat the same material in separate places. This integration streamlines the workflow by allowing the author to manage content in Flare as a single source, and publish some, or all of that content into your ServiceNow® knowledge base.
MadCap Connect for ServiceNow®
So now you may be wondering, “How can I access MadCap Connect for ServiceNow® and how do I set it up in MadCap Flare?” Let’s go over the steps.
Retrieve the ServiceNow® Credentials
After Flare 2020 is installed, the next step is to retrieve the required ServiceNow® credentials that allow Flare and MadCap Connect for ServiceNow® to connect to your ServiceNow® instance. Before you can use this integration, a ServiceNow system administrator must log in to ServiceNow® Service Management and create a new entry in the ServiceNow® application registry. This one-time step allows you to retrieve the client ID and client secret that you will need when you are setting up the integration in Flare.
Create a Publishing Destination
Publishing destinations in Flare are used to easily send a copy of your output files into a specified location so others can access them. Using a publishing destination, you can point to your instance of ServiceNow® and have Flare transfer topics into a ServiceNow® knowledge base. Publishing destinations can be created and stored in the Project Organizer > Destinations folder.
In the publishing destination, select MadCap Connect for ServiceNow® from the publishing type dropdown. You then must activate the plug-in with a MadCap Connect for ServiceNow® license key or start the free 30-day trial.
After the plug-in is activated, log in to your ServiceNow® instance with your credentials. This is where you need the client ID and the client secret that was retrieved after creating a new entry in the ServiceNow® application registry.
Once you have successfully logged in and connected to your instance of ServiceNow®, there are additional options in the publishing destination. Most of these fields are optional, however, the only required fields are to select a default knowledge base and default category
For more information on the rest of these options, please visit this topic in Flare’s online Help.
Map to ServiceNow® Knowledge Categories Using a Flare TOC
It is recommended to create a TOC in Flare that is specific for publishing into ServiceNow®. Having a separate TOC allows you to organize the structure and the hierarchy of your TOC books so that you can easily publish them into the desired category. There are two options for the Flare TOC when publishing into ServiceNow®:
The first method is to have Use TOC to define categories selected. This option allows you to use the structure of the TOC to determine which categories the topics will publish. This option will be checked by default.
When Use TOC to define categories is selected, the books in the TOC are used to define the categories. Flare provides a unique way to map topics to categories in a ServiceNow® knowledge base by using the TOC structure. The first level book will become a top-level category. The second level book will become a nested category under the first level category. Topics at the third level will become articles and will use the nested second level book as the category.
The second publishing method for the TOC is to have all topics in the Flare TOC published to the default category that is set in the publishing destination. This can be set by deselecting Use TOC to define categories.
Publishing Your Content: Create a Clean XHTML Target
MadCap Connect for ServiceNow® supports publishing Clean XHTML targets from Flare. This target type will remove MadCap specific code and will produce clean XHTML files that ServiceNow® can ingest. In your Clean XHTML target, select the TOC created for ServiceNow®.
It is recommended to select Convert stylesheet styles to inline styles in the target if you would like the styles applied to your Flare topics to carry over into ServiceNow®. ServiceNow® does not use stylesheets the same way as Flare, so selecting this option converts your styles into inline styles in the topic files. This allows formatting to be included for articles published to ServiceNow®.
Another target option to keep in mind is to select Exclude content not linked directly or indirectly from the target. By selecting this option, the only topics that will be published into ServiceNow® are the topics that are linked directly or indirectly from the target.
Note: Files that are not linked to the TOC but are linked to a file in the TOC are still included in the output. These topics will be published to the default knowledge base and category specified from the publishing destination. You can view all of the files that are published to ServiceNow® by inspecting the files generated in the Flare output folder.
Select the ServiceNow® publishing destination by going to the Publishing tab.
Once your target settings are configured, click Publish to build and publish your single-sourced content into your ServiceNow® knowledge base.
The Published Content
Here is how the content looks when published into my ServiceNow® knowledge base. The top-level books in the TOC are mapped to ServiceNow® Categories and the second level books in the TOC become nested categories.
In the articles, you will notice all of the content, images, and links are preserved.
When your articles need to be updated, simply go back into Flare to make your updates and then republish into ServiceNow®. The articles in ServiceNow® will be updated with the newly published changes.
Additional Considerations
- Multimedia files in Flare, such as videos are not supported and will not be published. However, links to YouTube and Vimeo videos are preserved.
- The user publishing from Flare to ServiceNow® must also have the appropriate permissions enabled in ServiceNow®. For more information, please click on the Quick Help icon for Required Permissions when logging in to ServiceNow® from Flare.
Now, it’s time for you to try it out! MadCap Connect for ServiceNow® is available to test free for 30 days. It can be purchased as a separate add-on to Flare or comes included with your MadCap AMS subscription. This plug-in can save you a lot of time by allowing you to single-source your content from MadCap Flare to ServiceNow® Knowledge articles. For additional information and best practices, please visit the Flare Online Help.
Do you have any questions about the plugin? Feel free to leave a comment below or reach out to me directly at jcatolico@madcapsoftware.com.
