OTRSの一般インターフェースは、OTRSをウェブサービスによって他のシステムと通信させる複合レイヤーのフレームワークから成ります。このコミュニケーションは双方向になりえます。:
供給者としてのOTRS: OTRSは、外部システムからのリクエストを聞き、要求されたアクションを行なって、情報を処理し、リクエストに答えるサーバーとして働きます。
依頼者としてのOTRS: OTRSは、遠隔のシステムにリクエストを送り、レスポンスを待って、クライアント情報収集者として働きます。
一般インターフェースは柔軟で、かつカスタマイズするのが簡単になるようにレイヤー・モデルに基づいた構造である。
レイヤーは1セットのファイルである。それは、一般インターフェースがウェブサービスの異なる部分をどのように行なうかコントロールします。正しい構成を使用すると、一つは新規モジュールを作成せずに、異なる外部システムのために異なるウェブサービスを構成することができます。
注記
遠隔のシステムが一般インターフェースの現在の束ねられたモジュールを支援しない場合、その特定のウェブサービスのために特別のモジュールを開発している必要がある。
OTRS出荷時に提供される一般インタフェース・モジュールのリストは今後更新され増加していくでしょう。
図:グラフィカル・インターフェース・レイヤー
このレイヤーは遠隔のシステムとの正確なコミュニケーションに責任を持ちます。依頼を受け取り、供給者として働く場合、レスポンスを生成し、依頼者として働く場合、依頼および受信応答を生成します。
供給者コミュニケーションは「nphgenericinterface.pl」と呼ばれる新規ウェブサーバによって取り扱われます。
Requester communication could be initiated during an event triggered by a Generic Interface module or any other OTRS module. This event is catched by the event handler and depending on the configuration the event will be processed directly by the requester object or delegated to the Scheduler (a separated daemon designed to process tasks asynchronously).
このレイヤーは、データ構造とOTRSそしてリモートシステムの間の翻訳について責任を持ちます(データ内部およびデータ外部層)。通常遠隔のシステムはOTRS(異なる値およびそれらの値の名前を含む)とは異なっているデータ構造を持っています。そしてここに受信情報を「OTRSが理解する何かへと変更するレイヤーの重要性が存在します。また、逆にデータ辞書を使うリモートシステムへの送信情報についてもです。
例:「優先度」(OTRS)は遠隔のシステムでの「Prio」と呼ばれるかもしれません。また、それは、値「1 低」(OTRS)が遠隔のシステムについての「情報」にマッピングされるべきです。
コントローラーは同様のオペレーションあるいは依頼アクション(Invokers)の集合です。例えば、チケット・コントローラーはいくつかの標準チケット・オペレーションを含んでいます。カスタム・コントローラは実装可能です。例えば「チケット外部会社」コントローラーは標準チケット・コントローラーと同様の機能を含みます。しかし異なるデータ・インターフェイスまたは機能名（リモート・システム機能名に適応する）または異なるコードを完成します。
一般インターフェースのための1つのアプリケーションは、同じ種類のもう一つのリモートシステムと話すことだけができるようなリモートシステムと情報を同期できるようになります。この場合、新規コントローラーは開発される必要があります。そして、オペレーションと依頼アクション(Invokers)は、リモートシステムの振る舞いをエミュレートしなければいけません。その振る舞いは、OTRSが提供するインターフェイスがリモートシステムのインターフェイスと同様です。
オペレーションはOTRSの内に行なうことができる単一の行為です。オペレーションにはすべて同じプログラミングインターフェースがあります、それらは1つの特定のパラメタへデータを受け取り、成功ステータス、潜在的なエラーメッセージおよび返るデータを持ったデータ構造を返します。
通常、オペレーションは、コアモジュールを呼び出すために、すでにマップされたデータ（内部）を使います。そしてOTRSでアクション（チケット作成、ユーザー更新、キューの無効か、通知送信）を実行します。オペレーションはアクションを実行するOTRS APIへのフルの権限を持っています。
一般インターフェイスは、供給者としてそして同様に要求者としてアクションを実施するために定義済フローをも待っています。
これらのフローは以下に記述されます。
HTTPリクエスト
OTRSは、HTTPリクエストを受け取りそれをレイヤーに渡します。
供給者モジュールはこれらのアクションを実行しコントロールすることを担当しています。
ネットワーク・トランスポート
ネットワーク・トランスポート・モジュールは、データ・ペイロードをデコードし、オペレーション名とデータのそれ以外の部分とを区別します。
オペレーション名およびオペレーションデータは供給者に返されます。
データ外部
リモートシステムから送信されたデータ（これはモジュールベースのレイヤーではありません）。
マッピング
データは、このオペレーション(入信する依頼データ用マッピング)のためのマッピング構成で指定されるように、外部システム・フォーマットからOTRS内部形式へ変換されます。
既に変換されたデータは、供給者に返されます。
データ内部
変換され、そしてオペレーション(これはモジュールベースのレイヤではありませんん)に渡される準備が整ったデータ。
オペレーション
データを受取り、有効化します。
ユーザ・アクセス・コントロールを行います。
アクションを実行します。
オペレーション
供給者に結果データを返します。
データ内部
オペレーションから返されるデータ。
マッピング
データは、マッピング構成(発信の応答データ用マッピング)で指定されるリモート・システム・フォーマットに変換されます。
既に変換されたデータは、供給者に返されます。
データ外部
返答としてネットワーク・トランスポートに渡されるために変換され、準備されるようなデータ。
ネットワーク・トランスポート
既にリモート・システム・フォーマット済みのデータを受け取ります。
このネットワーク・トランスポートタイプのための有効なレスポンスを構成します。
HTTPレスポンス
応答はウェブサービス・クライアントに返送されます。
エラーの場合には、エラー・レスポンスが、遠隔のシステム(例えばSOAPエラー、HTTPエラーなど)に送られます。
イベント・トリガー・ハンドラ
ウェブサービス構成に基づいて、依頼が同期か非同期かを決定します。
同期
依頼者への直通電話は、新規依頼を作成し、それをレイヤーを通して渡すためにされます。
非同期
OTRSスケジューラのための新規一般インターフェース(依頼者)タスクを作成します。（スケジューラーに依頼の実行を委任することによって、ユーザー体験は非常に改善されるかもしれません。そうでなければ、常に依頼を準備する必要になってしまいます。またリモート実行はそれらの依頼のきっかけとなるOTRSエベントに追加されます。）
その次のサイクルでは、スケジューラ・プロセスは新規タスクを読んで、新規依頼を作成し、それをレイヤーへ渡す依頼者への呼び出しを作成します。
依頼アクション(Invokers)
イベントからデータを受け取ります。
受信データ(もし必要ならば)を有効にします。
データを補足する(もし必要ならば)呼び出しコア・モジュール。
依頼データ構造を返すか、あるいは卒なく依頼を取り消すために依頼者にStop Communication信号を送ってください。
データ内部
依頼アクション(Invokers)(これはモジュールベースのレイヤではありません)から渡されるようなデータ。
マッピング
データは、マッピング構成(発信の応答データ用マッピング)で指定されるリモート・システム・フォーマットに変換されます。
既に変換されたデータは、依頼者に返されます。
データ外部
変換され、遠隔のシステムに送るために準備できたデータ。
ネットワーク・トランスポート
依頼者からリモート・システム表示形式に既に変換されたリモート・オペレーション・フォーマットおよびデータを受け取ります。
ネットワーク・トランスポートの有効な依頼を構成します。
遠隔のシステムにリクエストを送り、応答を待ちます。
ネットワーク・トランスポート
レスポンスを受け取り、データ・ペイロードをでコードします。
依頼者にデータを返します。
データ外部
リモート・システムから受け取るデータ。
マッピング
データは、このオペレーション(入信応答データ用マッピング)のためのマッピング構成の中で指定される外部システム・フォーマットからOTRS内部形式へと変換されます。
既に変換されたデータは、依頼者に返されます。
データ内部
既に変形済データは、依頼者に返されます。
依頼アクション(Invokers)
返信データを受け取る
特に各依頼アクション(Invokers)(もしあればエラーハンドリングを含む)に必要とされていたデータを処理します。
依頼者に依頼アクション(Invokers)結果およびデータを返します。
イベント・ハンドラあるいはスケジューラ
依頼者からのデータを受け取ります。スケジューラの場合、このデータは、タスクを直ぐにまたは将来に再スケジュールするような情報を含んでいるかもしれません。
Webサービスは、私たちの場合、OTRSとリモート・システムとの間のコミュニケーション方法です。
Webサービスの核心はその構成(Configuraiton)です。尚、ここで、以下が定義されます。ウェブサービスがどのアクションを内部に行なうことができるか(オペレーション)、どんなアクションが、OTRS要求がリモート・システムを実行できるか（依頼アクション(Invokers)）どのようにデータが他からひとつのシステムへ変換されるか（Mapping）そしてどのプロトコル上でコミュニケーションが発生するのはどのプロトコル上か（Transport）。
The Generic Interface is the framework that makes it possible to create Web Services for OTRS in a predefined way, using already made building blocks that are independent from each other and interchangeable.
ウェブサービスGUI(GUI)は、ユーザー・フレンドリーで便利なインターフェースで複雑なウェブサービス構成を構築することを可能にするツールです。それは次のものに許可します:
ウェブサービスを作成および削除します。
既存のウェブサービスのためのエクスポート/インポート構成(YAMLファイルフォーマット中の)。
ビュー、ウェブサービスで既存のウェブサービス用の復旧と旧構成のエクスポート
デバッガ画面中の各ウェブサービスのすべてのコミュニケーション・ログを追跡してください。
管理者インターフェース(システム管理ボックス中の)のメイン画面中の「ウェブサービス」リンクは、ウェブサービス概要画面に向かいます。そこでは、ウェブサービス構成を管理することができます。新規ウェブサービスを加えるか、あるいはこの画面からの既存の構成を変更することができます。
ウェブサービス構成画面は、その上部に案内のために「パンくずリスト」を持っています。この案内はウェブサービス構成のどの部分に自分がいるのかを正確に知るために便利です。 また、その案内は、さらにユーザが構成プロセスの任意の部分にいつでも(このアクションは変更を保存しないでしょう)ジャンプすることを可能にします。
注記
新規ウェブサービスを作るために、「ウェブサービスの追加」ボタンを押し、必須情報を提供します。
図:ウェブサービス概要
この部分中の必要な唯一のフィールドは、システムにおいて独特である必要があり、空にしておくことができないウェブサービス「名」です。さらに、他のフィールドは「デバッグのしきい値」および「有効性」のように構成に必要であるが、これらのフィールドはすでに各リスト用にデフォルト値でたくさんあります。
「デバッグのしきい値」のためのデフォルト値は「デバッグ」します。このように構成された時、全てのコミュニケーションログがデータベースで登録されます。続いて起こるデバック閾値はより制限的で システム内の１セットより低く古いコミュニケーションログを破棄します。
デバッグ閾値レベル（下から上へ）
Debug
Info
通知
Error
さらに、「供給者としてのOTRS」および「依頼者としてのOTRS」のためのネットワーク・トランスポート・プロトコルを定義することは可能です。
データベースの中で新規ウェブサービスを登録するために「保存」ボタンをクリックするか、またはこのオペレーションを廃棄するために「キャンセル」をクリックして下さい。ウェブサービス概要画面に戻ります。
YAMLフォーマットの中に既にウェブサービス構成ファイルを持っていれば、画面の左側の「インポート・ウェブサービス」ボタンをクリックすることができます。ウェブサービスのインポートについてより詳細には、次のセクション「ウェブサービス変更」をチェックしてください。
注記
ウェブサービスに、より多くの詳細を変更・追加するためには、ウェブサービス概要画面中のウェブサービス名をクリックしてください。
図:ウェブサービスの追加
この画面においては、ウェブサービスのすべての部分を扱う機能の完全セットを持っています。アクション・カラムの左側に いくつかのボタンがあります。それによりウェブサービス上で全ての可能なアクションを実行できます。
Clone web service.(クローン・ウェブサービス)
Export web service.(エクスポート・ウェブサービス)
Import web service.(インポート・ウェブサービス)
Configuration History.(構成履歴)
Delete web service.(ウェブサービスの削除)
Debugger.(デバッガ)
注記
「構成履歴」および「デバッガ」はあなたを異なる画面ヘ導きます。
ウェブサービスのクローンを作るために、「クローンのウェブサービス」ボタンをクリックする必要があります。ダイアログは、あなたが使用できるデフォルト名またはウェブサービス用の新規名を表示します。
注記
ウェブサービスの名前が間違いなくシステム内にユニークであることを忘れないでください。
ウェブサービスのクローンを作成するために「クローン」ボタンをクリックして下さい。またはダイアログを閉じるために「キャンセル」をクリックして下さい。
図:ウェブサービスのエクスポート
「エクスポート ウェブサービス」ボタンは、YAMLファイルの中への現在のウェブサービスの構成をダンプし、それをダウンロードし、ファイルシステム上にそれを格納する機会を与えます。ウェブサービスを統合したければこれは特に有用です。（ひとつのサーバからもうひとつのサーバへ。例えばテスト環境から生産システムへ）
警告
ウェブサービス構成中の格納されたパスワードはすべて、プレインテキスト・フォーマットでエクスポートされます。
「エクスポート・ウェブサービス」をクリックする直後、ちょうどウェブページ上のファイルダウンロードリンクでクリックする時のようにブラウザの保存ダイアログが現れます。
注記
各オペレーティング・システム上のブラウザにはそれぞれそれ自身の保存ダイアログ画面およびスタイルがあります。ブラウザとその構成によってはダイアログが示されないことはありえます。また、ファイルはデフォルト・ディレクトリにあなたのファイルシステム上に保存されます。必要な場合はより特殊な指示があるかブラウザ・ドキュメンテーションをチェックしてください。
図:ウェブサービスのエクスポート
有効なウェブサービス構成YAMLファイルは、インポート・ウェブサービス機能を使用するように要求されます。「インポート・ウェブサービス」ボタンをクリックし、構成ファイルを探してブラウズし、入力ボックス中の完全なパスを提供してください。
ファイルから新規ウェブサービスを作るために「インポート」ボタンをクリックするか、あるいはダイアログを閉じるために「キャンセルしてください。」
注記
ウェブサービス名は、構成ファイル名から得られます。(例えば、ファイル名がMyWebservice.ymlならば、結果として生じるウェブサービスはMyWebserviceと命名されます。)ウェブサービスが、あなたがインポートしたいウェブサービスと同じ名前でシステムで登録されれば、システムは、あなたにインポートウェブサービスの名前を変更させるためにウェブサービス変更画面に導くでしょう。
図：ウェブサービスのインポート
ウェブサービス構成へのすべての変更はウェブサービス履歴(ジャーナルとしての)に新規エントリーを作ります。ウェブサービス履歴画面は、ウェブサービスのためのすべての構成バージョンのリストを表示します。「構成履歴の一覧」の中の列(バージョン)はそれぞれ、ウェブサービス履歴に一度の修正を表わします。
それが特定の日付/時刻であれば、全体の構成を示すには行のうちの1つをクリックしてください。構成はこの画面の「履歴詳細」セクションの中で示されるでしょう。ここでは、選択されたウェブサービス構成バージョンをエクスポートすることも、あるいは現在のウェブサービス構成へそのバージョンを回復することもできます。
「エクスポート・ウェブサービス構成」は、ウェブサービス変更画面中の「エクスポート・ウェブサービス」機能として正確に作用します。より詳細には、そのセクションを参照します。
現在のウェブサービス構成への変更が予想通りに働かず、変更を手動で復帰するのが簡単でない場合、「ウェブサービス構成を復帰」ボタンをクリックすることができます。これは、あなたが必ずウェブサービス構成を復帰させるかどうかあなたに尋ねるためにダイアログを開始するでしょう。現在の選択したバージョンで構成を代替するためにこのダイアログで「ウェブサービス構成を復帰」をクリックするか、あるいは、「キャンセル」をクリックしてダイアログを閉じます。
警告
ウェブサービス構成に格納されたどんなパスワードもプレインテキスト・フォーマットでエクスポートされるだろうということを覚えておいてください。
構成を回復する場合は注意してください。このプロセスは不可逆です。
図:ウェブサービス履歴
時としてウェブサービスを完全に削除することが必要な場合があります。これをするために、あなたは「ウェブサービスの削除」ボタンを押すことができます。すると、新規ダイアログが確認を求めて現われるでしょう。
ウェブサービスの削除を確認するために「削除」をクリックするか、またはダイアログを閉じるために「キャンセル」をクリックして下さい。
警告
ウェブサービスの削除はやり直しがききません。ウェブサービスを削除する場合、注意してください。
図：ウェブサービスの削除
デバッガは、ウェブサービスのログを格納します。デバッガ画面では、供給者あるいは依頼者タイプのいずれかのためのウェブサービス・コミュニケーションをすべて追跡することができます。
この画面が示される場合、依頼リストがロードし始めます。リストが完全に満たされた後、その詳細をチェックするために列のうちの1つを選ぶことができます。(列とはコミュニケーション・シーケンスを意味します)これは詳述します、下のボックスに現われます。
画面の右側ではフィルタを使用して、コミュニケーション・リストを狭くすることができます。次のものによってフィルタすることができます：
コミュニケーション・タイプ(供給者または依頼者)
日付:前、及び/または特定の日付の後
リモートのIPアドレス
上記すべての組み合わせ
フィルタ設定がセットされた後、「リフレッシュ」ボタンを押してください。検索基準を満たす新規リストが表示されるはずです。
注記
フィルターの検索基準に依存しますが、新規リストが結果を返さないこともあり得ます。
アクション・カラムの下の画面の左の側では、「ウェブサービスに戻る」を選択するか、あるいは「クリア」ボタンを押すことによりデバッガログを取り除くことができます。ダイアログが開いて、ログの削除を確認されます。アクションを実行するためにダイアログボタンで「クリア」をクリックするか「キャンセル」をクリックしてこのダイアログを閉じます。
「リクエスト詳細」セクションで、選択されたコミュニケーションの詳細をすべて見ることができます。ここでは、完全なフローを追跡し、起こりうるエラーをチェックし、あるいは成功の応答を確認することができます。
図:ウェブサービス・デバッガ
ウェブサービス変更画面に戻って、その右側をレビューしましょう。ここでは、ウェブサービスのためのすべての一般データを修正することができます。一般データとはたとえば名前、記述、デバッグ閾値などです。さらに下には二つ以上の選択があります。それによって、「供給者としてのOTRS」や「依頼者としてのOTRS」といったコミュニケーション・タイプ用の特定のパラメタを変更することができます。
ウェブサービス構成は各レベル上に保存する必要があります。このことは設定が変われば、現在の構成レベルを保存してしまうことで、他へのリンクや構成の深い部分が無効にしてしまうことを意味します。保存後に、無効となったリンクは 再び構成を継続することを可能にすることで、再度可能にできます。
「供給者としてのOTRS」セクションにおいては、ネットワーク・トランスポート・プロトコルをセットするか構成することが可能です。登録されるネットワーク・トランスポート・バックエンドだけがリストに示されます。ネットワーク・トランスポートを構成するためには「構成」ボタンをクリックします。さらに、このボックスの中に新規オペレーションを追加することは可能です。これを行うするためには「オペレーションを追加」リストから可能なオペレーションをひとつ選択します。これはあなたをオペレーション構成画面ヘ導くでしょう。新規オペレーションを保存した後に、それは上記のテーブルにリストされるでしょう。
「依頼者としてのOTRS」は前のものに非常に似ています。しかし、「オペレーション」の代わりに、ここで依頼アクション(Invokers)を加えることができます。
ウェブサービスの構成を保存し継続するために「保存」ボタンをクリックするか、あるいはウェブサービス概要画面に保存し返るために「保存して終了」をクリックするか、現在の構成レベル変更を廃棄し、かつウェブサービス概要画面に返るために「キャンセル」をクリックして下さい。
図:ウェブサービスの変更
注記
他の一般インターフェイスの構成画面のように（ネットワーク・トランスポート、オペレーション、依頼アクション(Invokers)およびマッピング）初期の構成（追加）画面は単にふたつのオプションを表します。「保存」と「キャンセル」です。構成画面に再度戻ると、新規オプション「保存および終了」が現われます。この特徴の振る舞いは下に定義されます。
「保存」はデータベースに現在の構成レベルを格納するでしょう。そして、それは、あなたが行った変更をレビューする、あるいはより深い設定を構成するために、前画面に戻ります。
「保存および終了」はデータベースに現在の構成レベルを格納します。また、それは、構成階層中の前画面(直上部の構成レベルへ)に戻ります。
「キャンセル」は、現在の構成レベルへのどんな構成変更も廃棄し、構成階層中の前画面に戻ります。
In future the list of available network transports will be increased. Currently only "HTTP::SOAP" and "HTTP::REST" transports are available. Each transport has different configuration options to setup and they might use different frontend modules to configure them,
供給者として「HTTP::SOAP」プロトコルを構成することは全く簡単です。設定は二つのみです。:「ネームスペース」および「最大のメッセージ長」。これらのフィールドは必須です。最初のものは、曖昧さを少なくする文脈に、SOAP方法を与えるURIです。また、第2のものは、OTRSが処理する SOAPメッセージのために最大サイズ(バイトで)を指定することができるフィールドです。
Figure: Web service provider network transport HTTP::SOAP.
For "HTTP::REST" the configuration might be a bit more complicated, as it grows dynamically for each configured operation by adding: "Route mapping for Operation '<OperationName>':" and "Valid request methods for Operation '<OperationName>':" settings to the default transport settings "Maximum message length:" and "Send Keep-Alive:"
Route mapping for Operation '<OperationName>':
In this setting a resource path is set. This path must be defined according to the needs of the web service considering that the path in conjunction with the HTTP request method determines the Generic Interface operation to be executed.
Path can contain variables in the form of ':<VariableName>' each path string that fits on the position of the variable name will be added to the request payload using the variable name defined in this setting.
サンプル:
Route mapping: /Resource
Valid requests:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One
Invalid requests:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource?Param1=One
Route mapping: /Resource/:ID
Valid requests:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1?Param1=One
In both cases ID = 1 will be sent to the operation as part of the payload. In the second case also Param1 = One will be added, depending on the HTTP request method other parameters will be added if they come as a JSON string in the request header.
Invalid requests:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One
Route mapping: /Resource/OtherResource/:ID/:Color
Valid requests:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1/Red
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherReosurce/123/Blue?Param1=One
In the first example ID = 1 and Color = Red, while in the second ID = 123 and Color = Blue.
Invalid requests:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1?Param1=One
In the first example the part of the path '/OtherResource' is missing as well as the :Color variable, on the second example just :Color variable is missing.
Valid request methods for Operation '<OperationName>':
The HTTP request methods to determine the operation to use together with the route mapping, possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE.
Totally different operations can share exactly the same mapping path, but the request method must be unique for each operation, in order to determine correctly the operation to use on each request.
Figure: Web service provider network transport HTTP::REST.
The actions that can be performed when you are using OTRS as a provider are called "Operations". Each operation belongs to a controller. Controllers are collections of operations or invokers, normally operations from the same controller need similar settings and share the same configuration dialog. But each operation can have independent configuration dialogs if needed.
Name, Description, Backend, and Mappings are fields that normally appear on every operation, other special fields can appear in non default configuration dialogs to fulfill specific needs of the operation.
通常は、各オペレーションに2つのマッピングする構成セクションがあります。一つは入信データ、もう一つは発信データです。各マッピング指示のために異なるマッピングするタイプ(バックエンド)を選ぶことができます。なぜなら、それらの構成が互いから独立して、さらにオペレーション・バックエンドから独立しているからです。正常で、最も一般的な実行は、両方のケースに（逆の構成を持つ）同じマッピングタイプを使うオペレーションです。完全なマッピング構成は、マッピングタイプに依存して個別の画面の中で行われます。
オペレーション・バックエンドは事前に投入されており編集可能ではありません。ウェブサービス編集画面に対するオペレーションを選択する時、このパラメタを見るでしょう。フィールドは参考に過ぎません。
In the left part of the screen on the action column you have the options: "Go back to web service" (discarding all changes since the last save) and "Delete". If you click on the last one, a dialog will open and ask you if you like to remove the operation. Click on "Delete" button to confirm the removal of the operation and it configuration or "Cancel" to close the delete dialog.
図:ウェブサービス・オペレーション
依頼者用ネットワークトランスポート構成は供給者用の構成に似ています。依頼者の「HTTP::SOAP」ネットワーク・トランスポートのために、セットすることができるフィールドがさらにもっとあります。
必須フィールドの「エンドポイント」および「ネームスペース」とは別に、(エンドポイントとは、リクエストを受け入れるリモート・システム・ウェブサービス・インターフェースのURIのこと)さらに次のように明示することができます:
SOAPメッセージのための符号化(utf-8, latin1, iso-8859-1, cp1250など)
SOAPAction Header: you can use this to send an empty or filled SOAPAction header. Set to "No" and the SOAPAction header on the SOAP message will be an empty string, or set to "Yes" to send the soap action in Namespace#Action format and define the separator (typically "/" for .Net web services and "#" for the rest).
認証: 認証機構をセットするためには、いかなる認証も使わないか、またはリストからひとつを選択するために、「-」をセットします。そうすればフィールド詳細が現れるでしょう。
注記
Currently only the "BasicAuth" (HTTP) authentication mechanism is implemented. You can decide whether or not to use it depending on the Remote System configuration. If used, you must provide the User Name and the Password to access the remote system.
警告
認証用パスワードを供給しそのあとでYAMLファイルをウェブサービスへエクスポートするならば、このパスワードは暴露され、TYAMLファイルの内部のプレインテキスト文字列に書き込まれるでしょう。必要に応じて予防措置を講じてください。
Figure: Web service requester network transport (HTTP::SOAP).
In the case of HTTP::Rest, this configuration also grows dynamically depending on the configured invokers by adding "Controller mapping for Invoker '<InvokerName>':" and "Valid request command for Invoker '<InvokerName>':" for each invoke. Authentication and SSL options are similar to the ones in HTTP::SOAP
ホスト
The host name or IP Address and port of the remote system, if no port is specified, port 80 is used by default.
Controller mapping for Invoker '<InvokerName>':
In this setting a resource path is set. This path must be defined according to the needs of the remote web service and following its definition.
Path can contain variables in the form of ':<VariableName>' for each variable name that matches the current data (to be sent), will be replaced by the corresponding data value. This matched variable names and values will be remove from the current data. Depending on the HTTP request command the remaining data could be sent as a JSON string in the request body or as query parameters within the URI.
サンプル:
For data: Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four.
Controller mapping: /Resource
After Replacements:
/Resource
Remaining Data:
Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four
Controller mapping: /Resource/:Var1
After Replacements:
/Resource/One
Remaining Data:
Var2 = Two, Var3 = Three and Var4 = Four
Controller mapping: /Resource/:Var1?Param1=:Var2&Var3=:Var3
After Replacements:
/Resource/One?Param1=Two&Var3=Three
Remaining Data:
Var4 = Four
Valid request command for Invoker '<InvokerName>':
This determine the HTTP request method to use, possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE. If no command is selected, Default command is used.
デフォルトコマンド
Used as a fall-back for all Invokers with out a defined request command
Figure: Web service provider network transport HTTP::REST.
The actions that can be performed when you are using OTRS as a requester are called "Invokers". Each invoker belongs to a controller (controllers are collections of operations or invokers). Usually invokers from the same controller need similar settings and share the same configuration dialogs. Each invoker can have independent configuration dialogs if needed.
Name, Description, Backend, and Mappings are fields that normally appear on every invoker. Additionally the list of event triggers and other special fields can appear on non default configuration dialogs to fulfill special needs of the invoker.
通常は、各依頼アクション(Invokers)につき2つのマッピング構成セクションがあります。ひとつは入信データでもう一方は発信データです。それらの構成が相互に独立して、さらに依頼アクション(Invokers)バックエンドから独立しているので、各マッピング指示のために異なるマッピングするタイプ(バックエンド)を選ぶことができます。正常で、最も一般的な実行は、依頼アクション(Invokers)が逆の構成で、両方の場合の中で同じマッピングタイプを使用するということです。完全なマッピング構成は個別の画面の中で行われます。それはマッピングタイプに依存します。
依頼アクション(Invokers)バックエンドは事前に投入されており編集可能ではありません。ウェブサービス編集画面に対する依頼アクション(Invokers)を選択する時、このパラメタを見るでしょう。フィールドは参考に過ぎません。
Event triggers are events within OTRS such as "TicketCreate", "ArticleSend", etc. These can act as triggers to execute the invoker. Each invoker needs to have at least one event trigger registered, or the invoker will be useless, because it will never be called. The asynchronous property of the event triggers define if the OTRS process will handle the invoker or if it will be delegated to the OTRS Scheduler.
注記
The OTRS Scheduler is a separate process that executes tasks in the background. Using this the OTRS process itself will not be affected if the Remote System takes a long time to respond, if it is not available or if there are network problems. If you don't use the scheduler using web services can make OTRS slow or non-responsive. Therefore it is highly recommend to use asynchronous event triggers as often as possible.
イベント・トリガーを追加するためには、最初に最初のリストからイベント・ファミリーをつぎに第二のリストからイベント名を選択し、それから非同期プロパティをセットします。（イベントのきっかけが非同期ではないという意味で未検証ならば）プラスのボタンを最後にクリックします。新規イベント・トリガーが作成され、それは依頼アクション(Invokers)「イベント・トリガー」リスト上でリストされます。
To delete an Event trigger, simply locate the event trigger to be deleted in the "Event Triggers" list and click on the trash icon at the end of the row. This will open a dialog that asks you if you are sure to delete the event trigger. Click "Delete" to remove the event trigger from the list, or "Cancel" to close the dialog.
アクション・カラム画面の左部には、以下のオプションがあります:「ウェブサービスに戻る」（最後の保存以来変更をすべて廃棄して）と「削除」です。あなたが最後のものをクリックすれば、ダイアログは出現し、あなたが依頼アクション(Invokers)を削除したいかを尋ねます。確認するために「削除」をクリックすると、依頼アクション(Invokers)とその構成の削除する、あるいは「キャンセル」して削除ダイアログを閉じるかを確認されます。
図:ウェブサービス依頼アクション(Invokers)
There are cases where you need to transform the data from one format to another (map or change data structure), because normally a web service is used to interact with a Remote System, that is highly probable that is not another OTRS system and / or could not understand the OTRS data structures and values. In these cases some or all values have to be changed, and sometimes even the names of the values (keys) or even the complete structure, in order to match with the expected data on the other end. To accomplish this task the Generic Interface Mapping Layer exists.
リモート・システムは自身のデータ構造を持ちます。それは新規マッピングモジュールをおのおののケースに対して作成することができます。（例えば、OTRS出荷時で、SAPソリューションマネージャに用にカスタマイズされたマッピング・モジュールがあります。）しかし、それは必ずしも必要だとは限りません。モジュールMapping::Simpleは、ほとんどのマッピング要求をカバーすべきです。
注記
Mapping::Simpleがウェブサービスのすべてのマッピングする必要をカバーするとは限らない場合、新規マッピングモジュールが作成されるべきです。新規マッピングするモジュールを作成する方法に関してもっと学習するために、OTRS開発マニュアルを調べてください。
このモジュールは、デフォルト値をマッピングさせる機会を与えます。各キーあるいは全体のコミュニケーション・データに見合う値のために。
画面の初めに、あなたがデフォルトルールをセットできる一般的なセクションを見ます。そのルールは全てのマップされていないキーや値に適用します。利用可能な3つのオプションがあり、これらのオプションは下のようにリストされます:
保持（変更しないままにして）：キーや値をとにかく触りません。
無視（キー/値ペアを捨てます):これがキーに適用されれば、それはキーと値を削除します。なぜならキーが削除されると続いてその関連値も削除されるからです。これが値に適用されれば、値だけが削除され、キーは保持されます。この時それは空の値に関連付けられます。
MapTo（デフォルトとして供給されたキーまたは値の使用）：定義されたマップルールのない全てのキーとまたは値は、デフォルトとしてこれを使います。このオプションを選択するとき、新規のテキストフィールドがこのデフォルトをセットするために現れます。
新規キーマップのために「+」ボタンをクリックすると、単一のマッピング構成用の新規ボックスを表示します。必要なだけ多くのキーマッピングを追加することができます。再度「＋」をクリックするだけで新規マッピングボックスが既存のものの下に現れます。このマッピングボックスから、次のようなオプションを持つ単一のキーのためにマップを定義することができます。
正確な値(s):古いキーが正確に一致すれば、古い重要な文字列は新規ものに変更されます。
正規表現: 重要なストリングは正規表現規則に従って代替されます。
新規値マップ「+」ボタンを押すと、値マップのための新規列を表示します。ここではキーマップに関して同じオプションでマップすべき各値(正確な値および正規表現)に関するルールを定義することも可能も可能です。必要なだけ多くのマップする値を追加できます。そしてもしそれらのひとつを削除したければ、単に各マッピング値の列の「-」ボタンをクリックします。
完全なキーマッピングセクション（ボックス）を削除可能ならば、単に削除したいボックスの右上端にある「-」ボタンを押します。
完全なマッピング構成を削除する必要がある場合: 対応するオペレーションか依頼アクション(Invokers)画面に戻って、以前に選択し、その値を「-」にセットするというマッピング指示を捜して、変更を適用するために構成を保存してください。
図:ウェブサービスマッピング
コマンドライン・インタフェース(CLI)はウェブサービスとジョブをする速い方法です。それは、基本操作を行なうために使用できるツールセットから成ります:
YAMLファイルに基づいてウェブサービスを作成、更新、読み込み、リスト、削除します。
フィルタオプションでデバッガログを読み込みます。
注記
ウェブサービスと連動するするためにCLIを使用する必要はありません。管理者インターフェースへ統合された、ウェブサービスのすべての部分と相互作用する画面の完全セットがあります。このマニュアルに含まれたウェブサービスGUIセクションを読んでください。
「WebserviceConfig.pl」は基本的だが、速く、強力です、ウェブサービス構成で働くツールとして開発されました。次のアクションを実行できるようになります:
追加：構成ソースとしてYAMLファイルを使うウェブサービスを作成します。
更新：既存のウェブサービスを変更します。異なるまたは変更されたYAMLファイルを使って構成は変更可能です。
読み込み：画面に表示されたウェブサービスの構成を入手します。
リスト:システムに登録されたですべてのウェブサービスの完全なリストを入手します。
削除:システムからウェブサービスを削除すること。このアクションは取消不能なので利用の際はご注意ください。
警告
ウェブサービスREADオペレーションは、プレインテキストとして画面にすべての構成を表示します。これには格納されたパスワードを含みます。これに注意して、必要とされる予防措置を講じてください!
サンプル : 新規ウェブサービス構成の作成:
shell> OTRS_HOME/bin/otrs.WebserviceConfig.pl -a write -n <webservice_name> -f /path/to/yaml/file
さらに、次のオプションを備えた「otrs.WebserviceConfig.pl」を使用することができます:
-a read -i <webservice_id> - 格納された構成を読むこと。
-a write -n <webservice_name> -f /path/to/yaml/file - 新規ウェブサービスを作ること。
-a write -i <webservice_id> -f /path/to/yaml/file - ウェブサービスを更新すること。
-a list - 利用可能なウェブサービスをリストすること。
-a delete -i <webservice_id> - ウェブサービスを削除すること。
コマンドライン・インタフェースによる別の利用可能なツールは"otrs.GenericInterfaceDebugRead.pl" スクリプトです。それはウェブサービス・デバッガ・ログエントリを検索するインターフェイスです。
サンプル: デバッガ・ログエントリの検索:
shell> bin/otrs.GenericInterfaceDebugRead.pl
オプションのパラメタは"otrs.GenericInterfaceDebugRead.pl"のために使用されます。
-c - コミュニケーションID(md5sumフォーマット)によってフィルタします。
-t - CommunicationType(「プロバイダー」あるいは「依頼者」)によってフィルタします。
-a - 日付(その日、またはある日の後)によってフィルタします。
-b - 日付(その日、またはある日の後)によってフィルタします。
-i - IPアドレス(有効なIPv4かIPv6アドレス)によってフィルタします。
-w - ウェブサービスIDによってフィルタします。
-d - 詳細なコミュニケーション・データを含みます。
サンプル: すべてのパラメタを備えたデバッガ・ログエントリを検索:
shell> ./otrs.GenericInterfaceDebugRead.pl -c a7cc4d9f5c70387a9bfbe1351bc88966 -t Provider -a '2011-07-22 00:00:00' -b '2011-07-26 00:00:00' -i 127.0.0.1 -w 123 -d 1
注記
上記にリストされたフィルタ・オプションの少なくともひとつを含んでいること強くお薦めします、"-d"オプションが選択されていればさらに良いです。 なぜならば多くの情報はデータベースから引き出され画面に表示され、さらに実際より必要以上の多くの情報が遅いレスポンス時間の原因となりえます。
その設計から、ウェブサービスは 単一のOTRSシステムから別のシステム（例えば、テストか開発環境からプロダクション・システムまで）まで ポータブルになるように着想されました。したがって、それはデータベースからウェブサービス構成を抽出し、かつそれを別のものにインポートする、容易な方法を持つために必要でした。このタスクを遂行するために、一般インターフェースはウェブサービス構成基礎としてYAMLファイルを使用します。
なぜYAMLなのでしょう? YAMLは人間が読み書きするのに優しいことを目指したマークアップ言語です(JSONより理解するほうが簡単です)。YAMLは数的タグのようなXMLが持ついくつかの制限を持ちません。それはオープンで標準化されており、全ウェブサービス構成を格納するほどに十分に完全です。
注記
YAMLについてより知りたければ http://www.yaml.org/ をご覧ください。
下記はYAMLフォーマットによるウェブサービス設定ファイル例です:
---
Debugger:
DebugThreshold: debug
Description: This an example of a web service configuration
Provider:
Operation:
CloseIncident:
Description: This is a test operation
MappingInbound: {}
MappingOutbound: {}
RemoteSystemGuid: ''
Type: Test::Test
Test:
Description: This is a test operation
MappingInbound:
Config:
KeyMapDefault:
MapTo: ''
MapType: Keep
KeyMapExact:
Prio: Priority
ValueMap:
Priority:
ValueMapExact:
Critical: 5 Very High
Information: 1 Very Low
Warning: 3 Normal
ValueMapDefault:
MapTo: 3 Normal
MapType: MapTo
Type: Simple
MappingOutbound:
Config:
KeyMapDefault:
MapTo: ''
MapType: Ignore
KeyMapExact:
Priority: Prio
ValueMap:
Prio:
ValueMapExact:
1 Very Low: Information
3 Normal: Warning
5 Very High: Critical
ValueMapDefault:
MapTo: ''
MapType: Ignore
Type: Simple
Type: Test::Test
Transport:
Config:
MaxLength: 10000000
NameSpace: http://www.example.com/actions
Type: HTTP::SOAP
RemoteSystem: remote.system.description.example.com
Requester:
Invoker:
Test:
Description: This is a test invoker
Events:
- Asynchronous: 1
Event: TicketCreate
- Asynchronous: 0
Event: ArticleUpdate
MappingInbound:
Type: Simple
MappingOutbound:
Type: Simple
Type: Test::Test
Transport:
Config:
Authentication:
Password: '*******'
Type: BasicAuth
User: otrs
Encoding: utf-8
Endpoint: http://www.example.com:8080/endpoint
NameSpace: http://www.example.com/actions
SOAPAction: Yes
SOAPActionSeparator: '#'
Type: HTTP::SOAP
Description(摘要):ウェブサービスを記述する短いテキスト。
RemoteSystem（リモート・システム）:リモート・システムの短い摘要。
Debugger(デバッガ）:デバッガ・セッティング用のコンテナ。
Provider(供給者):供給者セッティング用のコンテナ。
Requester(依頼者):依頼者セッティング用のコンテナ。
デバッグ閾値：デバッガ・レベル
可能な値
debug(デバッグ): 全てのログはすべてデータベースに格納されます。
info(情報): 情報、通知およびエラーレベルログはデータベースに格納されます。
notice(通知): 通知、エラーレベルログデータベースに格納されます。
error(エラー): エラーレベルログだけがデータベースに格納されます。
Operation(オペレーション): 各オペレーション設定用コンテナ。
Transport（トランスポート）: ネットワーク・トランスポート用コンテナ。
<OperationName>: オペレーション用のユニークな名前、それ自身のオペレーション設定用コンテナ(基数0..n, しかし重複しない).
このセクションは、他のオペレーションがもっと含んでいるかもしれないタイ「Test::Test」、あるいは異なるセッティング、からのオペレーションに基づきます。
Description（摘要）:オペレーションを記述する短いテキスト。
MappingInbound（マッピング・インバウンド）: 入信依頼データ用マッピング設定用コンテナ。
MappingOutbound（マッピング・アウトバウンド）: 発信応答データ用マッピング用設定コンテナ。
Type（タイプ）: Controller::Operation formatでのオペレーション・バックエンド。
このセクションは、タイプ「Simple」からのマッピングに基づきます。他のマッピングはより多くの異なる設定を含みます。
Config(構成): このマッピング設定用コンテナ。
Type（タイプ）: マッピング・バックエンド。
KeyMapDefault: マップ未設定キーのコンテナ
ValueMapDefault: 全てのマップ未設定の値の設定のコンテナ。
KeyMapExact: 全ての正確なキーマッピング (基数 0 .. 1)。
KeyMapRegEx: 全ての正規表現キーマッピング用コンテナ (基数 0 .. 1)。
ValueMap: 全ての値マッピング用コンテナ (基数 0 .. 1)。
MapTo: 使用される新しい値 (MapTypeがMapToにセットされた場合のみ適用可能)。
MapType: マッピング用規則。
可能な値
Keep（保持）: 変更なく終了。
Ignore（無視）: やめる
MapTo（マップトゥー）: MapTo値を変更
<newkey>: a container for value mappings for this new key （KeyMapExact and KeyMapRegExからの新規キーに依存する基数）
Invoker（依頼アクション）: 各依頼アクション(Invokers)のセッティング用のコンテナ。
Transport(トランスポート): 依頼者ネットワーク・トランスポート設定用コンテナ。
<InvokerName>: 依頼アクション用のユニーク名前。依頼アクションそれ自身の設定用コンテナ。(基数0..n 但し重複なく)
このセクションは、タイプ"Test::Test"からの依頼アクションに基づいています。他の依頼アクションはより多く異なる設定を含んでいるかもしれません。
Description（摘要）: 依頼アクションを記述する短いテキスト
Events（イベント）: イベント・トリガー設定の未命名のリスト用コンテナ
MappingInbound（マッピング・インバウンド）: 入信応答データ用マッピング設定用コンテナ
MappingOutbound（マッピング・アウトバウンド）: 発信依頼データ用マッピング設定用コンテナ
Type（タイプ）: Controller::Invoker フォーマットでの依頼アクションのバックエンド
リスト要素: (基数 0 .. n)
Asynchronous（非同期）: もし依頼アクションの実行がスケジューラに可能な値を委任するならセットします。
可能な値
0: スケジューラで取扱い不能です。
1: スケジューラで取扱い可能です。
Event（イベント）: イベント・。トリガー名。
Possible Values (チケットのイベント用の)
チケット作成
TicketDelete (チケット削除)
TicketTitleUpdate (チケット・タイトル・更新)
TicketUnlockTimeoutUpdate (チケット・アンロック・タイムアウト更新)
TicketQueueUpdate (チケットキュー更新)
TicketTypeUpdate (チケット・タイプ・更新)
TicketServiceUpdate (チケットサービス更新)
TicketSLAUpdate (チケットSLA更新)
TicketCustomerUpdate (チケット顧客更新)
TicketFreeTextUpdate (チケットフリーテキスト更新)
TicketFreeTimeUpdate (チケットフリータイム更新)
TicketPendingTimeUpdate (チケット保留時間更新)
TicketLockUpdate (チケットロック更新)
TicketArchiveFlagUpdate (チケットアーカイブ更新)
TicketStateUpdate (チケット・状態・更新)
TicketOwnerUpdate (チケット所有者更新)
TicketResponsibleUpdate (チケット応答可能更新)
TicketPriorityUpdate (チケット優先権更新)
HistoryAdd (履歴追加)
HistoryDelete (履歴削除)
TicketAccountTime (チケットアカウント時間)
TicketMerge （チケット結合)
TicketSubscribe (チケット・登録)
TicketUnsubscribe (チケット・登録解除)
TicketFlagSet (チケットフラグセット)
TicketFlagDelete (チケットフラグ削除)
TicketSlaveLinkAdd (チケットスレーブリンク追加)
TicketSlaveLinkDelete (チケットスレーブリンク削除)
TicketMasterLinkDelete (チケットマスターリンク削除)
Possible Values (for article events) (可能な値（記事イベントに関する）)
Article Events (記事イベント)
ArticleCreate (記事作成)
ArticleFreeTextUpdate (記事フリーテキスト更新)
ArticleUpdate (記事更新)
ArticleSend (記事送信)
ArticleBounce (記事返答)
ArticleAgentNotification (記事担当者通知)
ArticleCustomerNotification (記事顧客通知)
ArticleAutoResponse (記事自動返信)
ArticleFlagSet (記事フラグセット)
ArticleFlagDelete (記事フラグ削除)
ArticleAgentNotification (記事担当者通知)
ArticleCustomerNotification (記事顧客通知)
このセクションは、依頼者ネットワーク・トランスポートHTTP::SOAPに基づきます。他のトランスポートはより多く異なる設定を含むかもしれません。
Config（構成）: 特定のネットワークトランスポート構成セッティング用のコンテナー。
Type（タイプ）: 依頼者ネットワークトランスポートバックエンド
Authentication(認証): 認証セッティング用のコンテナ
Encoding(エンコーディング): SOAPメッセージ・リクエスト符号化
Endpoint(エンドポイント): OTRSリクエストを受け入れるリモート・サーバ・ウェブサービスのURI
NameSpace(名前空間): すべての依頼アクション(Invokers)にこのウェブサービスが所有しているコンテキストを与えるURI.
SOAPAction(SOAPアクション): SOAPメッセージ(in "<NameSpace> <Separator> <Action>" format).の中の空か満たされたSOAPActionヘッダーを送ること。
可能な値
YES(はい): 埋まったSOAPActionヘッダーを送る。
No(いいえ): 空のSOAPActionヘッダーを送る
SOAPActionSeparator: 記入された SOAPAction ヘッダの <Separator> をセットする。
可能な値
'/': .netウェブサービスのために使用されます。
'#': すべての休息ウェブサービスのために使用されます。
コネクタは、OTRSがウェブサービス供給者あるいは依頼アクションとして働く場合、あるいは、OTRSがウェブサービス依頼者として働く場合、オペレーションとも呼ばれるアクションのセットの核心になります。しかし、さらに、それは特別のマッピングあるいはトランスポートも含むことができます。
1つのコネクタは、オペレーションのみ、依頼アクション(Invokers)のみ、あるいはその両方だけ、であり得ます。コネクタはマッピングやトランスポートのように他のコネクタのパーツを利用することさえ可能です。そのようなことは何もコネクタにとっては特殊なことではなくむしろそれらを実装しようとしている。
言いかえれば、コネクタは単なるコントローラー層に制限されていない。しかし、もし必要ならばそれはデータマッピングまたはネットワークのトランスポート層まで拡張することができます。
一般インターフェースのモジュール設計により、コネクタはプラグ・インと見なすことができます。;これは、コネクタを加えることによって、次のものを使用して、一般インターフェースの能力を拡張することができることを意味します: 使用法：OTRS機能追加、OTRSカスタム・モジュール、サードパーティ・モジュール等。
OTRSのこのバージョンで含まれて、次のコネクタは、使用される準備ができています。
セッション
チケット
このコネクタは他のオペレーションの中で使用することができる有効なSessionIDを作成するのに有能である。
提供：
オペレーション:
セッション作成
SessionCreateは、TicketCreateのような他のコネクタからの他のオペレーションの中で使用される、新規新規有効なSessionIDを作成します。
注記
他のコネクタからの他のオペレーションの中でSessionIDを使用するために、オペレーションはSessionIDによって認証を実装する必要がある。バンドルされたオペレーションの残りはすべて認証方法として有効なSessionIDを受け入れることができます。
可能な属性:
<SessionCreate>
<!--このレベルでは次の２つの必須選択項目があります。-->
<!--Optional:-->
<UserLogin>?</UserLogin>
<!--Optional:-->
<CustomerUserLogin>?</CustomerUserLogin>
<!--Optional:-->
<Password>?</Password>
</SessionCreate>
このコネクタは、チケットとダイアログするために基本機能を供給します。
提供：
オペレーション:
チケット作成
TicketCreate(チケット作成)
TicketGet(チケット取得)
TicketSearch(チケット検索)
TicketCreateは、OTRSにチケットを作成するインターフェースを提供します。チケットは記事を含んでいなければいけないし、いくつか添付を含むことができます。全ての定義された動的フィールドも、TicketCreateオペレーション上でセットすることができます。
可能な属性:
<TicketCreate>
<!--このレベルでは次の３つの必須選択項目があります。-->
<!--Optional:-->
<UserLogin>?</UserLogin>
<!--Optional:-->
<CustomerUserLogin>?</CustomerUserLogin>
<!--Optional:-->
<SessionID>?</SessionID>
<!--Optional:-->
<Password>?</Password>
<Ticket>
<Title>?</Title>
<!--このレベルでは次の２つの必須選択項目があります。-->
<!--Optional:-->
<QueueID>?</QueueID>
<!--Optional:-->
<Queue>?</Queue>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<TypeID>?</TypeID>
<!--Optional:-->
<Type>?</Type>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ServiceID>?</ServiceID>
<!--Optional:-->
<Service>?</Service>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<SLAID>?</SLAID>
<!--Optional:-->
<SLA>?</SLA>
<!--このレベルでは次の3つの必須選択項目があります。-->
<!--Optional:-->
<StateID>?</StateID>
<!--Optional:-->
<State>?</State>
<!--このレベルでは次の２つの必須選択項目があります。-->
<!--Optional:-->
<PriorityID>?</PriorityID>
<!--Optional:-->
<Priority>?</Priority>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<OwnerID>?</OwnerID>
<!--Optional:-->
<Owner>?</Owner>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ResponsibleID>?</ResponsibleID>
<!--Optional:-->
<Responsible>?</Responsible>
<CustomerUser>?</CustomerUser>
<!--Optional:-->
<CustomerID>?</CustomerID>
<!--Optional:-->
<PendingTime>
<Year>?</Year>
<Month>?</Month>
<Day>?</Day>
<Hour>?</Hour>
<Minute>?</Minute>
</PendingTime>
</Ticket>
<Article>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ArticleTypeID>?</ArticleTypeID>
<!--Optional:-->
<ArticleType>?</ArticleType>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<SenderTypeID>?</SenderTypeID>
<!--Optional:-->
<SenderType>?</SenderType>
<!--Optional:-->
<From>?</From>
<Subject>?</Subject>
<Body>?</Body>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ContentType>?</ContentType>
<Charset>?</Charset>
<MimeType>?</MimeType>
<!--Optional:-->
<HistoryType>?</HistoryType>
<!--Optional:-->
<HistoryComment>?</HistoryComment>
<!--Optional:-->
<AutoResponseType>?</AutoResponseType>
<!--Optional:-->
<TimeUnit>?</TimeUnit>
<!--Optional:-->
<NoAgentNotify>?</NoAgentNotify>
<!--０回以上の繰り返し:-->
<ForceNotificationToUserID>?</ForceNotificationToUserID>
<!--０回以上の繰り返し:-->
<ExcludeNotificationToUserID>?</ExcludeNotificationToUserID>
<!--０回以上の繰り返し:-->
<ExcludeMuteNotificationToUserID>?</ExcludeMuteNotificationToUserID>
</Article>
<!--０回以上の繰り返し:-->
<DynamicField>
<Name>?</Name>
<!--1回以上の繰り返し:-->
<Value>?</Value>
</DynamicField>
<!--０回以上の繰り返し:-->
<Attachment>
<Content>cid:61886944659</Content>
<ContentType>?</ContentType>
<Filename>?</Filename>
</Attachment>
</TicketCreate>
チケット更新オペレーションは、既存のチケットからの属性を修正するかあるいは新規記事を追加する能力を追加します。その記事は、チケットと新規記事のための添付と全ての定義済動的フィールドを含みます。
注記
チケット属性を修正する新規記事を作成することは必要ではありません。
可能な属性:
<TicketUpdate>
<!--このレベルでは次の３つの必須選択項目があります。-->
<!--Optional:-->
<UserLogin>?</UserLogin>
<!--Optional:-->
<CustomerUserLogin>?</CustomerUserLogin>
<!--Optional:-->
<SessionID>?</SessionID>
<!--Optional:-->
<Password>?</Password>
<!--このレベルでは次の２つの選択項目があります。-->
<TicketID>?</TicketID>
<TicketNumber>?</TicketNumber>
<!--Optional:-->
<Ticket>
<!--Optional:-->
<Title>?</Title>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<QueueID>?</QueueID>
<!--Optional:-->
<Queue>?</Queue>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<TypeID>?</TypeID>
<!--Optional:-->
<Type>?</Type>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ServiceID>?</ServiceID>
<!--Optional:-->
<Service>?</Service>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<SLAID>?</SLAID>
<!--Optional:-->
<SLA>?</SLA>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<StateID>?</StateID>
<!--Optional:-->
<State>?</State>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<PriorityID>?</PriorityID>
<!--Optional:-->
<Priority>?</Priority>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<OwnerID>?</OwnerID>
<!--Optional:-->
<Owner>?</Owner>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ResponsibleID>?</ResponsibleID>
<!--Optional:-->
<Responsible>?</Responsible>
<!--Optional:-->
<CustomerUser>?</CustomerUser>
<!--Optional:-->
<CustomerID>?</CustomerID>
<!--Optional:-->
<PendingTime>
<Year>?</Year>
<Month>?</Month>
<Day>?</Day>
<Hour>?</Hour>
<Minute>?</Minute>
</PendingTime>
</Ticket>
<!--Optional:-->
<Article>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ArticleTypeID>?</ArticleTypeID>
<!--Optional:-->
<ArticleType>?</ArticleType>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<SenderTypeID>?</SenderTypeID>
<!--Optional:-->
<SenderType>?</SenderType>
<!--Optional:-->
<From>?</From>
<Subject>?</Subject>
<Body>?</Body>
<!--このレベルでは次の２つの選択項目があります。-->
<!--Optional:-->
<ContentType>?</ContentType>
<Charset>?</Charset>
<MimeType>?</MimeType>
<!--Optional:-->
<HistoryType>?</HistoryType>
<!--Optional:-->
<HistoryComment>?</HistoryComment>
<!--Optional:-->
<AutoResponseType>?</AutoResponseType>
<!--Optional:-->
<TimeUnit>?</TimeUnit>
<!--Optional:-->
<NoAgentNotify>?</NoAgentNotify>
<!--Zero or more repetitions:-->
<ForceNotificationToUserID>?</ForceNotificationToUserID>
<!--Zero or more repetitions:-->
<ExcludeNotificationToUserID>?</ExcludeNotificationToUserID>
<!--Zero or more repetitions:-->
<ExcludeMuteNotificationToUserID>?</ExcludeMuteNotificationToUserID>
</Article>
<!--Zero or more repetitions:-->
<DynamicField>
<Name>?</Name>
<!--1 or more repetitions:-->
<Value>?</Value>
</DynamicField>
<!--Zero or more repetitions:-->
<Attachment>
<Content>cid:166861569966</Content>
<ContentType>?</ContentType>
<Filename>?</Filename>
</Attachment>
</TicketUpdate>
このオペレーションは全てのチケットの属性を得るために使用されます。（この属性は、動的フィールド、すべての記事、およびチケットに属する全ての添付を含みます。）
可能な属性:
<TicketGet>
<!--You have a MANDATORY CHOICE of the next 3 items at this level-->
<!--Optional:-->
<UserLogin>?</UserLogin>
<!--Optional:-->
<CustomerUserLogin>?</CustomerUserLogin>
<!--Optional:-->
<SessionID>?</SessionID>
<!--Optional:-->
<Password>?</Password>
<!--1 or more repetitions:-->
<TicketID>?</TicketID>
<!--Optional:-->
<DynamicFields>?</DynamicFields>
<!--Optional:-->
<Extended>?</Extended>
<!--Optional:-->
<AllArticles>?</AllArticles>
<!--Optional:-->
<ArticleSenderType>?</ArticleSenderType>
<!--Optional:-->
<ArticleOrder>?</ArticleOrder>
<!--Optional:-->
<ArticleLimit>?</ArticleLimit>
<!--Optional:-->
<Attachments>?</Attachments>
<!--Optional:-->
<HTMLBodyAsAttachment>?</HTMLBodyAsAttachment>
</TicketGet>
TicketSearchオペレーションは、事前定義された基準に一致するチケットIDのリストを返します。
可能な属性:
<TicketSearch>
<!--You have a MANDATORY CHOICE of the next 3 items at this level-->
<!--Optional:-->
<UserLogin>?</UserLogin>
<!--Optional:-->
<CustomerUserLogin>?</CustomerUserLogin>
<!--Optional:-->
<SessionID>?</SessionID>
<!--Optional:-->
<Password>?</Password>
<!--Optional:-->
<Limit>?</Limit>
<!--Zero or more repetitions:-->
<TicketNumber>?</TicketNumber>
<!--Zero or more repetitions:-->
<Title>?</Title>
<!--Zero or more repetitions:-->
<Queues>?</Queues>
<!--Zero or more repetitions:-->
<QueueIDs>?</QueueIDs>
<!--Optional:-->
<UseSubQueues>?</UseSubQueues>
<!--Zero or more repetitions:-->
<Types>?</Types>
<!--Zero or more repetitions:-->
<TypeIDs>?</TypeIDs>
<!--Zero or more repetitions:-->
<States>?</States>
<!--Zero or more repetitions:-->
<StateIDs>?</StateIDs>
<!--Zero or more repetitions:-->
<StateType>?</StateType>
<!--Zero or more repetitions:-->
<StateTypeIDs>?</StateTypeIDs>
<!--Zero or more repetitions:-->
<Priorities>?</Priorities>
<!--Zero or more repetitions:-->
<PriorityIDs>?</PriorityIDs>
<!--Zero or more repetitions:-->
<Services>?</Services>
<!--Zero or more repetitions:-->
<ServiceIDs>?</ServiceIDs>
<!--Zero or more repetitions:-->
<SLAs>?</SLAs>
<!--Zero or more repetitions:-->
<SLAIDs>?</SLAIDs>
<!--Zero or more repetitions:-->
<Locks>?</Locks>
<!--Zero or more repetitions:-->
<LockIDs>?</LockIDs>
<!--Zero or more repetitions:-->
<OwnerIDs>?</OwnerIDs>
<!--Zero or more repetitions:-->
<ResponsibleIDs>?</ResponsibleIDs>
<!--Zero or more repetitions:-->
<WatchUserIDs>?</WatchUserIDs>
<!--Zero or more repetitions:-->
<CustomerID>?</CustomerID>
<!--Zero or more repetitions:-->
<CustomerUserLogin>?</CustomerUserLogin>
<!--Zero or more repetitions:-->
<CreatedUserIDs>?</CreatedUserIDs>
<!--Zero or more repetitions:-->
<CreatedTypes>?</CreatedTypes>
<!--Zero or more repetitions:-->
<CreatedTypeIDs>?</CreatedTypeIDs>
<!--Zero or more repetitions:-->
<CreatedPriorities>?</CreatedPriorities>
<!--Zero or more repetitions:-->
<CreatedPriorityIDs>?</CreatedPriorityIDs>
<!--Zero or more repetitions:-->
<CreatedStates>?</CreatedStates>
<!--Zero or more repetitions:-->
<CreatedStateIDs>?</CreatedStateIDs>
<!--Zero or more repetitions:-->
<CreatedQueues>?</CreatedQueues>
<!--Zero or more repetitions:-->
<CreatedQueueIDs>?</CreatedQueueIDs>
<!--Zero or more repetitions:-->
<DynamicFields>
<!--You have a MANDATORY CHOICE of the next 6 items at this level-->
<!--Optional:-->
<Equals>?</Equals>
<!--Optional:-->
<Like>?</Like>
<!--Optional:-->
<GreaterThan>?</GreaterThan>
<!--Optional:-->
<GreaterThanEquals>?</GreaterThanEquals>
<!--Optional:-->
<SmallerThan>?</SmallerThan>
<!--Optional:-->
<SmallerThanEquals>?</SmallerThanEquals>
</DynamicFields>
<!--Optional:-->
<Ticketflag>
<!--Optional:-->
<Seen>?</Seen>
</Ticketflag>
<!--Optional:-->
<From>?</From>
<!--Optional:-->
<To>?</To>
<!--Optional:-->
<Cc>?</Cc>
<!--Optional:-->
<Subject>?</Subject>
<!--Optional:-->
<Body>?</Body>
<!--Optional:-->
<FullTextIndex>?</FullTextIndex>
<!--Optional:-->
<ContentSearch>?</ContentSearch>
<!--Optional:-->
<ConditionInline>?</ConditionInline>
<!--Optional:-->
<ArticleCreateTimeOlderMinutes>?</ArticleCreateTimeOlderMinutes>
<!--Optional:-->
<ArticleCreateTimeNewerMinutes>?</ArticleCreateTimeNewerMinutes>
<!--Optional:-->
<ArticleCreateTimeNewerDate>?</ArticleCreateTimeNewerDate>
<!--Optional:-->
<ArticleCreateTimeOlderDate>?</ArticleCreateTimeOlderDate>
<!--Optional:-->
<TicketCreateTimeOlderMinutes>?</TicketCreateTimeOlderMinutes>
<!--Optional:-->
<ATicketCreateTimeNewerMinutes>?</ATicketCreateTimeNewerMinutes>
<!--Optional:-->
<TicketCreateTimeNewerDate>?</TicketCreateTimeNewerDate>
<!--Optional:-->
<TicketCreateTimeOlderDate>?</TicketCreateTimeOlderDate>
<!--Optional:-->
<TicketLastChangeTimeOlderMinutes>?</TicketLastChangeTimeOlderMinutes>
<!--Optional:-->
<TicketLastChangeTimeNewerMinutes>?</TicketLastChangeTimeNewerMinutes>
<!--Optional:-->
<TicketLastChangeTimeNewerDate>?</TicketLastChangeTimeNewerDate>
<!--Optional:-->
<TicketLastChangeTimeOlderDate>?</TicketLastChangeTimeOlderDate>
<!--Optional:-->
<TicketChangeTimeOlderMinutes>?</TicketChangeTimeOlderMinutes>
<!--Optional:-->
<TicketChangeTimeNewerMinutes>?</TicketChangeTimeNewerMinutes>
<!--Optional:-->
<TicketChangeTimeNewerDate>?</TicketChangeTimeNewerDate>
<!--Optional:-->
<TicketChangeTimeOlderDate>?</TicketChangeTimeOlderDate>
<!--Optional:-->
<TicketCloseTimeOlderMinutes>?</TicketCloseTimeOlderMinutes>
<!--Optional:-->
<TicketCloseTimeNewerMinutes>?</TicketCloseTimeNewerMinutes>
<!--Optional:-->
<TicketCloseTimeNewerDate>?</TicketCloseTimeNewerDate>
<!--Optional:-->
<TicketCloseTimeOlderDate>?</TicketCloseTimeOlderDate>
<!--Optional:-->
<TicketPendingTimeOlderMinutes>?</TicketPendingTimeOlderMinutes>
<!--Optional:-->
<TicketPendingTimeNewerMinutes>?</TicketPendingTimeNewerMinutes>
<!--Optional:-->
<TicketPendingTimeNewerDate>?</TicketPendingTimeNewerDate>
<!--Optional:-->
<TicketPendingTimeOlderDate>?</TicketPendingTimeOlderDate>
<!--Optional:-->
<TicketEscalationTimeOlderMinutes>?</TicketEscalationTimeOlderMinutes>
<!--Optional:-->
<TTicketEscalationTimeNewerMinutes>?</TTicketEscalationTimeNewerMinutes>
<!--Optional:-->
<TicketEscalationTimeNewerDate>?</TicketEscalationTimeNewerDate>
<!--Optional:-->
<TicketEscalationTimeOlderDate>?</TicketEscalationTimeOlderDate>
<!--Optional:-->
<ArchiveFlags>?</ArchiveFlags>
<!--Zero or more repetitions:-->
<OrderBy>?</OrderBy>
<!--Zero or more repetitions:-->
<SortBy>?</SortBy>
<!--Zero or more repetitions:-->
<CustomerUserID>?</CustomerUserID>
</TicketSearch>
The following is a basic but complete web service configuration file in YAML format to use all the Ticket Connector operations with the SOAP network transport. In order to use it in OTRS you need to copy the content, save it into a file and call it GenericTicketConnectorSOAP.yml, and import it into OTRS in the Web Services screen in the Admin panel by clicking in the "Add web service" action from the overview screen and then clicking in the "Import web service" action in the add screen.
---
Debugger:
DebugThreshold: debug
TestMode: 0
Description: Ticket Connector SOAP Sample
FrameworkVersion: 3.4.x git
Provider:
Operation:
SessionCreate:
Description: Creates a Session
MappingInbound: {}
MappingOutbound: {}
Type: Session::SessionCreate
TicketCreate:
Description: Creates a Ticket
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketCreate
TicketUpdate:
Description: Updates a Ticket
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketUpdate
TicketGet:
Description: Retrieve Ticket data
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketGet
TicketSearch:
Description: Search for Tickets
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketSearch
Transport:
Config:
MaxLength: 100000000
NameSpace: http://www.otrs.org/TicketConnector/
Type: HTTP::SOAP
RemoteSystem: ''
Requester:
Transport:
Type: ''
Similar example can be done for the REST network transport, REST web services uses HTTP operations such as "POST", "GET", "PUT", "PATCH" etc. This operations in conjunction with a URI path called resource defines a OTRS Generic Interface Operation or Invoker (depending on the communication way).
The following example uses /Session resource for SessionCreate, /Ticket resource for TicketSearch and TicketCreate and resource /Ticket/{TicketID} for TicketGet and TicketUpdate (Where {TicketID} is the actual TicketID value of a ticket e.g. /Ticket/123). In order to use it in OTRS you need to copy the content, save it into a file and call it GenericTicketConnectorREST.yml, and import it into OTRS in the Web Services screen in the Admin panel by clicking in the "Add web service" action from the overview screen and then clicking in the "Import web service" action in the add screen.
---
Debugger:
DebugThreshold: debug
TestMode: '0'
Description: Ticket Connector REST Sample
FrameworkVersion: 3.4.x git
Provider:
Operation:
SessionCreate:
Description: Creates a Session
MappingInbound: {}
MappingOutbound: {}
Type: Session::SessionCreate
TicketCreate:
Description: Creates a Ticket
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketCreate
TicketGet:
Description: Retrieves Ticket data
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketGet
TicketSearch:
Description: Search for Tickets
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketSearch
TicketUpdate:
Description: Updates a Ticket
MappingInbound: {}
MappingOutbound: {}
Type: Ticket::TicketUpdate
Transport:
Config:
KeepAlive: ''
MaxLength: '100000000'
RouteOperationMapping:
SessionCreate:
RequestMethod:
- POST
Route: /Session
TicketCreate:
RequestMethod:
- POST
Route: /Ticket
TicketGet:
RequestMethod:
- GET
Route: /Ticket/:TicketID
TicketSearch:
RequestMethod:
- GET
Route: /Ticket
TicketUpdate:
RequestMethod:
- PATCH
Route: /Ticket/:TicketID
Type: HTTP::REST
RemoteSystem: ''
Requester:
Transport:
Type: ''
The following code is a Perl script that can connect to OTRS via the generic interface. In order to perform the operations provided by the Ticket Connector, it uses two Perl CPAN modules SOAP::Lite and Data::Dumper. Please make sure that your environment is capable to use these modules before you try to run the script.
#!/usr/bin/perl -w
# --
# otrs.SOAPRequest.pl - sample to send a SOAP request to OTRS Generic Interface Ticket Connector
# Copyright (C) 2001-2018 OTRS AG, https://otrs.com/
# --
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see https://www.gnu.org/licenses/gpl-3.0.txt.
# --
use strict;
use warnings;
# use ../ as lib location
use File::Basename;
use FindBin qw($RealBin);
use lib dirname($RealBin);
use SOAP::Lite;
use Data::Dumper;
# ---
# Variables to be defined.
# this is the URL for the web service
# the format is
# <HTTP_TYPE>:://<OTRS_FQDN>/nph-genericinterface.pl/Webservice/<WEB_SERVICE_NAME>
# or
# <HTTP_TYPE>:://<OTRS_FQDN>/nph-genericinterface.pl/WebserviceID/<WEB_SERVICE_ID>
my $URL = 'http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnector';
# this name space should match the specified name space in the SOAP transport for the web service.
my $NameSpace = 'http://www.otrs.org/TicketConnector/';
# this is operation to execute, it could be TicketCreate, TicketUpdate, TicketGet, TicketSearch
# or SessionCreate. and they must to be defined in the web service.
my $Operation = 'TicketCreate';
# this variable is used to store all the parameters to be included on a request in XML format. Each
# operation has a determined set of mandatory and non mandatory parameters to work correctly. Please
# check the OTRS Admin Manual in order to get a complete list of parameters.
my $XMLData = '
<UserLogin>some user login</UserLogin>
<Password>some password</Password>
<Ticket>
<Title>some title</Title>
<CustomerUser>some customer user login</CustomerUser>
<Queue>some queue</Queue>
<State>some state</State>
<Priority>some priority</Priority>
</Ticket>
<Article>
<Subject>some subject</Subject>
<Body>some body</Body>
<ContentType>text/plain; charset=utf8</ContentType>
</Article>
';
# ---
# create a SOAP::Lite data structure from the provided XML data structure.
my $SOAPData = SOAP::Data
->type( 'xml' => $XMLData );
my $SOAPObject = SOAP::Lite
->uri($NameSpace)
->proxy($URL)
->$Operation($SOAPData);
# check for a fault in the soap code.
if ( $SOAPObject->fault ) {
print $SOAPObject->faultcode, " ", $SOAPObject->faultstring, "\n";
}
# otherwise print the results.
else {
# get the XML response part from the SOAP message.
my $XMLResponse = $SOAPObject->context()->transport()->proxy()->http_response()->content();
# deserialize response (convert it into a perl structure).
my $Deserialized = eval {
SOAP::Deserializer->deserialize($XMLResponse);
};
# remove all the headers and other not needed parts of the SOAP message.
my $Body = $Deserialized->body();
# just output relevant data and no the operation name key (like TicketCreateResponse).
for my $ResponseKey ( keys %{$Body} ) {
print Dumper( $Body->{$ResponseKey} );
}
}
The following code is a Perl script that can connect to OTRS via the generic interface. In order to perform the operations provided by the Ticket Connector, it uses three Perl CPAN modules JSON, REST::Client and Data::Dumper. Please make sure that your environment is capable to use these modules before you try to run the script.
#!/usr/bin/perl
# --
# otrs.RESTRequest.pl - sample to send a REST request to OTRS Generic Interface Ticket Connector
# Copyright (C) 2001-2018 OTRS AG, https://otrs.com/
# --
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see https://www.gnu.org/licenses/gpl-3.0.txt.
# --
use strict;
use warnings;
## nofilter(TidyAll::Plugin::OTRS::Perl::Dumper)
# use ../ as lib location
use File::Basename;
use FindBin qw($RealBin);
use lib dirname($RealBin);
use JSON;
use REST::Client;
# ---
# Variables to be defined
# This is the HOST for the web service the format is:
# <HTTP_TYPE>:://<OTRS_FQDN>/nph-genericinterface.pl
my $Host = 'http://localhost/otrs/nph-genericinterface.pl';
my $RestClient = REST::Client->new(
{
host => $Host,
}
);
# This is the Controller and Request the format is:
# /Webservice/<WEB_SERVICE_NAME>/<RESOURCE>/<REQUEST_VALUE>
# or
# /WebserviceID/<WEB_SERVICE_ID>/<RESOURCE>/<REQUEST_VALUE>
# This example will retrieve the Ticket with the TicketID = 1 (<REQUEST_VALUE>)
my $ControllerAndRequest = '/Webservice/GenericTicketConnectorREST/Ticket/1';
my $Params = {
UserLogin => "some user login", # to be filled with valid agent login
Password => "some user password", # to be filled with valid agent password
DynamicFields => 1, # optional, if set to 1,
# ticket dynamic fields included in response
AllArticles => 1, # optional, if set to 1,
# all ticket articles are included in response
# more options to be found in
# /Kernel/GenericInterface/Operation/Ticket/TicketGet.pm's
# Run() subroutine documentation.
};
my @RequestParam;
# As sample web service configuration for TicketGet uses HTTP method GET all other parameters needs
# to be sent as URI query parameters
# ----
# For GET method
my $QueryParams = $RestClient->buildQuery( %{ $Params } );
$ControllerAndRequest .= $QueryParams;
# The @RequestParam array on position 0 holds controller and request
@RequestParam = ($ControllerAndRequest);
$RestClient->GET(@RequestParam);
# ----
# # ----
# # For POST method
# my $JSONParams = encode_json $Params;
# # The @RequestParam array on position 0 holds controller and request
# # on position 1 it holds the JSON data string that gets posted
# @RequestParam = (
# $ControllerAndRequest,
# $JSONParams
# );
# $RestClient->POST(@RequestParam);
# # ----
# If the host isn't reachable, wrong configured or couldn't serve the requested page:
my $ResponseCode = $RestClient->responseCode();
if ( $ResponseCode ne '200' ) {
print "Request failed, response code was: $ResponseCode\n";
exit;
}
# If the request was answered correctly, we receive a JSON string here.
my $ResponseContent = $RestClient->responseContent();
my $Data = decode_json $ResponseContent;
# Just to print out the returned Data structure:
use Data::Dumper;
print "Response was:\n";
print Dumper($Data);
Given the above example on a REST configuration for Generic Ticket Connector we have that:
For Ticket Create: use POST method on /Ticket path.
For Ticket Search: use GET method on /Ticket path.
For Ticket Update: use PATCH method on /Ticket/{TicketID} path (where {TicketID} is a template represented by :TicketID in the transport configuration)
For Ticket Get: use GET method on /Ticket/{TicketID} path (where {TicketID} is a template represented by :TicketID in the transport configuration)
cURL Command:
shell> curl "http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket?UserLogin=agent&Password=123" -H "Content-Type: application/json" -d "{\"Ticket\":{\"Title\":\"REST Create Test\", \"Type\": \"Unclassified\", \"Queue\":\"Raw\",\"State\":\"open\",\"Priority\":\"3 normal\",\"CustomerUser\":\"customer\"},\"Article\":{\"Subject\":\"Rest Create Test\",\"Body\":\"This is only a test\",\"ContentType\":\"text/plain; charset=utf8\"}}" -X POST
Response:
{
"ArticleID":5484,
"TicketNumber":"1001936",
"TicketID":"1686"
}
cURL Command:
curl "http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/1686?UserLogin=agent&Password=123"
Response:
{
"Ticket": [
{
"Age": 777,
"PriorityID": 3,
"ServiceID": "",
"Type": "Unclassified",
"Responsible": "root@localhost",
"StateID": 4,
"ResponsibleID": 1,
"ChangeBy": 2,
"EscalationTime": 0,
"Changed": "2014-06-30 19:08:14",
"OwnerID": 2,
"RealTillTimeNotUsed": 0,
"GroupID": 1,
"Owner": "agent",
"CustomerID": "OTRS",
"TypeID": 1,
"Created": "2014-06-30 19:08:12",
"Priority": "3 normal",
"UntilTime": 0,
"EscalationUpdateTime": 0,
"QueueID": 2,
"Queue": "Raw",
"State": "open",
"Title": "REST Create Test",
"CreateBy": 2,
"TicketID": 1686,
"StateType": "open",
"EscalationResponseTime": 0,
"UnlockTimeout": 0,
"EscalationSolutionTime": 0,
"LockID": 1,
"TicketNumber": "1001936",
"ArchiveFlag": "n",
"Lock": "unlock",
"CreateTimeUnix": 1404173292,
"SLAID": "",
"CustomerUserID": "customer"
}
]
}
cURL Command:
curl "http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/1686?UserLogin=agent&Password=123" -H "Content-Type: application/json" -d "{\"Ticket\":{\"Queues\":\"Postmaster\"}}" -X PATCH
Response:
{
"TicketNumber":"1001936",
"TicketID":"1686"
}