2022-06-07 / Questetra Developers Blog /

reportId の項で説明したように、プロセスやタスクのデータをダウンロードするには、基準となる criteria を利用する方法もあります。

以下の作業は、対象となるワークフローアプリのデータ閲覧権限を持つアカウントで行う必要があります。自分のアカウントが「データ閲覧権限」を持っているかどうかは、「アカウント設定」 > 「権限」で確認できます。

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

前回の記事では、ワークフローAPIを使ってプロセスデータを検索し、そのデータを様々な形式でダウンロードする方法をご紹介しましたので、絞り込み検索の保存方法などについてはそちらをご参照ください。

検索パラメータの準備

前述のとおり、いずれのAPIエンドポイントでも、以下の3つのパラメータが必要です。

  • 検索結果の開始位置を示す start
  • 検索結果の取得件数上限を示す limit
  • 検索条件を指定するパラメータ
    • reportId
    • criteria

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

criteria にて、JSON 形式で検索条件を指定します。例えば、次の検索条件は、下記の JSON データとなります。

  • 簡単な申請アプリ（アプリID 2726）」のプロセスについて
  • プロセス開始日が2022年1月1日から1月31日の間
  • 未終了のプロセス
  • 検索結果に「金額(データ番号0)」と「ファイル(データ番号5)」のデータ項目を表示する
  • 検索結果を「開始日」の「降順」でソートする
{
  "processModelInfoId":2726,
  "processInstanceStartDateFrom":"2022-01-01",
  "processInstanceStartDateTo":"2022-01-31",
  "processInstanceState":["STARTED"],
  "fields":[
    {
      "type":"decimal",
      "number":0
    },
    {
      "type":"file",
      "number":5
    }
  ],
  "sortProperty":"processInstanceStartDatetime",
  "sortDirection":"DESC"
}

この JSON をテキストファイルとして保存します。この記事では、ファイル名を「search_criteria.txt」とします。

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

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

/API/OR/ProcessInstance/listCsvUtf16 にリクエストを送信し、検索条件を満たすプロセス一覧を取得してみましょう。この API のレスポンスは、 Excel と互換性のあるフォーマットである UTF-16 の CSV 形式で返されます。

Questetra BPM Suite では、API へのアクセスに OAuth 2 と Basic 認証が利用できます。ここでは、設定が簡単な Basic 認証を使用します。

Questetra BPM Suite の Basic 認証については、「ユーザ情報をローカルデータと同期させる（準備編）」で、有効化設定からパスワード確認までの手順を説明していますので、そちらをご参照ください。

$ curl -u {EMAIL ADDRESS}:{PASSWORD for Basic authentication} \
> 'https://example.questetra.net/API/OR/ProcessInstance/listCsvUtf16' \
> --data-urlencode criteria@search_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0'

URL エンコーディングを curl コマンドに渡すには、-data-urlencode オプションで各パラメータを key@path または ‘key=value’ として送信します。短いパラメータの場合は、’key=value’として直接コマンドに埋め込むのが良いでしょう。JSONである criteria は、直接埋め込むには長すぎるため、上記のコマンド例では、テキストファイルに保存されているものを渡しています。criteria@search_criteria.txt と記述することで、search_criteria.txt の内容がパラメータ criteria に渡されます。

パラメータ limit は、検索結果数の上限（デフォルトでは1、最大1000）を指定し、start はどの検索結果数から始めるか（デフォルトでは0）を指定します。1000件以上の検索結果を取得したい場合は、start の値を変更してAPIに繰り返しアクセスする必要があります。

また、curl コマンドの-uオプションで Basic 認証を行うことも可能です。-u オプションを指定してください。メールアドレスとパスワードをコロン(:)で区切って記入してください。

CSVデータは UTF-16LEでエンコードされているため、bash の stdout に出力すると文字化けしてしまうことがあります。結果をファイルに出力するには、以下のように設定します。

$ curl -u {EMAIL ADDRESS}:{PASSWORD for Basic authentication} \
>...(omitted)... > output.csv

以下は、返された結果の例です。なお、検索結果には指定されていなくても、全てのプロセスに共通の項目（アプリの ID など）がデフォルトで含まれます。

"アプリID"	"アプリ名"	"カテゴリ"	"バージョン"	"プロセスID"	"状態"	"開始ユーザID"	"開始ユーザ"	"開始組織ID"	"開始組織"	"件名"	"開始日時"	"終了日時"	"トークンの現在地"	"金額"	"ファイル_FileName"	"ファイル_ContentType"
4	"簡単な申請アプリ"	"テストアプリ"	9	23	"未終了"	1	"サウスポール"	1	"00 全社"	"テスト申請２"	"2022-01-14 15:44:46"		"承認"	"60,000"	"README.txt"	"text/plain"
4	"簡単な申請アプリ"	"テストアプリ"	9	22	"終了"	1	"サウスポール"	1	"00 全社"	"テスト申請１"	"2022-01-14 15:42:05"	"2022-01-14 15:42:51"		"22,000"	"ques-kun.png"	"image/png"

結果にデータ項目を含めるには、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 全社","テスト申請１","2022-01-14 15:42: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":"2022-01-14T15:44: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":"2022-01-14T15:00:51",
      "processInstanceId":22,
      "processInstanceIdForView":"p22",
      "processInstanceInitQgroupId":1,
      "processInstanceInitQgroupName":"00 全社",
      "processInstanceInitQuserId":1,
      "processInstanceInitQuserName":"サウスポール",
      "processInstanceSequenceNumber":7,
      "processInstanceStartDatetime":"2022-01-14T15:42:05+0900",
      "processInstanceState":"ENDED",
      "processInstanceTitle":"テスト申請１",
      "processModelInfoCategory":"テストアプリ",
      "processModelInfoId":4,
      "processModelInfoName":"簡単な申請アプリ",
      "processModelVersion":9
    }
  ]
}

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

プロセスと同様に、ワークフロー API を利用してタスク情報を取得することができます。

タスクをダウンロードするための 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 コマンドでタスク検索結果を取得する

検索条件を満たすタスクを CSV UTF-16 形式で返す /API/OR/Workitem/listCsvUtf16 にアクセスしてみましょう。以下にコマンドの例を示します。

$ curl -v -u {EMAIL ADDRESS }:{PASSWORD for Basic authentication} \
> 'https://example.questetra.net/API/OR/Workitem/listCsvUtf16' \
> --data-urlencode criteria@search_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0' > ~/Desktop/output.txt

検索対象がプロセスからタスクに変わりましたが、パラメータはプロセス検索のときとまったく変わりません。criteria には同じ JSON のファイルを指定します。

プロセス検索と同様にUTF-16LEでエンコードされているため、標準出力では多くの場合、文字化けしてしまいます。ファイルに出力してから Excel にインポートするのが良いでしょう。

以下はその結果の一例です。3件目以降の結果は省略しています。

"アプリID"	"アプリ名"	"カテゴリ"	"バージョン"	"プロセスID"	"状態"	"開始ユーザID"	"開始ユーザ"	"開始組織ID"	"開始組織"	"件名"	"開始日時"	"終了日時"	"ノード番号"	"工程名"	"状態"	"締切"	"処理担当者ID"	"処理担当者"	"処理担当組織ID"	"処理担当組織"	"タスク発生日時"	"担当決定日時"	"処理開始日時"	"処理完了日時"	"数値0"	"ファイル_FileName"	"ファイル_ContentType"
6	"簡単な申請アプリ"	"テストアプリ"	2	15	"終了"	1	"サウスポール"	1	"00 全社"	"テスト申請１"	"2022-01-14 15:07:28"	"2022-01-14 17:37:41"	2	"確認"	"処理完了"		11	"カナリア"	2	"10 管理部"	"2022-01-14 15:43:44"	"2022-01-14 15:43:46"	"2022-01-14 17:37:34"	"2022-01-14 17:38:38"	"22,000"	"ques-kun.png"	"image/png"
6	"簡単な申請アプリ"	"テストアプリ"	2	15	"終了"	1	"サウスポール"	1	"00 全社"	"テスト申請１"	"2022-01-14 15:42:05"	"2022-01-14 15:42:51"	1	"申請"	"処理完了"		1	"サウスポール"	1	"00 全社"	"2022-01-14 15:42:04"	"2022-01-14 15:42:05"	"2022-01-14 15:42:06"	"2022-01-14 15:43:42"	"22,000"	"ques-kun.png"	"image/png"
...

UTF-8のCSV形式で結果を返す/API/OR/ProcessInstance/listCsv や、UTF-8のJSON形式で結果を返す/API/OR/ProcessInstance/list に対しても同様に使用することができます。以下は、それぞれの検索結果の例です。

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

"アプリID","アプリ名","カテゴリ","バージョン","プロセスID","状態","開始ユーザID","開始ユーザ","開始組織ID","開始組織","件名","開始日時","終了日時","ノード番号","工程名","状態","締切","処理担当者ID","処理担当者","処理担当組織ID","処理担当組織","タスク発生日時","担当決定日時","処理開始日時","処理完了日時","数値0","ファイル_FileName","ファイル_ContentType"
6,"簡単な申請アプリ","テストアプリ",2,15,"終了",1,"サウスポール",1,"00 全社","テスト申請１","2022-01-14 16:07:28","2022-01-14 17:37:41",2,"確認","処理完了",,11,"カナリア",2,"10 管理部","2022-01-14 15:43:44","2022-01-14 15:43:46","2022-01-14 17:37:34","2022-01-14 17:38:38","22,000","ques-kun.png","image/png"
6,"簡単な申請アプリ","テストアプリ",2,15,"終了",1,"サウスポール",1,"00 全社","テスト申請１","2022-01-14 15:42:05","2022-01-14 15:43:42",1,"申請","処理完了",,1,"サウスポール",1,"00 全社","2022-01-14 15:42:04","2022-01-14 15:42:05","2022-01-14 15:42:06","2022-01-14 15:43:42","22,000","ques-kun.png","image/png"
...

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

{
  "count": 4,
  "workitems": [
    {
      "allocateDatetime": "2022-01-14T15:43:46+0900",
      "allocatedQgroupId": 2,
      "allocatedQgroupName": "10 管理部",
      "allocatedQuserId": 11,
      "allocatedQuserName": "カナリア",
      "offerDatetime": "2022-01-14T15:43:44+0900",
      "data": {
        "0": {
          "dataType": "DECIMAL",
          "id": 2424,
          "processDataDefinitionNumber": 0,
          "subType": null,
          "value": "22,000",
          "viewOrder": 1
        },
        "1": {
          "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
        }
      },
      "endDatetime": "2022-01-14T17:37:38+0900",
      "failType": null,
      "id": 2434,
      "nodeName": "確認",
      "nodeNumber": 2,
      "processInstanceDebug": false,
      "processInstanceEndDatetime": "2022-01-14T17:37:41",
      "processInstanceId": 15,
      "processInstanceIdForView": "p15",
      "processInstanceInitQgroupId": 1,
      "processInstanceInitQgroupName": "00 全社",
      "processInstanceInitQuserId": 1,
      "processInstanceInitQuserName": "サウスポール",
      "processInstanceSequenceNumber": 2,
      "processInstanceStartDatetime": "2022-01-14T15:42:05+0900",
      "processInstanceState": "ENDED",
      "processInstanceTitle": "テスト申請１",
      "processModelInfoCategory": "テストアプリ",
      "processModelInfoId": 6,
      "processModelInfoName": "簡単な申請アプリ",
      "processModelVersion": 2,
	 "read": false,
      "starred": false,
      "startDatetime": "2022-01-14T15:42:04+0900",
      "state": "ENDED",
      "swimlaneType": "NORMAL",
      "timeLimitDatetime": null
    },
...

このように、Web API を利用することで、プロセス/タスクに関する情報を簡単に検索・ダウンロードすることができます。監査のためにバックアップが必要な場合や、ビジネスの状況を分析したい場合など、業務データを他のシステムに取り込む必要がある場合にご利用ください。

See also

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

%d人のブロガーが「いいね」をつけました。