Interceptors

Use designer actions and descriptor metadata for standard low-code behavior first. Interceptors are an advanced extension point for adding JavaScript lifecycle logic when the generated CRUD flow needs validation, transformation, or replacement behavior.

Interceptors allow you to run custom JavaScript code before, after, or instead of Create, Update, and Delete operations on dynamic entities.

Interceptor Types

Defining Interceptors in JSON Descriptors

The designer stores entity interceptors in the entity interceptors array:

{
  "name": "LowCodeDemo.Customers.Customer",
  "interceptors": [
    {
      "commandName": "Create",
      "type": "Pre",
      "javascript": "if (!args.getValue('Name')) {\n  globalError = 'Name is required.';\n}"
    }
  ]
}

Interceptor Descriptor

Defining Interceptors with Attributes

Use the [DynamicEntityCommandInterceptor] attribute on a C# class:

[DynamicEntity]
[DynamicEntityCommandInterceptor(
    "Create",
    InterceptorType.Pre,
    "if(!context.commandArgs.data['Name']) { globalError = 'Name is required!'; }"
)]
[DynamicEntityCommandInterceptor(
    "Create",
    InterceptorType.Post,
    "context.log('Entity created: ' + context.commandArgs.entityId);"
)]
public class Organization
{
    public string Name { get; set; }
}

The Name parameter must be one of: "Create", "Update", or "Delete". The InterceptorType can be Pre, Post, or Replace. When Replace is used, the default database operation is completely skipped and only your JavaScript handler executes. Multiple interceptors can be added to the same class (AllowMultiple = true).

Defining Interceptors with Fluent API

Use the Interceptors list on an EntityDescriptor to add interceptors programmatically in startup configuration:

AbpDynamicEntityConfig.EntityConfigurations.Configure(
    "MyApp.Organizations.Organization",
    entity =>
    {
        entity.Interceptors.Add(new CommandInterceptorDescriptor("Create")
        {
            Type = InterceptorType.Pre,
            Javascript = "if(!context.commandArgs.data['Name']) { globalError = 'Name is required!'; }"
        });

        entity.Interceptors.Add(new CommandInterceptorDescriptor("Delete")
        {
            Type = InterceptorType.Post,
            Javascript = "context.log('Deleted: ' + context.commandArgs.entityId);"
        });
    }
);

See Attributes & Fluent API for more details on Fluent API configuration.

JavaScript Context

Inside interceptor scripts, you have access to:

context.commandArgs

context.currentUser

context.emailSender

Logging

Use these methods instead of console.log (which is blocked in the sandbox).

db (Database API)

Full access to the Scripting API for querying and mutating data.

Interceptors can also use common scripting services such as user, tenant, auth, settings, features, config, http, events, jobs, blob, encryption, textTemplating, files, images, and attachments when they are enabled by the scripting capability profile.

globalError

Set this variable to a string to abort the operation and return an error:

globalError = 'Cannot delete this entity!';

globalError is answered like userFriendlyError(message). To choose the kind of error, call one of the error helpers instead. They abort the operation immediately, and ABP exception handling decides the HTTP status and the error response:

// 400 with a validation error for the Quantity field
if (context.commandArgs.getValue('Quantity') < 0) {
    validationError('Quantity cannot be negative.', [{ message: 'Quantity cannot be negative.', members: ['Quantity'] }]);
}

// 403 with a coded business error; the caller sees the code's localized text
if (!context.currentUser.isInRole('admin')) {
    businessError('Only administrators can close orders.', 'Acme.Orders:CloseRequiresAdmin');
}

Any other failure, such as an uncaught throw new Error(...), aborts the operation with the LowCode:ScriptExecutionFailed error and HTTP status 500, without the script's message. See Runtime Failures.

Page Interceptors and Execution Order

A page can define its own Create, Update, and Delete interceptors in its interceptors array. They run when the operation comes through that page. Each page interceptor can set entityExecutionOrder to control how it is combined with the entity interceptor of the same command and type:

The order applies to both Pre and Post interceptors. Because the page interceptor runs first by default, it can set a value, such as an owner field, before the entity interceptor validates it. The entity interceptor is the rule shared by every write path, so it runs last unless a page interceptor asks for entityFirst.

A Replace interceptor of the page runs instead of the entity's Replace interceptor. entityExecutionOrder only affects Pre and Post interceptors.

Earlier versions ran page interceptors after the entity interceptor by default. An interceptor saved without entityExecutionOrder now runs first; set entityFirst on the interceptors that must keep the old order.

{
  "name": "my-campaigns",
  "type": "dataGrid",
  "entityName": "Acme.Campaigns.Campaign",
  "interceptors": [
    {
      "commandName": "Create",
      "type": "Pre",
      "javascript": "context.commandArgs.setValue('OwnerId', context.currentUser.id);"
    },
    {
      "commandName": "Delete",
      "type": "Pre",
      "entityExecutionOrder": "entityFirst",
      "javascript": "context.log('Deleting ' + context.commandArgs.entityId);"
    }
  ]
}

Examples

Pre-Create: Validation

{
  "commandName": "Create",
  "type": "Pre",
  "javascript": "if(!context.commandArgs.data['Name']) {\n  globalError = 'Organization name is required!';\n}"
}

Post-Create: Email Notification

{
  "commandName": "Create",
  "type": "Post",
  "javascript": "if(context.currentUser.isAuthenticated && context.emailSender) {\n  await context.emailSender.sendAsync(\n    context.currentUser.email,\n    'New Order Created',\n    'Order total: $' + context.commandArgs.data['TotalAmount']\n  );\n}"
}

Pre-Update: Role-Based Authorization

{
  "commandName": "Update",
  "type": "Pre",
  "javascript": "if(context.commandArgs.data['IsDelivered']) {\n  if(!context.currentUser.roles.includes('admin')) {\n    globalError = 'Only administrators can mark orders as delivered!';\n  }\n}"
}

Pre-Delete: Business Rule Check

{
  "commandName": "Delete",
  "type": "Pre",
  "javascript": "var project = await db.get('LowCodeDemo.Projects.Project', context.commandArgs.entityId);\nif(project.Budget > 100000) {\n  globalError = 'Cannot delete high-budget projects!';\n}"
}

Pre-Update: Negative Value Check

{
  "commandName": "Update",
  "type": "Pre",
  "javascript": "if(context.commandArgs.data['Quantity'] < 0) {\n  globalError = 'Quantity cannot be negative!';\n}"
}

Replace-Create: Custom Insert Logic

When you need to completely replace the default create operation with custom logic:

{
  "commandName": "Create",
  "type": "Replace",
  "javascript": "var data = context.commandArgs.data;\ndata['Code'] = 'PRD-' + Date.now();\nvar result = await db.insert('LowCodeDemo.Products.Product', data);\ncontext.log('Product created with custom code: ' + data['Code']);\nreturn result.Id;"
}

Important: Replace-Create interceptors must return the new entity's Id (Guid). The system uses this value to fetch and return the created entity. Use return result.Id; after db.insert(...).

Replace-Update and Replace-Delete interceptors do not need to return a value.

Pre-Update: Self-Reference Check

{
  "commandName": "Update",
  "type": "Pre",
  "javascript": "if(context.commandArgs.data.ParentCategoryId === context.commandArgs.entityId) {\n  globalError = 'A category cannot be its own parent!';\n}"
}

See Also

• Scripting API
• Model Descriptor Files
• Custom Endpoints