---
title: "Approval UID-backed Config"
description: "Rules for the approvalUid and taskCardUid fields on approval triggers and approval nodes."
---

# Approval UID-backed Config

Both the approval trigger and the approval node carry two UID-backed config fields:

| Field | Surface it points at | Where it lives |
|---|---|---|
| `approvalUid` | Initiator interface (trigger) / approver interface (node) | `workflow.config.approvalUid` (trigger) or `node.config.approvalUid` (node) |
| `taskCardUid` | Task card — "My Applications" (trigger) / "My Approvals" (node) | `workflow.config.taskCardUid` (trigger) or `node.config.taskCardUid` (node) |

These UIDs anchor a tree of UI schema records. They are normally generated by the UI when the user opens the relevant designer panel. When authoring the workflow programmatically (CLI / HTTP / agent), follow the rule below.

## v2 binding only

For approval UI authoring in this skill, use only `approvalUid` and `taskCardUid`:

- Approval trigger initiator UI: `workflow.config.approvalUid`.
- Approval node approver UI: `node.config.approvalUid`.
- Trigger/node task-card details: `workflow.config.taskCardUid` or `node.config.taskCardUid`.

Do **not** create or rely on legacy v1 bindings such as `workflow.config.applyForm` or `node.config.applyDetail`. Those fields do not satisfy v2 approval UI authoring and should be treated as failed validation for a newly built approval workflow. If a legacy workflow already has these fields, leave them untouched unless the user explicitly asks for migration, but still build and verify the v2 `approvalUid` surfaces for new work.

## Rule

For any UID-backed config value on an approval trigger or approval node:

1. **Keep the existing value if one is already present** in the source payload. Never overwrite a UID that the user (or an earlier authoring step) has already bound.
2. **If the value is missing**, generate one before persisting the config:
   - Resolve the shared helper path from [nocobase-utils UID generation](../../../nocobase-utils/references/uid/index.md) in the current workspace. Locate `skills/nocobase-utils/scripts/uid.js` directly — do not assume a document-relative path.
   - Run `node <resolved-path-to-uid.js>` and write the generated value into the config.
3. **Never leave placeholder strings** such as `uid-for-initiator-interface`, `uid-for-task-card`, or `uid-for-approval-interface` in the final payload.

## When the UID needs accompanying schema

Generating a UID only reserves the identifier. The actual UI schema underneath is built through the approval UI authoring routes. See [ui-config/index.md](ui-config/index.md) for route selection (`applyApprovalBlueprint` for first-time setup vs. localized `flowSurfaces` operations for incremental edits).

If you generate a UID but never wire schema beneath it, the corresponding surface will render empty at runtime.

For complete approval workflow setup, UID-backed schema is not optional:

- Trigger `approvalUid` should point to an initiator surface with an `approvalInitiator` / `ApplyFormModel` and the default submit action.
- Approval-node `approvalUid` should point to an approver surface with both `approvalInformation` / `ApprovalDetailsModel` for read-only original data and `approvalApprover` / `ProcessFormModel` for handling actions and approver-editable fields.
- `taskCardUid` improves "My Applications" / "My Approvals" card details, but it does not replace either `approvalUid` surface.

The binding must be saved on the owner config, not merely created as an unreferenced root. After initiator authoring, re-read the workflow and require `workflow.config.approvalUid`. After approver authoring, re-read each approval node and require `node.config.approvalUid`. If the field is absent or empty, the corresponding UI is detached from the approval runtime.
