Station 9 of 10
Customisation with and without code in ERPNext
What you leave this station with
The ability to place any customisation request on the correct rung of a five-rung ladder, and to execute the first four rungs without writing code.
Everything so far was using the system as it ships. This station asks: what do you do when that is not enough?
The answer surprises people. In most requests, you write nothing. The largest skill at this station is not writing; it is refusing to write when writing is not required.
Why this system is different here
Return to the idea this whole path opened on: everything is a doctype, and the doctype itself is data in the database rather than code in a file.
Fields, screens, workflows, reports and permissions are all rows in tables. The consequence is practical rather than theoretical: what you change from inside the interface survives the upgrade, because the upgrade updates code and does not wipe your data.
So “will my customisation survive?” has a clean answer here: it survives if it is data, and it needs maintenance if it is code. That alone explains why entire systems get built on this framework without forking it, and it is the strongest thing on this product’s side in the ERPNext guide.
The customisation ladder — five rungs, tried in order
The rule that governs this entire station: do not descend a rung until you have proved the one above it is insufficient.
| Rung | The tool | Code? | Survives the upgrade | When to use it |
|---|---|---|---|---|
| 1 | A custom field, or changing an existing field’s properties | No | Yes | A missing piece of information, or a field that must become mandatory |
| 2 | Screen layout, and customising lists and reports | No | Yes | “The screen is crowded”, or “the report is missing a column” |
| 3 | Workflow, approvals and permissions | No | Yes | “This document needs a manager’s approval” |
| 4 | Automation rules, print formats and alerts | No | Yes | “When this happens, do that” |
| 5 | A separate app on top of the framework | Yes | If it holds to the interfaces | Real calculation logic, or an external integration |
Note what is not on the table at all: editing inside ERPNext’s own files. That is not a rung on the ladder; it is stepping off it. Whoever edits the original buys pain at every upgrade for ever, and loses the single most valuable property of an open-source project — that somebody else maintains it for you.
The first four rungs — what you actually build
The custom field. Add one field to the sales order, make it mandatory, then create an order without filling it and read the objection. Then surface it in the list view. That is four requests out of every ten that reach development teams, all of them here, with no line of code.
Screen layout. Hide the fields your team does not use, and reorder the sections. Do not underrate this: a screen carrying forty fields of which the team uses eight is the commonest reason users reject a perfectly sound system. Adoption is a screen-design question before it is a training question.
Workflow. Define states and approval stages on one document — a purchase order above a threshold, for instance. Then exercise it from two different accounts. The difference between a system that is believed and one that is worked around is the presence or absence of a real approval.
The automation rule. Bind an event to an action: on submission, send an alert or update a field. Then read the execution log. The discipline rule here: every automation writes a log, and an automation whose effect appears nowhere readable is a fault waiting to happen.
The fifth rung — a separate app
When code is genuinely required, it is not written inside ERPNext; it is written in a separate app installed alongside it. That is the structure set out at station two: the framework, the app, the site, and the bench holding them together.
The effect on a project is large: your code lives in your repository, carries its own version, and can be removed. An app that cannot be removed without breaking the site is an app written wrongly.
Three rules govern this rung.
Extend, never modify. Add a new doctype, or hook your logic onto the events of existing documents, and do not change the behaviour of the original from within it.
All financial logic leaves a trace. Anything that touches entries must be readable in a report, because what is not read is not reviewed, and what is not reviewed is discovered at audit.
Do not write what the system already writes. Most of the code seen on real projects rebuilds an existing report, or a computed field available from the interface, or a permission set with two clicks.
The question to ask before every request
Before you execute any customisation request, ask in order:
- Is this a gap in the system or a gap in the procedure? Many requests are correctly described as “our team works in an odd way”, and their remedy is a procedure rather than a field.
- Who benefits, and what do they decide with this information? A request that changes no decision is a request to defer.
- What is the lowest rung on the ladder that satisfies it?
- Who maintains it in two years?
The fourth question is what separates a consultant from an implementer. Every customisation is a debt, and its interest is paid at every upgrade. Treat customisations as a free feature and you build a system nobody can upgrade three years later.
The practical rule that ends half the requests
Return to what you did at station seven: you built three reports from the interface with no code.
That is the answer to most of what reaches developers under the heading “we need a new report”. The test is simple: try building it in the interface first. Succeed in ten minutes and you have saved the project a week; fail and you now know why it needs code — and that knowledge is what you write into the request.
The three commonest errors
Customising before using. A team that asks for changes before it has run a full month. The rule: no customisation before three months of real operation, because half the requests fall away on their own once people acclimatise.
Customising without documentation. A field somebody added a year ago that nobody can account for, and which stays for ever because deleting it is frightening. Write one line for each customisation: who asked, why, and when it gets reviewed.
Copying customisations by hand from test to production. It works once, then the two environments diverge silently and every test becomes a lie. What is customised moves as one unit, never by pressing the same buttons again.
The acceptance test for this station
- Add a mandatory custom field to a document, and read the system’s objection when you leave it empty.
- Re-lay a screen by hiding what is not used, and count the fields before and after.
- Build a workflow with one approval and exercise it from two different accounts.
- Create an automation rule that fires an alert on an event, and verify its log.
- Take three real customisation requests — from your work or from user forums — and place each on its rung with a written reason. That table is a portfolio piece, and it is the closest thing you can show at a consulting interview.
What comes next
You know the system, you know its limits, and you know how to go past them with discipline. The last station converts all of it into something other people can see: an official certification with its published detail, a portfolio built out of the outputs of the previous nine stations, and a route to a first job.