Questetra BPM Suite の Web API には、ユーザ登録情報やシステム権限を操作できる System Settings API と、プロセスやタスクを操作できる Workflow API の 2 つがあります。今回は bash の curl コマンドを用いて、Workflow API 経由でプロセス（インスタンス）・タスクの一覧をダウンロードする方法を紹介します。Workflow API を利用することで、プロセス・タスクをデータを定期的に自動ダウンロードするスクリプトなどを作成できます。
プロセスのデータをダウンロードする
Questetra BPM Suite の Web UI にはプロセス検索機能がついています。例えばこのように、プロセスの件名を入力することで検索を行うことができます。
この検索結果を Workflow API 経由で取得することができます。例えば、CSV (UTF-16, Excel 互換) 形式でダウンロードした場合、次のような検索結果が API から返ってきます。
"アプリID" "アプリ名" "カテゴリ" "バージョン" "プロセスID" "状態" "開始ユーザID" "開始ユーザ" "開始組織ID" "開始組織" "件名" "開始日時" "終了日時"
8 "HTTP開始テスト用" "" 15 144 "未終了" "テスト" "2018-12-26 15:23:58"
8 "HTTP開始テスト用" "" 15 143 "未終了" "テスト" "2018-12-26 15:13:50"
8 "HTTP開始テスト用" "" 15 142 "未終了" "テスト" "2018-12-26 15:12:27"
...プロセスをダウンロードできる API エンドポイントは 3 種類あります。
- /API/OR/ProcessInstance/listCsvUtf16: CSV (UTF-16) 形式
- /API/OR/ProcessInstance/listCsv: CSV (UTF-8) 形式
- /API/OR/ProcessInstance/list: JSON (UTF-8) 形式
このうち、/API/OR/ProcessInstance/listCsvUtf16 は「CSV ダウンロード (Excel 互換)」機能、
/API/OR/ProcessInstance/listCsv はプロセス検索ページの「CSV ダウンロード (UTF-8)」機能に対応しています。
検索パラメータの準備
いずれの API エンドポイントでも、必要になるパラメータは以下の 3 つです。
- 検索結果の開始位置を示す start
- 検索結果の取得件数上限を示す limit
- 検索条件を示す criteria
start（デフォルト値 0） と limit（デフォルト値 1, 上限値 1000）は目的に応じて適切な数値を指定すれば OK です。criteria については事前に少し準備が必要になります。
criteria とは、検索条件を示した XML データです。例えば、
- 「簡単な申請アプリ（プロセスモデル番号 6）」のプロセス
- プロセス終了日が 2018 年 9 月 1 日 〜 2018 年 9 月 30 日である
- プロセスが終了している
- データ項目「数値 0（データ番号 0）」「日付 0（データ番号 1）」を検索結果に表示する
という検索条件の場合、criteria は次のようになります。
<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>6</process-model-info-id>
<end-date-from>2018-09-01</end-date-from>
<end-date-to>2018-09-30</end-date-to>
<states>
<state>ENDED</state>
</states>
<data>
<decimal>
<data-definition-number>0</data-definition-number>
<value></value>
<view></view>
</decimal>
<date>
<data-definition-number>1</data-definition-number>
<value></value>
<view></view>
</date>
</data>
</process-instance-criteria>criteria は Web UI でのプロセス検索時にも利用されています。criteria の記述形式を把握して自力で XML を書くのは難しいので、本記事ではWeb UI で利用されている criteria をGoogle Chrome の「検証」ツールを使用して取得し、API アクセスに利用します。まずは criteria の取得方法から紹介します。
手始めに Questetra BPM Suite に Google Chrome からログインし、ワークフローパネルを開いてください。左メニューの「プロセス/タスクの状況確認 > 全プロセス」からプロセス検索ページにジャンプできます。
このページ上で右クリックメニューから「検証」ツールを開いてください。ウインドウを分割するように検証ツールが表示されます。検証ツール内の Network タブを選択した状態でプロセス検索を行うと、ブラウザから Questetra BPM Suite に送信されたリクエストを確認することができます。API で取得したいデータに合わせてフィルタ・表示項目を設定し、「更新」ボタンを押してください。
list?_dc={数字} という項目が出てきたら、それが送信されたリクエストです。”XHR”を選択すると便利です。
項目をクリックすると詳細が開きます。criteria は最下部の Form Data に記載されています。この XML データをテキストファイルに保存しておいてください。
それでは curl コマンドで Workflow API にアクセスしてみましょう。
curl コマンドでプロセス検索結果を取得する
検索結果に合致したプロセスを UTF-16 の CSV 形式で返す /API/OR/ProcessInstance/listCsvUtf16 にアクセスして、検索結果を取得してみましょう。UTF-16 の CSV データは Excel へデータをインポートするのに向いています。
Questetra BPM Suite では、API アクセスの際に OAuth2 認証と Basic 認証を利用できます。今回は簡単に利用できる Basic 認証を用います。
$ curl -u {メールアドレス}:{basic認証パスワード} \
> 'https://example.questetra.net/API/OR/ProcessInstance/listCsvUtf16' \
> --data-urlencode criteria@process_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0'URL エンコードを curl コマンドに任せるために、各種パラメータは –data-urlencode オプションで key@path または ‘key=value’ として送信します。短いパラメータであれば、’key=value’ としてコマンドに直接埋め込むのがいいでしょう。XML データである criteria は直接記述するには長いので、上のコマンド例ではテキストファイルに保存しておいたものを渡しています。criteria@process_criteria.txt と記述すると、パラメータ criteria に process_criteria.txt の内容が渡されます。
パラメータ limit は検索結果数の上限（デフォルトは 1、上限は 1000）を、start は検索結果の何件目からを返すかを、指定しています（デフォルトは 0）。1000 件を超える検索結果を取得したい場合は、start の値を変更して繰り返し API アクセスする必要があります。
また、curl コマンドでは -u オプションで Basic 認証が行えます。メールアドレスとパスワードをコロン (:) でつないで記述してください。
CSV データは UTF-16LE でエンコードされているので、bash に標準出力すると文字化けしてしまうことが多いです。そこで、結果をファイル出力するには次のようにしてください。
$ curl -u {メールアドレス}:{basic認証パスワード} \
> (中略) ... > output.csv結果の例を次に挙げます。
"アプリID" "アプリ名" "カテゴリ" "バージョン" "プロセスID" "状態" "開始ユーザID" "開始ユーザ" "開始組織ID" "開始組織" "件名" "開始日時" "終了日時" "数値0" "日付1"
6 "簡単な申請アプリ" "" 2 15 "終了" 1 "チュートリアル" 1 "00 全社" "テスト" "2018-09-10 16:07:28" "2018-09-10 17:37:41" "1,000" "2018-09-10"
6 "簡単な申請アプリ" "" 1 14 "終了" 1 "チュートリアル" 1 "00 全社" "テスト" "2018-09-10 15:40:05" "2018-09-10 17:34:00" "1,000" "2018-09-10"結果を UTF-8 の CSV 形式で返す /API/OR/ProcessInstance/listCsv、UTF-8 の JSON 形式で返す /API/OR/ProcessInstance/list も同じように使用できます。それぞれ、次のようにデータが返ってきます。
/API/OR/ProcessInstance/listCsv (CSV, UTF-8)
"アプリID","アプリ名","カテゴリ","バージョン","プロセスID","状態","開始ユーザID","開始ユーザ","開始組織ID","開始組織","件名","開始日時","終了日時","数値0","日付1"
6,"簡単な申請アプリ","",2,15,"終了",1,"チュートリアル",1,"00 全社","テスト","2018-09-10 16:07:28","2018-09-10 17:37:41","1,000","2018-09-10"
6,"簡単な申請アプリ","",1,14,"終了",1,"チュートリアル",1,"00 全社","テスト","2018-09-10 15:40:05","2018-09-10 17:34:00","1,000","2018-09-10"/API/OR/ProcessInstance/list (JSON, UTF-8)
{
"count": 2,
"processInstances": [
{
"activeTokenNodeName": null,
"data": {
"0": {
"dataType": "DECIMAL",
"id": 2424,
"processDataDefinitionNumber": 0,
"subType": null,
"value": "1,000",
"viewOrder": 1
},
"1": {
"dataType": "DATE",
"id": 2425,
"processDataDefinitionNumber": 1,
"subType": "DATE_YMD",
"value": "2018-09-10",
"viewOrder": 2
}
},
"processInstanceDebug": false,
"processInstanceEndDatetime": "2018-09-10T17:37:41",
"processInstanceId": 15,
"processInstanceIdForView": "p15",
"processInstanceInitQgroupId": 1,
"processInstanceInitQgroupName": "00 全社",
"processInstanceInitQuserId": 1,
"processInstanceInitQuserName": "チュートリアル",
"processInstanceSequenceNumber": 2,
"processInstanceStartDatetime": "2018-09-10T16:07:28+0900",
"processInstanceState": "ENDED",
"processInstanceTitle": "テスト",
"processModelInfoCategory": "",
"processModelInfoId": 6,
"processModelInfoName": "簡単な申請アプリ",
"processModelVersion": 2
},
{
"activeTokenNodeName": null,
"data": {
"0": {
"dataType": "DECIMAL",
"id": 2366,
"processDataDefinitionNumber": 0,
"subType": null,
"value": "1,000",
"viewOrder": 1
},
"1": {
"dataType": "DATE",
"id": 2367,
"processDataDefinitionNumber": 1,
"subType": "DATE_YMD",
"value": "2018-09-10",
"viewOrder": 2
}
},
"processInstanceDebug": false,
"processInstanceEndDatetime": "2018-09-10T17:34:00",
"processInstanceId": 14,
"processInstanceIdForView": "p14",
"processInstanceInitQgroupId": 1,
"processInstanceInitQgroupName": "00 全社",
"processInstanceInitQuserId": 1,
"processInstanceInitQuserName": "チュートリアル",
"processInstanceSequenceNumber": 1,
"processInstanceStartDatetime": "2018-09-10T15:40:05+0900",
"processInstanceState": "ENDED",
"processInstanceTitle": "テスト",
"processModelInfoCategory": "",
"processModelInfoId": 6,
"processModelInfoName": "簡単な申請アプリ",
"processModelVersion": 1
}
]
}タスクのデータをダウンロードする
プロセスと同じように、タスクの情報も Workflow API から取得することができます。プロセス検索と同様に criteria が必要ですが、プロセス検索ページの右上の「プロセスのレベルで見る」を「タスク処理のレベルで見る」に切り替えて、タスク検索ページを開くことで同じように調べることができます。
タスクダウンロードの API エンドポイントも 3 種類用意されています。
- /API/OR/Workitem/listCsvUtf16: CSV (UTF-16, Excel 互換) 形式
- /API/OR/Workitem/listCsv: CSV (UTF-8) 形式
- /API/OR/Workitem/list: JSON (UTF-8) 形式
curl コマンドでタスク検索結果を取得する
検索結果に合致したタスクを UTF-16 の CSV 形式で返す /API/OR/Workitem/listCsvUtf16 にアクセスしてみましょう。コマンド例を次に挙げます。
$ curl -v -u {メールアドレス}:{basic認証パスワード} \
> 'https://shichijo-onmae-134.questetra.net/API/OR/Workitem/listCsvUtf16' \
> --data-urlencode criteria@workitem_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0' > ~/Desktop/output.txt検索対象がプロセスからタスクに変わりましたが、パラメータはプロセス検索のときとまったく変わりません。criteria を調べる先がタスク検索ページであることに注意してください。また、プロセス検索のときと同様に UTF-16LE でエンコードされているので、標準出力すると多くの場合で文字化けします。ファイルに出力して Excel にインポートするのがよいでしょう。
結果の例を次に挙げます。最初の 2 件のみを抜き出しています。
"アプリID" "アプリ名" "カテゴリ" "バージョン" "プロセスID" "状態" "開始ユーザID" "開始ユーザ" "開始組織ID" "開始組織" "件名" "開始日時" "終了日時" "ノード番号" "工程名" "状態" "締切" "処理担当者ID" "処理担当者" "処理担当組織ID" "処理担当組織" "タスク発生日時" "担当決定日時" "処理開始日時" "処理完了日時" "数値0" "日付1"
6 "簡単な申請アプリ" "" 2 15 "終了" 1 "チュートリアル" 1 "00 全社" "テスト" "2018-09-10 16:07:28" "2018-09-10 17:37:41" 2 "確認" "処理完了" 11 "カナリア" 2 "10 管理部" "2018-09-10 16:07:44" "2018-09-10 17:37:34" "2018-09-10 17:37:34" "2018-09-10 17:37:38" "1,000" "2018-09-10"
6 "簡単な申請アプリ" "" 2 15 "終了" 1 "チュートリアル" 1 "00 全社" "テスト" "2018-09-10 16:07:28" "2018-09-10 17:37:41" 1 "申請" "処理完了" 1 "チュートリアル" 1 "00 全社" "2018-09-10 16:07:28" "2018-09-10 16:07:28" "2018-09-10 16:07:28" "2018-09-10 16:07:42" "1,000" "2018-09-10"
...結果を UTF-8 の CSV 形式で返す /API/OR/Workitem/listCsv、UTF-8 の JSON 形式で返す /API/OR/Workitem/list も同じように使用できます。それぞれ、次のようにデータが返ってきます。
/API/OR/Workitem/listCsv (CSV, UTF-8)
"アプリID","アプリ名","カテゴリ","バージョン","プロセスID","状態","開始ユーザID","開始ユーザ","開始組織ID","開始組織","件名","開始日時","終了日時","ノード番号","工程名","状態","締切","処理担当者ID","処理担当者","処理担当組織ID","処理担当組織","タスク発生日時","担当決定日時","処理開始日時","処理完了日時","数値0","日付1"
6,"簡単な申請アプリ","",2,15,"終了",1,"チュートリアル",1,"00 全社","テスト","2018-09-10 16:07:28","2018-09-10 17:37:41",2,"確認","処理完了",,11,"カナリア",2,"10 管理部","2018-09-10 16:07:44","2018-09-10 17:37:34","2018-09-10 17:37:34","2018-09-10 17:37:38","1,000","2018-09-10"
6,"簡単な申請アプリ","",2,15,"終了",1,"チュートリアル",1,"00 全社","テスト","2018-09-10 16:07:28","2018-09-10 17:37:41",1,"申請","処理完了",,1,"チュートリアル",1,"00 全社","2018-09-10 16:07:28","2018-09-10 16:07:28","2018-09-10 16:07:28","2018-09-10 16:07:42","1,000","2018-09-10"
.../API/OR/Workitem/list (JSON, UTF-8)
{
"count": 4,
"workitems": [
{
"allocateDatetime": "2018-09-10T17:37:34+0900",
"allocatedQgroupId": 2,
"allocatedQgroupName": "10 管理部",
"allocatedQuserId": 11,
"allocatedQuserName": "カナリア",
"offerDatetime": "2018-09-10T16:07:44+0900",
"data": {
"0": {
"dataType": "DECIMAL",
"id": 2424,
"processDataDefinitionNumber": 0,
"subType": null,
"value": "1,000",
"viewOrder": 1
},
"1": {
"dataType": "DATE",
"id": 2425,
"processDataDefinitionNumber": 1,
"subType": "DATE_YMD",
"value": "2018-09-10",
"viewOrder": 2
}
},
"endDatetime": "2018-09-10T17:37:38+0900",
"failType": null,
"id": 2434,
"nodeName": "確認",
"nodeNumber": 2,
"processInstanceDebug": false,
"processInstanceEndDatetime": "2018-09-10T17:37:41",
"processInstanceId": 15,
"processInstanceIdForView": "p15",
"processInstanceInitQgroupId": 1,
"processInstanceInitQgroupName": "00 全社",
"processInstanceInitQuserId": 1,
"processInstanceInitQuserName": "チュートリアル",
"processInstanceSequenceNumber": 2,
"processInstanceStartDatetime": "2018-09-10T16:07:28+0900",
"processInstanceState": "ENDED",
"processInstanceTitle": "テスト",
"processModelInfoCategory": "",
"processModelInfoId": 6,
"processModelInfoName": "簡単な申請アプリ",
"processModelVersion": 2,
"starred": false,
"startDatetime": "2018-09-10T17:37:34+0900",
"state": "ENDED",
"swimlaneType": "NORMAL",
"timeLimitDatetime": null
},
...このように、Web API を利用することで簡単にプロセス・タスクを検索しダウンロードすることができます。「監査のためにバックアップを取りたい！」「業務状況の分析をしたい！」など、業務データを他のシステムにインポートする必要がある場合にぜひご活用ください。
付録: 検索結果のソート基準を変更する方法
デフォルトの状態では、検索結果は次のような基準でソートされています。
- プロセス検索→プロセス開始日時の降順
- タスク検索→タスク発生日時の降順
このソート基準を変更するためには、criteria を編集する必要があります。例えば「プロセス終了日時の昇順」でソートしたプロセス検索結果を取得する場合、先に挙げた criteria を次のように編集してください。
<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>6</process-model-info-id>
<end-date-from>2018-09-01</end-date-from>
<end-date-to>2018-09-30</end-date-to>
<states>
<state>ENDED</state>
</states>
<data>
<decimal>
<data-definition-number>0</data-definition-number>
<value></value>
<view></view>
</decimal>
<date>
<data-definition-number>1</data-definition-number>
<value></value>
<view></view>
</date>
</data>
<sort-property>processInstanceEndDatetime</sort-property>
<sort-direction>ASC</sort-direction>
</process-instance-criteria>太字で示した 2 行のように、process-instance-criteria 要素内に sort-property 要素と sort-direction 要素を追加します。sort-property 要素はソートに用いる項目を、sort-direction 要素は昇順／降順を指定します。タスク検索の場合も同様に、workitem-criteria 要素内にその 2 要素を追加してください。
sort-property 要素に指定できる値（プロセス検索）
| 開始日時 | processInstanceStartDatetime |
|---|---|
| 終了日時 | processInstanceEndDatetime |
sort-property 要素に指定できる値（タスク検索）
| 工程名 | nodeName |
|---|---|
| タスク発生日 | offerDatetime |
| 処理完了日時 | endDatetime |
| 締切 | timeLimitDatetime |
| 処理担当者 | allocatedQuserId |
sort-direction 要素に指定できる値（プロセス／タスク検索共通）
| 昇順 | ASC |
|---|---|
| 降順 | DESC |