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-8) 形式でダウンロードした場合、次のような検索結果が API から返ってきます。
"アプリID","アプリ名","カテゴリ","バージョン","プロセスID","状態","開始ユーザID","開始ユーザ","開始組織ID","開始組織","件名","開始日時","終了日時","トークンの現在地","金額","ファイル_FileName","ファイル_ContentType"
4,"簡単な申請アプリ","チュートリアル",9,23,"終了",1,"チュートリアル",1,"00 全社","テスト申請２","2020-05-01 14:48:46",,"60,000","README.txt","text/plain"
4,"簡単な申請アプリ","チュートリアル",9,22,"終了",1,"チュートリアル",1,"00 全社","テスト申請１","2020-05-01 14:47:05",,"22,000","ques-kun.png","image/png"プロセスをダウンロードできる 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でデータを指定、取得するためには、以下の2つのツールがあります。
- reportId
- criteria
ここでは、reportIdを利用する方法についてのみ説明します。 criteriaメソッドを使う場合の説明はこちらをご覧ください。
いずれの API エンドポイントでも、必要になるパラメータは以下の 3 つです。
- 検索結果の開始位置を示す start
- 検索結果の取得件数上限を示す limit
- 検索条件を指定するパラメータ
- reportId
- criteria
このプロセスでは、reportIdとcriteria は同じ機能を果たすため、一度に使用されるのはどちらか一方のみです。
start（デフォルト値 0） と limit（デフォルト値 1, 上限値 1000）は目的に応じて適切な数値を指定すれば OK です。
reportIdは、QuestetraのWeb UIでプロセスデータの保存検索を指定・取得するために利用できる機能です。
リストの保存機能を使って検索条件を保存すると、保存されたリストには自動的に reportId が付与されます。このIDは、プロセスの検索データを参照する際に、条件XMLの代わりに使用できるリファレンスとして機能します。
Questetraの「ワークフロー」から「全プロセス」＞「フィルタ」にてドロップダウンメニューで「開始日」と「終了日」を指定します。
指定したAppに関連するプロセスの一覧が、指定した日付範囲で表示されます。
「このリストに名前をつけて保存」をクリックすると、保存された検索の名前を指定できるウィンドウが表示されます。
リストが保存されると、自動的にreportIdが割り当てられ、URLに表示されます。
選択したリスト名がサイドメニューの[その他]に表示され、ワンクリックで保存した検索結果を呼び出すことができるようになります。
curlコマンド では、reportIdを使ってリストデータを表現することができます。
curl コマンドでプロセス検索結果を取得する
検索結果に合致したプロセスを UTF-16 の CSV 形式で返す /API/OR/ProcessInstance/listCsvUtf16 にアクセスして、検索結果を取得してみましょう。UTF-16 の CSV データは Excel へのインポートに最適です。
Questetra BPM Suite では、API アクセスの際に OAuth2 認証と Basic 認証を利用できます。今回は簡単に利用できる Basic 認証を利用します。
Questetra BPM Suite での Basic 認証については、「ユーザ情報をローカルデータと同期させる（準備編）」で有効化設定からパスワードの確認までの手順を紹介しています。
$ curl -u {メールアドレス}:{basic認証パスワード} \
> 'https://example.questetra.net/API/OR/ProcessInstance/listCsvUtf16' \
> --data-urlencode 'reportId=1234567' \
> --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" "開始組織" "件名" "開始日時" "終了日時" "トークンの現在地" "金額" "ファイル_FileName" "ファイル_ContentType"
4 "簡単な申請アプリ" "チュートリアル" 9 23 "未終了" 1 "チュートリアル" 1 "00 全社" "テスト申請２" "2020-05-01 14:48:46" "承認" "60,000" "README.txt" "text/plain"
4 "簡単な申請アプリ" "チュートリアル" 9 22 "終了" 1 "チュートリアル" 1 "00 全社" "テスト申請１" "2020-05-01 14:47:05" "2020-05-01 15:00:51" "22,000" "ques-kun.png" "image/png"データ項目を取得したい場合は、criteriaでデータ項目番号を指定する必要があります。本記事ではWeb UIの検索からcriteriaを取得しているので、Web UIの検索画面で表示項目エリアを開き、取得したいデータ項目にチェックを入れた状態で「更新」ボタンをクリックし、最新のcriteriaを取得してください。
結果を 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","開始組織","件名","開始日時","終了日時","トークンの現在地","金額","ファイル_FileName","ファイル_ContentType"
4,"簡単な申請アプリ","チュートリアル",9,23,"未終了",1,"チュートリアル",1,"00 全社","テスト申請２",,"承認","60,000","README.txt","text/plain"
4,"簡単な申請アプリ","チュートリアル",9,22,"終了",1,"チュートリアル",1,"00 全社","テスト申請１","2020-05-01 14:47:05",,"22,000","ques-kun.png","image/png"/API/OR/ProcessInstance/list (JSON, UTF-8)
{
"count":2,
"processInstances":[
{
"activeTokenNodeName":["承認"],
"data":{
"0":{
"dataType":"DECIMAL",
"id":3071,
"processDataDefinitionNumber":0,
"subType":null,
"value":"60,000",
"viewOrder":4
},
"5":{
"dataType":"FILE2",
"id":3076,
"processDataDefinitionNumber":5,
"subType":null,
"value":[
{
"contentType":"text\/plain",
"id":3085,
"image":false,
"length":7,
"lengthText":"7 bytes",
"name":"README.txt",
"processDataInstanceId":3076
}
],
"viewOrder":6
}
},
"processInstanceDebug":false,
"processInstanceEndDatetime":null,
"processInstanceId":23,
"processInstanceIdForView":"p23",
"processInstanceInitQgroupId":1,
"processInstanceInitQgroupName":"00 全社",
"processInstanceInitQuserId":1,
"processInstanceInitQuserName":"チュートリアル",
"processInstanceSequenceNumber":8,
"processInstanceStartDatetime":"2020-05-01T14:48:46+0900",
"processInstanceState":"STARTED",
"processInstanceTitle":"テスト申請２",
"processModelInfoCategory":"チュートリアル",
"processModelInfoId":4,
"processModelInfoName":"簡単な申請アプリ",
"processModelVersion":9
},
{
"activeTokenNodeName":null,
"data":{
"0":{
"dataType":"DECIMAL",
"id":3046,
"processDataDefinitionNumber":0,
"subType":null,
"value":"22,000",
"viewOrder":4
},
"5":{
"dataType":"FILE2",
"id":3051,
"processDataDefinitionNumber":5,
"subType":null,
"value":[
{
"contentType":"image\/png",
"id":3060,
"image":true,
"length":7236,
"lengthText":"7.1 KB",
"name":"ques-kun.png",
"processDataInstanceId":3051
}
],
"viewOrder":6
}
},
"processInstanceDebug":false,
"processInstanceEndDatetime":"2020-05-01T15:00:51",
"processInstanceId":22,
"processInstanceIdForView":"p22",
"processInstanceInitQgroupId":1,
"processInstanceInitQgroupName":"00 全社",
"processInstanceInitQuserId":1,
"processInstanceInitQuserName":"チュートリアル",
"processInstanceSequenceNumber":7,
"processInstanceStartDatetime":"2020-05-01T14:47:05+0900",
"processInstanceState":"ENDED",
"processInstanceTitle":"テスト申請１",
"processModelInfoCategory":"チュートリアル",
"processModelInfoId":4,
"processModelInfoName":"簡単な申請アプリ",
"processModelVersion":9
}
]
}タスクデータをダウンロードする
プロセスと同じように、タスク情報も Workflow API から取得することができます。プロセス検索と同様に criteria が必要ですが、プロセス検索ページの右上の「プロセスのレベルで見る」を「タスク処理のレベルで見る」に切り替えて、タスク検索ページを開くことで同じように調べることができます。
タスクデータには、次のように、reportIdとして指定できる2つの特別な値があります。
- ALLOCATED – マイタスク
- OFFERED – 引き受け待ち
例えば、以下のようなURLを指定すると、「 引き受け待ち 」リストに掲載されているタスクのデータが返されます。
https://****.questetra.net/API/OR/Workitem/list?reportId=OFFEREDタスクダウンロードの 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://example.questetra.net/API/OR/Workitem/listCsvUtf16' \
> --data-urlencode 'reportId=1234567' \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0' > ~/Desktop/output.txt検索対象がプロセスからタスクに変わりましたが、パラメータはプロセス検索時とまったく変わりません。reportId を調べる先がタスク検索ページであることに注意してください。先ほどプロセス検索用に保存したreportIdは使用できません。
プロセス検索時と同様に UTF-16LE でエンコードされているので、標準出力すると多くの場合で文字化けします。ファイルに出力して Excel にインポートすることをおすすめします。
結果の例は次のとおりです。最初の 2 件のみを抜き出しています。
"アプリID" "アプリ名" "カテゴリ" "バージョン" "プロセスID" "状態" "開始ユーザID" "開始ユーザ" "開始組織ID" "開始組織" "件名" "開始日時" "終了日時" "ノード番号" "工程名" "状態" "締切" "処理担当者ID" "処理担当者" "処理担当組織ID" "処理担当組織" "タスク発生日時" "担当決定日時" "処理開始日時" "処理完了日時" "数値0" "日付1"
6 "簡単な申請アプリ" "" 2 15 "終了" 1 "チュートリアル" 1 "00 全社" "テスト" "2020-04-10 16:07:28" "2020-04-10 17:37:41" 2 "確認" "処理完了" 11 "カナリア" 2 "10 管理部" "2020-04-10 16:07:44" "2020-04-10 17:37:34" "2020-04-10 17:37:34" "2020-04-10 17:37:38" "1,000" "2020-04-10"
6 "簡単な申請アプリ" "" 2 15 "終了" 1 "チュートリアル" 1 "00 全社" "テスト" "2020-04-10 16:07:28" "2020-04-10 17:37:41" 1 "申請" "処理完了" 1 "チュートリアル" 1 "00 全社" "2020-04-10 16:07:28" "2020-04-10 16:07:28" "2020-04-10 16:07:28" "2020-04-10 16:07:42" "1,000" "2020-04-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 全社","テスト","2020-04-10 16:07:28","2020-04-10 17:37:41",2,"確認","処理完了",,11,"カナリア",2,"10 管理部","2020-04-10 16:07:44","2020-04-10 17:37:34","2020-04-10 17:37:34","2020-04-10 17:37:38","1,000","2020-04-10"
6,"簡単な申請アプリ","",2,15,"終了",1,"チュートリアル",1,"00 全社","テスト","2020-04-10 16:07:28","2020-04-10 17:37:41",1,"申請","処理完了",,1,"チュートリアル",1,"00 全社","2020-04-10 16:07:28","2020-04-10 16:07:28","2020-04-10 16:07:28","2020-04-10 16:07:42","1,000","2020-04-10"
.../API/OR/Workitem/list (JSON, UTF-8)
{
"count": 4,
"workitems": [
{
"allocateDatetime": "2020-04-10T17:37:34+0900",
"allocatedQgroupId": 2,
"allocatedQgroupName": "10 管理部",
"allocatedQuserId": 11,
"allocatedQuserName": "カナリア",
"offerDatetime": "2020-04-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": "2020-04-10",
"viewOrder": 2
}
},
"endDatetime": "2020-04-10T17:37:38+0900",
"failType": null,
"id": 2434,
"nodeName": "確認",
"nodeNumber": 2,
"processInstanceDebug": false,
"processInstanceEndDatetime": "2020-04-10T17:37:41",
"processInstanceId": 15,
"processInstanceIdForView": "p15",
"processInstanceInitQgroupId": 1,
"processInstanceInitQgroupName": "00 全社",
"processInstanceInitQuserId": 1,
"processInstanceInitQuserName": "チュートリアル",
"processInstanceSequenceNumber": 2,
"processInstanceStartDatetime": "2020-04-10T16:07:28+0900",
"processInstanceState": "ENDED",
"processInstanceTitle": "テスト",
"processModelInfoCategory": "",
"processModelInfoId": 6,
"processModelInfoName": "簡単な申請アプリ",
"processModelVersion": 2,
"read": false,
"starred": false,
"startDatetime": "2020-04-10T17:37:34+0900",
"state": "ENDED",
"swimlaneType": "NORMAL",
"timeLimitDatetime": null
},
...このように、Web API を利用することで簡単にプロセスやタスクを検索しダウンロードすることができます。「監査のためにバックアップを取りたい！」「業務状況の分析をしたい！」など、業務データを他のシステムにインポートする必要がある場合にぜひご活用ください。