プロセスコンテキストグラフの取得
プロセスコンテキストグラフは、プロジェクトのイベントログから構築された、プロセスの実際の実行状況を記述する1つのJSONドキュメントです。ケースとは何か、ケースの開始と終了、ステップおよびその間の手渡し、ケースがたどる経路、分岐点およびその分岐を説明するルール、問題が起きる箇所、処理にかかる時間、誰が何をするかを表します。すべての部分にはどれだけのデータに基づいているかが示されています。
「プロセスコンテキストグラフ」という名前は、市場で使われるものの標準はありません。mindzieが意味するのは、プロジェクトがすでに回答可能な内容から定義したデフォルトのもので、エージェントが読み込み、人間がチェックできる固定された形状で1つのドキュメントにまとめたものです。プロジェクトはグラフに格納されている以上の多くのことに答えられます。あなた自身のレポートとJSONはそれについてです。
2種類のエージェントがこのグラフを介してやり取りします。内部エージェント - プロジェクト内で動作するmindzieエージェント - は「Process Context Graph」レポートの実行時にこれを構築します。外部エージェント - あなた自身のコードで作ったエージェントで、ご自身のマシンからプロジェクトに単一の呼び出しで要求します。独自のエージェントを接続するでは、両者がどのように連携するかを図で説明しています。
利用目的
- エージェントが読み込みます。 プロセスに取り掛かる前に読み込むことで、実際のステップ名、通常経路、意思決定ポイントや例外を、一問一答で発見することなく把握できます。
- 人間がチェックします。 同じ内容がレポート画面にレポートとして出力され、プロセスマップ、説明された各意思決定に対する決定表、およびそれぞれの主張の証拠が並びます。レポートの表とJSONは同じデータから書き出されているため、異なる内容になることはありません。
これは説明にすぎません。推奨も何も提案せず、誰が何をしてよいかは示しません。
2段階で取得
ステップ1 - Process Context Graphレポートを一度実行する
画面上で: プロジェクトのReports(レポート)画面を開き、Process Context GraphカードのCreate reportをクリックし、次にStartをクリックします。Reportsをご覧ください。
独自エージェントから: プロジェクトが開始されデータがロードされた状態で、以下のコマンドでカードを見つけて開始します。
mz reports cards
mz jobs create-agent --card process-context-graph
mz jobs run --slug process-context-graph
mz jobs status --slug process-context-graph
mz jobs create-agent --cardはジョブのslugを返し、次の2つのコマンドはそれを使います。カードが一度も実行されていないプロジェクトでは process-context-graph です。実行はAIジョブで、プロジェクトのAIクレジットを消費します。終了するとレポートは他のレポートと同様にReports画面に自動公開されます。
待ち時間を想定してください。 160万件のイベント、約25万件のケースのログでは45分かかりました。その規模のログの場合は最大1時間程度を見ておくとよいでしょう。mz jobs statusはrunningからdoneに変わるまで進捗表示はありません。プロジェクトのジョブは1つずつ順番に実行されるため、それ以外のジョブは待機します。
後から再実行すると同じレポートの新しいバージョンが公開されます。以前のバージョンおよびJSONはそのまま残ります。
ステップ2 - 1回の呼び出しでグラフを取得する
mz reports context-graph > process-context-graph.json
プロジェクトの現在のプロセスコンテキストグラフをJSON形式でファイルに書き出します。最新の公開済みドキュメントで、形状名はmindzie.process-context-graphです。再計算もAIも使わず、すでに公開されているレポートを読み取るだけです。同一ドキュメントはカードが出力するファイルprocess-context-graph.jsonと同じなので、mz reports attachment --slug process-context-graph --name process-context-graph.jsonでも全く同じバイトを取得できます。
プロジェクトで一度もレポートが実行されていない場合は呼び出しが拒否され、（ステップ1の）レポート実行コマンドを案内します。実行は自動で開始しません。これはAIクレジット消費を防ぐためです。
Windowsではコマンドプロンプトで実行してください。PowerShellは>でファイルに送るテキストを再エンコードするためです。ファイルを定義と照合する方法は以下の「グラフを自分で検証」参照。エージェント側でmzとキーを取得する方法は独自のエージェントを接続するにあります。
実際の例
以下のグラフは、実際の購入から支払いまでのログからProcess Context Graphカードが作成したものです：1,593,532イベント、251,658ケース（1ケースは1購入注文の1行アイテム）。JSONは約300KBで44ステップ、188手渡し、16バリアント、25意思決定ポイント、48シーケンスルール、48例外、4エスカレーション、25ポリシー、20仮定、7未解決質問を含み、このページ末尾の定義を満たしています。
図として描画
この図はJSONから短いスクリプトで直接描いたもので、内容を示しています。ステップと最も多忙な手渡し（ケースの少なくとも4%以上が通る）をグラフのステージ別に表示し、手渡しされたケース数と典型的な待機時間を示しています。太線は主要フロー、破線はその他経路、赤破線は例外とグラフがマークした部分です。読み取るとアイテムの72%はClear Invoiceで終了し、最も長い典型的待機はinvoice receiptからclearingまでの36日であることがわかります。
短縮したJSON
受け取ったエージェントの形です。ほとんどのリストは1件に切り詰め、22の部分中14は省略されています（最後の行参照）。すべての主張には証拠が付帯しています：いくつのケース、その内数、測定方法、強度など。
{
"schema": "mindzie.process-context-graph",
"schema_version": "1.0",
"source": {
"data_version": "v0001",
"log_digest": "4804d5916fc0",
"case_notion": "one purchase order line item (purchase order number plus item number)",
"cases": 251658,
"events": 1593532,
"period_start": "2015-03-08",
"period_end": "2020-04-09",
"time_basis": "clock"
},
"success_criteria": [
{
"id": "sc:cleared",
"statement": "The item is paid: the case ends with Clear Invoice.",
"test": "last event of the case is Clear Invoice",
"share_met": 0.7203,
"evidence": {
"cases": 181257,
"of_cases": 251658,
"share": 0.7203,
"strength": "counted",
"method": "direct count of cases whose last event is Clear Invoice"
}
}
],
"outcomes": [
{
"id": "out:clear-invoice",
"end_activity": "Clear Invoice",
"kind": "success",
"cases": 181257,
"share": 0.7203
},
{
"id": "out:record-invoice-receipt",
"end_activity": "Record Invoice Receipt",
"kind": "open",
"cases": 23089,
"share": 0.0917
}
],
"edges": [
{
"id": "edge:record-invoice-receipt>clear-invoice",
"from": "act:record-invoice-receipt",
"to": "act:clear-invoice",
"kind": "normal",
"cases": 132667,
"share_of_from": 0.6575,
"median_wait_hours": 865.617,
"slow_wait_hours": 2479.663,
"evidence": {
"cases": 132667,
"of_cases": 211303,
"share": 0.6279,
"strength": "counted",
"method": "cases with this hand-off at least once, out of cases with the first step; shares of the first step count every visit"
}
}
],
"decisions": [
{
"id": "dec:block-purchase-order-item",
"at": "act:block-purchase-order-item",
"branches": [
{
"to": "end",
"cases": 163,
"share": 0.3417
},
{
"to": "act:delete-purchase-order-item",
"cases": 131,
"share": 0.2746
},
{
"to": "act:reactivate-purchase-order-item",
"cases": 111,
"share": 0.2327
},
{
"to": "act:change-quantity",
"cases": 72,
"share": 0.1509
}
],
"baseline_share": 0.3417,
"rules": [
{
"id": "rule:block-purchase-order-item-1",
"when": [
"Spend area is not Trading & End Products",
"Order value (EUR) is above 502.5 and up to 2884.5"
],
"then": "act:delete-purchase-order-item",
"cases": 113,
"holds": 0.708,
"evidence": {
"cases": 80,
"of_cases": 113,
"share": 0.708,
"strength": "weak",
"method": "rule fitted by a decision tree on the hand-offs counted here; share is how often the next step matched"
}
}
],
"explained": true,
"evidence": {
"cases": 477,
"of_cases": 499,
"share": 0.6688,
"strength": "weak",
"method": "first visit of the step in each case; rules score 67% against 34% for always guessing the commonest next step; explained needs at least 10 points more"
}
}
],
"policies": [
{
"id": "pol:create-purchase-order-item-record-goods-receipt-within-30-days",
"kind": "service_level",
"statement": "Possible service level, inferred: Create Purchase Order Item -> Record Goods Receipt within 30 days (88% of 74,809 cases finish inside it; 8.1% finish in the quarter of the limit just inside it, 4.0% just outside)",
"threshold_hours": 720.0,
"share_met": 0.8839,
"evidence": {
"cases": 66126,
"of_cases": 74809,
"share": 0.8839,
"strength": "hypothesis",
"method": "share of positive waits at or under the limit; a limit counts when at least half of the waits meet it and twice as many fall in the quarter just inside it as just outside it"
}
}
],
"...": "and 14 more parts"
}
各部分の内容
| 部分 | 内容 |
|---|---|
source |
グラフ構築に用いたデータ：データバージョン、読み込んだログ、ケースの概念、ケース数、イベント数、期間、時刻の基準（稼働時間か時計時間か） |
process |
1ケースが何を表し、プロセスが何のためと思われるか |
success_criteria |
成功したケースの判定方法および各判定の達成ケース割合 |
outcomes |
ケースの終了パターンとそれぞれのケース数・割合 |
stages |
ケースが通過する段階と各段階のアクティビティ |
nodes |
アクティビティひとつごとと開始・終了ノードの情報：ケース数、イベント数、繰り返し、次ステップまでの典型時間、担当役割 |
edges |
手渡しひとつごと：ケース数、割合、待機時間の中央値と最長ケースの待機時間 |
variants |
メイン経路、許容されるバリエーション、ケース数が1%未満の例外経路 |
model |
経路から発見したプロセスモデルと受け入れるケース割合 |
decisions |
ケースが分岐するポイントの分岐枝分かれと、その分岐を説明するif-thenルール（存在する場合） |
sequence_rules |
ほぼ常に成り立つ順序ルールと各ルールが成り立つケース割合 |
exceptions |
繰り返し、スキップ、順序違反のステップ、稀なアクティビティ、失敗した終了 |
escalations |
長時間待機や失敗後に主に現れるステップ |
policies |
ほとんどのケースが制限内に収まる時間制限と達成割合 |
roles |
ログに実行者が記録されている場合、どの役割がどのアクティビティを担当したか |
object_types, object_relations |
オブジェクト中心ログ向けに、オブジェクトの種類と関係 |
evidence_levels |
証拠強度の5ラベル、それぞれの定義 |
assumptions, open_questions |
作業開始前に決まったこと、計測できなかったこと、読者が調査すべきこと |
カウントは整数、割合は0から1の数値、時間は時間単位です。すべての部分はすべてのグラフに含まれ、内容がなければ空リストであり欠落はありません。値がnullになることはありません。
一部はコードにより厳密にカウントされ（同じデータで再実行すれば同じ数値）、その他はデータの読み取りです—ケースの意味、成功判定、段階の位置など。レポートはどちらかを明示します。
各部分の信頼度
主張を持つすべての部分は1つのevidenceオブジェクトを有し、その根拠：対象ケース数、適用可能なケース数、成立割合、測定方法と強度ラベルを示します。
| ラベル | 意味 |
|---|---|
counted |
ログからの直接カウント |
strong |
適用ケースの95%以上で成り立ち、対象ケースが100件以上ある |
moderate |
80%以上のケースで成り立ち、対象ケースが30件以上ある |
weak |
それ以下のすべて |
hypothesis |
アクティビティ名やタイミングから読み取った仮説、ルールとしては検証されていない |
強度ラベルをまず見てください。countedはログの事実、hypothesisは検証する価値のあるアイデアです。
完全定義
形状は固定されバージョン管理されています。これはバージョン1.0で、一度合格したドキュメントは永続的に合格扱いです。フィールドの変更は新しいバージョンとなり、それ用のスキーマファイルが別途用意されます。
mindzie.process-context-graph-1.0.schema.jsonをダウンロード
スキーマファイルはJSON Schema（draft-07）で表現された完全な形状であり、任意のバリデーターで検証可能です。グラフのレポート公開時に必ず検証されます：形状に合致しないグラフは公開されず、理由は問題部分名と不備内容になります。
グラフを自分で検証する
スキーマファイルとグラフを隣に置き、任意のJSON Schemaバリデーターで検証してください。Pythonでは以下をcheck_graph.pyとして保存してください。
import json
import jsonschema
with open("process-context-graph.json", encoding="utf-8") as file:
graph = json.load(file)
with open("mindzie.process-context-graph-1.0.schema.json", encoding="utf-8") as file:
schema = json.load(file)
jsonschema.validate(graph, schema)
print("valid")
実行します:
pip install jsonschema
python check_graph.py
検証に合格するとvalidと表示され、合わなければ該当する部分で止まります。プロジェクトはレポート公開時に必ず検証しているため、公開済みのグラフは必ず合格します。
次に
- 独自のエージェントを接続する - キーを作り、文を1つ貼り付けて、プロジェクトを自分のエージェントに渡します。
- あなた自身のレポートとJSON - デフォルトを超えて、同じ方法で自分のレポートとJSONファイルを作成します。
- Cubeのツールボックス - グラフの構築に使われるツールおよびその他のツール群。