【2019年9月リリース】業務アプリに外部連携用の開発者設定を追加

業務アプリに、外部連携用の開発者設定をドラフト版公開しました！

• 各業務アプリ毎にWebhookの設定ができます 

Webhookとは、業務アプリの文書が更新された時に外部アプリケーションへ文書の更新情報を通知できる仕組みです。

Webhookについて

業務アプリの文書の更新(登録,更新,削除)のタイミングで外部システムが公開するHTTPエンドポイントに、更新イベントをHTTPのPOSTメソッドで通知するメカニズム

Webhookで送信されるデータ

Webhookの呼び出しは、以下のようにHTTP/1.1で行われます。

POST {URLに含まれるパス} HTTP/1.1
Host: {URLのホストパート}
Content-Type: application/json; charset=utf-8

{
    "appId":"業務アプリID",
    "recordId":文書番号となる32ビット符号付整数値,
    "recordStatus": "更新後の文書のステータスコード",
    "event": "CREATE" or "UPDATE" or "DELETE",
    "regAccount":{
        "loginId":"操作したユーザID",
        "name":"操作したユーザの名前",
        "type":操作したユーザの種類
    },
    "updAccount":{
        "loginId":"操作したユーザID",
        "name":"操作したユーザの名前",
        "type":操作したユーザの種類
    },
    "contentUrl": "文書URL",
    "regDate": "登録日時(UTC)",
    "updDate": "更新日時(UTC)",
    "sessionOwner":{
　　　　"loginId":"操作した店舗ID",
　　　　"name":"操作した店舗の名前",
　　　　"type":操作した店舗の種類
    },
    "sessionSubOwner":{
        "loginId":"スタッフ機能を利用している場合のスタッフID",
　　　　"name":"スタッフの名前",
　　　　"type":スタッフの種類
    },
    "data":{
        "10001": "部品の値のCSVと同じ文字列表現",
        "10002": ... 
    },
    "token": "リクエストの発行元を検証するためのトークン"
}

Webhookで発行されたtokenの検証

セッション操作APIで、Webhookを生成した発行元が正しい業務アプリであるか確認することができます。

• 呼び出しURL

https://your-domain/h2/STRSessionManipurator.do

• リクエスト

パラメータ名	意味	必須	制約
func	動作モード	○	validateWebhookTokenを指定します。
key	WebAPIキー	○	セッション操作APIが利用可能なWebAPIキーを指定します。
token	トークン	○	Webhookで発行されたTokenを指定します。

 

Webhookを設定してみよう

• 業務の管理権限及びシステムの管理権限が必要となります
• 注意 :  事前にWebhook通知を受けるエンドポイント、プログラムをご準備ください
  • 関係の無いURLを登録すると、文書情報が漏れる可能性がございます。

1. [ 業務の管理 ] > [ 業務アプリの設定 ] > 任意の業務アプリの[ 編集 ] を開く

2. [ 開発者向け機能 ] > [ Webhookの設定 ] > [ Webhookを追加 ]ボタンを押下

3. [ ペイロードURL ] を設定する

   項目	説明
   ペイロードURL	外部アプリケーションへ通知するURLを設定する

4. [ 保存する ]ボタンを 押下し、設定を保存する

　 以上で、Webhookの設定は完了です。

Webhookで通知してみよう

• Webhookを設定した業務アプリで実施してください

文書を登録する

全ての業務アプリで文書登録時にWebhook通知が送られます。

文書を更新する

業務アプリ雛形「クレーム管理」を元に作成した業務アプリで、文書更新時にWebhook通知が送られます。

文書のステータスを変更する

全ての業務アプリで文書のステータス変更時にWebhook通知が送られます。 

• 例として、業務アプリ雛形「レポート登録」を元にした業務アプリでは下記の様な動作を行います。
  

  操作	更新前のステータス	更新後のステータス	Webhook通知
  一時保存する	一時保存	一時保存	無し
  登録する	一時保存	店長承認待ち	有り
  登録する	一時保存	確認中(受付)	有り
  承認する	店長承認待ち	確認中(受付)	有り
  店舗に返す	確認中(受付)	一時保存(要確認)	有り
  確認済み	確認中(受付)	確認済み	有り
  確認中に戻す	確認済	確認中(受付)	有り

 文書を削除する

全ての業務アプリで文書更新時にWebhook通知が送られます。

Webhookの履歴を確認しよう

• システムの管理権限が必要となります（業務の管理権限）

1. [ システムの管理 ] > [ 連携アプリの設定 ] > [ Webhookの履歴 ] を開く

　下記の情報を、Webhookの履歴画面から確認することができます。

• Webhook通知された時間
• 更新があった業務アプリ
• Webbhook通知のステータスコード
• Webhook通知されたペイロードURL

 

また、右端にある"</>"を押下すると、HTTP request/response情報が確認できます。