Client Scripts (Custom JavaScript)
Client Scripts let you add your own JavaScript code that runs automatically inside AdmCloud screens, without modifying the product or relying on a custom development project. They're used to customize the behavior of a specific form (for example, calculating a value, showing or hiding a field, or validating something before saving) using the JavaScript API AdmCloud exposes for this purpose.
What is it and what is it for?
A Client Script is a piece of JavaScript code you save in AdmCloud so it's automatically injected into a given screen. There are two ways to use it:
- On Load (by object/screen): the mode available to end users. You pick the screen (for example, an invoice, an item, or any other card or transaction) and write different code for when that screen opens in Add, Edit or View mode. AdmCloud automatically runs that code every time any user in the selected group opens that screen.
- By Event: a single script triggered by a specific system event (for example, before or after saving, before or after a status change, or when scanning a barcode). This option can only be created by AdmCloud technical support staff or a Partner, since it's usually used for more advanced customizations or to package a behavior inside a Plugin.
This feature is meant for businesses that need very specific behavior AdmCloud doesn't offer natively, and that have someone (in-house or a Partner) able to write JavaScript using the API AdmCloud documents for this purpose.
How to use it
- Open the Client Scripts list. You'll see every existing script with its description, the screen (object) it applies to, its owner and whether it's marked as protected.
- Click "New" and choose "On Load". This is the option available to end users; "By Event" only shows up for AdmCloud technical support or Partners.
- Type a Name to identify the script in the list, and pick the Object (the system screen) where you want it to run.
- Write the JavaScript code in the editor for each form mode: when a record of that object is being Added, Edited or Viewed. You can leave the modes you don't need blank.
- Define who can use it and who can edit it: the User Group determines which users will have the script run when they open that screen; the Owner is responsible for the script; and the Protected checkbox restricts editing or deleting its structure to the owner only.
- Save. AdmCloud validates the information (see below) and, if everything checks out, the script becomes active immediately for the users in the selected group.
- Review, edit or delete an existing script from its detail view. If you're the owner and your plan allows it, you can also transfer it to another company of the same Partner, by entering the destination user's email.
A poorly written script can break the screen it's injected into. AdmCloud does not validate your code's syntax when you save it (the editor only highlights JavaScript syntax); an error in the code can prevent that form from loading correctly for every user in the affected group. Test it first with a small group of users.
Key capabilities
- Your own JavaScript code, automatically injected into the Add, Edit and View screens of a system object, without touching the product.
- Scope controlled by User Group, so the script only runs for the users it's meant for.
- A "Protected" script can only be edited or deleted by its owner, useful when it was installed by a Partner or a technician.
- "By Event" mode (reserved for technical support/Partners) to trigger code before or after saving, a status change, an employee assignment, or a barcode scan.
- Transfer a script to another company of the same Partner, to reuse the same customization across several customers.
- A direct link to the JavaScript API documentation AdmCloud exposes, so you know which functions and data you can use inside your script.
Key fields
| Field | What it's for |
|---|---|
| Name | The script's description, used to identify it in the list. It must be unique. |
| Object | The system screen (card or transaction) where the script will run in "On Load" mode. |
| User Group | Determines which users will have this script run when they open the selected screen. |
| Owner | The user responsible for the script; must be an active user. They're the one who can edit or delete it when it's marked Protected. |
| Protected | When checked, only the owner can modify or delete the script's structure. |
| Script on Add / Edit / View | The JavaScript code that runs when the chosen object's screen opens to create, edit or just view a record, respectively. |
| Event and Code | Only available in "By Event" mode: the system event that triggers the code, and the code itself. |
Validations when saving
- Name is required and can't be repeated with another Client Script's name.
- The Object (screen) must exist among the screens AdmCloud supports.
- For "By Event" scripts, the chosen event must be compatible with the selected object (for example, some status-change events only apply to Trips or Service Requests, and other events only to certain inventory screens).
- Owner is required and must be an active user in the system.
- A Protected script can only be edited or deleted by its owner; other users get a message that they don't have permission.
- A script can't be deleted if it's being used inside a Plugin; you must unlink it from the Plugin first.
Availability and permissions
- Creating, viewing, editing and deleting scripts requires the Customization permission in your user group.
- The "By Event" option only shows up for users with an AdmCloud admin/support role, technical manager, or Partner; end users can only create "On Load" scripts by object.
- Transferring a script to another company additionally requires the permission to create Plugins.
Tips and common mistakes
"You don't have permission to modify this script": shows up when the script is marked Protected and whoever is trying to edit or delete it isn't its owner. Ask the registered owner to make the change.
Can't delete the script: if the message says it's in use inside a Plugin, open that Plugin and remove the reference to the script before trying to delete it again.
Check the JavaScript API documentation before writing your code; the Client Scripts list has a direct link to that documentation with the functions and data available for your customizations.
Need your script to trigger on a system event (before/after saving, a status change, etc.) instead of simply when the form opens? That mode is configured by AdmCloud technical support or your Partner; reach out to them to evaluate your case.