Workflow Transition Tasks
Introduction
Workflow Transition Tasks are automated activities that execute when a document transitions from one Workflow State to another.
In previous versions, workflows only managed approvals (Approve/Reject/Move Forward). In Version 16, they have been extended so that when a transition occurs, the system can also execute automated actions such as:
Running backend scripts
Calling external APIs via webhooks
Executing pre-defined methods from apps
This allows workflows to be much more robust and aids in minimizing manual steps in business processes.
You can associate one or more Transition Tasks with each Workflow Transition so that you can add approvals with your own business logic.
A Typical Set of Transition Tasks
You can make a Workflow Transition Task execute any of the following types of actions:
App-Defined Actions – Predefined methods exposed by installed Frappe/ERPNext apps (controlled through hooks.py).
Server Scripts – Custom code directly in the ERPNext UI to perform certain logic.
Webhooks – External API calls that are invoked when the workflow transition occurs.
This allows approvals to be integrated both with internal automations (such as creating linked records) and external systems (such as pushing data to CRMs, HRMS, or other services).
A Server Script Transition Task
Transition tasks can execute in two modes:
Synchronous (Default):
Tasks execute sequentially as soon as the transition is started.
If one task fails, the whole transition is rolled back.
Example:
If your transition task is to "Create a Customer Record" and it fails, the approval will not be approved.
Asynchronous (Optional):
Triggered using the "Asynchronous" checkbox.
Tasks execute once the transition has finished, in the background.
These tasks do not block or impact the state change.
Example:
A webhook that informs Slack of an approval can be executed asynchronously so the approval is not held up.
This enables you to decouple important actions (need to succeed) from non-important actions (notifications, logs, integrations).
App-Defined Actions
Every Frappe app can implement custom workflow tasks using the workflow_methods hook in hooks.py.
These methods must take a doc: Document parameter, i.e., the document to be executed with the state transition.
Example:
Creating a custom action in an app
hooks.py
workflowmethods = [ { "name": "Create a customer", "method": "myapp.shop.doctype.kirana.createcustomer" } ]
myapp/shop/doctype/kirana.py
def createcustomer(doc): customer = frappe.newdoc("Customer") customer.customername = "Customer " + doc.name customer.customertype = "Individual" customer.save()
- This action will be accessible once created in the "Tasks" dropdown while setting up Workflow Transition Tasks.
⚠️ Note:
End users do not author app-defined actions themselves. They are forced to depend on developers to author them in apps. Server Scripts are the recommended choice for user-level customizations.
Server Scripts
Server Scripts allow you to perform custom logic without modifying app code.
Script Type: Workflow Task
Parameter: doc: Document (the document being transitioned).
- You can put in any Python logic such as validations, field updates, or creation of related records.
!
Example
Automatically assign a project manager when a Project is approved.
Update a custom status field on a related document.
Validate business rules before approving.
Once established, these scripts may be applied to a Workflow Transition Task just like app-defined actions.
Webhooks
Webhooks provide a means by which ERPNext can notify external systems about workflow transitions.
Build a Webhook with the Doc Event field as workflow_transition.
- Link this webhook to your Workflow Transition Task.
When transitioning, the webhook will trigger and submit the document data to the supplied external endpoint.
Some of the examples are:
Notify to enternal Hr system that employees leave is approved.
Push approved Purchase Orders to a third-party supplier API.
Send notifications to Slack, Microsoft Teams, or WhatsApp integrations.
Related Topics
- Workflow state
- Workflow actions
- Workflows