#Approval

#Introduction

Approval is a process type specifically designed for human-initiated and human-processed tasks to decide the status of relevant data. It is commonly used for office automation or other manual decision-making processes, such as creating and managing manual workflows for scenarios like "leave requests," "expense reimbursement approvals," and "raw material procurement approvals."

The Approval plugin provides a dedicated workflow type (trigger) "Approval (event)" and a dedicated "Approval" node for this process. Combined with NocoBase's unique custom collections and custom blocks, you can quickly and flexibly create and manage various approval scenarios.

#Create a Workflow

When creating a workflow, select the "Approval" type to create an approval workflow:

Afterward, in the workflow configuration interface, click the trigger to open a dialog for more configuration.

#Trigger Configuration

#Bind a Collection

NocoBase's Approval plugin is designed for flexibility and can be used with any custom collection. This means the approval configuration does not need to reconfigure the data model but directly reuses an existing collection. Therefore, after entering the trigger configuration, you first need to select a collection to determine which collection's data creation or update will trigger this workflow:

Then, in the form for creating (or editing) data for the corresponding collection, bind this workflow to the submit button:

After that, when a user submits this form, the corresponding approval workflow will be triggered. The submitted data is not only saved in the corresponding collection but is also snapshotted into the approval flow for subsequent approvers to review and use.

#Withdraw

If an approval workflow allows the initiator to withdraw it, you need to enable the "Withdraw" button in the initiator's interface configuration:

Once enabled, an approval initiated by this workflow can be withdrawn by the initiator before any approver processes it. However, after any approver in a subsequent approval node has processed it, it can no longer be withdrawn.

#Initiator's Form Interface Configuration

Finally, you need to configure the initiator's form interface. This interface will be used for submission actions when initiating from the approval center block and when re-initiating after a withdrawal. Click the configure button to open the dialog:

You can add a form for the initiator's interface based on the bound collection, or add descriptive text (Markdown) for prompts and guidance. The form is mandatory; otherwise, the initiator will not be able to perform any actions upon entering this interface.

After adding a form block, just like in a regular form configuration interface, you can add field components from the corresponding collection and arrange them as needed to organize the content to be filled in the form:

In addition to the direct submit button, you can also add a "Save as Draft" action button to support a temporary storage process:

#Approval Node

In an approval workflow, you need to use the dedicated "Approval" node to configure the operational logic for approvers to process (approve, reject, or return) the initiated approval. The "Approval" node can only be used in approval workflows. Refer to Approval Node for details.

#Configure Approval Initiation

After configuring and enabling an approval workflow, you can bind it to the submit button of the corresponding collection's form, allowing users to initiate an approval upon submission:

After binding the workflow, when a user submits the current form, an approval is initiated.

#To-do Center

The To-do Center provides a unified entry point for users to view and process their to-do tasks. Approvals initiated by the current user and their pending tasks can be accessed through the To-do Center in the top toolbar, and different types of to-do tasks can be viewed through the navigation on the left.

#My Submissions

#View Submitted Approvals

#Directly Initiate a New Approval

#My To-dos

#To-do List

#To-do Details

#HTTP API

#Initiator

#Initiate from Collection

To initiate from a data block, you can make a call like this (using the create button of the posts collection as an example):

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

Here, the URL parameter triggerWorkflows is the workflow's key; multiple workflow keys are separated by commas. This key can be obtained by hovering the mouse over the workflow name at the top of the workflow canvas:

Upon a successful call, the approval workflow for the corresponding posts collection will be triggered.

If you need to trigger an event for one-to-one related data in this action (one-to-many is not yet supported), you can use ! in the parameter to specify the trigger data for the association field:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post.",
    "category": {
      "title": "Test category"
    }
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey!category"

Upon a successful call, the approval event for the corresponding categories collection will be triggered.

#Initiate from Approval Center

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "collectionName": "<collection name>",
    "workflowId": <workflow id>,
    "data": { "<field>": "<value>" },
    "status": <initial approval status>,
  }'
  "http://localhost:3000/api/approvals:create"

Parameters

• collectionName: The name of the target collection for initiating the approval. Required.
• workflowId: The ID of the workflow used to initiate the approval. Required.
• data: The fields of the collection record created when initiating the approval. Required.
• status: The status of the record created when initiating the approval. Required. Possible values include:
  • 0: Draft, indicates saving without submitting for approval.
  • 1: Submit for approval, indicates the initiator submits the approval request, entering the approval process.

#Save and Submit

When an initiated (or withdrawn) approval is in a draft state, you can save or submit it again through the following API:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "data": { "<field>": "<value>" },
    "status": 2
  }'
  "http://localhost:3000/api/approvals:update/<approval id>"

#Get List of Submitted Approvals

curl -X GET -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/approvals:listMine"

#Withdraw

The initiator can withdraw a record currently in approval through the following API:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  "http://localhost:3000/api/approvals:withdraw/<approval id>"

Parameters

• <approval id>: The ID of the approval record to be withdrawn. Required.

#Approver

After the approval workflow enters an approval node, a to-do task is created for the current approver. The approver can complete the approval task through the interface or by calling the HTTP API.

#Get Approval Records

To-do tasks are approval records. You can get all of the current user's approval records through the following API:

curl -X GET -H 'Authorization: Bearer <your token>' \
  "http://localhost:3000/api/approvalRecords:listMine"

Here, approvalRecords is a collection resource, so you can use common query conditions such as filter, sort, pageSize, and page.

#Get a Single Approval Record

curl -X GET -H 'Authorization: Bearer <your token>' \
  "http://localhost:3000/api/approvalRecords:get/<record id>"

#Approve and Reject

curl -X POST -H 'Authorization: Bearer <your token>' -d \
  '{
    "status": 2,
    "comment": "Looks good to me.",
    "data": { "<field to modify>": "<value>" }
  }'
  "http://localhost:3000/api/approvalRecords:submit/<record id>"

Parameters

• <record id>: The ID of the record to be approved. Required.
• status: The status of the approval process. 2 for "Approve", -1 for "Reject". Required.
• comment: Remarks for the approval process. Optional.
• data: Modifications to the collection record at the current approval node after approval. Optional (only effective upon approval).

#Return v1.9.0+

Before v1.9.0, returning used the same API as 'Approve' and 'Reject', with "status": 1 representing a return.

Starting from v1.9.0, returning has a separate API:

curl -X POST -H 'Authorization: Bearer <your token>' -d \
  '{
    "returnToNodeKey": "<node key>",
  }'
  "http://localhost:3000/api/approvalRecords:return/<record id>"

Parameters

• <record id>: The ID of the record to be approved. Required.
• returnToNodeKey: The key of the target node to return to. Optional. When a range of returnable nodes is configured in the node, this parameter can be used to specify which node to return to. If not configured, this parameter does not need to be passed, and it will default to returning to the starting point for the initiator to resubmit.

#Delegate

curl -X POST -H 'Authorization: Bearer <your token>' -d \
  '{
    "assignee": <user id>,
  }'
  "http://localhost:3000/api/approvalRecords:delegate/<record id>"

Parameters

• <record id>: The ID of the record to be approved. Required.
• assignee: The ID of the user to delegate to. Required.

#Add Signer

curl -X POST -H 'Authorization: Bearer <your token>' -d \
  '{
    "assignees": [<user id>],
    "order": <order>,
  }'
  "http://localhost:3000/api/approvalRecords:add/<record id>"

Parameters

• <record id>: The ID of the record to be approved. Required.
• assignees: A list of user IDs to add as signers. Required.
• order: The order of the added signer. -1 means before "me", 1 means after "me".