Creating a configuration file for conversions

If you need to convert knowledge articles from a third-party application to a format that can be used by Knowledge Management, you can create a configuration file. For more information, see Converting-articles-from-external-file-formats.

Using a text editor, such as Notepad, create a config.properties file. Depending upon your requirements, you can provide parameters to configure the Article Conversion Tool. This topic describes the various parameters that you can use.

Terms used in this topic

This topic uses the following terms to explain the format of parameter values that you must use in the config.properties file:

dataLocation—Location of the required information in the original knowledge articles. The location can be mapped to specific fields in Knowledge Management. Depending on the file format, its value can change:
Custom XML files—Specify the name of the custom XML tag that contains the required information. Alternatively, you can tag an attribute that might contain the required data.
HTML files—Specify the tag address within the HTML file that contains the required information
(fixedValue)—Fixed text value. If the parameter value format includes both the data location and the fixed text value, then the fixed text value is used only if the specified dataLocation does not exist in a particular source knowledge article, or if it does not contain a value.
Important
Fixed text values must be enclosed in parentheses, as shown in the Value format column of the tables in this topic.

Custom XML tag attributes

For Custom XML files, you can set parameter values to tag attributes. The following rules apply when you define tag attributes in the configuration file:

Enclose the attributes in square brackets.
Add the attributes after the tag name.
Specify the values of the attributes by using the equal ( =) sign
Separate the attributes with semicolons ( ; ).

Example

CTI.category = (tier one),category[id=Tier1;type=operation]

In this example,

tier one is the fixed value.
category is the name of the Custom XML tag that contains the information.
id and type are the names of the Custom XML tag attributes.
Tier 1 and operation are the values of the respective tag attributes.

Important

You can convert multiple articles at a time. However, the Conversion Utility tool supports converting one article per Custom XML file. If there are multiple articles in a single Custom XML file, you must first split each article into a single Custom XML file, and then proceed with the conversion.

HTML tag addresses

The tag address refers to the exact location of a tag in an HTML file.

Example

Title=/HTML/BODY/P[2]/,/HTML/HEAD/TITLE

In this example, the topic title is located in the second paragraph (second <P> tag), which is again enclosed within the <BODY> tag, which is enclosed within the <HTML> tag in the HTML source file.

An alternative tag address is provided after a comma, wherein the topic title is located within the <TITLE> tag, which is again enclosed within the <HEAD> tag, which is enclosed within the <HTML> tag in the HTML source file.

Login and common parameters

Ue the following parameters to provide the basic information about the knowledge articles source files.

Parameter	Description	Value format	Mandatory
ARUser	User name for the AR System Server administrator.		✅️
ARPassword	Password for the ARUser.		✅️
inputPath	Location of the article to be converted.		✅️
imageIdentifier	Prefix that is used in the original knowledge articles to identify image file paths. The prefix be followed by a forward slash ( / ). When the Article Conversion Tool encounters an image identifier, it uses the information that follows the forward slash to scan the directory for the referenced file.	imageIdentifier/	❌️
imagesPath	Location of the image files that are used by the original knowledge articles.		❌️
attachmentsPath	Location of the attachments in the original knowledge articles		❌️
attachmentIdentifier	Prefix that is used in the original knowledge articles to identify attachment file paths. The prefix must be followed by a forward slash ( / ). When the Article Conversion Tool encounters an attachment identifier, it uses the information that follows the forward slash to scan the directory for the referenced file.	attachmentIdentifier/	❌️
ARServer	Host name of the AR System Server.		✅️
webServer	Host name of the IT Service Management server.		✅️
webPort	Port number used to communicate with the IT Service Management.		✅️
apiPort	Port number used by APIs to communicate with the AR System Server.		❌️
httpProtocol	Indicates whether the hyperlinks in the original knowledge articles use HTTP or the HTTPS.		✅️
KBurlIdentifier	Prefix that is used in the original knowledge articles to identify hyperlinks to other knowledge articles. The prefix must be followed by a forward slash ( / ). When the Article Conversion Tool encounters a knowledge article URL identifier, it uses the information that follows the forward slash to scan the directory for the referenced knowledge article source file.	KBurlIdentifier/	❌️

Metadata parameters

Identify this section of the configuration file by adding the [metadata] tag. These parameters predefine metadata field values that will be mapped to the converted knowledge articles.

Tip

For a better reading experience, press F to view the following table in full screen mode. Press Esc to exit full screen mode.

The following table lists the metadata parameters that you can add to the configuration file.

Parameter	Description	Value format	Mandatory
ownerGroup	Name of the support group to which the knowledge article's owner belongs. The group must already be registered in the AR System database.	(fixedValue),dataLocation	✅️
ownerGroupId	Group ID of the support group to which the knowledge article's owner belongs.	(fixedValue),dataLocation	✅️
owner	Full name of the AR System user who owns the knowledge article. It can be the author or another user. Specify First Name and Last Name, separated by a space. For example, Allen Allbrook.	(fixedValue),dataLocation	✅️
ownerId	Login name of the AR System user who owns the knowledge article. It can be the author or another user. For example, Allen.	(fixedValue),dataLocation	✅️
KMS_author	Full name of the AR System user who created the knowledge articles. Specify First Name and Last Name, separated by a space. For example, Bob Baxter.	(fixedValue),dataLocation	✅️
authorId	Login name of the AR System user who created the knowledge article. For example, Bob.	(fixedValue),dataLocation	✅️
KMS_assigned	Login name of the AR System user to whom the knowledge article is currently assigned. For example, Bob.	(fixedValue),dataLocation	✅️
KMS_prevAssigned	Login name of the AR System user to whom the knowledge article was previously assigned. For example, Mary.	(fixedValue),dataLocation
KMS_companies	Name of the company for which the original knowledge article was created. The company must already be registered in the AR System database.	(fixedValue),dataLocation	✅️
KMS_title	Title of the knowledge article.	dataLocation	❌️
attachments	Comma-separated list of attachment file names.	dataLocation	❌️
CTI2.sub1	Name of the product to which the knowledge article is relevant.	dataLocation	❌️
CTI2.sub2	Name of the manufacturer of the product to which the knowledge article is relevant.	dataLocation	❌️
CTI2.sub3	Model or version of the product to which the knowledge article is relevant.	dataLocation	❌️
CTI3.category	Name of the Business Service (CI) that is relevant to the knowledge article. The CI must already exist in the Atrium CMDB.	dataLocation	❌️
CTI.category	Operational categorization Tier 1. For more information, seeCategorization.	(fixedValue),dataLocation	❌️
CTI.type	Operational categorization Tier 2.	(fixedValue),dataLocation	❌️
CTI.item	Operational categorization Tier 3.	(fixedValue),dataLocation	❌️
CTI2.category	Product categorization Tier 1.	(fixedValue),dataLocation	❌️
CTI2.type	Product categorization Tier 2.	(fixedValue),dataLocation	❌️
CTI2.item	Product categorization Tier 3.	(fixedValue),dataLocation	❌️
CTI4.category	Geographic region of the site of the company to which the knowledge article is relevant. This region could be a continent or a country.	(fixedValue),dataLocation	❌️
CTI4.type	Further narrows down the location of the site, by indicating a smaller area in which a group of sites is located. This location could be a state or a city.	(fixedValue),dataLocation	❌️
CTI4.item	Pinpoints a single site to which the knowledge article is relevant. This site could be a city or an office building.	(fixedValue),dataLocation	❌️
KMS_visibility_groups	Names of the visibility groups to whom the knowledge articles will be visible, sorted by company. For more information, see Managing knowledge article visibility. Enter values for this parameter in the following format: Company1~!~Group1~!~Group1\|Company2~!~Group1~!~Group2\|Company3... The following variables are used in the parameter: Company–The company that owns the visibility groups that follow it. Group–The name of each visibility group that belongs to a particular company. The characters ~!~ represent the separators between the name of the company and each of the visibility groups that belong to it. The vertical bar ( \|) represents the start of a different company's data	Refer to the Description column for this parameter	✅️
KMS_creationDate	Date on which the knowledge article was created.	(fixedValue),dataLocation	❌️
KMS_lastModifiedDate	Most recent date on which the knowledge article was modified.	(fixedValue),dataLocation	❌️
KMS_reviewDate	Date on which the knowledge article is scheduled for review.	(fixedValue)	❌️
KMS_documentId	Document ID of the knowledge article.	dataLocation	✅️
KMS_keyWords	Search keywords that users can enter to locate the knowledge article.	dataLocation	❌️
KMS_status	Current status of the knowledge article in its lifecycle.	(fixedValue),dataLocation	✅️
KMS_prevStatus	Previous status of the knowledge article.	(fixedValue)	❌️
language	Language in which the knowledge article is written.	(fixedValue),dataLocation	✅️
KMS_kblinks_prefix	Prefix used in hyperlinks to other knowledge articles. This prefix includes the KBurlIdentifier value.	KMS_kblinks_prefix	❌️
KMS_kblinks_suffix	Suffix used in hyperlinks to other knowledge articles. This suffix can be used to specify URL attributes.	KMS_kblinks_suffix	❌️

Source parameters

Identify this section of the configuration file by adding the [src] tag. These parameters are used to map knowledge article content fields in the original articles to fields on the desired knowledge article template in Knowledge Management.

Parameter	Description	Value format	Mandatory
formName	The knowledge article template that you want the converted knowledge articles to use. The following options are available: HowToTemplate ProblemsSolutionTemplate ReferenceTemplate KnownErrorTemplate	AR form name, including the prefix	✅️
How to template parameters
RKMTemplateQuestion	Maps the Question field in Knowledge Management, where you can capture the details of the question that is being addressed by the knowledge article.	dataLocation	✅️
RKMTemplateAnswer	Maps the Answer field in Knowledge Management, where you can capture the solution details of the question that is being addressed by the knowledge article.	dataLocation	✅️
RKMTemplateTechnicianNotes	Maps the Technical Notes field in Knowledge Management, where you can capture miscellaneous technical information that is relevant to the knowledge article.	(fixedValue),dataLocation	✅️
Problem Solution template parameters
RKMTemplateProblem	Maps the Problem field in Knowledge Management, where you can describe the problem or question that the knowledge article addresses.	dataLocation	✅️
RKMTemplateSolution	Maps the Solution field in Knowledge Management, where you can describe the answer to the problem or question that the knowledge article addresses.	dataLocation	✅️
RKMTemplateTechnicianNotes	Maps the Technical Notes field in Knowledge Management, where you can capture miscellaneous technical information that is relevant to the knowledge article.	(fixedValue),dataLocation	✅️
Reference template parameters
Reference	Maps the Reference field in Knowledge Management, where you can capture the reference information that is relevant to the knowledge article.	dataLocation	✅️
Known Error template parameters
RKMTemplateError	Maps the Error field in Knowledge Management, where you can capture details of the error relevant to the knowledge article.	dataLocation	✅️
RKMTemplateRootCause	Maps the Root Cause field in Knowledge Management, where you can capture details of the root cause of the error that is relevant to the knowledge article.	dataLocation	✅️
RKMTemplateFix	Maps the Workaround/Fix field in Knowledge Management, where you can capture details of the fix for the error that is relevant to the knowledge article.	dataLocation	✅️
RKMTemplateTechnicianNotes	Maps the Technical Notes field in Knowledge Management, where you can capture miscellaneous technical information that is relevant to the knowledge article.	(fixedValue),dataLocation	✅️

Sample configuration files

You can refer to the attached samples while creating your own configuration file.