CA SDM テキスト API インターフェース

この記事には、以下のトピックが含まれています。
casm173
この記事には、以下のトピックが含まれています。
テキストAPI の概要
テキスト API
は、テキストベースの入力を使用して、CA SDM データベースの案件、リクエスト、連絡先、アセットなどのオブジェクトを作成および更新できるインターフェースです。 Text API を使用すると、ユーザがアクセス可能なフィールドの大部分に値を割り当てることができます。
CA SDM では、すべての入力文字列が UTF-8 形式である必要があります。それ以外の形式を使用すると、データが破損する可能性があります。 pdm_unconv ユーティリティを使用すると、ローカルの文字セットから UTF-8 に、または UTF-8 からローカルの文字セットにデータを変換できます。
Text API には、以下のインターフェースを使用してアクセスできます。
  • コマンド ライン
  • 電子メール
Web サービスを、アプリケーション間統合で Text API の代替機能として使用できます。
コマンド ライン インターフェース
pdm_text_cmd
コマンドを使用して、Text API コマンド ライン インターフェースを有効にします。 処理するテーブルや実行する操作などの情報は、pdm_text_cmd コマンドのパラメータを使用して指定できます。
Text API に入力した情報は、入力ファイルの形式で、または STDIN から直接、pdm_text_cmd コマンドに渡されます。
コマンド プロンプトからパラメータを渡す場合は、Ctrl + Z キー(Windows)または Ctrl + D キー(POSIX)を使用します。
bop_cmd および pdm_text_nxd コマンドのパラメータとして単一引用符または二重引用符を使用することはできません。
入力フォーマット
Text API への入力は以下の方法で指定されます。
  • コマンド ライン インターフェースでは、入力は通常、
    pdm_text_cmd
    コマンドに渡すテキスト ファイルに指定されます。
  • 電子メール インターフェースでは、入力は電子メールのテキスト内に指定されます。 正規表現を指定して、ターゲット オブジェクト ID を検索できます。
どちらのインターフェースを使用しても、同じ方法で Text API への入力をフォーマットします。
入力の基本フォーマットは以下のとおりです。
%keyword=value
または
%PROPERTY={{property_label}}value
Text API コマンドの通常の動作では、2 つ以上の矛盾するコマンドが存在する場合は最後のコマンドが優先されますが、以下の例外があります。
  • メッセージに、メールボックス ルール フィルタ文字列と一致する有効なチケット ID 成果物、または複数の Text API チケット ID コマンドが含まれている場合、最初のオカレンスが使用されます。 また、チケット ID 成果物(メールボックス ルール フィルタ文字列を使用して識別される)は、最初に検出されたコマンドにかかわらず、どの Text API チケット ID コマンドよりも優先されます。
  • メッセージに複数のログ コメント Text API コマンドが含まれる場合、すべてのコメントがポストされますが、それらがチケット アクティビティ ログに表示される順序は異なる場合があります。
フィルタに一致するすべてのチケット ID 成果物(有効かどうかにかかわらず)と、メッセージ内の Text API チケット ID コマンド(適用可能かどうか、あるいは適用されたかどうかにかかわらず)はすべて、メッセージがポストされる前にコメント化されます。 メールボックス ルール フィルタによって識別されたチケット ID 成果物は「-((...))-」と表示されます。 Text API チケット ID コマンドの先頭のパーセンテージ記号(%)は、2 つの開かっこ「((」とコマンドの後に続く 2 つの閉かっこ「))」に変換されます。 ログ コメント(%LOG=…)付きの別の Text API コマンドの後に Text API チケット ID コマンドがある場合、コメント化された Text API チケット ID コマンドは個別のログ コメントになります。
ログ コメントは、1 つのメッセージ内で複数回使用でき、さらに各オカレンスが適用される唯一の Text API コマンドです。 ほかのコマンドでは、Text API は最後のオカレンスのみを使用します。これは、ほかのコマンドの複数のオカレンスは相互に矛盾するためです。 複数のログ コメント コマンドによって個別のログ コメント メッセージがチケットにポストされますが、その順序は必ずしも決まっていません。
また、Text API チケット ID コマンドがメッセージの先頭、またはほかの 2 つの Text API コマンドの間に存在する場合、そのコマンドはログ コメントに変換されます。 前のコマンドがログ コメント(%LOG=…)または更新の説明(%DESCRIPTION=…)である場合、コマンドは個別のログ コメントになるのではなく、前のコマンドに追加されます。
テキスト API におけるキーワードの使用
Text API に対する入力として 2 種類のキーワードを使用できます。
  • text_api.cfg
    ファイルの[KEYWORDS]セクションにおける定義: これは、更新可能な複数のテーブルのフィールドに直接関係するキーワードのグループです。 たとえば、[案件の詳細]フォームのほとんどのフィールドは [KEYWORDS] セクションで定義します。 これらのキーワードを使用して、更新または作成するレポート内のフィールドの値を設定できます。 たとえば、以下の行は案件の優先度を5に設定します。
    %PRIORITY=5
    text_api.cfg
    ファイルの [KEYWORDS] セクションには、すべてのキーワードが列挙されています。 追加のキーワードを定義できます(たとえば、ユーザのデータベース スキーマをカスタマイズする際に、追加したフィールドへの Text API のアクセスを許可する場合など)。
  • text_api.cfg
    ファイルの内容にかかわらず、特殊なキーワードが常に以下のように定義されています。
キーワード
説明
ASSET
チケットに項目を添付するのに使用します(リクエスト、案件、および変更要求で有効)。 指定する値は項目名で、すでに存在している必要があります。 チケットには複数の項目を添付できるため、このキーワードは複数回指定できます。
ATTACHMENT
チケットに電子メール添付ファイルを追加するのに、電子メール インターフェースによって内部的に使用されます。
DESCRIPTION
チケットの説明フィールドに使用する値を指定します。 キーワードを明示的に指定せずに入力をText APIに送信した場合は、このキーワードが使用されます。 メッセージがキーワードで始まらず、チケット ID 成果物またはキーワードを含む場合、Mail Eater によって自動的にこのキーワードが適用されます。
text_api.cfgの[OPTIONS]セクションの以下のエントリを使用して、DESCRIPTIONキーワードが更新でどのように処理されるかを変更できます。
UPDATE_DESC_IS_LOG
このオプションをYESに設定した場合、この値が使われてログ コメントが作成されます。 このオプションをNOに設定した場合、既存の説明フィールドがこの値で上書きされます。
FROM_EMAILFROM_EMAIL_OVERRIDE
ca_contactレコードの[電子メール アドレス]フィールドに対して照合するのに、電子メール インターフェースによって使用されます。 これはチケットの log_agent としても使用されます。 両方を指定すると、FROM_EMAIL が無視されます。
FROM_EMAIL はメッセージの送信者アドレスで、Mail Eater によって自動的に設定されます。
FROM_PERSID
操作の log_agent を定義するために、コマンド ライン インターフェースによって使用されます(たとえば、ca_contact レコードにユーザ ID がない場合など)。 p パラメータが指定されている場合
、このキーワードは pdm_text_cmd によって自動的に渡されます。
値は、ca_contact レコードの persistent_id に対して照合されます。
FROM_USERID
操作のlog_agentを定義するのに、コマンド ライン インターフェースでのみ使用します。 u パラメータが指定されている場合、このキーワードは
pdm_text_cmd
によって自動的に渡されます。 値は、連絡先のユーザ ID に対して照合されます。
LOG
ログ エントリを作成するのに使用します(リクエスト、変更要求、案件、および連絡先で有効)。 メッセージがキーワードで始まらず、チケット ID 成果物またはキーワード、あるいは DESCRIPTION キーワードのいずれかを含む場合、Mail Eater によって自動的にこのキーワードが適用されます。
PROPERTY
プロパティの値を設定するのに使用します(リクエスト、変更要求、および案件でのみ有効)。 等号記号と値が後ろに続くほかのキーワードとは異なり、PROPERTYキーワードの構文には以下のようにプロパティ ラベルを含める必要があります。
PROPERTY={{property_label}}value
データベースに表示されるとおりに
property_label
を指定する必要があります。
SEARCH
アセットの複数のチケットを更新するクエリで使用するキーワードのリストを指定するために、コマンドライン インターフェースでのみ使用します。 値は、検索で使用するキーワードのリストです。
キーワードの入力規則
キーワードの入力フォーマットには、以下の規則が適用されます。
  • すべてのキーワード(PROPERTY を含む)の前にパーセント(%)記号を付けます。 パーセント記号は列 1 にある必要があります。 最初の空白ではない行の入力の行頭がパーセント記号ではない場合、チケット ID 成果物とキーワードのどちらが検出されたかによって、
    %DESCRIPTION= または %LOG=
    が受信データのプレフィックスとして使用されます。
    %DESCRIPTION
    が設定された場合、最初のキーワードまでのメッセージの内容がチケットの説明としてポストされます。
    %LOG=
    が設定された場合、最初のキーワードまでのメッセージの内容がログ コメントとしてポストされます。
  • キーワード内、パーセント記号とキーワードの間、およびキーワードと等号(=)記号の間にはスペースを使用しないでください。
  • 値を引用符で囲まないでください。等号(=)記号以降のすべてのデータは値とみなされます。
  • キーワードでは大文字と小文字が区別されません。
  • 入力に重複したキーワードが含まれる場合、最後のキーワードが使用されます。重複するキーワードが存在しない場合、キーワード/値ペアを指定する順序は重要ではありません。
  • キーワードの値は、Web インターフェースの対応するフィールドに指定する場合と同様に指定します。 たとえば、アナリストの連絡先タイプを指定するには、データベースにこの値が整数で格納されている場合も、
    %CONTACT_TYPE=Analyst
    を使用します。
    CONTACT_TYPE
    キーワードは
    text_api.cfg
    に定義されていて、格納されている値と一致するように指定した値を変換します。
    値で大文字と小文字が区別されるかどうかは、基になる DBMS によって決まります。
  • 文字列データは、複数行に渡っていてもかまいません。
チケットを更新するための電子メールのフォーマット
チケットを作成または更新するために、電子メール メッセージをフォーマットできます。
チケットを作成または更新するために電子メール メッセージをフォーマットするには、以下のフィールドを使用します。
  • 受信者
    特権ユーザ用に設定された CA SDM の連絡先に割り当てられているメールボックス名を指定します。
  • 送信者
    電子メールを送る人を指定します。 適用されるメールボックス ルールで
    [匿名を許可]
    オプションが指定されていない限り、この人物は、
    ca_contact
    テーブルで定義されている必要があります。
    [送信者]アドレスは通常、ユーザの電子メール プログラム設定の一部であり、通常はメッセージ単位で設定されません。
  • 添付ファイル
    Text API に添付ファイルを送るため、電子メールにドキュメントおよび他のファイルを添付します。
  • 件名
    チケットを作成する場合は特に、メールボックス ルール内のキーワードに一致させます。
  • 本文
    Text API を使用して、電子メールの本文を指定します。 作成または更新するチケットのタイプにより、キーワード
    ISSUE_ID
    REQUEST_ID
    または
    CHANGE_ID
    を指定できます。
電子メール メッセージの開始および終了区切り文字
電子メール インターフェースによっては、メール メッセージの最初または最後に、電子メール インターフェースの誤動作を招く情報(たとえば、MIME エンコーディング)が追加されることがあります。
ご使用の電子メール インターフェースで情報を追加する場合、start-request と end-request という区切り文字を使用できます。
電子メール インターフェースは、start-request より前と end-request より後に入力された情報を無視します。
CA SDM Maileater では、受信するメールで HTML およびリッチ テキスト形式(RTF)の電子メールをサポートするようになりました。
例: start-request および end-request 区切り文字の使用
"start-request" message_body "end-request"
Text API におけるアーチファクトの使用
Text API は、電子メール通知の件名と本文を処理します。 メールボックス ルールを使用すると、Text API が使用するアーチファクトおよび値を識別できます。 たとえば、インシデントに対するルールを Incident:{{object_id}} と定義した場合、Incident:1234 が Text API 用に %INCIDENT_ID=1234 と変換されていることがわかります。 1234 はインシデント用の ref_num です。 アーチファクトは、電子メールにおいて一意で、見つけやすくする必要があるため、アーチファクトを %Incident: {{object_id}}% のように、より特徴的にすることができます。
文字、数字、カンマ、スラッシュ(/)、プラス記号(+)、または等号(=)は、アーチファクトに使用されることがあるため、{{object_id}} キーワードはこれら以外の字に続けます。 このように記述しない場合、アーチファクトに続く文字が値の一部であると誤解されたり、アーチファクトの値に含まれる文字が、アーチファクトに続く文字であると誤解される可能性があります。
Mail Eater を使用して以下を実行できます。
  1. Text API によってサポートされる適切なチケット、または他のオブジェクトにマップする電子メール内のアーチファクト(Incident:1234 など)を検出します。
  2. アーチファクトを Text API トークン(%INCIDENT_ID=1234 など)に変換します。
  3. Mail Eater は、タグ付けされたメッセージを Text API にサブミットします。 Text API は電子メールを処理して、Text API に含まれるテキスト、コマンド、または両方を適切なチケットに適用し、Text API が受信した電子メール メッセージが正常に適用されたかどうかを示す自動応答電子メールを生成します。 実行されたアクションによって、通知電子メール メッセージも、チケットの作成のような特定のイベントを示すために、別々に送信されます。
チケットを更新する通知応答のセットアップ方法
Text API デーモン(pdm_text_nxd)は、コマンド ラインや電子メールのような外部インターフェースからの情報を使用してチケットを作成し更新します。 ユーザ(連絡先)が電子メール通知に返信するとチケットを更新できるように、電子メールで Text API を使用するようセットアップできます。 返信のテキストはログ コメント アクティビティとしてチケットに追加されます。
チケットを更新する通知応答をセットアップするには、以下の手順に従います。
  1. 連絡先が使用する通知方法を、pdm_mail -T
    reply_email_address
    、または pdm_mail -F
    reply_email_address に設定します。
    reply_email_address
    は、メールボックスの受信アドレスを指定します。 連絡先が電子メールの返信をクリックすると、返信しようとしているメッセージの From または Reply-To アドレスが宛先のアドレスに挿入されます。
    -T は Reply-To アドレスを設定します。 -F は From アドレスを設定します。別のアドレスが返信用として指定されていない場合は、このアドレスが使用されます。
    Reply-To アドレスを使用しないか、使用できないメール プログラムもあります。
  2. Text API キーワードを使用して、メールボックス ルールを作成または更新します。
    メールボックス ルール フィルタにおけるユーザ定義のアーチファクトは、以下の Text API キーワードを置換します。
オブジェクト
Text API キーワード
ID
インシデント
%INCIDENT_ID
Ref_num
問題
%PROBLEM_ID
Ref_num
リクエスト
%REQUEST_ID
Ref_num
Chg_ref_num
%CHANGE_ID
Chg_ref_num
案件
%ISSUE_ID
Ref_num
  1. ルールに一致する通知フレーズを作成または更新します。
  2. 通知フレーズを使用するメッセージ テンプレートを作成または更新します。
  3. ステップ 2 で作成したメッセージ テンプレートを以下のように更新し、ステップ 4 で作成または更新したメッセージ テンプレートを指定します。
ユーザが通知を受信し、それに対して応答すると以下のアクションが実行されます。
  1. フィルタ文字列が検出されると、プレースホルダによって示される関連するチケット ID キーワードや値がある場合は、メッセージに追加されます。
  2. 一致するチケット ID アーチファクトが検出されると、対応するチケットが、ログ コメント、新規の説明、またはメッセージ内のテキストに一致するその他の値、キーワード、コマンドのいずれかを使用して更新されます。
  3. 一致するチケット ID アーチファクトが検索されない場合、説明およびメッセージ内のテキスト、キーワード、コマンドに一致する他のパラメータを使用して、チケットが作成されます。
インシデント通知に対する応答のセットアップ方法の例
この例では、インシデント通知に対する応答をセットアップする方法を示します。
インシデント通知に対する応答をセットアップするには、以下の手順に従います。
  1. 以下のフィールドおよび値を使用して、メールボックス ルールを作成します。
    • フィルタ - 本文の内容
    • フィルタ文字列 - %Incident: {{object_id}}%
    • 大文字と小文字を区別しない - はい
    • アクション - オブジェクトの更新
    • アクション オブジェクト - インシデント
  2. 以下のルールを含む通知フレーズを作成します。
    • シンボル - インシデント応答
    • コード - インシデント応答
    • アクティブ - アクティブ
    • 説明 - インシデント/問題/リクエストへの返答に埋め込むコメント
    • フレーズ - @{call_req_id.type.sym} へコメントを追加するには、この電子メールに返信するか、以下の行を(自分で作成した行に)追加してください。
      %Incident:{call_req_id.ref_num}%
      メールボックス ルールの自動応答テキストでは、call_req_id. プレフィックスを省略します。 このプレフィックスは、メールボックス ルールのテキストがすでに含まれているコンテキストを適用します。また、コンテキスト内ですでに動作している場合、このようなコンテキスト変更は有効ではありません。
  3. 以下の通知フレーズを使用するメッセージ テンプレートを作成または更新します。
    • 通知メッセージ本文
      This is a simple notification. @{notification_phrase[IncidentURL1].phrase}
  4. ステップ 1 で作成したメッセージ テンプレートを以下のように更新し、ステップ 3 で作成したメッセージ テンプレートを指定します。
    メッセージ テンプレート -
    メールボックス ルール名
エンド ユーザによるチケットの更新例
エンド ユーザ(John Smith)が電子メール通知に返信し、インシデント チケットを更新する方法の例を以下に示します。
電子メールの本文(Body)か件名(Subject)には、オブジェクト ID が含まれます。 フィルタ文字列内の {{object_id}} プレースホルダは、オブジェクト ID を表します。
  1. 以下の説明を含む通知が John Smith に送信されます。
    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 は、通知に以下のように返信します。
    This is my response...
  3. Mail Eater は、John Smith の電子メールを以下のテキスト バージョンで受信します。
    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. Mail Eater は順番にルールを処理し、%Incident:1234% アーチファクトを検索します。
    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. Mail Eater は、Text API キーワードおよび {{object_id}} 値を %INCIDENT_ID= statement に追加し、{{object_id}} 値が検出された個所にマーカーを付けます。 以下のテキストは、Text API に送信されるデータを示しています。 太字のテキストは、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:-((...))-%
    %INCIDENT_ID=1234
  6. Text API は、Incident 1234 にログ コメントを追加します。
キーワードの変換方法
text_api.cfgに定義されている多くのキーワードには、指定した値をデータベース格納に適した値に変換するための関連するメソッドがあります。 この機能により、基礎的な実装の知識がないユーザでも、Web インターフェースの場合と同じように値を指定できます。
構成ファイルには、ISSUE.PRIORITY や CONTACT.CONTACT_TYPE など、このタイプのキーワード定義の例がいくつかあります。 キーワードの追加定義が必要になった場合(たとえば、データベース スキーマのカスタマイズ時に追加したフィールドへのアクセス権を Text API に付与するなど)、以下のいずれかの事前定義済みメソッドを使用できます。
方法
出力タイプ
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
変換する必要がある値が、これらの定義済みメソッドで対応できない場合は、カスタム メソッドを記述する必要があります。 メソッドは、入力としてSTRING値を取り、出力として値(INTEGER、STRING、またはUUID)を返す必要があります。 値を判断できない(つまり、設定されない)ことを示すのに-1(または"-1")の値を返します。 UUIDの場合は、"(uuid) NULL"を返します。
たとえば、ユーザ ID を ca_contact テーブル参照に変換するメソッドを作成した場合、 Administrator などの入力値がメソッドに渡され、Administrator のユーザ ID に対応した ca_contact テーブル ID がメソッドから返されます。
環境設定ファイルにキーワードを定義する方法により、同じフィールドに複数のキーワード マッピング(指定された値に応じた異なる変換メソッドなど)を定義することができます。 たとえば、担当者にいくつかの異なるキーワード マッピングを指定して、異なる入力値に基づいてどのように値を設定するかを定義することができます。 入力がユーザ ID、姓/名/ミドルネーム、および実際の ca_contact ID(たとえば、793ED69B4E87A545BD8E911834D829FC)の場合、 変換が不要なca_contact IDを除いて、各キーワードは異なる変換メソッドにマップされます。