Workflow Analytics API

Workflow Analytics API は Microsoft Power BI などの分析ツールや DocuWare 統合ソリューションで直接読み込んで使用できるデータを提供し、それによりワークフローデータの統合を簡素化します。これにより、ユーザーはビジネスプロセスからの重要な分析情報の抽出、分析、ビジュアル化ができるようになります。

DocuWare 7.13では、ワークフロー分析APIがオンプレミス版DocuWareでも利用可能になりました。

ワークフロー分析APIは、オンプレミス版DocuWareのインストール先において、以下のディレクトリに自動的にインストールされます：

物理パス： Program Files\DocuWare\Web\WorkflowAnalyticsService
仮想パス（IIS内）： {組織ドメイン}/DocuWare/Workflow/Analytics

ワークフロー分析 API の主な機能

プロセスの最適化、ボトルネックの特定、ワークロードやリソースの管理のための分析をサポートします。
開発者向けに JSON 形式でデータを提供し、シームレスな統合とより簡単なデータ操作を実現します。
一般的な分析ツールとの間で即時的な互換性を確保するために、CSV 形式でデータを提供します。
ミドルウェアの必要性を低減しながら、DocuWare Cloud のコンプライアンスおよびセキュリティ基準のメリットを享受することができます。
ワークフローごとにデータを 90 日間確実に保存します。
データを 24 時間ごとに自動で更新します。
大規模なデータセットを効率的に処理し、最適なパフォーマンスを実現します。

認証と承認

認証

Workflow Analytics API を使用するには、DocuWare (プラットフォーム) にログインし、OAuth2 ベアラートークンを使用して API にアクセスする必要があります。
DocuWare の認証方法に関する詳細情報

承認

Workflow Analytics API からデータにアクセスするためには、認証を受けたユーザーはデータを要求する指定のワークフローの "設計者" または "コントローラー" のいずれかの役割を持っている必要があります。

ワークフロー分析データの収集を可能にする

Workflow Analytics を使用するには、最初に各ワークフローでデータの収集を有効にする必要があります。データの収集を有効にするワークフローを指定し、各ワークフローで収集するデータの種類 (データプロジェクション) を決定する必要があります。

API ドキュメント

アナリティクスの構成: 特定のワークフローのデータプロジェクションの検証、アクティブ化、非アクティブ化を行うためのエンドポイントのコレクションです。
Workflow Analytics: 特定のワークフローのデータプロジェクションからデータを取得するためのエンドポイントのコレクションです。

API ドキュメントは次の URL からアクセスできます: …/DocuWare/Workflow/Analytics/index.html

データプロジェクション

関連するデータの収集を容易化するために、いわゆるデータプロジェクションが提供されています。データプロジェクションの各種類には、専用のエンドポイントを介してアクセスすることができます。

データプロジェクションとは、特定の目的のためのデータの提供を意図して定義されたデータセットのことです。

データプロジェクションの種類

現在は、以下のデータプロジェクションの種類が利用可能です。

データプロジェクションの種類	説明
`GeneralTaskExecutionTimes`	処理された各タスクの割り当てからユーザーによる確認までの期間を返します。
`GeneralTaskDecisions`	ディシジョンが下された日時を含む処理された各タスクについて選択されたディシジョンを返します。
`GeneralTaskDecisionUser`	ディシジョンが下された日時を含む処理された各タスクについてディシジョンを選択したユーザーを返します。
`GeneralTaskFormFieldData`	処理された各タスクで選択されたディシジョンとともに送信されたデータ (利用可能な場合) を返します。
`GeneralTaskReactionTimes`	各タスクの割り当てからユーザーによるピックアップ (既読としてマーク) までの期間を返します。
`WorkflowErrorExits`	ワークフローが下したエラーの終了 (利用可能な場合) を返します。
`WorkflowRuntime`	ワークフローインスタンスの期間 (開始日時、終了日時、実行中、完了、失敗、停止などのステータスを含む) を返します。
`GlobalVariablesChanges`	ワークフロー全体でグローバル変数に保存されたデータ (利用可能な場合) を保存日時を含めて返します。

データの永続性

データプロジェクションが有効化されると、データの収集は直ちに開始されます。データプロジェクションの各ステータスは、以下のいずれかを示しています。

InProgress: データの収集が現在進行中です。
Ready : データの収集は完了しており、利用可能です。

データは、プロジェクションがアクティブ化してから 24 時間以内に入手できるようになります。各データプロジェクションは、アクティブなワークフローインスタンスからのすべてのデータと、過去 90 日以内に完了したインスタンスからのデータへのアクセスを提供しています。 90 日以上前に完了したワークフローインスタンスはご利用いただけません。

データの形式

各データプロジェクションは 2 種類のデータ形式をサポートしており、クエリパラメーター "format=" (デフォルトの値: JSON) を指定してリクエストすることができます。

JSON 形式と CSV 形式の両方を提供することで、弊社のデータプロジェクションは開発者とエンドユーザーの多様なニーズに確実に応えられるようになっています。

JSON

目的: JSON は、インテグレーターや開発者のニーズに対応するように設計されています。
使用方法: 開発者が簡単に変換してアプリケーションやソリューションに統合可能な標準的なデータセットを作成します。

CSV

目的: CSV は、Analytics/BI や表計算アプリケーションでデータセットを直接使用するユーザーに対応するための形式です。
使用方法: 結果リストの CSV エクスポートと同様に、そういったアプリケーションと一般的に互換性のあるデータセットを作成します。さらに、エンコーディングやタイムゾーンの調整などのカスタマイズオプションも用意されています。

CSV 形式の追加クエリパラメーター

csvIsUtc=

目的: UTC と既定の形式、または組織設定で指定されたタイムゾーンと日付の形式で日付を取得します。

既定値: <1>false。 true に設定すると、日付は UTC と既定の形式で提供されます。

encodingName=

目的: データのエンコーディングを指定します。

既定値: <1>UTF8

サポートされているエンコーディング: UTF8、ANSI、ASCII、Big5、ShiftJIS、Unicode、UTF8 (BOM なし)。

API の使用方法

特定のワークフローでデータプロジェクションを有効にする

要件:

OAuth2 ベアラートークン
- DocuWare の認証方法に関する詳細情報
JSON ペイロード: (必須)
- FileCabinetId: (文字列、必須) ファイルキャビネットの GUID です。
- WorkflowNamesList: (文字列配列、必須) 有効にするワークフロー名のリストです。
  - ワークフロー名 (Name) は以下で取得できます: .../DocuWare/Platform/Workflow/DesignerWorkflows
- ProjectionTypesList: (文字列配列、必須)

API エンドポイント:

POST /DocuWare/Workflow/Analytics/Configuration/EnableProjections

リクエストの例:

{
  "FileCabinetId": "3938dcdd-d2c9-467a-b01a-5daf96c0ea0c",
  "WorkflowNamesList": [
    "Accounts Payable"
  ],
  "ProjectionTypesList": [
    "WorkflowRuntime","GeneralTaskExecutionTimes"
  ]
}

可能性のある応答:

200 OK: データプロジェクションは正常に有効化されました。

{
  "HasChanges": true,
  "OperationSummaries": [
    {
      "WorkflowName": "Accounts Payable",
      "WorkflowId": "bf8d21f9-4b0d-481e-95a2-e7f014adf3b7",
      "ProjectionType": "WorkflowRuntime",
      "Message": "Success"
    }
  ]
}

400 Bad Request: 入力データが無効です。
401 Unauthorized: 認証が欠落しているか、または無効です。
404 Not Found: 指定されたワークフローまたはファイルキャビネットが存在しません。

有効なデータプロジェクションを確認する

要件:

OAuth2 ベアラートークン
- DocuWare の認証方法に関する詳細情報

API エンドポイント:

GET /DocuWare/Workflow/Analytics/Configuration

可能性のある応答:

200 OK

[
  {
    "WorkflowId": "bf8d21f9-4b0d-481e-95a2-e7f014adf3b7",
    "WorkflowName": "Accounts Payable",
    "ProjectionType": "WorkflowRuntime",
    "LastEventTimestamp": "/Date(1726493274127+0000)/",
    "ProjectionProcessingState": "Ready"
  }
]

400 Bad Request: 入力データが無効です。
401 Unauthorized: 認証が欠落しているか、または無効です。
404 Not Found: 指定されたワークフローまたはファイルキャビネットが存在しません。
500 Internal Server Error

データプロジェクションのデータを取得する

要件:

OAuth2 ベアラートークン
- DocuWare の認証方法に関する詳細情報
WorkflowId: (文字列による UUID、必須) ワークフローの ID です。
- ワークフロー ID (Id) は以下で取得できます: .../DocuWare/Platform/Workflow/DesignerWorkflows
format (文字列、オプション)
csvIsUtc (ブール値、オプション)
encodingName (文字列、オプション)

API エンドポイント:

例: GET /DocuWare/Workflow/Analytics/{workflowId}/WorkflowRuntime

可能性のある応答:

200 OK

[
  {
    "workflowVersion": 1,
    "docId": 18,
    "runtime": "00:00:34.6158214",
    "state": "Completed",
    "startTime": "/Date(1726493198284)/",
    "timeOfCompletion": "/Date(1726493232900)/"
  }
]

401 Unauthorized: 認証が欠落しているか、または無効です。
500 Internal Server Error

追加のワークフロー関連 API のエンドポイント

以下のエンドポイントは Workflow Analytics API ではなく、DocuWare Platform API の一部です。 Workflow Analytics API が過去のデータに重点を置いているのに対し、これらのエンドポイントはリアルタイムのデータを提供します。これらは、Workflow Analytics API からの分析情報をサポートして補完するワークフローに関する重要な情報を提供します。

GET /DocuWare/Platform/Workflow/DesignerWorkflows
- 現在のユーザーが設計者権限を持っているすべての公開ワークフローのリストを返します。
GET /DocuWare/Platform/Workflow/Workflows
- 現在のユーザーがオープンなタスクを割り当てているすべてのワークフローのリストを提供します。
GET /DocuWare/Platform/Workflow/Workflows/{workflowId}/Tasks
- 現在のユーザーから見て、workflowId によって識別される指定されたワークフローに現在割り当てられているすべてのタスクを取得します。
GET DocuWare/Platform/Workflow/ControllerWorkflows/{workflowId}/Tasks
- ワークフローコントローラーから見て、現在のユーザーにタスクが割り当てられているすべてのワークフローのリストを返します。
GET DocuWare/Platform/Workflow/ControllerWorkflows/{workflowId}/Tasks
- ワークフローコントローラーから見て、workflowId によって識別される指定されたワークフロー内のユーザーに割り当てられているすべてのタスク (インスタンス ID、受信日、タスク名) を取得します。