Table of Contents

Entity operations

Scripts in ERP.net allow you to perform full CRUD operations- Retrieve, Create, Update, and Delete- on entities from the Domain Model.

The examples below demonstrate typical usage patterns.

Note

For details on how to access all available entities, and their attributes, refer to the Domain Model documentation. This resource provides the exact paths and structure you need when working with different parts of the model in your scripts.

Note

Any modification made in a script- creation, update, or delete- will not take effect until the actual transaction is committed. The script itself does not control the transaction; committing or rolling back changes is handled by the outer business logic that invoked the script.

Accessing the current entity (a.k.a subject)

You can access the entity that triggered the script using the subject variable. This variable is automatically provided in the script's context and refers to the object that caused the script to execute.

E.g., in a user business rule attached to the Customers repository, the subject variable will refer to the specific customer entity being processed when the script runs.

You can use subject to read or modify its attributes directly.

// The subject is a customer. We can change some of its data attributes.
// Activate the current customer and set a new number
subject.Active = false;
subject.Number = 'CUST-002';

Retrieve

Scripts can retrieve entities from the Domain Model using queries or by directly fetching an entity by its identifier.

GetById

Use the repository's getById() method to retrieve a single entity by its unique identifier.

// Example: Get a customer by ID
var customerId = "12345678-90ab-cdef-1234-567890abcdef";
var customer = Domain.Crm.Sales.CustomersRepository.getById(customerId);
if (customer != null) {
  // Do something with the customer entity.
}

j```
> [!NOTE]
>
> Always check if the result is `null` to handle cases where the entity is not found.

### Query

Use the repository's `query()` method to search for and retrieve collections of entities matching specific criteria.

```js
// Example: Get all active customers
var activeCustomers = Domain.Crm.Sales.CustomersRepository.query({
    active: { equals: true }
})

This will retrieve all customers where the active data attribute is set to true.

--

This script is triggered from a business rule attached to the Customers repository. It retrieves all sales orders for the current customer (subject) where the order date (documentDate) is today.

// Example: Get all sales orders from today for the current customer
var today = new Date();
var todaysSalesOrders = Domain.Crm.Sales.SalesOrdersRepository.query({
    customer: { equals: subject },
    documentDate: { equals: today }
});

Create

Creating a new entity

Entities can be created using the appropriate repository's createNew() method. This will instantiate a new entity object that you can initialize with the required data attribute values before saving or using it in your logic.

For example, to create a new customer:

// Create a new customer
var customer = Domain.Crm.Sales.CustomersRepository.createNew();
customer.Number = 123;
customer.Active = true;
Note

Make sure to set all required attributes and observe any business rules or validation logic relevant to the entity you are creating.

You can also create and assign related entities (such as customer types, parties) immediately after creation:

// Create a new customer and assign a new customer type and a new party.
var myCustomerType = Domain.Crm.Sales.CustomerTypesRepository.createNew();
myCustomerType.Name = "Retail";

var myCustomerPerson = Domain.General.Contacts.PersonsRepository.createNew();
myCustomerPerson.FirstName = "John";
myCustomerPerson.LastName = "Doe";

var customer = Domain.Crm.Sales.CustomersRepository.createNew();
customer.CustomerType = myCustomerType;
customer.Party = myCustomerPerson;

This approach is especially useful when building documents or records that require multiple related entities to be created together.

Creating multiple entities in a loop

You can create multiple entities by using a loop and setting their attributes individually. This approach is useful when you need to generate a series of related records, such as sales order lines or batch entries.

// Create a sales order.
var salesOrder = Domain.Crm.Sales.SalesOrdersRepository.createNew();
salesOrder.DocumentType = Domain.Systems.Documents.DocumentTypesRepository.createNew();
salesOrder.DocumentType.EntityName = 'Crm_Sales_Orders';
salesOrder.DocumentDate = new Date();
salesOrder.DocumentNo = '12345';
salesOrder.Customer = Domain.Crm.Sales.CustomersRepository.createNew();
salesOrder.Customer.Party = Domain.General.Contacts.CompaniesRepository.createNew();
salesOrder.Customer.Party.Name = 'My Company Ltd.';

// Create 10 sales order lines.
for (let i = 0; i < 10; i++) {
    let salesOrderLine = Domain.Crm.Sales.SalesOrderLinesRepository.createNew();
    salesOrderLine.SalesOrder = salesOrder;
    salesOrderLine.LineNo = (i + 1) * 10;
    salesOrderLine.Product = Domain.General.Products.ProductsRepository.createNew();
    salesOrderLine.Quantity = new Domain.Types.Quantity(10, null);
}

This technique gives you more control over attribute assignment and is especially helpful for more complex initialization or conditional logic.

Update

Entities can be updated by setting their attributes to new values.

If you have a reference to an entity- whether retrieved via query(), getById(), or from the subject variable- you can modify its attributes directly in your script.

Updating data attributes

Here's how to update fields of an existing entity:

// Example: Update a customer's status and number
subject.Active = false;
subject.Number = "CUST-999";

If you need to update an entity obtained from a repository:

// Get a specific customer and update its data attributes
var customer = Domain.Crm.Sales.CustomersRepository.getById("12345678-90ab-cdef-1234-567890abcdef");
if (customer != null) {
    customer.Active = true;
    customer.Number = "CUST-1000";
}

Batch updates

You can update multiple entities in a loop:

// Example: Deactivate all customers whose ThruDate is before today
var today = new Date();

var expiredCustomers = Domain.Crm.Sales.CustomersRepository.query({
    thruDate: { lessthanorequal: today }
});

for (let i = 0; i < expiredCustomers.length; i++) {
    expiredCustomers[i].Active = false;
}

This script finds all customers with a ThruDate earlier than today and sets their Active data attribute to false.

Delete

Entities can be deleted in scripts using the Delete() method. This removes the entity from the system. You can delete individual entities or all items in a collection.

Deleting a single entity

Call the Delete() method on an entity object to remove it:

// Example: Delete a customer
var customer = Domain.Crm.Sales.CustomersRepository.getById("12345678-90ab-cdef-1234-567890abcdef");
if (customer != null) {
    customer.Delete();
}

Deleting all items in a collection

Some collections (e.g., document lines) support the DeleteAll() method, which deletes every entity in the collection:

// Example: Delete all lines from a sales order
var salesOrder = subject;
if (salesOrder.Lines.Count > 0) {
    salesOrder.Lines.DeleteAll();
}

Deleting a specific object from a collection

You can also delete a specific entity from a collection using Delete(obj):

var salesOrderLine = salesOrder.Lines[0];
salesOrder.Lines.Delete(salesOrderLine);
Warning

Use delete operations with caution.

Suggest improvement to this page