Scripting API

The designer and React runtime cover the standard CRUD, form, filter, and export workflows. Use the scripting API when an interceptor, action, or custom endpoint needs server-side JavaScript.

The Low-Code System provides a server-side JavaScript scripting engine for executing custom business logic within interceptors, custom endpoints, event handlers, background jobs, and background workers. Scripts run in a sandboxed environment with access to a database API backed by EF Core.

Scripts are wrapped in an async function, so await and top-level return are supported.

Designer Code Editor

JavaScript fields in the Low-Code Designer use a code editor with syntax highlighting and low-code-aware autocomplete. The editor is available for interceptors, custom endpoints, event handlers, background jobs, and background workers.

The Available context list shows the globals enabled for the current script type. The list is based on the scripting capability profile, so an application can disable services such as HTTP, email, files, or background jobs for a specific script type.

Autocomplete covers:

• Common globals such as db, currentUser, emailSender, http, events, and jobs
• Endpoint, event handler, background job, background worker, and interceptor context variables
• Dynamic entity names in db.query(...), db.get(...), file, image, and attachment helpers
• Dynamic entity properties inside query lambda parameters and query results
• Enum names and values through enums and enumValues
• File and image field selectors through fileFields and imageFields

fileFields is intentionally limited to File properties and imageFields is limited to Image properties. They are safe selector trees for file and image helpers, not lists of every entity property.

await files.save(fileFields.Acme.Campaigns.Campaign.Document, {
    fileName: 'brief.pdf',
    contentType: 'application/pdf',
    base64: base64Content
});

Unified Database API (db)

The db object is the main entry point for all data operations.

Key Design Principles

• Immutable Query Builder — each query method returns a new builder instance. The original is never modified.
• Database-Level Execution — all operations (filters, aggregations, joins, set operations) translate to SQL via EF Core and Dynamic LINQ.
• No in-memory processing of large datasets.

db.query(entityName) is asynchronous. Always await it before chaining query methods, and await the terminal operation such as toList(), count(), first(), or sum().

// Immutable pattern — each call creates a new builder
var baseQuery = (await db.query('Entity')).where(x => x.Active);
var cheap = baseQuery.where(x => x.Price < 100);     // baseQuery unchanged
var expensive = baseQuery.where(x => x.Price > 500);  // baseQuery unchanged

Query API

Basic Queries

var productQuery = await db.query('LowCodeDemo.Products.Product');
var products = await productQuery
    .where(x => x.Price > 100)
    .orderBy(x => x.Price)
    .take(10)
    .toList();

var filteredProductQuery = await db.query('LowCodeDemo.Products.Product');
var result = await filteredProductQuery
    .where(x => x.Price > 100 && x.Price < 500)
    .where(x => x.StockCount > 0)
    .orderByDescending(x => x.Price)
    .skip(10)
    .take(20)
    .toList();

Query Methods

Supported Operators in Lambda

Variable Capture

External variables are captured and passed as parameters:

var minPrice = 100;
var config = { minStock: 10 };
var nested = { range: { min: 50, max: 200 } };

var query = await db.query('Entity');

var result = await query.where(x => x.Price > minPrice).toList();
var result2 = await query.where(x => x.StockCount > config.minStock).toList();
var result3 = await query.where(x => x.Price >= nested.range.min).toList();

Contains / IN Operator

var targetPrices = [50, 100, 200];
var query = await db.query('Entity');
var products = await query
    .where(x => targetPrices.includes(x.Price))
    .toList();

Select Projection

var productQuery = await db.query('LowCodeDemo.Products.Product');
var projected = await productQuery
    .where(x => x.Price > 0)
    .select(x => ({ ProductName: x.Name, ProductPrice: x.Price }))
    .toList();

Joins

Explicit Joins

var orderLineQuery = await db.query('LowCodeDemo.Orders.OrderLine');
var orderLines = await orderLineQuery
    .join('LowCodeDemo.Products.Product', 'p', (ol, p) => ol.ProductId === p.Id)
    .take(10)
    .toList();

// Access joined data via alias
orderLines.forEach(line => {
    var product = line.p;
    context.log(product.Name + ': $' + line.Amount);
});

Left Join

var orderQuery = await db.query('LowCodeDemo.Orders.Order');
var orders = await orderQuery
    .leftJoin('LowCodeDemo.Customers.Customer', 'c', (o, c) => o.CustomerId === c.Id)
    .toList();

orders.forEach(order => {
    if (order.c) {
        context.log('Has match: ' + order.c.Name);
    }
});

LINQ-Style Join

var orderLineQuery = await db.query('LowCodeDemo.Orders.OrderLine');
orderLineQuery
  .join('LowCodeDemo.Products.Product',
        ol => ol.ProductId,
        p => p.Id)

Join with Filtered Query

var productQuery = await db.query('LowCodeDemo.Products.Product');
var expensiveProducts = productQuery.where(p => p.Price > 100);

var orderLineQuery = await db.query('LowCodeDemo.Orders.OrderLine');
var orderLines = await orderLineQuery
  .join(expensiveProducts,
        ol => ol.ProductId,
        p => p.Id)
  .toList();

Set Operations

Set operations execute at the database level using SQL:

var productQuery = await db.query('LowCodeDemo.Products.Product');
var cheap = productQuery.where(x => x.Price <= 100);
var inStock = productQuery.where(x => x.StockCount > 0);

var affordableInStock = await cheap.intersect(inStock).toList();
var soldOutBudgetItems = await cheap.except(inStock).toList();

Aggregation Methods

All aggregations execute as SQL statements:

var productQuery = await db.query('LowCodeDemo.Products.Product');

var totalValue = await productQuery.sum(x => x.Price);
var avgPrice = await productQuery.where(x => x.StockCount > 0).average(x => x.Price);
var cheapest = await productQuery.min(x => x.Price);

GroupBy with Select

var campaignQuery = await db.query('LowCodeDemo.ContentStudio.Campaign');
var grouped = await campaignQuery
    .groupBy(x => x.Status)
    .select(g => ({
        Status: g.Key,
        Count: g.count(),
        TotalBudget: g.sum(x => x.Budget),
        AvgBudget: g.average(x => x.Budget),
        MinBudget: g.min(x => x.Budget),
        MaxBudget: g.max(x => x.Budget)
    }))
    .toList();

GroupBy Aggregation Methods

GroupBy with Items

var campaignQuery = await db.query('LowCodeDemo.ContentStudio.Campaign');
var grouped = await campaignQuery
    .groupBy(x => x.Status)
    .select(g => ({
        Status: g.Key,
        Count: g.count(),
        Items: g.take(10).toList()
    }))
    .toList();

GroupBy Security Limits

Math Functions

Math functions translate to SQL functions (ROUND, FLOOR, CEILING, ABS, etc.):

var productQuery = await db.query('LowCodeDemo.Products.Product');
var products = await productQuery
    .where(x => Math.round(x.Price) > 100)
    .toList();

var result = await productQuery
    .where(x => Math.abs(x.StockCount) < 10 && Math.floor(x.Price) >= 4)
    .toList();

CRUD API

Direct CRUD methods on the db object:

Note: The entityName parameter can be either a dynamic entity (e.g., "LowCodeDemo.Products.Product") or a reference entity (e.g., "Volo.Abp.Identity.IdentityUser"). However, insert, update, and delete operations only work on dynamic entities — reference entities are read-only.

// Get by ID
var product = await db.get('LowCodeDemo.Products.Product', id);

// Insert
var newProduct = await db.insert('LowCodeDemo.Products.Product', {
    Name: 'New Product',
    Price: 99.99,
    StockCount: 100
});

// Update
var updated = await db.update('LowCodeDemo.Products.Product', {
    Id: existingId,
    Name: 'Updated Name',
    Price: 149.99
});

// Delete
await db.delete('LowCodeDemo.Products.Product', id);

Script Context

Scripts receive a context object and common global shortcuts. Available services can be enabled or disabled per script type with capability profiles.

Common Services

Global helpers are also available:

The error helpers are described in Error Handling.

Interceptor Context

Interceptors add args and commandArgs:

Set globalError to abort an operation with a user-facing error. It is answered like userFriendlyError(message):

if (!args.getValue('Name')) {
    globalError = 'Name is required.';
}

To reject invalid input with a 400 response, use validationError:

if (!args.getValue('Name')) {
    validationError('Name is required.', [{ message: 'Name is required.', members: ['Name'] }]);
}

Custom Endpoint Context

Custom endpoints add request globals and response helpers. See Custom Endpoints for details.

Event, Job, and Worker Context

Event handlers, background jobs, and background workers are configured in the Designer Actions section or in JSON descriptor files. See Script Actions for descriptors, examples, and dry-run testing.

Event handler example:

context.log('Received event ' + eventName);

if (eventData && eventData.campaignId) {
    await jobs.enqueueAsync('SendCampaignSummary', {
        campaignId: eventData.campaignId
    });
}

Background job example:

var campaign = await db.get('Acme.Campaigns.Campaign', jobData.campaignId);
if (!campaign) {
    userFriendlyError('Campaign not found.');
}

await email.queueAsync(jobData.to, 'Campaign summary', campaign.Name);

Background worker example:

var campaignQuery = await db.query('Acme.Campaigns.Campaign');
var staleCount = await campaignQuery
    .where(campaign => campaign.Status === 0)
    .count();

context.log('Stale draft campaigns: ' + staleCount);

Service Helpers

HTTP

The http helper supports outbound requests with timeout, response-size, host, and HTTPS policy checks.

Options include headers, query, timeoutMs, contentType, and responseType (json, text, or base64).

Authorization, Settings, Features, and Config

if (await auth.isGrantedAsync('Acme.Campaigns.Create')) {
    var enabled = await features.isEnabledAsync('Acme.Campaigns');
    var threshold = await settings.getIntAsync('Acme.Campaigns.Threshold', 10);
    var baseUrl = config.get('ExternalApi:BaseUrl');
}

Events and Background Jobs

await events.publishAsync('Acme.Campaigns.CampaignCompleted', { id: campaignId });

await jobs.enqueueAsync('SendCampaignSummary', { campaignId: campaignId }, {
    priority: 'Normal',
    delayMs: 60000
});

Files, Images, and Attachments

The file helpers use low-code page services so permissions, file validation, linked-blob checks, and foreign access stay consistent with the runtime.

File content is passed as base64 data. File operations are subject to configured read/write size limits.

Use fileFields and imageFields when you want typed selectors for file or image properties:

await files.save(fileFields.Acme.Campaigns.Campaign.Document, {
    fileName: 'brief.pdf',
    contentType: 'application/pdf',
    base64: base64Content
});

var content = await images.get(
    imageFields.Acme.Campaigns.Campaign.BannerImage,
    campaignId
);

The selector path is based on the full entity name and the File or Image property name. Record-level attachments are entity-level, not property-level, so they use the attachments helper instead of field selectors.

Email

The email and emailSender globals use the configured ABP IEmailSender.

Email operations validate the recipient address, apply allowed or blocked domain rules when configured, and enforce the per-execution email limit.

if (email.isAvailable) {
    await email.queueAsync(
        'ops@example.com',
        'Campaign completed',
        'Campaign ' + campaignId + ' completed.'
    );
}

Test JavaScript Dry Run

The Designer can run JavaScript without saving it where the Test JavaScript panel is available. The built-in dry-run panel supports custom endpoints, interceptors, event handlers, background jobs, and background workers.

Dry-run execution returns the endpoint response or script status, logs, captured side effects, duration, and error diagnostics. When the script fails, the result also shows the HTTP status and the error response body that a caller would receive. See Testing Error Responses.

For endpoint dry runs, the request method, path, route values, query values, headers, and body are supplied by the test panel. Endpoint authentication and permission metadata are checked against the current user. For interceptor dry runs, the test panel supplies command metadata and command data. For event handler dry runs, it supplies eventData. For background job and worker dry runs, it supplies the job or worker input JSON.

Configuration

Configure scripting limits with the LowCode:Scripting configuration section or AbpLowCodeScriptingOptions.

Configure<AbpLowCodeScriptingOptions>(options =>
{
    options.Script.Timeout = TimeSpan.FromMinutes(1);
    options.Script.MaxStatements = 100_000;
    options.Script.MaxMemoryBytes = 128 * 1024 * 1024;
    options.Script.MaxRecursionDepth = 64;

    options.Query.MaxLimit = 10_000;
    options.Query.DefaultLimit = 1000;
    options.Query.MaxExpressionNodes = 200;
    options.Query.MaxExpressionDepth = 10;
    options.Query.MaxArraySize = 500;
    options.Query.MaxGroupCount = 500;

    options.Capabilities.Endpoint.EnableHttp = false;
});

Most numeric limits can be set to null to explicitly disable that limit. Keep the defaults for untrusted or tenant-authored scripts.

Capability Profiles

The same services are not required in every script type. Capability profiles let you disable services per execution type:

{
  "LowCode": {
    "Scripting": {
      "Capabilities": {
        "Interception": {
          "EnableDb": true,
          "EnableHttp": false
        },
        "Endpoint": {
          "EnableDb": true,
          "EnableHttp": true
        },
        "EventHandler": {
          "EnableDb": true
        },
        "BackgroundJob": {
          "EnableDb": true
        },
        "BackgroundWorker": {
          "EnableDb": true
        }
      }
    }
  }
}

Each profile supports flags such as EnableDb, EnableCurrentUser, EnableCurrentTenant, EnableEmail, EnableConfig, EnableHttp, EnableAuthorization, EnableSettings, EnableFeatures, EnableEvents, EnableBackgroundJobs, EnableEncryption, EnableTextTemplating, EnableBlob, and EnableFiles.

Security

Sandbox Constraints

Query Security Limits

Integration Limits

Property Whitelist

Only properties defined in the entity model can be queried. Accessing undefined properties throws a SecurityException.

SQL Injection Protection

All values are parameterized:

var malicious = "'; DROP TABLE Products;--";
// Safely treated as a literal string — no injection
var query = await db.query('Entity');
var result = await query.where(x => x.Name.includes(malicious)).count();

Blocked Features

The following are not allowed inside lambda expressions: typeof, instanceof, in, bitwise operators, eval(), Function(), new RegExp(), new Date(), console.log(), setTimeout(), globalThis, window, __proto__, constructor, prototype, Reflect, Proxy, Symbol.

Error Handling

Scripts report an error by calling one of the error helpers. Each helper throws the ABP exception it is named after, so a script error is handled exactly like the same exception thrown by application code: ABP exception handling decides the HTTP status and the error response body, localizes error codes, and applies your status code mappings.

Error Helpers

The default statuses are the ones ABP assigns to these exception types. The helpers stop the script; you don't need to throw their result.

userFriendlyError shows message to the user. details adds more text to the error response. When code is given and has localized text, the localized text is shown instead of message:

if (campaign.Status === 2) {
    userFriendlyError('The campaign is already published.', null, 'Create a new campaign to make changes.');
}

businessError with a code throws a BusinessException. The caller sees the localized text of the error code, and the values in data fill its {name} placeholders. message is written to the server log. Define the text in a localization resource mapped to the code's namespace (see Using Error Codes); a code without localized text is answered with ABP's generic error message. When the script's own message should reach the caller together with a code, use userFriendlyError(message, code) instead. Without a code, businessError works like userFriendlyError and shows message:

if (order.Total > budget.Remaining) {
    businessError('Budget is exceeded.', 'Acme.Campaigns:BudgetExceeded', null, {
        remaining: budget.Remaining
    });
}

validationError returns 400 with the listed validation errors. Each error is an object with a message and the members (input names) it applies to, or a plain string. A single error object can be passed instead of a list, and members can be a single name. When errors is omitted or lists nothing, message becomes the only validation error; when message is empty too, the error reads "The request is not valid.":

var errors = [];
if (!body.name) {
    errors.push({ message: 'Name is required.', members: ['name'] });
}
if (body.budget < 0) {
    errors.push({ message: 'Budget cannot be negative.', members: ['budget'] });
}
if (errors.length > 0) {
    validationError('The campaign is not valid.', errors);
}

entityNotFound returns 404 with ABP's not-found message for the given entity name and id:

var campaign = await db.get('Acme.Campaigns.Campaign', route.id);
if (!campaign) {
    entityNotFound('Acme.Campaigns.Campaign', route.id);
}

authorizationError is handled like any ABP authorization failure: 401 for an anonymous caller and 403 for a signed-in user by default:

if (!(await auth.isGrantedAsync('Acme.Campaigns.Publish'))) {
    authorizationError('You are not allowed to publish campaigns.');
}

data is an object. Its properties are added to the exception data, the same way WithData(name, value) adds them in C#.

HTTP Status Code Mapping

An error code can be mapped to another HTTP status with AbpExceptionHttpStatusCodeOptions. The mapping applies to script errors wherever a script answers an HTTP request, including interceptors and custom endpoints:

Configure<AbpExceptionHttpStatusCodeOptions>(options =>
{
    options.Map("Acme.Campaigns:BudgetExceeded", HttpStatusCode.Conflict);
});

With this mapping, businessError('Budget is exceeded.', 'Acme.Campaigns:BudgetExceeded') returns 409 instead of 403. See HTTP Status Code Mapping.

Where Script Errors Go

Every script type handles a failed script the same way. The script type does not choose the status or the error body; ABP exception handling does:

Calculated and rollup properties are compiled expressions, not scripts, so these rules do not apply to them.

Runtime Failures

A script that fails on its own is reported with the error code LowCode:ScriptExecutionFailed and HTTP status 500, unless that code is mapped to another status. This includes:

• An uncaught JavaScript error, such as throw new Error('...') or reading a property of undefined
• A syntax error
• A script longer than MaxScriptLength
• The timeout, memory, statement count, or recursion depth limit
• A result that the script type cannot use
• An unexpected failure in a script service, such as an outgoing HTTP call that timed out

The caller receives only the LowCode:ScriptExecutionFailed code and its localized message. The original message, the failure reason, and the script line and column are written to the server log and shown by Test JavaScript. They are not sent to the caller unless the application sends exception details to clients (AbpExceptionHandlingOptions.SendExceptionsDetailsToClients).

Use an error helper for any error whose message the user should see. throw new Error('Valid email is required') is a runtime failure, so the caller gets a 500 response without that message.

Exceptions that ABP already handles pass through unchanged. These include the error helpers' exceptions, a database concurrency conflict (409), and any exception that has its own HTTP status.

Testing Error Responses

When a script fails in Test JavaScript, the result keeps the error diagnostics (type, code, message, line, column, details, validation errors, and data) and also shows:

• The HTTP status that the application's exception handling gives the error, including status code mappings
• The error response body that a caller receives (code, message, details, data, and validationErrors)

For a failed custom endpoint test, the endpoint response shows the same status and error message. The status of an authorization error is resolved from the current user (401 or 403), even if the application's authorization handler would answer a real request differently, for example with a redirect to the login page.

Catching Errors

// Try-catch for safe execution
try {
    var query = await db.query('Entity');
    var products = await query.where(x => x.Price > 0).toList();
} catch (error) {
    context.log('Query failed: ' + error.message);
}

Best Practices

1. Use specific filters — avoid querying all records without where()
2. Set limits — always use take() to limit results
3. Validate early — check inputs at the start of scripts
4. Use first() for single results — instead of toList()[0]
5. Keep scripts focused — one responsibility per interceptor
6. Use context.log() — never console.log()
7. Handle nulls — check for null before property access

Examples

Inventory Check on Order Creation

// Pre-create interceptor for Order
var productId = context.commandArgs.getValue('ProductId');
var quantity = context.commandArgs.getValue('Quantity');

var productQuery = await db.query('LowCodeDemo.Products.Product');
var product = await productQuery
    .where(x => x.Id === productId)
    .first();

if (!product) { entityNotFound('LowCodeDemo.Products.Product', productId); }
if (product.StockCount < quantity) {
    userFriendlyError('Only ' + product.StockCount + ' items are in stock.');
}

context.commandArgs.setValue('TotalAmount', product.Price * quantity);

Inventory Overview (Custom Endpoint)

var productQuery = await db.query('LowCodeDemo.Products.Product');

var totalProducts = await productQuery.count();
var productsWithStock = await productQuery
    .where(x => x.StockCount > 0).count();
var averagePrice = await productQuery
    .where(x => x.Price > 0).average(x => x.Price);

return ok({
    totalProducts: totalProducts,
    productsWithStock: productsWithStock,
    averagePrice: averagePrice
});

See Also

• Interceptors
• Custom Endpoints
• Script Actions
• Model Descriptor Files