【OTRS】Webサービスを設定してREST APIでチケットを検索・取得できるようにしてみた

#OTRS

植木和樹

2017.03.23

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

こんにちは植木和樹＠上越妙高オフィスです。ひさびさにOTRSネタです。

クラスメソッドではAWSからの通知メールや、各種監視ツールからの通知メールの管理にOTRSを利用しています。

Gmailに届いたメールは、OTRSがPOP3取り込み自動的にチケット化してくれます。取り込む際にPostmaster Filterという機能を使って、特定条件のメールの優先度をあげたり、担当者を振り分けたりすることができます。

またメールサブジェクトに特定の文字列（例えばAWSのケースID番号など）が含まれていた場合には、そのケースIDでチケットをスレッド化（FollowUp）してくれるため、メッセージIDなどが付与されていないメールも散乱せずうまくまとめることができるようになっています。

OTRSのチケット情報はMySQLに格納されています。これまでチケットの検索（たとえば緊急チケットがきた際にChatworkやTwilioで通知する）は、OTRSサーバーのシェルスクリプトから直接mysqlコマンドでSQLを実行して行っていました。ただcrontab + シェルスクリプトだと下記のような問題がありました。

処理がOTRSサーバー上にあり密結合している
シェルスクリプトだと難しい処理がきつい
他のWebサービスとの連携がしんどい
検索はともかく、チケット作成とか更新ができてなかった

OTRSのマニュアルを調べたところWebサービスという仕組みがあり、REST APIを設定できるようなので今回試してみました。

環境

OTRS Free 5.0.11 / 5.0.17

REST APIの設計

今回はまずチケットの検索(Search)と取得(Get)を行ってみたいと思います。また毎回ログインIDとパスワードをパラメーターで渡すのでなく、事前にログインしてセッションIDを取得しておきセッションID指定で認証を通すようにします。

パス	Webサービス名	名前	メソッド	コントローラー	機能
/Ticket/:TicketID	Ticket	Get	GET	Ticket::TicketGet	指定したチケットIDの情報を取得します。
/Ticket/	Ticket	Search	GET	Ticket::TicketSearch	検索条件に該当するチケットIDを返します。
/Session/Login	Session	Login	POST	Session::SessionCreate	ログインしてセッションIDを取得します。

上記のパス構成だとTicketとSessionというWebサービスを2つ、そしてオペレーションを3つ設定していきます。

OTRS RESTインターフェースの設定

OTRSでのWebサービスの設定については公式ドキュメントを参照してください。

Generic Interface

日本語だとアイオーアーキテクトさんのページを参考にさせていただきました。

OTRS のRESTインタフェースを利用する｜アイオーアーキテクト

大まかな設定の流れ

新しいAPIは大まかに下記の流れで設定します。

Webサービスを作成する
操作可能なオペレーションを追加する
パスとオペレーションのMappingを定義する

チケットの検索と取得といったオペレーションは2と3を必要分くりかえして設定します。

1. Webサービスを作成する

OTRSでのWebサービスの設定は管理者ユーザーになって、システム管理 - Webサービスから行なうことができます。

20170323_OTRS_RestAPI_001

20170323_OTRS_RestAPI_002

Webサービスにはサービス名とネットワーク・トランスポート（APIの実装方式：RESTまたはSOAP）を設定します。なお今回はOTRSがAPIの提供者になるのでプロバイダーとしてのOTRSに設定します。

20170323_OTRS_RestAPI_003

設定を保存したら、次にオペレーションを追加します。

2. 操作可能なオペレーションを追加する

Webサービスで利用可能なチケット操作を選択します。

セッションの作成
チケットの作成、更新、検索、取得

の5つのオペレーションを選択することができます。ここではチケットの取得（Ticket::TicketGet)を選択しましょう。

20170323_OTRS_RestAPI_004

オペレーションを選択すると設定画面に移ります。オペレーション名を記入し、データマッピングはSimple（JSON形式）を選んでおきます。

20170323_OTRS_RestAPI_005

設定を保存したら、最後にオペレーションとパスのマッピングを行います。

3. パスとオペレーションのMappingを定義する

マッピング設定は、Webサービス画面のネットワーク・トランスポートの横にある「設定」ボタンから行なうことができます。

20170323_OTRS_RestAPI_006

先程作成した"Get"オペレーションに対するパスマッピングを設定します。設定内容は下記の画像を参考にしてください。

20170323_OTRS_RestAPI_007

これでチケット取得(Get)に対するAPI設定は完了です。

同様にチケット検索(Search)についてもオペレーションを追加すると、下記のような結果になります。

20170323_OTRS_RestAPI_008

セッション作成はSessionという別Webサービスで作成しましょう。

20170323_OTRS_RestAPI_100

Loginオペレーションを定義します。

20170323_OTRS_RestAPI_101

オペレーションの設定は次の通りです。セッション取得時に指定するユーザーIDとパスワードがURLパラメータとして渡されるのはセキュリティ的に良くないのでPOSTのみ受け付けるようにしています。

20170323_OTRS_RestAPI_102

REST APIを試す

localhostからcurlコマンドでREST APIにアクセスしてみましょう。

まずはユーザーIDとパスワードを渡してセッションIDを入手します。下記に示すURLで /otrs/nph-genericinterface.pl/Webservice までは固定パスとなります。その後に"Webサービス名(/Session)" + "マッピング(/Login)"が続いてURLが構成されています。

$ curl -X POST 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Session/Login' -d '{ "UserLogin": "ueki.kazuki", "Password": "password"}'
{"SessionID":"DDEIJ0xGMwYJmxDRVK4H81BTyAE70hAq"}

セッションIDを入手したらチケットを取得してみましょう。Webサービス"Ticket"にチケットID(1)を指定してGETメソッドでアクセスします。

$ curl -sG 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Ticket/1' -d 'SessionID=DDEIJ0xGMwYJmxDRVK4H81BTyAE70hAq' | jq "."
{
  "Ticket": [
    {
      "Age": 53324307,
      "PriorityID": "3",
      "ServiceID": "",
      "Type": "Unclassified",
      "Responsible": "root@localhost",
      "StateID": "1",
      "ResponsibleID": "1",
      "ChangeBy": "1",
      "EscalationTime": "0",
      "OwnerID": "1",
      "Changed": "2017-03-22 09:39:52",
      "RealTillTimeNotUsed": "0",
      "GroupID": "1",
      "Owner": "root@localhost",
      "CustomerID": null,
      "TypeID": 1,
      "Created": "2015-07-15 08:30:30",
      "Priority": "3 normal",
      "UntilTime": 0,
      "EscalationUpdateTime": "0",
      "Queue": "Raw",
      "QueueID": "2",
      "State": "new",
      "Title": "Welcome to OTRS!",
      "CreateBy": "1",
      "TicketID": "1",
      "StateType": "new",
      "UnlockTimeout": "0",
      "EscalationResponseTime": "0",
      "EscalationSolutionTime": "0",
      "LockID": "1",
      "TicketNumber": "2015071510123456",
      "ArchiveFlag": "n",
      "CreateTimeUnix": "1436949030",
      "Lock": "unlock",
      "SLAID": "",
      "CustomerUserID": null
    }
  ]
}

チケット情報が取得できました！それでは最後にチケットを検索してみましょう。

$ curl -sG 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Ticket/' -d 'SessionID=DDEIJ0xGMwYJmxDRVK4H81BTyAE70hAq' -d 'Queue=Raw' -d 'StateType=new' | jq "."
{
  "TicketID": [
    "1"
  ]
}

検索条件にマッチしたチケットIDが取得できました。

まとめ

OTRSのWebサービス機能でREST APIインターフェースを設定する方法をご紹介しました。今回はチケットの検索と取得のみを設定しましたが、同様な方法でチケット作成や更新のオペレーションも追加できます。

OTRSをREST APIで操作できるようになると、外部システムとの連携が実現しやすくなります。たとえばメールをSESで受信してLambdaでフィルターして必要なものだけチケット化したり、メールアドレスを元に顧客情報を紐付けてチケット情報を更新するといった連携もできるようになりそうです。SNSをAPI Gateway+Lambdaで受けてOTRSでチケット化するなんてこともできそうですね。夢が広がります。

チケット管理システムはお問い合わせやアラート受信など運用の要となる部分です。REST APIで色々なシステムと連携させ、自動化・省力化など効率化を進めてみるのはいかがでしょうか？