2023-01-17 / Questetra Developers Blog /

Deprecated

最新の情報は次のリンク先をご確認ください

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

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

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

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

検索パラメータの準備

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

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

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

criteria は、検索条件を指定する XML データです。例えば、以下のような検索条件を指定すると、以下のようなXMLが表示されます。

  • 簡易請求アプリ（アプリID20）」のプロセスについて
  • プロセス終了日が2020年4月1日から5月31日の間
  • 終了したプロセス
  • 検索結果に「金額(データ番号0)」と「ファイル(データ番号5)」のデータ項目を表示する
<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
  <process-model-info-id>20</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>
    <date>
      <data-definition-number>5</data-definition-number>
      <value></value>
      <view></view>
    </date>
  </data>
</process-instance-criteria>

criteria は、Web UI のプロセス検索でも使用されています。自分で criteria の記述形式を理解してXMLを書くのは大変なので、今回は Google Chrome の「検証ツール」を使って、Web UIで使われている criteria を取得し、それを使ってAPIにアクセスすることにします。まずはcriteriaを取得する方法を紹介します。

まず、Google ChromeでQuestetra BPM Suiteにログインし、「ワークフロー」パネルを開きます。左メニューの「プロセス/タスク状況確認」の「全プロセス」をクリックすると、プロセス検索画面に遷移します。

このページでは、ウェブブラウザ上の任意の場所を右クリックして、メニューから「検証」を選択（またはCtrl+Shift+Iを押す）して、検証ツールを開きます。検証ツールがウィンドウを分割して表示されます。検証ツールの[ネットワーク]タブを選択した状態でプロセス検索を行うと、ブラウザからQuestetra BPM Suite に送信されたリクエストを確認することができます。API で取得したいデータに合わせて、フィルタ・表示項目を設定し、[更新]ボタンをクリックします。(ここでは、「シンプルなリクエストアプリ」を選択し、表示項目に「金額」と「ファイル」を追加することにします)

「list?_dc={NUMBER}」という名前で表示されている項目が、送信されたリクエストです。

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

項目名をクリックすると詳細が表示されます。下部のフォームデータ欄に criteria が記載されています。

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

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

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

検索条件を満たすプロセスをUTF-16のCSV形式で返す/API/OR/ProcessInstance/listCsvUtf16 にアクセスして検索結果を取得してみましょう。このフォーマットは、Excel と互換性があります。

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@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 と記述することで、process_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

以下は、返された結果の例です。

"AppID"	"App Name"	"Category"	"Version"	"Process ID"	"Status"	"Start UserID"	"Start User"	"Start Organization ID"	"Start Organization"	"Title"	"Start Time"	"End Time"	"Token Current Position"	"Amount"	"File_FileName"	"File_ContentType"
20	"Simple Request App"	"Tutorial"	1	93	"Running"	1	"Tutorial"	1	"00 Questetra"	"Test Request 2"	"2020-05-18 10:30:11"		"Approve"	"60,000"	"README.txt"	"text/plain"
20	"Simple Request App"	"Tutorial"	1	92	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test Request 1"	"2020-05-18 10:28:28"	"2020-05-18 10:34:42"		"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)

"App ID","App Name","Category","Version","Process ID","Status","Start User ID","Start User","Start Organization ID","Start Organization","Title","Start Time","End Time","Token Current Position","Amount","File_FileName","File_ContentType"
20,"Simple Request App","Tutorial",1,93,"Running",1,"tutorial",1,"00 Questetra","Test Request 2","2020-05-18 10:30:11",,"Approve","60,000","README.txt","text/plain"
20,"Simple Request App","Tutorial",1,92,"Completed",1,"tutorial",1,"00 Questetra","Test Request 1","2020-05-18 10:28:28","2020-05-18 10:34:42",,"22,000","ques-kun.png","image/png"

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

{
  "count":2,
  "processInstances":[
    {
      "activeTokenNodeName":["Approve"],
      "data":{
        "0":{
          "dataType":"DECIMAL",
          "id":5784,
          "processDataDefinitionNumber":0,
          "subType":null,
          "value":"60,000",
          "viewOrder":4
        },
        "5":{
          "dataType":"FILE2",
          "id":5789,
          "processDataDefinitionNumber":5,
          "subType":null,
          "value":[
            {
              "contentType":"text\/plain",
              "id":5798,
              "image":false,
              "length":7,
              "lengthText":"7 bytes",
              "name":"README.txt",
              "processDataInstanceId":5789
            }
          ],
          "viewOrder":6
        }
      },
      "processInstanceDebug":false,
      "processInstanceEndDatetime":null,
      "processInstanceId":93,
      "processInstanceIdForView":"p93",
      "processInstanceInitQgroupId":1,
      "processInstanceInitQgroupName":"00 Questetra",
      "processInstanceInitQuserId":1,
      "processInstanceInitQuserName":"tutorial",
      "processInstanceSequenceNumber":2,
      "processInstanceStartDatetime":"2020-05-18T10:30:11+0900",
      "processInstanceState":"STARTED",
      "processInstanceTitle":"Test Request 2",
      "processModelInfoCategory":"Tutorial",
      "processModelInfoId":20,
      "processModelInfoName":"Simple Request App",
      "processModelVersion":1
    },
    {
      "activeTokenNodeName":null,
      "data":{
        "0":{
          "dataType":"DECIMAL",
          "id":5759,
          "processDataDefinitionNumber":0,
          "subType":null,
          "value":"22,000",
          "viewOrder":4
        },
        "5":{
          "dataType":"FILE2",
          "id":5764,
          "processDataDefinitionNumber":5,
          "subType":null,
          "value":[
            {
              "contentType":"image\/png",
              "id":5773,
              "image":true,
              "length":7236,
              "lengthText":"7.1 KB",
              "name":"ques-kun.png",
              "processDataInstanceId":5764
            }
          ],
          "viewOrder":6
        }
      },
      "processInstanceDebug":false,
      "processInstanceEndDatetime":"2020-05-18T10:34:42",
      "processInstanceId":92,
      "processInstanceIdForView":"p92",
      "processInstanceInitQgroupId":1,
      "processInstanceInitQgroupName":"00 Questetra",
      "processInstanceInitQuserId":1,
      "processInstanceInitQuserName":"tutorial",
      "processInstanceSequenceNumber":1,
      "processInstanceStartDatetime":"2020-05-18T10:28:28+0900",
      "processInstanceState":"ENDED",
      "processInstanceTitle":"Test Request 1",
      "processModelInfoCategory":"Tutorial",
      "processModelInfoId":20,
      "processModelInfoName":"Simple Request App",
      "processModelVersion":1
    }
  ]
}

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

プロセスと同様に、ワークフロー 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 コマンドでタスク検索結果を取得する

検索条件を満たすタスクを 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@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 にインポートするのが良いでしょう。

以下はその結果の一例です。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

Appendix: 検索結果のソートルールを変更する方法

デフォルトでは、検索結果は以下のルールに基づいてソートされます。

  • プロセス検索：プロセス開始時刻の降順
  • タスク検索：タスクオファー時間の長い順

これらのソートルールを変更するには、criteria を編集する必要があります。例えば「プロセス終了時刻の昇順」でプロセス検索結果を取得したい場合は、前述の criteria を以下のように編集してください。

<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>20</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>
<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>

process-instance-criteria 要素の中にsort-property 要素とsort-direction 要素を太い2行で示すように追加します。sort-property 要素では、ソートに使用する項目を指定し、sort-direction 要素では、昇順/降順を指定します。タスク検索の場合も同様に、workitem-criteria 要素内に2つの要素を追加します。

sort-property 要素に指定可能な値(プロセス検索)

開始日 時間processInstanceStartDatetime
終了日時間processInstanceEndDatetime

sort-property 要素に指定可能な値(タスク検索)

タスク名nodeName
提供時間offerDatetime
終了時間endDatetime
締め切りtimeLimitDatetime
オペレーター
allocatedQuserId

sort-direction 要素に指定可能な値（プロセス／タスク検索に共通)

昇順ASC
降順DESC

See also

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

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