ユーザーフォーム
User Forms のドキュメント
User Forms
ベースパス: /api/v1/user-forms
ユーザーフォームは、続行前に人間のレビューを必要とするワークフローステップによって生成される human-in-the-loop 承認/レビューフォームです。ワークフローステップが人間入力ステップとして設定されると、実行が一時停止しレビュー用フォームが作成されます。
エンドポイント概要
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/user-forms | JWT | 認証済みユーザーのフォームを一覧 |
| GET | /api/v1/user-forms/:formId | None | フォーム HTML コンテンツを取得 |
| POST | /api/v1/user-forms/:activityRunId/:status | None | フォームの承認/却下を送信 |
GET /api/v1/user-forms
認証済みユーザーが所有するワークフローの全ユーザーフォームを一覧します。
認証
JWT が必要です（authMiddleware + activeOrgPreferenceMiddleware）。
クエリパラメータ
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | ページ番号（最小: 1） |
limit | number | 20 | 1 ページあたり件数（最小: 1、最大: 100） |
search | string | – | ワークフロー名で検索（大文字小文字を区別しない） |
sortBy | string | "createdAt" | ソートフィールド: createdAt、updatedAt、workflowName、status |
sortOrder | string | "desc" | ソート方向: asc、desc |
status | string | – | ステータスでフィルター: pending、approved、rejected |
レスポンス 200 OK
フォームオブジェクトフィールド:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | フォーム ID |
workflowId | string (UUID) | 関連ワークフロー ID |
workflowName | string | ワークフロー名 |
workflowDescription | string | null | ワークフローの説明 |
workflowRunId | string (UUID) | このフォームを作成したワークフロー実行 |
activityRunId | string (UUID) | このフォームで一時停止したアクティビティ（ステップ）実行 |
workflowStepName | string | 承認が必要なステップ名 |
workflowStepDescription | string | null | ステップの説明 |
status | "pending" | "approved" | "rejected" | レビューステータス |
reviewedBy | string | null | レビュアーのユーザー ID（レビュー済みの場合） |
reviewedAt | string (ISO 8601) | null | フォームがレビューされた日時 |
createdAt | string (ISO 8601) | フォーム作成日時 |
updatedAt | string (ISO 8601) | 最終更新日時 |
GET /api/v1/user-forms/:formId
ユーザーフォームの HTML コンテンツを返します。このエンドポイントは 公開 です（認証不要）— フォームはレビュアーに送られるリンク経由でアクセスされます。
認証
不要（一意のフォーム ID 経由で公開アクセス可能）。
パスパラメータ
| Parameter | Type | Description |
|---|---|---|
formId | string (UUID) | フォーム ID |
レスポンス 200 OK
| Field | Type | Description |
|---|---|---|
html | string | ブラウザで描画可能なフォームの HTML 定義 |
使用パターン
フォームは通常 iframe で描画するか、新しいブラウザタブで開きます。HTML には approve/reject エンドポイントへ送信するフォームが含まれます。
POST /api/v1/user-forms/:activityRunId/:status
フォームの承認または却下を送信します。一時停止中のワークフローをフォームデータで再開します。このエンドポイントは 公開 です — レビュアーがフォーム内の承認/却下をクリックして送信します。
認証
不要（フォームリンクが認可として機能します）。
パスパラメータ
| Parameter | Type | Description |
|---|---|---|
activityRunId | string (UUID) | フォームに関連するアクティビティ実行 ID |
status | "approve" | "reject" | 承認決定 |
リクエストボディ（multipart/form-data）
レビュアーが入力した任意のフォームフィールド値。ファイルフィールドは自動的にオブジェクトストレージにアップロードされ、送信データ内のファイルはプリサイン URL に置き換えられます。
レスポンス
送信確認の HTML ページを返します。
- 成功時: 「Form Submitted Successfully」の成功ページ
- 既に送信済み: 「Form Already Submitted」の情報ページ
どちらの場合も HTTP ステータスは 200 OK です（ブラウザ遷移向け HTML レスポンス）。
エラー
| Status | Reason |
|---|---|
404 Not Found | アクティビティ実行またはワークフロー実行が見つからない |
500 Internal Server Error | ワークフローに Temporal ワークフロー関連付けがない |
ワークフロー連携に関する注記
ユーザーフォームは以下の場合にワークフロー実行中に表示されます。
- ワークフローステップの定義で
is_human_input_step: trueである - エグゼキューターが Temporal ワークフローを一時停止しフォームレコードを作成する
- フォームリンクがレビュアーに通知される（通常メールまたは通知）
- レビュアーがフォームを送信し、Temporal シグナルで実行を再開する
フォームデータ（レビュアー入力を含む）は後続処理のステップ入力としてワークフローステップへ渡されます。