2014-05-26

HipChatとJIRAを連携させる

Atlassian HipChat

JIRA上で課題チケットに何らかの変更があった時、それをHipChatの特定のルームに通知することができます。下記に手順を説明します。

下記の手順、JIRAのあるプロジェクトで課題チケットが起票された際に、HipChatに通知を飛ばすようにします。

この設定のために必要なものは

HipChat APIの認証トークン（HipChatグループ管理者のみ発行可能）
JIRAのシステム管理者アカウント
プラグイン HipChat for JIRA (OnDemandを利用の場合は不要）

です。ここではプラグインのインストール手順は省きます。

1. HipChat APIの認証トークンを取得する

1-1. HipChat Group Adminにログイン

Group AdminのメニューにあるAPIをクリックします。パスワードを再度聞かれるので入力してください。

f:id:nyumi:20140526202800p:plain

1-2. トークンの作成

"Create new token"のフォームに下記を入力して"Create"を押します。

Type : Administration (Notificationだと動作しません)
Label : JIRA (* 好きな名前を付けます）

f:id:nyumi:20140526203752p:plain

16進数の認証トークンが発行されました。これをJIRAに設定します。

2 JIRAにHipChatの認証トークンを設定する

2-2. JIRAにシステム管理者でログイン

ログイン後、右のツールチップアイコンから、"システム"を選択します。

システム画面のサイドバーにHipChat設定、のメニューがあるのでそれをクリックします。

f:id:nyumi:20140526205341p:plain

2-2. 認証トークンを設定

先ほどHipChatの管理画面で作成したトークンを入力します。

API Base URL : https://api.hipchat.com （デフォルトのまま）
管理トークン: 先ほどHipChat管理画面作成したトークンを入力

"Save"を押します。上部に"HipChat 設定の保存に成功しました。"とメッセージがでればOKです。

3 JIRAのワークフローにHipChat通知のアクションを設定する

JIRAからHipChatへの通知を実際に設定するためには、JIRAの各プロジェクトに設定されているワークフロー内の遷移（トランジション）でPost function（事後操作）の追加、という機能を利用します。つまり、課題に対して、状態（ステータス）の遷移が発生したときに発生するアクションを登録します。

3-1. JIRAにシステム管理者でログイン

ログイン後、右のツールチップアイコンから、"課題"を選択します。

システム画面のサイドバーにワークフロー、のメニューがあるのでそれをクリックします。

3-2. ワークフローの確認

各プロジェクトで有効になっているワークフローの一覧が出てきますので、設定したいプロジェクトのワークフローの右にある操作-編集をクリックします。

"ダイアグラム"タブを押して、ワークフローの状態と遷移を確認します。

下記のダイアグラムで、チケットの起票が"Create"という遷移（トランジション）で発生しているのがわかります。

f:id:nyumi:20140526212718p:plain

3-3. 事後操作（post function) の追加

ワークフローダイアグラムで、矢印上に示される遷移（トランジション）名（ここではCreate）をクリックすると右に編集パネルがでてくるので"事後操作"リンクをクリックします。

"Create"トランジションに登録されている事後動作の一覧が出てきますので"Add post function"のリンクをクリックしてHipChatへの通知を登録します。

f:id:nyumi:20140526213612p:plain

さらに次の画面で下記を設定します。

フィルタリング条件（JQL）- 既存のフィルタが選べないのが残念
通知先ルーム - 複数選択可
各ルームにあるクライアントの通知をトリガーするかどうか - する場合はクライアント側に通知（ポップアップや音などクライアント側の設定によります）が入ります

f:id:nyumi:20140526220502p:plain

追加すると、"事後操作"一覧画面に戻ります。

3-4.事後操作の並び替え

さらにここでもう一仕事。今登録した事後操作（HipChat通知）を一番下に移動させる必要があります。しないでおくと、HipChat側で下記のように注意されます。課題キーやリンクも正しく表示されません。

悪い例：

The post function should be configured after the issue is actually created within the transition for project テストプロジェクト (YUMITEST) so that this notification could show the issue key. Please contact your JIRA administrator to fix this.

事後操作一覧で、HipChatの通知を上から一番下に動かします。↓をちくちくクリックします。

f:id:nyumi:20140526215516p:plain

とりあえず、これで課題チケット作成の際にHipChatで通知を飛ばすためのワークフロー上の設定は完了です。

3-5. ワークフローの公開

ただ今編集したワークフローはドラフトの状態なので、設定を有効にするためにはこれを公開する必要があります。

f:id:nyumi:20140526215723p:plain

"ドラフトの公開"を押します。これで反映されたはず。

3. 動作確認

JIRA上でさっきのワークフローを公開したプロジェクトで課題を作成します

f:id:nyumi:20140526231355p:plain

届きました。パチパチ。リンクをクリックすると、JIRAの課題に飛びます。

f:id:nyumi:20140526231913p:plain

設定手順は以上になります。ちょっとワークフローの事後操作の更新あたりが面倒ですね・・・ f:id:nyumi:20140510095448p:plain

2014-05-11

HipChat APIのWebhooksについて

Atlassian HipChat

f:id:nyumi:20140510094154p:plain

Webhook（Webフック）とは

Atlassian社のHipChatは仕事上のインスタントメッセージのやり取りに特化したアプリケーションサービスです。

JIRA, Confluence, GitHubからHipChatへの情報プッシュによる連携はよく知られていることですが、HipChatのWeb APIを利用すると逆も出来ます。つまり、HipChatのルーム内でイベント（入退室、メッセージ、通知、トピック変更）があったとき、それを外部のサービスに知らせることが出来る、ということです。

これHipChatのAPIのWebhooksという機能を利用します。WebhookはHipChat APIのversion 2（現在ベータ版）で対応しています。HipChatのAPIはシンプルなREST 形式で認証用のトークンがあれば簡単に利用できます。

Webfookの利用手順としては下記の3ステップになります。このページではそれぞれのステップについて詳しく説明します。

アカウント設定画面で認証用のトークンを発行
Webhookを作成する
外部のサービスで情報を受け取る

1.の認証用トークンを既に持っている場合は1.の手順は不要です。API version 1でのグループ管理者によるトークンとは別のものなのでご注意を。

1. 認証用のトークンを発行

まずはHipChatのウェブサイトにいき、ログインしてアカウント設定画面にいきます。右上のAccount Settingから進みます。

f:id:nyumi:20140511113551p:plain

アカウント設定画面の左メニューでAPI accessをクリック、再度パスワードを聞かれるので入力します。

f:id:nyumi:20140511113935p:plain

まだトークンを作成していない場合は赤いCreate tokenボタンが表示されますのでそれをクリックします。

f:id:nyumi:20140511114658p:plain

トークンができました、パチパチ。このトークンを利用するとそのユーザーの権限でAPIによるHipChatの操作ができてしまいますので、取り扱いには注意してください。

f:id:nyumi:20140511115205p:plain

2. Webhookを作成する

HipChatのイベントが発生した際に外部サービスに通知するためのWebhookをAPIで作成します。現在HipChatでWebhookに対応しているイベントは指定したルームに対して

誰かが入室したとき (room_enter)
誰かが退室したとき (room_exit)
メッセージが送られた時 (room_mesasge)
告知が送られてきた時 (room_notification)
トピックが変更された時 (room_topic_change)

です。HipChatで上記のイベントが発生したときに、どういったデータ（Json形式）が送られてくるのかマニュアルに記載はありますが、実際にテストをして内容を見てみたいと思います。今回はメッセージのイベント送信のWebhookを作成します。

Webhookの作成にはCreate webhookというIFを利用します。リクエスト内容（ボディ）は以下になります。

requset.json

{
"url"          : "http://www.myservice.com/api/testhook.php",
"event"     : "room_message",
"name"    : "test_message_webhook"
}
url : HipChatでイベントが発生したとき（ここではメッセージがルームに送られた時）にWebhookがそのデータをPOSTする先のURL
pattern : メッセージがこの正規表現にマッチした際のみ、データを送信（指定しなければすべて送る）
event : HipChatのイベント検知のタイプ
name : このWebhookの名前、任意でつけます

またリクエストの際にAPIのURLに下記のパラメータを追加します。

ルーム名またはルームID - イベントを検知する対象ルームをパスパラメータとしてURL中に指定します。ここではテスト用のHipChatルーム、testroomを利用します。
認証用トークン(auth_token) - 1のて順で発行した認証用のトークン。クエリストリングとして追加します。

実際にcurlコマンドでWebhookを作成してみます。

＄curl https://api.hipchat.com/v2/room/testroom/webhook?auth_token=UR67***認証用トークン***** -X "Post" -H "Content-Type: application/json" -d @request.json
 {"id": 31792, "links": {"self": "https://api.hipchat.com/v2/room/testroom/webhook/31792"}}

作成されたWebhookのidとそのWebhookの情報取得のためのAPIのURL(Get Webhook)が返ってきました。成功です。

3. 外部のサービスで情報を受け取る

実際に先ほど作成したWebhookがどういったデータを外部のサービス（先ほどjsonの中で指定したURL）に渡しているのか見てみましょう。

先ほど指定したURLに下記のような簡単なスクリプトを設置します。外部から受け取ったリクエストの内容（ヘッダとボディ）をエラーログに出力する簡単なPHP スクリプトです。

http://www.myservice.com/api/testhook.php

<?php
    $log_file = "/var/tmp/request.log";
    $headers = getallheaders();
    while (list ($header, $value) = each ($headers)) {
            error_log("$header: $value\n", 3, $log_file);
    }
    error_log("\n", 3, $log_file);
    $str = file_get_contents('php://input');
    error_log($str, 3, $log_file);
    error_log("\n", 3, $log_file);
?>

HipChatでWebhookを作成したルームでメッセージを送信してみます。

f:id:nyumi:20140511130138p:plain

すると、上記のtesthook.phpにHipChatからアクセスがいきます。データ届きましたね！

request.log

Host: www.myservice.com
User-Agent: HipChat.com
Content-Length: 630
Content-Type: application/json
connection: close

{
    "event": "room_message",
    "item": {
        "message": {
            "date": "2014-05-11T04:00:00+00:00",
            "from": {
                "id": 751596,
                "links": {
                    "self": "https://api.hipchat.com/v2/user/751596"
                },
                "mention_name": "YumiNakajima",
                "name": "Yumi Nakajima"
            },
            "id": "c9e9dde3-bef7-4600-969d-c7d7e8e88fb5",
            "mentions": [],
            "message": "HipChatでメッセージを送りました"
        },
        "room": {
            "id": 559679,
            "links": {
                "self": "https://api.hipchat.com/v2/room/559679",
                "webhooks": "https://api.hipchat.com/v2/room/559679/webhook"
            },
            "name": "testroom"
        }
    },
    "oauth_client_id": "8add0238-4c72-4995-9bf1-7a91455f7de6",
    "webhook_id": 31792
}

上記のようにHipChatで送信されたメッセージや、送信者、ルーム名が返されます。添付ファイルがある場合は、添付ファイルのURL、メンションがあればメンション名も入ります。

ちなみにApacheのアクセスログはこんな感じ

54.224.228.247 - - [11/May/2014:00:00:09 -0400] "POST /api/mvhook.php HTTP/1.0" 200 6 "-" "HipChat.com"

終わりに

HipChatでメッセージなどのイベント内容が他サービスに送れて何ができるの？と思いましたが、下記のようなことをすると面白いかもしれません

HipChat上でメンションを入れたメッセージで、他人にタスク（Google Task, Asanaなど）をアサインする。例：

@TaoYamada このタスクお願いします

HipChat上でサーバやサービスのオペレーションを実行する（対象ルームには適切なアクセス権限が必要かもしれません）：例

@ServiceServer01 deploy → ServiceServer01でデプロイ開始@ServiceServer01 monitor → 監視を開始、または監視結果を表示

Automate the Web - Zapierがこの機能をつかって、HipChatでのイベントから各種サービスへの連携を実現していますね。まだHipChat API version 2はベータ版ということですがいろいろ試してみると面白いと思います f:id:nyumi:20140510095448p:plain

2014-05-09

HipChat コマンド集

Atlassian HipChat

f:id:nyumi:20140510094154p:plain

Atlassian社のHipChatは仕事上のインスタントメッセージのやり取りに特化したアプリケーションサービスです。

クライアントは英語版しかありませんが、至極シンプルなので誰でも簡単につかいこなせます。メッセージはもちろん日本語で送受信できます。

今日は HipChat クライアントで使える便利なコマンド & TIPS を紹介します。本家のマニュアルはこちら。

コマンド

コマンドは下記のようにスラッシュ付きでメッセージ入力欄に直接入力すればOKです。

f:id:nyumi:20150424202754p:plain

コマンドは

ルームに対する操作
自分の状態に対する操作
メッセージに対する操作

の３つの種類があります。

1. ルームに対する動作

コマンド		動作
/join <room name>		指定した既存のルームに入ります (ネィティブクライアントでは動作しません)
/part		現在のルームから退出します
/topic <new topic>		トピックを変更します

2. 自分の状態に対する操作

自分の状態を変更し、他のメンバーにコミュニケーション可能かどうか伝えます。HipChatには 4つの状態 (Available - 連絡可, Away - 離席中, Do not disturb - 取り込み中, Unavailable - 連絡不可) があり、Unavailable 以外はコマンドで変更できます。引数の<message>の指定がない場合はデフォルトの状態メッセージ（Available/Away/Do not disturb）になります。

自分や相手の状態と状態メッセージは、左のPEOPLE欄・ルームのメンバー一覧・プライベートチャットの相手の名前の下に表示されます。

コマンド		動作
/available <message>		自分の状態をAvailable (連絡可, )にします。メッセージを指定するとそれを状態名として表示します。
/away <message>		自分の状態をAway (離席中,)にします。メッセージを指定するとそれを状態名として表示します。
/dnd <message>		自分の状態をDo not disturb (応答不可, )にします。メッセージを指定するとそれを状態名として表示します。

オフラインになると、Unavailable ( f:id:nyumi:20150424211655p:plain )の状態になります。

f:id:nyumi:20150424211833p:plain

3. メッセージに対する操作

コマンドの真価が発揮されるのは下記のメッセージのフォーマッティング操作でしょう。

コマンド	動作
/code <message>	メッセージをコードシンタックスハイライトで出力します。
/quote <message>	メッセージ等幅フォントで表示します。
/clear	現在のルームの会話履歴をクリアします。ログ自体は消えないのでご安心を。
/me (または/em） <message>	灰色のテキストで自分の状況を表現します。名前＋メッセージで表示されます。ルーム入退出時のお知らせメッセージと似ています。
s/置換対象の言葉/置換後の言葉	直前のタイポ（打ち間違い）を訂正します。最初にマッチしたもの１回のみの置換です。ただし、1分以内にしないといけません。
#<16進のカラー表記>	16進数のウェブカラーの見本を表示します。

終わりに

HipChatのコマンドですが、コマンドでタイポをすると恥ずかしいので（そのままメッセージに出てしまうので）自分はルーム操作や状態操作のコマンドについてはあまり使っていません。

f:id:nyumi:20140510095448p:plain

Monospace

in Yokohama

HipChatとJIRAを連携させる

1. HipChat APIの認証トークンを取得する

1-1. HipChat Group Adminにログイン

1-2. トークンの作成

2 JIRAにHipChatの認証トークンを設定する

2-2. JIRAにシステム管理者でログイン

2-2. 認証トークンを設定

3 JIRAのワークフローにHipChat通知のアクションを設定する

3-1. JIRAにシステム管理者でログイン

3-2. ワークフローの確認

3-3. 事後操作（post function) の追加

3-4.事後操作の並び替え

3-5. ワークフローの公開

3. 動作確認

HipChat APIのWebhooksについて

Webhook（Webフック）とは

1. 認証用のトークンを発行

2. Webhookを作成する

3. 外部のサービスで情報を受け取る

終わりに

HipChat コマンド集

コマンド

1. ルームに対する動作

2. 自分の状態に対する操作

3. メッセージに対する操作

終わりに