Quickstart - How to package knowledge articles using the Knowledge Packaging Tool

This section provides a Quickstart set of instructions for packaging knowledge articles using the Knowledge Packaging tool.

Search for	Example	Results
A single word	`cat`	Topics that contain the word "cat". You will also find its grammatical variations, such as "cats".
A phrase. You can specify that the search results contain a specific phrase.	`"cat food"` (quotation marks)	Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase.

Search for	Operator	Example
Two or more words in the same topic	`AND` `and` `+` (plus symbol) `&` (ampersand)	`cat AND dog` `"cat food"+milk` `"cat food"&"dog food"`
Either word in a topic	`OR` `or` `\|` (pipe)	`cat OR dog` `cat \| dog`
Topics that do not contain a specific word or phrase	`NOT` `not` `!` (exclamation point)	`NOT cat` `! dog`
Topics that contain one string and do not contain another	`^` (caret)	`cat ^ mouse`
A combination of search types	`( )` parentheses	`cat + (dog \| mouse)` `cat \| dog + (! mouse)`

Note

This procedure assumes that you have downloaded the Knowledge Packaging Tool ZIP file and that you have extracted its contents. If not, download the tool as described in How to download the Knowledge Packaging tool.
This section describes how to use the tool to package knowledge articles. In this case, the articles must be in HTML format, or in a format that can be saved to HTML format.
Advanced users: The Knowledge Packaging tool can also be used to package knowledge articles from other sources, and in various file formats. For example, knowledge articles retrieved from a custom knowledge base using an in-house article retriever plugin, or knowledge articles that have been retrieved and machine translated.

For more information, see the Service Anywhere Knowledge Packaging Tool guide that accompanies the Knowledge Packaging tool.

To package HTML articles using the Knowledge Packaging tool:

On your local machine, create a folder for the knowledge articles. For example, MyArticles.

Copy your knowledge articles to this folder.

For example, in the <Packaging_tool_deployment>/saw-article-packaging-tool folder, locate the Word document named sample-article.docx and copy it into the MyArticles folder.

For each article that you want to package, if the article is not already in HTML format, open it in the relevant application, and save it in HTML format.

For example, open sample-article.docx in Microsoft Word, and save it as an HTML file, sample-article.htm.

(Optional) You can also add links to external sources.

For example, to add a link in sample-article.docx to Youtube:

Open the file in a text editor.
Locate the last three lines of the HTML code:

Add the following lines above the </body> tag:

<p>
<div saw-collapsible="See also">
<iframe width="420" height="315" src="https://www.youtube.com/embed/FLIfIKOiC-o" frameborder="0" allowfullscreen>
</iframe>
</div>
</p>

When all of your articles are ready for packaging, open a command line prompt, and change to the saw-article-packager-tool folder:

cd <Packaging_tool_deployment>/saw-article-packager-tool

At the command prompt, enter:

article_packager.bat <full path to the MyArticles folder>

The batch file creates the <Packaging_tool_deployment>/saw-article-packager-tool/out folder, containing an knowledge-articles.zip file.

After you run the packaging tool:

Open and review the log files that were created and check for errors. The log files are located in: in the Packaging_tool_deployment>\saw-article-packager-tool\logs folder:

Log file	Description
error.log	Includes information about errors in the packaging process
info.log	Includes information about the packaging process
summary.log	Includes the following information: The number of articles that were created. The IDs of the articles that were skipped and the reason for each. The URLs of the images that could not be extracted and the reason for each. The IDs of the affected articles are also listed.

Log file

Description

error.log

Includes information about errors in the packaging process

info.log

Includes information about the packaging process

summary.log

Includes the following information:

The number of articles that were created.
The IDs of the articles that were skipped and the reason for each.
The URLs of the images that could not be extracted and the reason for each. The IDs of the affected articles are also listed.

Extract and explore the contents of the knowledge-articles.zip file. The knowledge-articles.zip file contains the following structure:

Folders
articles	Contains the output knowledge articles. The title of each article is placed under the `<head><title>` tag in the HTML. The names of the files are generated as part of the conversion process, and are all located in the same folder with unique names. file1.html file2.html
resources	Contains images that are embedded in the knowledge articles.
Files
metadata.xml	For example, title, author, or tags for each article, as well as each knowledge article's external ID. The external IDs are required in the future if a knowledge article needs to be overwritten.

Note

Open the HTML files to check that everything was implemented as you expected, including embedded images appearing properly, and that links between knowledge articles are working.
If you rerun the batch and a knowledge-articles.zip file already exists, an additional ZIP file is created with a sequential number appended to the name. If, however, you used the -override option, the knowledge-articles.zip file is overwritten each time.