Garoon ワークフロー REST API を使って承認済みワークフローを kintone に登録しよう
はじめに
2019 年 8 月度定期メンテナンスで、Garoon ワークフローの申請データを取得する REST API が追加されます。
これまで SOAP API のみで実行できた Garoon ワークフローの申請データの取得を REST API でも扱えるようになったので、経理システム等の外部システムとの連携がしやすくなりました。
今回は、外部システム= kintone として、承認された申請データを kintone アプリに登録するサンプルを紹介します。
完成イメージ
kintone カスタマイズを行い、承認済み物品購入ワークフローアプリで次のことを行います。
-
レコード一覧画面の[承認済み申請データを取得]ボタンをクリックすると、承認済みの Garoon の「物品購入申請」ワークフローの申請データをアプリに登録します。
-
レコード詳細画面の[添付ファイルを取得]ボタンをクリックすると、申請データに添付された添付ファイルを kintone へ登録します。
Garoon ワークフローの REST API は、「cybozu.com 共通管理者」または「ワークフローのアプリケーション管理者権限」をもつユーザーのみ実行できます。
データ取得のためのボタンは、権限に応じた表示制御を行っていません。
権限のないユーザーがボタンをクリックすると、エラーメッセージが表示されます。
Garoon / kintone の設定
Garoon ワークフローの設定
ワークフローの申請フォームを作成します。
手順
- 以下のリンクを右クリックし、保存してください。
sample_form.xml - ダウンロードしたサンプルフォームを Garoon 申請フォームに読み込みます。
読み込み方法は、 XMLファイルでの申請フォームの管理をご参考ください。
- 読み込んだ申請フォームの詳細画面を開き、経路情報を設定します。
詳細は、 経路情報の設定をご参考ください。
- 作成した申請フォームをユーザーが使用できるよう、申請フォームを有効にします。
作成した申請フォームの申請フォーム ID はカスタマイズで利用するので、メモしておいてください。
申請フォーム ID は、「申請フォームの詳細」画面の URL のクエリパラメーター fid=xx の xx 部分です。
例:https://YOUR_GAROON_DOMAIN.cybozu.com/g/workflow/system/form_view.csp?cid=-1&fid=66 の場合、申請フォーム ID は 66 です。
申請フォームの項目
サンプルフォームにおける申請フォームの項目は、次のようになっています。
項目名 | 項目タイプ | 項目コード | 備考 |
---|---|---|---|
標題 | 文字列(1行) | subject | 「必須項目にする」をチェックします。 |
■ 1 | 文字列(1行) | goods1_name | 「必須項目にする」をチェックします。 入力欄の前/後の文字:「品名:」を「前に配置」 |
型番1 | 文字列(1行) | goods1_model | 「必須項目にする」をチェックします。 入力欄の前/後の文字:「型番:」を「前に配置」 右隣への配置:配置する |
数量1 | 数値 | goods1_quantity | 「必須項目にする」をチェックします。 入力欄の前/後の文字:「数量:」を「前に配置」 右隣への配置:配置する |
単価1 | 数値 | goods1_unitPrice | 「必須項目にする」をチェックします。 入力欄の前/後の文字:「単価:¥」を「前に配置」 右隣への配置:配置する |
金額1 | 自動計算 | goods1_price | 計算内容:「四則演算」にチェック 「数量1」「×」「単価1」 入力欄の前/後の文字:「金額:¥」を「前に配置」 右隣への配置:配置する |
■ 2 | 文字列(1行) | goods2_name | 入力欄の前/後の文字:「品名:」を「前に配置」 |
型番2 | 文字列(1行) | goods2_model | 入力欄の前/後の文字:「型番:」を「前に配置」 右隣への配置:配置する |
数量2 | 数値 | goods2_quantity | 入力欄の前/後の文字:「数量:」を「前に配置」 右隣への配置:配置する |
単価2 | 数値 | goods2_unitPrice | 入力欄の前/後の文字:「単価:¥」を「前に配置」 右隣への配置:配置する |
金額2 | 自動計算 | goods2_price | 計算内容:「四則演算」にチェック 「数量2」「×」「単価2」 入力欄の前/後の文字:「金額:¥」を「前に配置」 右隣への配置:配置する |
■ 3 | 文字列(1行) | goods3_name | 入力欄の前/後の文字:「品名:」を「前に配置」 |
型番3 | 文字列(1行) | goods3_model | 入力欄の前/後の文字:「型番:」を「前に配置」 右隣への配置:配置する |
数量3 | 数値 | goods3_quantity | 入力欄の前/後の文字:「数量:」を「前に配置」 右隣への配置:配置する |
単価3 | 数値 | goods3_unitPrice | 入力欄の前/後の文字:「単価:¥」を「前に配置」 右隣への配置:配置する |
金額3 | 自動計算 | goods3_price | 計算内容:「四則演算」にチェック 「数量2」「×」「単価2」 入力欄の前/後の文字:「金額:¥」を「前に配置」 右隣への配置:配置する |
合計金額 | 自動計算 | totalPrice | 計算内容:「合計」にチェック 「金額1」「金額2」「金額2」を追加 入力欄の前/後の文字:「¥」を「前に配置」 |
希望納品日 | 日付 | dueDeliveryDate | 表示形式:「日付のみ」にチェック 初期値:「入力時の現在日付にする」にチェック |
添付ファイル | ファイル添付 | attachments | ー |
kintone アプリの作成とカスタマイズの適用
手順1. 「承認済み購入申請データ」アプリの作成
新規にアプリを作成し(参考:
アプリをはじめから作成する
)、次のようにフィールドを追加します。
フィールド名 | フィールドタイプ | フィールドコード/要素ID | 備考 |
---|---|---|---|
ー | スペース | attachBtn | JSカスタマイズで、「添付ファイルを取得する」ボタンを設置します |
申請番号 | 文字列(1行) | requestNumber | 「必須入力」にチェックします。 申請データの「申請番号」に対応します。 |
標題 | 文字列(1行) | subject | 「必須入力」にチェックする 申請データの「標題」に対応します。 |
作成日 | 日時 | createdAt | 「レコード登録時の日時を初期値にする」のチェックを外します。 申請データの「作成日時」に対応します。 |
ステータス | 文字列(1行) | status | 申請データの「ステータス名」に対応します。 |
申請者コード | 文字列(1行) | applicantCode | 申請者の「ログイン名」に対応します。 |
申請者名 | 文字列(1行) | applicantName | 申請者の「表示名」に対応します。 |
商品テーブル | ー | goods | 申請データに入力された ■ 1 〜 ■ 3 の「品名」「型番」「数量」「単価」「金額」を行として追加します。 設定の内容は後述します。 |
合計金額 | 数値 | totalPrice | 申請データの「合計金額」に対応します。 |
希望納品日 | 日付 | dueDeliveryDate | 「レコード登録時の日付を初期値にする」のチェックを外す。 申請データの「希望納品日」に対応します。 |
添付ファイルテーブル | ー | attachments | 設定の内容は後述します。 |
商品テーブルの内容は、次のように設定します。
フィールド名 | フィールドタイプ | フィールドコード | 備考 |
---|---|---|---|
品名 | 文字列(1行) | goodsName | 申請データの「品名」に対応します。 |
型番 | 文字列(1行) | goodsModel | 申請データの「型番」に対応します。 |
数量 | 数値 | goodsQuantity | 申請データの「数量」に対応します。 |
単価 | 数値 | goodsUnitPrice | 申請データの「単価」に対応します。 |
金額 | 数値 | goodsPrice | 申請データの「金額」に対応します。 |
添付ファイルテーブルの内容は、次のように設定します。
フィールド名 | フィールドタイプ | フィールドコード | 備考 |
---|---|---|---|
ファイルID | 文字列(1行) | fileId | 申請データの「添付ファイル」の id に対応します。 |
ファイル名 | 文字列(1行) | fileName | 申請データの「添付ファイル」の name に対応します。 |
Content-Type | 文字列(1行) | fileContentType | 申請データの「添付ファイル」の contentType に対応します。 |
添付ファイル | 添付ファイル | fileAttachment | 申請データの「添付ファイル」のファイルに対応します。 |
手順2. カスタマイズの適用
カスタマイズを適用します。
-
アプリの設定画面を開き、[設定]タブを選択します。
-
カスタマイズ/サービス連携の[JavaScript / CSS でカスタマイズ]を選択します。
-
カスタマイズを設定します。次のように設定します。
項目名 値 PC 用の JavaScript ファイル 以下の順で、リンクまたはファイルを追加してください。 - kintone-ui-component.min.js
- https://js.cybozu.com/jquery/3.4.1/jquery.min.js
- customize.js
詳細は、後述の サンプルコード を参照してください。
PC用のCSSファイル 以下のファイルを追加してください。 - kintone-ui-component.min.css
-
左上の[保存]ボタンをクリックして、カスタマイズを適用します。
kintone UI Component の入手方法
-
https://github.com/kintone-labs/kintone-ui-component/releases
にアクセスします。
- v0.〜で始まる最新バージョンの「Assets」から kintone-kintone-ui-component-0.x.tgz をダウンロードします。
- ダウンロードした tgz ファイルを解凍します。
- 解凍後のフォルダーの package / dist 以下にある kintone-ui-component.min.js と kintone-ui-component.min.css を利用します。
動作確認
- サンプルデータを登録します。Garoon で今回作成した「物品購入申請」ワークフローの申請データを作成し、「承認済み」または「完了」までステータスを進めます。
- ワークフローに対する管理者権限をもつユーザーで、「承認済み購入申請データ」アプリを開きます。
- レコード一覧画面で、[承認済み申請データを取得]ボタンをクリックし、申請データが登録されることを確認します。
- ファイルを添付した申請データのレコードを開き、[添付ファイルを取得]ボタンをクリックし、添付ファイルが登録されることを確認します。
サンプルコード
customize.js
承認済み物品購入ワークフローアプリから、承認済みの Garoon の「物品購入申請」ワークフローの申請データをアプリに登録します。 その後、申請データに添付されている添付ファイルを kintone に登録します。
プログラムの以下の部分を利用環境に合わせて書き換えてください。
- 13 行目の DOMAIN:利用している Garoon 環境のドメイン
- 15 行目の GAROON_FORM_ID: Garoon ワークフローの設定 でメモしておいた申請フォーム ID
|
|
取得する件数が多くなると、申請データのレコードを登録するまでに時間がかかります。
処理が終わるまでは
Spinner
を表示するなど工夫してください。
サンプルコードの解説
今回のサンプルコードのポイントです。
- 60 - 77 行目
Garoon ワークフローの 申請データを取得する API を利用して、申請データを取得します。
申請フォーム ID の指定や申請データのステータスで絞り込みしたいので、URL のクエリパラメーターとして指定します。
|
|
- 143 - 159 行目
申請データに添付されたファイルを取得する API を利用して、申請データのファイルを取得します。
|
|
- 192 - 199 行目
Garoon ワークフローの申請データのファイル取得 API を利用して取得したファイルの内容は、Base64 エンコードされています。
kintone にアップロードできるように Blob 形式に変換します。
|
|
- 201-219 行目
kintone の ファイルをアップロードする API は kintone REST API リクエストを送信する では利用できません。
そのため、ajax を使った HTTP リクエストでアップロードを行います。
|
|
- 286-291 行目、320-330 行目
kintone UI Component のボタンパーツを画面に配置します。ただし、すでにボタンが存在する場合は配置しません。
また、レコード詳細画面の添付ファイルテーブルに行がない場合は、「添付ファイルを取得」ボタンを非活性にしています。
|
|
おわりに
ワークフロー REST API が追加されたことで、Garoon ワークフローの外部システムとの連携を楽に実装できるようになりました。
今回承認経路は扱っていませんが、申請データの取得 API では申請データの承認・閲覧などの経路情報も取得できるので、「誰が承認 or 差し戻したか?」などの情報も連携できます。
なお、この記事では次の API を利用しています。
- Garoon
- kintone
この Tips は、2019 年 8 月版 Garoon および kintone UI Component v0 で動作を確認しています。