Workflow API を用いてプロセスやタスク一覧をダウンロードする

Questetra BPM Suite の Web API には、ユーザ登録情報やシステム権限を操作できる System Settings API と、プロセスやタスクを操作できる Workflow API の 2 つがあります。今回は bash の curl コマンドを用いて、Workflow API 経由でプロセス（インスタンス）・タスクの一覧をダウンロードする方法を紹介します。Workflow API を利用することで、プロセス・タスクをデータを定期的に自動ダウンロードするスクリプトなどを作成できます。

Mac, Linux では curl コマンドはインストール不要です。Windows の場合、Windows Subsystem for Linux 上などで使用することができます。

以下の作業は、対象のワークフローアプリに対する「データ閲覧権限」を持っているアカウントで行うことを前提としています。自身のアカウントが持っているデータ閲覧権限については、「アカウント設定 > 権限」から確認できます。

プロセスのデータをダウンロードする

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 エンドポイントでも、必要になるパラメータは以下の 3 つです。

検索結果の開始位置を示す start
検索結果の取得件数上限を示す limit
検索条件を示す criteria

start（デフォルト値 0）と limit（デフォルト値 1, 上限値 1000）は目的に応じて適切な数値を指定すれば OK です。criteria については事前に少し準備が必要になります。

criteria とは、検索条件を示した XML データです。例えば、

「簡単な申請アプリ（プロセスモデル番号 4）」のプロセス
プロセス終了日が 2020 年 4 月 1 日〜 2020 年 5 月 31 日である
プロセスが終了している
データ項目「金額（データ番号 0）」「ファイル（データ番号 5）」を検索結果に表示する

という検索条件の場合、criteria は次のようになります。

<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>4</process-model-info-id>
<end-date-from>2020-04-01</end-date-from>
<end-date-to>2020-05-31</end-date-to>
<states>
<state>ENDED</state>
</states>
<data>
<decimal>
<data-definition-number>0</data-definition-number>
<value></value>
<view></view>
</decimal>
<file>
<data-definition-number>5</data-definition-number>
<value></value>
<view></view>
</file>
</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”を選択すると便利です。

↑ Questetra BPM Suite に送信されたリクエストを確認する手順

項目をクリックすると詳細が開きます。criteria は最下部の Form Data に記載されています。

この XML データをテキストファイルに保存しておいてください。本記事では「process_criteria.txt」という名前で保存します。

それでは curl コマンドで Workflow API にアクセスしてみましょう。

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 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"	"開始組織"	"件名"	"開始日時"	"終了日時"	"トークンの現在地"	"金額"	"ファイル_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 が必要ですが、プロセス検索ページの右上の「プロセスのレベルで見る」を「タスク処理のレベルで見る」に切り替えて、タスク検索ページを開くことで同じように調べることができます。

タスクダウンロードの 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 criteria@workitem_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0' > ~/Desktop/output.txt

検索対象がプロセスからタスクに変わりましたが、パラメータはプロセス検索のときとまったく変わりません。criteria を調べる先がタスク検索ページであることに注意してください。ここではタスク検索用のcriteriaを「workitem_criteria.txt」という名前で保存し、指定しています。先ほどプロセス検索用に保存した「process_criteria.txt」は使用できません。

プロセス検索のときと同様に 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 を利用することで簡単にプロセス・タスクを検索しダウンロードすることができます。「監査のためにバックアップを取りたい！」「業務状況の分析をしたい！」など、業務データを他のシステムにインポートする必要がある場合にぜひご活用ください。

付録: 検索結果のソート基準を変更する方法

デフォルトの状態では、検索結果は次のような基準でソートされています。

プロセス検索→プロセス開始日時の降順
タスク検索→タスク発生日時の降順

このソート基準を変更するためには、criteria を編集する必要があります。例えば「プロセス終了日時の昇順」でソートしたプロセス検索結果を取得する場合、先に挙げた criteria を次のように編集してください。

<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>4</process-model-info-id>
<end-date-from>2020-04-01</end-date-from>
<end-date-to>2020-05-31</end-date-to>
<states>
<state>ENDED</state>
</states>
<data>
<decimal>
<data-definition-number>0</data-definition-number>
<value></value>
<view></view>
</decimal>
<file>
<data-definition-number>5</data-definition-number>
<value></value>
<view></view>
</file>
</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

Workflow API を用いてプロセスやタスク一覧をダウンロードする

プロセスのデータをダウンロードする

検索パラメータの準備

curl コマンドでプロセス検索結果を取得する

/API/OR/ProcessInstance/listCsv (CSV, UTF-8)

/API/OR/ProcessInstance/list (JSON, UTF-8)

タスクのデータをダウンロードする

curl コマンドでタスク検索結果を取得する

/API/OR/Workitem/listCsv (CSV, UTF-8)

/API/OR/Workitem/list (JSON, UTF-8)

付録: 検索結果のソート基準を変更する方法

sort-property 要素に指定できる値（プロセス検索）

sort-property 要素に指定できる値（タスク検索）

sort-direction 要素に指定できる値（プロセス／タスク検索共通）

いいね:

Related

Questetra BPM Suite

お知らせ

リソース

クエステトラ社について

Workflow API を用いてプロセスやタスク一覧をダウンロードする

プロセスのデータをダウンロードする

検索パラメータの準備

curl コマンドでプロセス検索結果を取得する

/API/OR/ProcessInstance/listCsv (CSV, UTF-8)

/API/OR/ProcessInstance/list (JSON, UTF-8)

タスクのデータをダウンロードする

curl コマンドでタスク検索結果を取得する

/API/OR/Workitem/listCsv (CSV, UTF-8)

/API/OR/Workitem/list (JSON, UTF-8)

付録: 検索結果のソート基準を変更する方法

sort-property 要素に指定できる値（プロセス検索）

sort-property 要素に指定できる値（タスク検索）

sort-direction 要素に指定できる値（プロセス／タスク検索共通）

共有:

いいね:

Related

Questetra BPM Suite