Server Scripts

What is it and what is it for?

A Server Script is a piece of C# code you attach to a system Object (for example, Service Requests or Trips) and a specific Event in its lifecycle (Before Save, After Save, and for some objects also before/after a status change or an employee assignment). When a user saves a transaction of that type, AdmCloud runs your script automatically on the server, with access to the record being saved.

This lets you implement business rules that are very specific to your company — which AdmCloud doesn't offer natively — without relying on a custom development of the product: validating a field's format, requiring a particular combination of data, or rejecting the transaction with your own error message if a condition isn't met.

How to use it

1. Create a new script (Create button) and give it a unique Name that helps you identify it later.
2. Select the Object where it will run (for example, Service Requests or Trips) and the Event that triggers it (Before Save, After Save, or one of the additional events available for that object).
3. Write the C# code in the syntax-highlighted editor. Inside the script you have the record variable available, representing the record being saved, to read or enforce conditions on its fields. For example:
   if (record.SKU.Length != 3) throw new ApplicationException("The code's length must be 3 characters");
4. Check "Protected" if you want only you (the Owner) to be able to edit it later; otherwise, any other user with edit permission will be able to modify it.
5. Save the script and test it by saving a transaction of the configured Object and Event, to confirm it behaves as expected before letting other users rely on it.
6. View, edit or delete the script from the list or its Details screen, which also shows the audit log of who created, edited or deleted it.

Key capabilities

• It runs automatically on the server, inside the same transaction that saves the record: if the script throws an error, the whole operation is rolled back.
• For most system objects you can hook into the Before Save and After Save events.
• For Service Requests and Trips you can also hook into before/after a status change and before/after an employee assignment.
• The script can raise your own error message (with throw new ApplicationException("...")) that the user sees directly on screen when trying to save.
• You can flag a script as Protected so only its Owner can modify it, preventing accidental changes from other users.
• Audit log on the Details screen showing who created, edited or deleted the script.

Key fields

Validations on save

• Name is required and must be unique — it can't already exist on another script.
• Object and Event are required, and their combination must be supported: for most objects only the Before Save and After Save events are allowed; the status-change and employee-assignment events are only available for Service Requests and Trips. Choosing an unsupported combination is rejected.
• Owner is required and must be an active user.
• Only the Owner can edit a script flagged as Protected; if another user tries, the change is rejected.
• A script that existing Plugins depend on can't be deleted; the system shows you which ones.
• The code can only use what scripts are allowed to use (see "Execution limits and security"); if it uses something that isn't allowed, saving is rejected, showing which element and on which line.
• If your C# code throws an ApplicationException while running against a real transaction, the user who was saving sees that message and the operation isn't completed; any other type of error also stops the operation, showing a generic message.

Availability

• Browsing and viewing the detail of Server Scripts requires the "Customization" permission on your user group, plus having the feature enabled for your company.
• The full feature requires the Enterprise plan.
• Creating, editing or transferring a script to another company is restricted to users flagged as "For Technical Support", because a poorly written script affects every transaction of the object it runs on.
• Deleting a script requires the matching permission level, and isn't allowed while the script is in use by a Plugin.

Execution limits and security

Scripts run on the same servers every company uses, so AdmCloud applies these controls to them. They also apply to numbering formulas and to payroll concept formulas.

• Maximum of 5 seconds per execution. If the script exceeds it (for example, because of a loop that never ends), AdmCloud stops it and the transaction isn't saved.
• Maximum call depth. If a function calls itself endlessly, AdmCloud stops it before it affects the server.
• Regular expressions with a time limit. You can use Regex to validate formats (tax IDs, fiscal receipt numbers, emails...); each match stops if it takes more than 1 second (RegexMatchTimeoutException).
• You can use the data in record, the basic C# types (numbers, text, dates, Math, Convert, Guid), System.Text and System.Globalization, lists and dictionaries, LINQ (method syntax or from ... select), local functions, lambdas, goto, and your own classes, structs, interfaces and enums. Also Environment.NewLine, Console.WriteLine and Debug.WriteLine.
• Not allowed: accessing files, the network, processes, threads or the server configuration (System.IO, System.Net, System.Diagnostics, System.Threading, the rest of Environment, GC), reflection (typeof, GetType(), Type), lock, async / await, and the #r / #load directives. In your classes, static fields, auto-properties and events (use const), static constructors, finalizers (~Class()) and record types aren't allowed.
• Existing scripts are also checked before each execution: if they use something that isn't allowed, the transaction isn't saved and the element and line to fix are shown.
• If a line starts with record. (for example record.Notes = "...";), write it as @record.Notes = "...";: in recent C# versions record is a reserved word at the start of a statement. Inside a condition (if (record.Total > 0)) it isn't needed.

Tips and common mistakes