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.

Related topics

Setting-up-and-going-live

Converting-articles-from-external-file-formats

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.

    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.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*