If you've ever needed to perform a bulk update, run a corrective script, or automate a complex domain operation, you've probably wished for one thing:
"Let me just run some JavaScript. Server-side."
Now you can.
Meet ExecuteScript a new Domain API endpoint that lets you execute raw JavaScript directly in the domain context, safely sandboxed and fully aware of your Domain Model.
No UI. No user business rule. No ceremony. Just JavaScript.
Let's unpack what this means and when you should use it.
What is ExecuteScript?
ExecuteScript is an unbound OData action exposed by the Domain API.
You invoke it with a simple HTTP POST, and the request body contains plain JavaScript source code. That code is executed server-side in a sandboxed runtime with access to the full Domain Model.
Inside the script, you can:
- Query domain data
- Create new objects
- Update existing records
- Delete data
- Log output via console.log
All of it runs in the same execution environment as ERP.net scripting, just without being tied to a specific document or event.
In short: this is on-demand server-side scripting via API.
The Endpoint
POST /api/domain/odata/ExecuteScriptThat's it. No parameters. No payload structure. No JSON wrapping.
The entire request body is treated as JavaScript.
Which brings us to an important warning,
The Request Body (Read This)
The request body must contain raw JavaScript text, UTF-8 encoded.
That means:
- It is not JSON
- There are no parameters
- The entire request stream is interpreted as JavaScript
If the body is empty or contains only whitespace, the action fails. Silently forgiving this would be irresponsible, so it doesn’t.
A Simple Example
Here's a minimal but realistic example that deactivates all active customers:
console.log('Starting script');
var customers = Domain.Crm.Sales.CustomersRepository.query({
active: { equals: true }
});
const customersCount = customers.length;
for (var i = 0; i < customersCount; i++) {
customers[i].Active = false;
}
console.log(`Processed ${customersCount} customers.`);Send this as the request body and the script runs server-side, applying changes in the domain context.
What Do You Get Back?
{
"ok": true,
"sessionId": "f3b2c8a7...",
"transactionId": "9d1a4e2c...",
"durationMs": 37,
"console": "Starting script\nProcessed 128 customers"
}Transaction behavior
ExecuteScript always runs in a transaction context. You can either control transactions from inside the script using the global Transaction object, or run inside an externally managed Domain API transaction by providing a TransactionId header. If the transaction is managed externally, the script should not call Transaction.begin(), Transaction.commit(), or Transaction.rollback() because those calls affect the same external transaction and can interfere with its lifecycle.
Example: internal transaction control
Transaction.begin();
try {
// ...make changes, validate conditions...
Transaction.commit(); // persist changes
} catch (e) {
Transaction.rollback(); // discard changes
Action.Cancel(e);
}Example: external transaction control (script runs inside an existing transaction)
POST /api/domain/odata/ExecuteScript
TransactionId: 9d1a4e2c...
Content-Type: text/plain
// Do NOT call Transaction.commit()/rollback() here.
// Changes stay in the external transaction until EndTransaction decides.When Should You Use ExecuteScript?
This endpoint is ideal for:
- One-off administrative or corrective operations
- Bulk data updates
- Automation and integration workflows
- Advanced tooling and DevOps-style scripts
- Controlled server-side execution without UI coupling
It is not a replacement for user business rules. It's a power tool. Treat it like one.
--
Get started
-
Domain API ExecuteScript
Execute raw JavaScript server-side via the Domain API, with access to the Domain Model, transaction control, and execution results. -
ERP.net Scripting documentation
Comprehensive guide to server-side JavaScript scripting in ERP.net, including runtime behavior, APIs, and best practices.
0 Comments