The Configuration File

This article contains the following topics:
casm171
This article contains the following topics:
The text_api.cfg file defines the keywords that are related directly to the fields of the various tables that you can update. You use this file both as a reference to find certain predefined values, such as keywords, and as a mechanism for configuring the Text API, although the default configuration file works for most installations without modification.
The text_api.cfg file is located in the following directory:
  • UNIX -- $NX_ROOT/site
  • Windows --
    installation-directory
    \site. For example: C:\Program Files\CA\Service Desk\site
The configuration file is divided into sections, with particular attributes defined within each section. Attribute definitions are of the following form:
keyword=value
None of the keywords are case-sensitive, whereas all values (except in the [OPTIONS] section) are case-sensitive.
You can view and modify the text_api.cfg file using any text editor.
If you are integrating with the CA NSM Alert Management Systems component, you must update text_api.cfg for any additional fields that are passed to CA SDM.
Options
The [OPTIONS] section of the text_api.cfg file defines processing options that may differ from one site to another. For example, there are options to determine the incoming date format, which fields allow linefeeds to be retained, and whether to allow issues, requests, or change orders to be updated using the email interface. All options in this section are configurable. Be aware that although you can remove table names from the VALID_TABLE_LIST, if you do not want to support Text API access to those tables, you cannot add table names to this list.
Defaults
Use the [XX_DEFAULTS] section provided in the text_api.cfg file for each interface using the Text API (for example, [EMAIL_DEFAULTS] for the email interface and [CMD_DEFAULTS] for the command line interface). The [XX_DEFAULTS] section defines the default values for fields and properties that are required in case the user does not supply them directly. XX refers to the interface type, such as CMD or EMAIL.
To set default values, use one of the following formats:
  • table_name
    .
    keyword
    =
    value
    The
    keyword
    must be defined either in the [KEYWORDS] section or as properties in your database. Any method associated with the keyword is automatically applied to the
    value
    . For example:
    ISSUE.PRIORITY=1
    The PRIORITY keyword is defined in text_api.cfg so that it performs a lookup to convert the value you specify to match the corresponding value that is stored in the database. Here, value 1 is converted to 5, which is the underlying database value for the priority symbol 1. This feature lets users specify the value just as they would in the web interface.
  • table_name
    .PROPERTY={{
    property_label
    }}
    value
    The
    property_label
    must be defined as a property in your database.
In both formats, the
table_name
must be one of the values defined by VALID_TABLE_LIST in the [OPTIONS] section, such as Issue, Request, or Contact.
Ignore Incoming
There are several [..._IGNORE_INCOMING] sections in the text_api.cfg file, one for each interface that uses the Text API (for example [TNG_IGNORE_INCOMING] for the CA NSM interface and [EXT_IGNORE_INCOMING] for the external interface used by other CA products). These sections define fields and properties that are ignored in the input (the format is the same as described in Defaults, except no “
=
value
” is specified). This feature lets you prevent users from setting certain values, which in turn, provides you with more security for such times as letting customers use the email interface.
The IGNORE sections work well when used in conjunction with the corresponding [..._DEFAULTS] sections because you can prevent the user from setting a particular value and supply a default value at the same time. For example, if you want to prevent email interface users from setting the priority of an issue, you could set the following values:
[EMAIL_DEFAULTS] ISSUE.PRIORITY=2 [EMAIL_IGNORE_INCOMING] ISSUE.PRIORITY
In this case, any priority that the user specifies in the email message body is ignored, and all issues created by the email interface are automatically assigned a priority of 2.
Example Input
The following examples show input that you can use in the body of an email message or in a file serving as input to the command-line interface.
Example: First Line Does Not Include a Keyword
In this example, because the first line is missing a %keyword in the first column, the literal %DESCRIPTION=
is added to the beginning of the message. This addition sets the description field to “This entire text goes to the description field” (with the line break intact, because ISSUE.DESCRIPTION is included in the list of fields for the LINEFEEDS_ALLOWED entry in the [OPTIONS] section of text_api.cfg).
This entire text goes into the description field %PRIORITY=None
Example: First Line Includes a Keyword
In this example, the PRIORITY keyword is defined in text_api.cfg so that it performs a lookup to convert the value you specify to match the corresponding value that is stored in the database. Here, the value None is converted to 0, which is the underlying database value for the priority symbol 1. This feature lets users specify the value as they would in the web interface.
%description=This is my description %priority=None %CATEGORY=Upgrade.PC %PROPERTY={{Current CPU}}266 mhz %PROPERTY={{Current Harddrive}}1 gig %PROPERTY={{Requested Upgrade}}4 gig harddrive
The specified values are used to set the description and priority fields for the ticket, similar to the previous example (notice that keyword case is unimportant).
The value of Upgrade.PC is searched, and the category field for the ticket is set appropriately.
Matching the following labels sets the three property values:
  • Current CPU
  • Current Hard drive
  • Requested Upgrade