CA SDM Text API Interface

This article contains the following topics:
casm1401
This article contains the following topics:
Overview of Text API
The
Text API
is an interface that lets you use text-based input to create and update objects in the CA SDM database, such as issues, requests, contacts, and assets. Using the Text API, you can assign values to most fields that are accessible to users.
CA SDM requires that all input be in UTF-8 format, or data can be corrupted. The pdm_unconv utility lets you convert data from a local charset to UTF-8 and from UTF-8 to a local charset.
You can access the Text API by using the following interfaces:
  • Command line
  • Email
  • CA NSM
You can use web services as the alternative to the Text API for cross-application integration.
Command Line Interface
Use the
pdm_text_cmd
command to activate the Text API command line interface. You can then specify information such as the table to process and the operation to perform by using parameters to the pdm_text_cmd command.
The input to the Text API is passed to the pdm_text_cmd command in the form of an input file, or directly from STDIN.
When passing the parameters from command prompt, use Ctrl+Z in Windows and Ctrl+D in POSIX.
You cannot use single or double quotation marks as parameters for the bop_cmd and pdm_text_nxd commands.
CA Network and Systems Management Interface
When CA NSM and CA SDM are integrated and you are creating requests from CA NSM events, the user_parms
parameter in writer rule definitions is passed to the Text API. The CA SDM writer process (tngwriter) defines its own replacement parameters for changing the text before sending it to the Text API. The keyword LOG_AGENT is added to the end of the input to set the log_agent for the request.
You need to update the Text_API.cfg file for all additional fields that are passed from CA NSM Alert Management Systems to CA SDM. This file is used for integrations with web services, email and AHD.DLL.
Input Format
Input to the Text API is specified in the following ways:
  • In the command-line interface, input is typically specified in a text file passed to the pdm_text_cmd command.
  • In the email interface, input is specified in the text of the email. You specify a regular expression to find the target object identifiers.
You format the Text API input in the same way no matter which interface you use.
The basic format for input is as follows:
%keyword=value
or
%PROPERTY={{property_label}}value
The normal behavior of Text API commands has the following exceptions, where the last-appearing of two or more conflicting commands takes precedence:
  • When a message contains multiple valid ticket ID artifacts matching the mailbox rule filter string, or multiple Text API ticket ID commands, the first one encountered is used. Also, a ticket ID artifact, which is identified using the mailbox rule filter string, overrides any Text API ticket ID command, regardless of which appears first.
  • When a message contains multiple log comment Text API commands, all comments are posted, although the order in which they appear in the ticket activity log can vary.
All ticket ID artifacts that match the filter, valid or otherwise, and Text API ticket ID commands within the message, applicable or otherwise, applied or otherwise, are commented out before the message is posted. The ticket ID artifacts identified through the mailbox rule filters appear as -((...))-. Leading percentage signs (%) in Text API ticket ID commands are converted to two opening parentheses ((, and two closing parentheses )) follow the command. If a Text API ticket ID command appears after another Text API command with a log comment (%LOG=…), then the commented-out Text API ticket ID command is made into a separate log comment.
The log comment is the only Text API command that can appear multiple times in one message and still have each occurrence applied. For any other commands, the Text API uses the last occurrence only, because multiple occurrences of other commands conflict with each other. Multiple log comment commands post separate log comment messages to the ticket, and not necessarily in any particular order.
In addition, if a Text API ticket ID command appears in the message either at the beginning of the message or in between two other Text API commands, it is converted into a log comment. If the previous command is a log comment (%LOG=…) or update description (%DESCRIPTION=…), it is appended to that command, rather than becoming a separate log comment.
Incoming messages that are sent HTML-only, without a plain-text version included, lose their message body. If the message matches any mailbox rule filters with an empty message body, a ticket can be created with an empty Description, or with the quoted message subject as the entirety of the ticket description.
How the Text API Uses Keywords
You can use two types of keywords as input to the Text API.
  • Definitions in the [KEYWORDS] section of the text_api.cfg file -- This type is a group of keywords that are related directly to the fields for the various tables that you can update. For example, most of the fields on the Issue Detail form are defined the [KEYWORDS] section. Using these keywords, you can set values for fields in the record that you are updating or creating. For example, the following line sets the priority of the issue to 5:
    %PRIORITY=5
    The [KEYWORDS] section of the text_api.cfg file lists all keywords. You can define additional keywords (for example, to allow Text API access to fields that you have added when customizing your database schema).
  • The following special keywords are always defined as follows, regardless of the contents of the text_api.cfg file:
Keyword
Description
ASSET
Used to attaches an item to a ticket (valid for requests, issues, and change orders). The value specified is the item name, which must already exist. You can specify this keyword multiple times, because a ticket can have multiple items attached to it.
ATTACHMENT
Used internally by the email interface to add email attachments to a ticket.
DESCRIPTION
Specifies the value to use for the ticket’s description field. This keyword is assumed if input is sent to the Text API without an explicit keyword. This keyword is applied automatically by the Mail Eater when the message does not begin with a keyword but does contain a ticket ID artifact or keyword.
You can change how the DESCRIPTION keyword is handled for updates using the following entry in the [OPTIONS] section of text_api.cfg:
UPDATE_DESC_IS_LOG
If this option is set to YES, the value is used to create a log comment. If the value is set to NO, the value overwrites the existing description field.
FROM_EMAILFROM_EMAIL_OVERRIDE
Used by the email interface to match against the Email Address field in the ca_contact record. It is also used as the log_agent for the ticket. If both are supplied, FROM_EMAIL is ignored.
FROM_EMAIL is set automatically by the Mail Eater with the sender address of the message.
FROM_PERSID
Used by the command line interface to define the log_agent for an operation (for example, when a ca_contact record does not have a User ID). This keyword is passed automatically by pdm_text_cmd if the -p parameter is specified
.
The value is matched to a ca_contact record persistent_id.
FROM_USERID
Used only in the command line interface to define the log_agent for an operation. This keyword is passed automatically by pdm_text_cmd if the -u parameter is specified. The value is matched to a contact’s User ID.
LOG
Used to create a log entry (valid for requests, change orders, issues, and contacts). This keyword is applied automatically by the Mail Eater when the message does not begin with a keyword but does contain either a ticket ID artifact or keyword, or a DESCRIPTION keyword.
LOG_AGENT
Used by the CA NSM interface to define the log_agent for an operation. The value is matched to a contact record’s ID field.
PROPERTY
Used to set the value of a property (valid only for requests, change orders, and issues). Unlike other keywords, which are followed by an equal sign and a value, the PROPERTY keyword syntax must include the property label, as follows:
PROPERTY={{property_label}}value
You must specify the
property_label
exactly as it appears in the database.
SEARCH
Used only in the command-line interface and the CA NSM interface to supply a list of keywords for use in a query to update multiple tickets for an asset. The value is a list of keywords used in the search.
The SEARCH keyword is automatically set by the CA NSM interface.
SEARCH_EXPLICIT
Used only in the CA NSM interface to override the SEARCH keyword supplied by the CA NSM interface. The values supplied are the same as the SEARCH keyword.
Keyword Input Conventions
The following conventions apply to keyword input formatting:
  • Prefix every keyword (including PROPERTY) with a percent (%) sign. The percent sign must be in column position one. If the first nonempty line of the input does not have a percent sign at the start of the line, either %DESCRIPTION= or %LOG= is used as the prefix for the incoming data, depending on whether a ticket ID artifact or keyword was found. If %DESCRIPTION is set, the contents of the message up to the first Keyword is posted as a ticket description. If %LOG= is set, the contents of the message up to the first Keyword is posted as a log comment.
  • Do not use any intervening spaces within the keyword between the percent sign and the keyword, or between the keyword and the equal (=) sign.
  • Do not quote values; all data after the equal sign is assumed to be the value.
  • Keywords are not case sensitive.
  • If the input includes duplicate keywords, the last keyword is used; otherwise, the order in which you specify the keyword/value pairs is unimportant.
  • Specify keyword values as you would for the corresponding field in the web interface. For example, to specify an Analyst contact type, you use %CONTACT_TYPE=Analyst, even though in the database this value is stored as an integer. The CONTACT_TYPE keyword is defined in text_api.cfg so that it converts the specified value to match the stored value.
    Whether the value is case sensitive depends on your underlying DBMS.
  • You can extend string data across multiple lines.
Format an Email Message To Update a Ticket
A user can format an email message to create or update a ticket.
To format an email message to create or update a ticket, use the following fields:
  • To
    Specifies the mailbox name assigned to the CA SDM contact set up for the privileged user.
  • From
    Specifies the person sending the email. The person must be defined in the ca_contact table unless the Allow Anonymous option is specified in the applicable mailbox rule.
    The From address is typically part of your email program configuration, and it is not typically set on a per-message basis.
  • Attachments
    Attaches documents and other files to the email to send attachments to the Text API.
  • Subject
    Matches keywords in a mailbox rule filter string, particularly when creating a ticket.
  • Body
    Specifies the message body of the email using the Text API. You can specify the keyword ISSUE_ID, REQUEST_ID, or CHANGE_ID, depending on the type of ticket to create or update a ticket.
Start and End Email Message Delimiters
Some email interfaces add information to the beginning or end of mail messages (for example, MIME encoding) that can cause the email interface to malfunction.
If your email interface adds information, you can use the following delimiters:
start-request and end-request. The email interface ignores information that is specified prior to start-request and subsequent to end-request.
The Mail Eater does not support emails in the RTF or HTML-only formats.
Example: Use start-request and end-request Delimiters
"start-request" message_body "end-request"
How the Text API Uses Artifacts
The Text API processes the subject or body of email notifications. Mailbox rules let you identify artifacts and values that the Text API uses. For example, you can define the rule for incidents as Incident:{{object_id}}, so finding Incident:1234 translates to %INCIDENT_ID=1234 for the Text API. 1234 is the ref_num for the Incident. Because the artifact must be unique in the email and easy to find, you can make the artifact more distinctive such as %Incident:{{object_id}}%.
Follow the {{object_id}} keyword with a character which is not a letter, number, comma, forward-slash (/), plus sign (+), or equals (=) sign, because these characters can appear within an artifact. Otherwise, it is possible that characters which follow the artifact can be misinterpreted as part of the value of the artifact, or that a character within the value of the artifact can be misinterpreted as the character which follows the value.
Mail Eater does the following:
  1. Finds the artifact within an email (such as Incident:1234) that maps to the appropriate ticket or other object supported by the Text API.
  2. Translates the artifact to a Text API token (such as %INCIDENT_ID=1234).
  3. Mail Eater submits the tagged message to the Text API. The Text API processes the email, applies the text, commands, or both which it contains to the appropriate ticket, and generates an automatic response email indicating whether the email message it received was successfully applied. Depending on the actions performed, a notification email message is also sent separately to indicate certain specific events, such as the creation of a ticket.
How to Set Up Notification Replies to Update Tickets
The Text API daemon (pdm_text_nxd) creates and updates tickets with information from external interfaces, such as the command line and email. You can set up mail to use the Text API so that users (contacts) can update tickets by replying to email notifications. The text of the reply is added as a log comment activity to the ticket.
To set up notification replies to update tickets, do the following:
  1. Set the notification method that the contact uses to pdm_mail - T
    reply_email_address
    or pdm_mail - F
    reply_email_address.
    The
    reply_email_address
    specifies the incoming address for the mailbox. When the contact clicks reply on an email that address is filled in from the From or Reply-To address of the message to which they are replying.
    -T sets the Reply-To address. -F sets the From address, which is used as the reply address if a separate one is not specified.
    Some mail programs do not or cannot honor a Reply-To address.
  2. Create or update a mailbox rule using a Text API keyword.
    The user-defined artifacts in the mailbox rule filters replace the following Text API keywords:
Object
Text API Keyword
Identifier
Incident
%INCIDENT_ID
Ref_num
Problem
%PROBLEM_ID
Ref_num
Request
%REQUEST_ID
Ref_num
Chg_ref_num
%CHANGE_ID
Chg_ref_num
Issue
%ISSUE_ID
Ref_num
  1. Create or update a notification phrase that matches the rule.
  2. Create or update a message template that uses the notification phrase.
  3. Update the mailbox rule that you created in Step 2 to specify the message template that you created or updated in Step 4.
After the user receives the notification and replies to it, the following actions occur:
  1. When the filter string is found, the relevant ticket ID keyword and value denoted by the placeholder, if any, are appended to the message.
  2. If a matching ticket ID artifact is found, the corresponding ticket is updated, with either a log comment, a new description, or other values in accordance with the text, keywords, and commands in the message.
  3. If a matching ticket ID artifact is not found, a ticket is created with a description and other parameters in accordance with the text, keywords, and commands in the message.
How to Set Up a Reply to an Incident Notification Example
This example shows how to set up a reply to an incident notification.
To set up a reply to an incident notification, do the following:
  1. Create a mailbox rule using the following fields and values:
    • Filter -- Body contains
    • Filter String -- %Incident:{{object_id}}%
    • Ignore Case -- YES
    • Action -- Update Object
    • Action Object -- Incident
  2. Create a notification phrase that includes the rule as follows:
    • Symbol -- Incident Reply
    • Code -- IncidentReply
    • Active -- Active
    • Description -- Comment that embeds the reply for an Incident/Problem/Request.
    • Phrase -- In order to add a comment to your @{call_req_id.type.sym}, just reply to this email or include the line below (on a line by itself):
      %Incident:{call_req_id.ref_num}%
      In auto-reply text of the mailbox rule, omit the call_req_id. prefix. This prefix applies a context which the mailbox rule text is already in, and such a context change is not valid when already acting within that context.
  3. Create or update a message template that uses the notification phrase as follows:
    • Notification Message Body
      This is a simple notification. @{notification_phrase[IncidentURL1].phrase}
  4. Update the mailbox rule that you created in Step 1 to specify the message template that you created in Step 3, as follows:
    Message Template --
    mailbox rule name
How an End User Updates a Ticket Example
The following example demonstrates how an end user (John Smith) replies to an email notification to update an incident ticket.
The Body or Subject of the email includes the object identifier. The {{object_id}} placeholder within the filter string denotes the object identifier.
  1. A notification is sent to John Smith and includes the following instructions:
    In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %Incident:1234%
  2. John Smith replies to the notification as follows:
    This is my response...
  3. The Mail Eater receives the following text version of the John Smith's email:
    This is my response... From: Service Desk Sent: Wednesday, September 18, 2009 10:22 AM To: Smith, John Subject: Simple Notification This is a simple notification. In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %Incident:1234%
  4. The Mail Eater processes rules in order and finds the %Incident:1234% artifact:
    This is my response... From: Service Desk Sent: Wednesday, September 18, 2009 10:22 AM To: Smith, John Subject: Simple Notification This is a simple notification. In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %INCIDENT_ID=1234
  5. The Mail Eater adds the Text API keywords and the {{object_id}} value to an %INCIDENT_ID= statement and leaves a marker where the {{object_id}} value was found. The following text shows the data that is sent to the Text API. The bold text shows values added by the Mail Eater.
    %LOG=This is my response...
    From: Service Desk
    Sent: Wednesday, September 18, 2009 10:22 AM
    To: Smith, John
    Subject: Simple Notification
    This is a simple notification.
    In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself).
    %Incident:-((...))-%
    %FROM_EMAIL=john.smith@company.com
    %INCIDENT_ID=1234
  6. The Text API add a log comment for Incident 1234.
Keyword Conversion Methods
Many of the keywords defined in text_api.cfg have an associated method to convert the value specified to a value that is appropriate for storage in the database. This feature lets users specify values just as they would in the web interface without having any knowledge of the underlying implementation.
The configuration file has several examples of this type of keyword definition, including ISSUE.PRIORITY and CONTACT.CONTACT_TYPE. If you need to define additional keywords (for example, to allow Text API access to fields that you have added when customizing your database schema), you can use one of the following predefined methods:
Method
Output Type
lookup_actbool
INTEGER
lookup_asset_by_name
UUID
lookup_asset_by_persid
UUID
lookup_chg_category
STRING
lookup_chg_status
STRING
lookup_cnt_by_email
UUID
lookup_cnt_by_last_first_middle
UUID
lookup_cnt_by_logonid
UUID
lookup_cnt_by_persid
UUID
lookup_cnt_meth
INTEGER
lookup_cnt_type
INTEGER
lookup_company
UUID
lookup_cr_status
STRING
lookup_cr_template
STRING
lookup_domain
INTEGER
lookup_grc
INTEGER
lookup_group
UUID
lookup_impact
INTEGER
lookup_iss_category
STRING
lookup_iss_status
STRING
lookup_loc
UUID
lookup_mfr_model
UUID
lookup_nr_family
INTEGER
lookup_org
UUID
lookup_person_contacting
INTEGER
lookup_position
INTEGER
lookup_priority
INTEGER
lookup_prob_category
STRING
lookup_product
INTEGER
lookup_resource_status
INTEGER
lookup_service_lvl
STRING
lookup_severity
INTEGER
lookup_state
INTEGER
lookup_timezone
STRING
lookup_type_of_contact
INTEGER
lookup_urgency
INTEGER
lookup_workshift
STRING
If the value you need to convert is not addressed by any of these predefined methods, you need to write a customized method. The method should take a STRING value as its input and return a value (either INTEGER, STRING or UUID) as its output. Return a value of -1 (or “-1”) to denote that the value cannot be determined and is therefore, not set. For UUID, return a “(uuid) NULL”.
For example, you might develop a method to convert a user ID to a ca_contact table reference. The incoming value, such as Administrator, would be passed to the method, and the method would return the ca_contact table id for the user ID of Administrator.
The manner in which you define keywords in the configuration file offers you the advantage of defining multiple keyword mappings to the same field, including different conversion methods, depending on the value being specified. For example, assignee can have several different keyword mappings to define how to set its value based on different input values. One input might be user ID, another might be last name, first name, middle name, and still another might be the actual ca_contact id (for example, 793ED69B4E87A545BD8E911834D829FC). Each keyword maps to a different conversion method, except the last one, which does not need to be converted.