Appearance
Customize an installed plugin
What you're doing
Making HCM, CRM or any installed plugin serve your business without modifying it. The original stays as shipped, so its upgrades stay safe. This is how SAP, Odoo, Dynamics 365, Salesforce and ERPNext work too.
Pick the lightest tool that does the job:
| You want to | Use |
|---|---|
| Change one label, hide or add one block on a shipped page | Layered override |
| Add your own data, screens, rules, workflows on top | Extend |
| Run your own logic when a record is saved | Extension point |
| Take over the whole plugin | Copy |
Extend it
Installed, Customize... , Extend. Studio starts a plugin of your own that depends on the installed one. The original keeps receiving updates. Your plugin declares the versions it works with (for example >=2.0.0 <3.0.0); the platform refuses to install it against another version. Only plugins with "extendable": true can be extended.
Copy it
Installed, Customize... , Copy. An editable copy under a new id at version 1.0.0, with the original's screens, data definitions and workflows (and Java source when the package shipped it). It is a fork: you merge later changes. It keeps the original's artifact names, so install it in place of the original. Compiled libraries and database migrations are not copied.
Layered overrides
Open the plugin's page, form or dashboard and choose Customize... (History tab). Add changes:
| Change | Effect |
|---|---|
| Change a setting | sets one value in a block, for example properties.text.value to Team roster |
| Remove | takes a block out |
| Replace | swaps a block |
| Add before / after | adds a block next to one |
| Add into a list | adds an item, such as a grid column |
Each change points at a block by its instance id. Check shows how many apply to the current version; Save changes stores them; Use the shipped version removes them. If an upgrade removes a block a change points at, that change is skipped, the page still works, and the editor lists it.
Extension points
A named moment where your own service steps in. Built in for every record: EntityRecordBeforeCreate, EntityRecordBeforeUpdate (return field values to merge), EntityRecordBeforeDelete (answer {"valid": false, "message": "..."} to stop it), and the informational After versions. Calls have a 2-second timeout and a circuit breaker; if your service fails the platform carries on. A plugin can declare its own points in plugin.json under extensionPoints. Binding a REPLACE point needs an elevated permission.
Upgrading a plugin that has extensions
Before an upgrade the platform checks each installed extension against the new version. If one is outside its declared range the upgrade stops and lists them. Upgrade those first, or use force (--force-upgrade in the CLI); it is recorded in the audit log.
Check it worked
Extension: it appears in Installed with its base named. Override: the page shows your change, and ?base=true on the page shows the shipped version.
Common mistakes
- Trying to edit a locked artifact: use Customize.
- Extending a plugin that is not
extendable: ask its publisher, or copy it.