Slack連携機能（version 2.6以降） ================================= .. contents:: 目次: :depth: 3 概要 ################################# 統合制御サーバーでは、 `Slack `_ のチャンネルにIROHA2のステータス情報を投稿することができる。 これにより、ユーザーはIROHA2が置かれているネットワークの外部からIROHA2のステータスを確認することができるようになる。 .. figure:: images/slack/overview_slack.jpg :scale: 40 :alt: Alternative Text :name: overview_slack Slack連携機能の概略図 主な機能は以下の通りである。 * Slackアプリのトークンの管理 * 実験課題番号に紐づいたSlackチャンネルの作成 * チャンネルへのユーザー登録補助（実際の登録作業はSlackアプリケーションで行う） * 指定したチャンネルへのメッセージおよび画像の投稿 * Slack投稿機能のOn/Off * 投稿内容および周期、モードの設定 Slackのワークスペースには、実験課題毎に専用のprivateチャンネルが作成され、このチャンネルにIROHA2のステータス情報を投稿する。 このチャンネルには装置スタッフおよび実験ユーザーが参加し、Slackアプリケーションから投稿を確認することができる。 Slackにおける準備 ################################# Slack連携機能を使用するまでの大まかな流れは以下の通りである。 1. Slackのワークスペースを作成する 2. Slackアプリを作成し、ワークスペースに追加する 3. 統合制御サーバーにアプリのトークンを登録する 4. 統合制御サーバーで設定を行う Slackのアプリを作成してワークスペースに追加するまでを説明する。 ワークスペースの作成 --------------------------------- ここでは詳細な説明は省略するが、 `公式のヘルプページ `_ などを参考にワークスペースを作成する。 アプリの作成 --------------------------------- SlackアプリはWeb APIを利用してチャンネルを作成したり、メッセージを投稿したりすることができる。 まず、 `slack api `_ にアクセスする。 .. figure:: images/slack/slack_api.jpg :scale: 60 :alt: Alternative Text :name: slack_api slack api のページ **Create an app** からアプリを作成することができる。 既存のアプリが存在しない場合には :numref:`create_an_app` のダイアログが表示される。 .. figure:: images/slack/create_an_app.jpg :scale: 60 :alt: Alternative Text :name: create_an_app アプリ作成ダイアログ :guilabel:`From scratch` を選択する。 .. figure:: images/slack/create_an_app2.jpg :scale: 60 :alt: Alternative Text :name: create_an_app2 アプリ作成ダイアログ（From scratch選択後） :guilabel:`App Name` にアプリ名を入力し、 :guilabel:`Pick a ~` でワークスペースを選択する （ :guilabel:`Pick a ~` に選択肢が表示されない場合には、 :guilabel:`Sign into a different workspace` からワークスペースにログインする必要がある）。 設定後、 :guilabel:`Create App` を選択し、アプリを作成する。 アプリの権限の設定 --------------------------------- 新規作成したアプリは初期状態では何の権限も持たないため、権限を追加する必要がある。 アプリを作成すると（もしくはslack apiの画面で既存のアプリを選択すると）、 :numref:`app_setting` が表示される。 .. figure:: images/slack/app_setting.jpg :scale: 60 :alt: Alternative Text :name: app_setting アプリ設定画面 アプリの権限を追加するには :guilabel:`OAuth & Permissions` を選択する。 .. figure:: images/slack/oauth_permission.jpg :scale: 60 :alt: Alternative Text :name: oauth_permission OAuth & Permissions画面 :guilabel:`Scopes` において、 :guilabel:`Bot Token Scopes` に権限を追加する。 :guilabel:`Add an OAuth Scope` を選択すると権限の一覧が表示されるので、必要な権限をすべて選択する。 必要な権限を :numref:`bot_token_scopes` に示す。 .. figure:: images/slack/bot_scope.jpg :scale: 100 :alt: Alternative Text :name: bot_scope Botの権限の設定 .. csv-table:: 追加する権限 :header-rows: 1 :widths: 30, 70 :name: bot_token_scopes OAuth scope, 説明 channels:manage, Publicチャンネルの管理と作成 channels:read, Publicチャンネルの情報を取得 chat:write, メッセージの投稿 files:write, ファイルのアップロード groups:write, privateチャンネルの作成 groups:read, privateチャンネルの情報を取得 team:read, ワークスペースの情報を取得 users:read, ワークスペースのユーザーの情報を取得 users:read:email, ワークスペースのユーザーのメールアドレスを取得 権限を1つ以上追加すると、 :guilabel:`OAuth & Permissions` の上部（ :numref:`oauth_permission` ）の :guilabel:`OAuth Tokens for Your Workspace` の :guilabel:`Install to Workspace` が有効になるため、これを選択する。 権限の追加を許可するかどうかを確認されるため、これを許可する。 トークンの取得 --------------------------------- 実際にアプリを利用してSlackにメッセージを投稿するにはトークンが必要になる。 アプリの権限の設定後、 :guilabel:`OAuth & Permissions` の上部（ :numref:`oauth_permission` ）の :guilabel:`OAuth Tokens for Your Workspace` にBotのトークンが表示されるようになる。 .. figure:: images/slack/bot_token.jpg :scale: 60 :alt: Alternative Text :name: bot_token Botのトークン このトークンの文字列をコピーしておき、後ほど統合制御サーバーに登録する。 ワークスペースへのアプリの追加 --------------------------------- Slackアプリケーションにおいて、作成したアプリをワークスペースに追加する。 詳細は `公式のヘルプページ `_ を参照のこと。 Slackユーザーの種別 ################################# Slackのユーザーは、ワークスペースのすべてのチャンネルにアクセスできる通常ユーザーと 特定（大抵は1つ）のチャンネルにしかアクセスできないゲストユーザーに分けられる。 装置スタッフは **通常ユーザー** としてワークスペースに招待しておく。 通常ユーザーとしてワークスペースに参加したユーザーは、統合制御サーバーで新しくチャンネルを作成した際に、 自動的にそのチャンネルに追加されるため、実験のたびに手動でチャンネルに追加する手間を省くことができる。 実験ユーザーは **ゲストユーザー** として特定のチャンネルに招待する。 ゲストユーザーは招待された特定のチャンネルにしかアクセスできないため、情報へのアクセスを制限することができる。 統合制御サーバーにおける操作 ################################# 統合制御サーバーにおいて、メニューから :guilabel:`Settings` 画面を開き、 :guilabel:`Slack` タブを選択してSlack連携機能の設定画面を表示する。 .. figure:: images/slack/irhintsrv_slack_setting.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_slack_setting Slack連携機能の設定画面 この設定画面は * 管理者のみがアクセスできる :guilabel:`Slack API Settings` パネル * すべてのユーザーがアクセスできる :guilabel:`Slack Post Settings` パネル で構成される。 :guilabel:`Slack API Settings` パネルでは、トークンの登録やチャンネルの作成、機能のOn/Offの切り替えなどを行う。 :guilabel:`Slack Post Settings` パネルでは、投稿するイベントの種類の選択、投稿周期の設定などを行う。 管理者による設定 ################################# トークンの登録（更新） --------------------------------- :guilabel:`Slack API Settings` パネルの :guilabel:`Token` 入力欄にトークンを入力し、 :guilabel:`Update` ボタンを押下する。 正しくトークンが登録されると、 :guilabel:`Workspace` にワークスペース名が表示されるようになる。 .. figure:: images/slack/irhintsrv_register_token.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_register_token トークンの登録 .. note:: ワークスペース名が表示されない場合、アプリの権限（Scope）の設定が誤っている可能性がある。 トークンが正しくない場合、以降の操作は行うことができない。 装置スタッフの表示 --------------------------------- :guilabel:`Slack API Settings` パネルの :guilabel:`BL member` にワークスペースに参加している装置スタッフの情報を表示することができる。 :guilabel:`Update` ボタンを押下すると装置スタッフの名前とメールアドレスが表として表示される。 .. figure:: images/slack/irhintsrv_bl_member.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_bl_member 装置スタッフの一覧 チャンネルの作成 --------------------------------- :guilabel:`Slack API Settings` パネルの :guilabel:`New Channel Name` においてチャンネルの作成を行うことができる。 .. figure:: images/slack/irhintsrv_channel_settings.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_channel_settings チャンネルの作成と選択 :guilabel:`New Channel Name` の入力欄に新しく追加するチャンネル名を入力する（通常は実験課題番号を入力する）。 装置管理サーバーにおいて連携データベースとの接続を行って実験課題情報を取得している場合、 入力欄に実験課題番号がリストとして表示されるため、そこから選択することもできる（前方検索でリストを絞ることができる）。 必要があれば実験課題番号を修正し、 :guilabel:`Add` ボタンを押下すると、ワークスペースに新しいチャンネルが作成される。 .. note:: Slackのチャンネル名には大文字を使用することができないため、大文字を入力した場合には自動的に小文字に変換される。 チャンネルの選択 --------------------------------- :guilabel:`Slack API Settings` パネルの :guilabel:`Channels` リストにおいてチャンネルの選択を行うことができる。 チャンネルを変更すると、メッセージの投稿先がそのチャンネルに変更される。 リストには統合制御サーバーで作成したチャンネルが含まれており、チャンネルを選択して :guilabel:`Change` ボタンを押下することで設定される。 チャンネルを変更すると、 :guilabel:`Channel Name (Proposal No.)` にそのチャンネル名が表示される。 チャンネルへのユーザーの招待補助機能 --------------------------------- Slackの料金プランによっては、Web APIからゲストユーザーを直接的に追加することができない場合があるため、 各チャンネルへのユーザーの招待および追加は手動で行うこととしている。 そのため、ユーザーの招待を補助する機能として、指定したチャンネルにユーザーの招待を促すメッセージを投稿する機能を作成した。 .. figure:: images/slack/irhintsrv_invite_users.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_invite_users ユーザーの招待補助機能 :guilabel:`Slack API Settings` パネルの :guilabel:`Posting channel for inviting member` においてメッセージの投稿先のチャンネルを設定する。 投稿先のチャンネルは現在選択されているチャンネルがデフォルトだが、任意のチャンネル（#generalなど）を選択することができる。 :guilabel:`Change` ボタンを押下すると招待を促すメッセージの投稿先が変更される。 :guilabel:`Slack API Settings` パネルの :guilabel:`Invite Member` において招待したいユーザーの情報を登録する。 * :guilabel:`Name & E-mail` ユーザーの名前とメールアドレスを入力する。 :guilabel:`＋` ボタンでユーザーを追加、 :guilabel:`－` ボタンでユーザーを削除することができる。 * :guilabel:`Message (optional)` 投稿するメッセージに文言を追加する（任意）。 :guilabel:`Request for invitation` ボタンを押下すると、指定したチャンネルに招待を促すメッセージが投稿される。 .. figure:: images/slack/invite_message.jpg :scale: 60 :alt: Alternative Text :name: invite_message ユーザーの招待を促すメッセージ チャンネルユーザーの表示 --------------------------------- :guilabel:`Slack API Settings` パネルの :guilabel:`Invite Member` にある :guilabel:`Update` ボタンを押下すると、 現在選択されているチャンネルに参加しているユーザーの情報が表として表示される。 .. note:: 招待されたユーザーがいつチャンネルに参加するかは、統合制御サーバーからはわからないので、 :guilabel:`Update` ボタンで情報を更新する必要がある。 Slack連携機能の有効化 --------------------------------- :guilabel:`Slack API Settings` パネルの :guilabel:`Service` ボタンを切り替え、 :guilabel:`Apply` ボタンを押下することで、Slack連携機能のOn/Offを切り替えることができる。 * On Slack連携機能を有効化する。現在選択されているチャンネルにメッセージが投稿される。 * Off Slack連携機能を無効化する。メッセージ投稿が停止する。 .. figure:: images/slack/irhintsrv_service_onoff.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_service_onoff Slack連携機能のOn/Off .. note:: 統合制御サーバーを再起動した場合、意図しないメッセージ投稿を避けるため、Slack連携機能は自動的にOffになる。 投稿の設定 ################################# 投稿に関する設定は管理者だけではなく、すべてのユーザーが行うことができる。 ただし、投稿自体のOn/Offは管理者のみ設定することができる。 イベントの選択 --------------------------------- 投稿するイベントの種類を選択する。選択されたイベントは、そのイベントが起きたタイミングでメッセージが投稿される。 .. figure:: images/slack/irhintsrv_event_setting.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_event_setting 投稿するイベントの選択 投稿したいイベントにチェックを付ける。それぞれのイベントの意味を :numref:`events` に示す。 .. csv-table:: イベントの種類 :header-rows: 1 :widths: 30, 70 :name: events イベント名, 説明 Begin, 測定の開始 End, 測定の終了 Apply, デバイスへのパラメータ送信 Sequence progress, シーケンスの進捗（コマンドの開始や終了など） Error, デバイス、測定、DAQにおけるエラー ページ下部の :guilabel:`Apply` ボタンを押下すると設定が反映される（他の投稿設定の項目と一括で反映できる）。 デバイスの選択 --------------------------------- 選択したデバイスのステータスを投稿することができる。メッセージは指定した周期で投稿される。 :guilabel:`Interval` に投稿する周期（秒）を入力する。 表にはデバイスの一覧が表示される（ :guilabel:`Scan Devices` で更新する必要がある）。 :guilabel:`Post` にチェックを付けると、そのデバイスのステータスが投稿されるようになる。 .. figure:: images/slack/irhintsrv_device_setting.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_device_setting 投稿するデバイスと周期の選択 ページ下部の :guilabel:`Apply` ボタンを押下すると設定が反映される（他の投稿設定の項目と一括で反映できる）。 投稿モードの選択 --------------------------------- 投稿のモードを選択する。それぞれのモードの説明を :numref:`modes` に示す。 .. figure:: images/slack/irhintsrv_mode_setting.jpg :scale: 60 :alt: Alternative Text :name: irhintsrv_mode_setting 投稿モードの選択 .. csv-table:: モードの種類 :header-rows: 1 :widths: 30, 70 :name: modes モード, 説明 Text, ステータス情報を文字列で投稿する Image, ステータス情報を画像で投稿する Both, TextとImageの両方で投稿する ページ下部の :guilabel:`Apply` ボタンを押下すると設定が反映される（他の投稿設定の項目と一括で反映できる）。 Imageモードで画像を投稿する場合、統合制御サーバーを起動している計算機にwkhtmltoimageをインストールする必要がある （下記のコマンドはCentOS7にインストールする場合）。 .. code-block:: bash $ sudo yum install xorg-x11-fonts-75dpi $ sudo yum install xorg-x11-fonts-Type1 $ wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox-0.12.6-1.centos7.x86_64.rpm $ sudo rpm -ivh wkhtmltox-0.12.6-1.centos7.x86_64.rpm