Garoon ワークフロー REST API を使って承認済みワークフローを kintone に登録しよう

Index

• はじめに
• 完成イメージ
• Garoon / kintone の設定
• 動作確認
• サンプルコード
• おわりに

はじめに

2019年8月度定期メンテナンスで、Garoon ワークフローの 申請データを取得する REST API が追加されます。
これまで SOAP API のみで実行できた Garoon ワークフローの申請データの取得を REST API でも扱えるようになったので、経理システム等の外部システムとの連携がしやすくなりました。

今回は、外部システム＝kintone として、承認された申請データを kintone アプリに登録するサンプルを紹介します。

完成イメージ

kintoneカスタマイズを行い、「承認済み物品購入申請情報」アプリで次のことを行います。

• レコード一覧画面の[承認済み申請データを取得]ボタンをクリックすると、承認済みの Garoonの「物品購入申請」ワークフローの申請データをアプリに登録します。
  
• レコード詳細画面の[添付ファイルを取得]ボタンをクリックすると、申請データに添付された添付ファイルを kintone に登録します。
  

※ Garoon ワークフローの REST API は、「cybozu.com共通管理者」または「ワークフローのアプリケーション管理者権限」を持つユーザーのみ実行できます。
データ取得のためのボタンは、権限に応じた表示制御を行っていません。
権限のないユーザーがボタンをクリックすると、エラーメッセージが表示されます。

Garoon / kintone の設定

Garoon ワークフローの設定

ワークフローの申請フォームを作成します。

手順

1. 以下からサンプルフォームをダウンロードしてください。
   sample_form.xml
   ※ リンクを右クリックし、リンク先のファイルを保存してください。
2. ダウンロードしたサンプルフォームをGaroon 申請フォームに読み込みます。
   読み込み方法は、「XMLファイルでの申請フォームの管理」をご参考ください。
3. 読み込んだ申請フォームの詳細画面を開き、経路情報を設定します。
   詳細は、「経路情報の設定」をご参考ください。
4. 作成した申請フォームをユーザーが使用できるよう、申請フォームを有効にします。

※ 作成した申請フォームの申請フォームID はカスタマイズで利用するので、メモしておいてください。
申請フォームIDは、「申請フォームの詳細」画面のURLのクエリパラメータ fid=xx の xx 部分です。
例：https://YOUR_GAROON_DOMAIN.cybozu.com/g/workflow/system/form_view.csp?cid=-1&fid=66 の場合、申請フォームID は 66 です。

申請フォームの項目

サンプルフォームにおける申請フォームの項目は、次のようになっています。

項目名	項目タイプ	項目コード	備考
標題	文字列（１行）	subject	「必須項目にする」をチェックします。
■ 1	文字列（１行）	goods1_name	「必須項目にする」をチェックします。 入力欄の前/後の文字：「品名：」を「前に配置」
型番1	文字列（１行）	goods1_model	「必須項目にする」をチェックします。 入力欄の前/後の文字：「型番：」を「前に配置」 右隣への配置：配置する
数量1	数値	goods1_quantity	「必須項目にする」をチェックします。  入力欄の前/後の文字：「数量：」を「前に配置」 右隣への配置：配置する
単価1	数値	goods1_unitPrice	「必須項目にする」をチェックします。 入力欄の前/後の文字：「単価：¥」を「前に配置」 右隣への配置：配置する
金額1	自動計算	goods1_price	計算内容：「四則演算」にチェック 「数量1」「×」「単価１」 入力欄の前/後の文字：「金額：¥」を「前に配置」 右隣への配置：配置する
■ 2	文字列（１行）	goods2_name	入力欄の前/後の文字：「品名：」を「前に配置」
型番2	文字列（１行）	goods2_model	入力欄の前/後の文字：「型番：」を「前に配置」 右隣への配置：配置する
数量2	数値	goods2_quantity	入力欄の前/後の文字：「数量：」を「前に配置」 右隣への配置：配置する
単価2	数値	goods2_unitPrice	入力欄の前/後の文字：「単価：¥」を「前に配置」 右隣への配置：配置する
金額2	自動計算	goods2_price	計算内容：「四則演算」にチェック 「数量2」「×」「単価2」 入力欄の前/後の文字：「金額：¥」を「前に配置」 右隣への配置：配置する
■ 3	文字列（１行）	goods3_name	入力欄の前/後の文字：「品名：」を「前に配置」
型番3	文字列（１行）	goods3_model	入力欄の前/後の文字：「型番：」を「前に配置」 右隣への配置：配置する
数量3	数値	goods3_quantity	入力欄の前/後の文字：「数量：」を「前に配置」 右隣への配置：配置する
単価3	数値	goods3_unitPrice	入力欄の前/後の文字：「単価：¥」を「前に配置」 右隣への配置：配置する
金額3	自動計算	goods3_price	計算内容：「四則演算」にチェック 「数量2」「×」「単価2」 入力欄の前/後の文字：「金額：¥」を「前に配置」 右隣への配置：配置する
合計金額	自動計算	totalPrice	計算内容：「合計」にチェック 「金額1」「金額2」「金額2」を追加 入力欄の前/後の文字：「¥」を「前に配置」
希望納品日	日付	dueDeliveryDate	表示形式：「日付のみ」にチェック 初期値：「入力時の現在日付にする」にチェック
添付ファイル	ファイル添付	attachments	ー

kintone アプリの作成とカスタマイズの適用

手順1. 「承認済み購入申請データ」アプリの作成

新規にアプリを作成し（参考：アプリをはじめから作成する）、次のようにフィールドを追加します。

フィールド名	フィールドタイプ	フィールドコード/要素ID	備考
ー	スペース	attachBtn	JSカスタマイズで、「添付ファイルを取得する」ボタンを設置します
申請番号	文字列（１行）	requestNumber	「必須入力」にチェックします。 申請データの「申請番号」に対応します。
標題	文字列（１行）	subject	「必須入力」にチェックする 申請データの「標題」に対応します。
作成日	日時	createdAt	「レコード登録時の日時を初期値にする」のチェックを外します。 申請データの「作成日時」に対応します。
ステータス	文字列（１行）	status	申請データの「ステータス名」に対応します。
申請者コード	文字列（１行）	applicantCode	申請者の「ログイン名」に対応します。
申請者名	文字列（１行）	applicantName	申請者の「表示名」に対応します。
商品テーブル	ー	goods	申請データに入力された ■ 1 〜 ■ 3 の「品名」「型番」「数量」「単価」「金額」を行として追加します。 設定の内容は後述します。
合計金額	数値	totalPrice	申請データの「合計金額」に対応します。
希望納品日	日付	dueDeliveryDate	「レコード登録時の日付を初期値にする」のチェックを外す。 申請データの「希望納品日」に対応します。
添付ファイルテーブル	ー	attachments	設定の内容は後述します。

商品テーブルの内容は、次のように設定します。

フィールド名	フィールドタイプ	フィールドコード	備考
品名	文字列（１行）	goodsName	申請データの「品名」に対応します。
型番	文字列（１行）	goodsModel	申請データの「型番」に対応します。
数量	数値	goodsQuantity	申請データの「数量」に対応します。
単価	数値	goodsUnitPrice	申請データの「単価」に対応します。
金額	数値	goodsPrice	申請データの「金額」に対応します。

添付ファイルテーブルの内容は、次のように設定します。

フィールド名	フィールドタイプ	フィールドコード	備考
ファイルID	文字列（１行）	fileId	申請データの「添付ファイル」の id に対応します。
ファイル名	文字列（１行）	fileName	申請データの「添付ファイル」の name に対応します。
Content-Type	文字列（１行）	fileContentType	申請データの「添付ファイル」の contentType に対応します。
添付ファイル	添付ファイル	fileAttachment	申請データの「添付ファイル」のファイルに対応します。

手順2. カスタマイズの適用

カスタマイズを適用します。

1. アプリの設定画面を開き、[設定]タブを選択します。
2. カスタマイズ/サービス連携の [JavaScript / CSSでカスタマイズ]を選択します。
3. カスタマイズの設定を行います。次のように設定します。
   

   項目名	値
   PC用のJavaScriptファイル	以下の順で、リンクまたはファイルを追加してください。 kintone-ui-component.min.js ※ https://js.cybozu.com/jquery/3.4.1/jquery.min.js customize.js 詳細は、後述の「サンプルコード（customize.js）」をご参照ください。
   PC用のCSSファイル	以下のファイルを追加してください。 kintone-ui-component.min.css ※

4. 左上の[保存]ボタンをクリックして、カスタマイズを適用します。

※ kintone UI Component の入手方法

1. https://github.com/kintone-labs/kintone-ui-component/releases にアクセスします。
2. v0.〜で始まる最新バージョンの「Assets」から kintone-kintone-ui-component-0.x.tgz をダウンロードします。
3. ダウンロードした tgz ファイルを解凍します。
4. 解凍後のフォルダー package > dist 以下のkintone-ui-component.min.js と kintone-ui-component.min.css を利用します。

動作確認

1. サンプルデータを登録します。
   Garoon で、今回作成した「物品購入申請」ワークフローの申請データを作成し、「承認済み」または「完了」までステータスを進めます。
2. ワークフローに対する管理者権限を持つユーザーで、「承認済み購入申請データ」アプリを開きます。
3. レコード一覧画面で、[承認済み申請データを取得]ボタンをクリックし、申請データが登録されることを確認します。
4. ファイルを添付した申請データのレコードを開き、[添付ファイルを取得]ボタンをクリックし、添付ファイルが登録されることを確認します。

サンプルコード

customize.js

「承認済み物品購入申請情報」アプリから、承認済みの Garoonの「物品購入申請」ワークフローの申請データをアプリに登録し、申請データに添付されている添付ファイルを kintone に登録します。

※ プログラムの以下の部分を利用環境に合わせて書き換えてください。

• 12行目のDOMAIN：利用している Garoon 環境のドメイン
• 14行目のGAROON_FORM_ID：Garoon ワークフローの設定 でメモしておいた申請フォーム ID

※取得する件数が多くなると、申請データのレコードを登録するまでに時間がかかります。処理が終わるまでは Spinner を表示するなどの工夫を行ってください。

サンプルコードの解説

今回のサンプルコードのポイントです。

• 59-76行目
  Garoon ワークフローの申請データの全件取得 APIを利用して、申請データを取得します。
  申請フォームIDの指定や、申請データのステータスで絞り込みしたいので、URLのクエリパラメータとして指定します。
  
• 142-158行目
  申請データに添付されたファイルの取得 API を利用して、申請データのファイルを取得します。
  
• 191-198行目
  Garoon ワークフローの申請データのファイル取得 API を利用して取得したファイルの内容は、 Base64エンコードされています。
  kintone にアップロードできるように Blob 形式に変換します。
  
• 200-218行目
  kintone の ファイルアップロード API は kintone.api で利用できません。そのため、ajax を使った HTTP リクエストでアップロードを行います。
  
• 285-290行目、319-329行目
  kintone UI Component のボタンパーツを画面に配置します。ただし、すでにボタンが存在する場合は配置しません。
  また、レコード詳細画面の添付ファイルテーブルに行がない場合は、「添付ファイルを取得」ボタンを非活性にしています。
  

おわりに

ワークフローREST API が追加されたことで、Garoon ワークフローの外部システムとの連携を楽に実装できるようになりました。

今回、承認経路は扱っていませんが、申請データの取得 API では 申請データの承認・閲覧などの経路情報も取得できるので、「誰が承認 or 差し戻ししたか？」などの情報も連携できます。

なお、この記事では次の API を利用しています。

• Garoon
  • 申請データの全件取得 API
  • 申請データに添付されたファイルの取得 API
• kintone
  • レコードの一括取得（クエリで条件を指定）
  • レコードの一括登録
  • ファイルのアップロード
  • レコードの更新（1件）

このTipsは、2019年8月版 Garoon および kintone UI Component v0 で確認したものになります。