Services

The ctx.services layer scripts use to read, create, update and query ERP data.

In VARIO Cloud, scripts access the full ERP functionality through ctx.services. This shared service layer is the backbone of all scripting — it is available in both workflow and batch scripts, and every service works identically in either context.

The services and methods shown below are examples. For the complete list of available services, methods, and parameters, see the Scripting Reference.

---

Entity Services

Entity services are the primary way to read, create, update, and deactivate business objects in VARIO Cloud. They manage core ERP records — accounts, articles, documents, CRM objects, and more. Most share a common method pattern:

Method	Description
getNewDto()	Create a new empty DTO
createNewDtoByTemplate(name)	Create a new DTO pre-filled from a named template
readById(id)	Read an entity by ID
create(dto)	Persist a new entity
update(dto)	Update an existing entity
deactivate(id)	Deactivate an entity

Not every service exposes every method — the available methods depend on the entity type.

const account = ctx.services.accountService.readById(accountId);
account.custom.myapp.externalId = 'EXT-123';
ctx.services.accountService.update(account);

---

VQL Service

The VARIO Cloud vqlService executes VQL queries from within scripts, giving you full access to the query language for lookups, aggregations, and existence checks. queryAll() returns a List<Map> — access fields directly by their attribute path.

const results = ctx.services.vqlService.queryAll(
  `SELECT id, number FROM article.query WHERE number = '${number}' LIMIT 1`
);

if (results && results.length > 0)
{
  const articleId = results[0].id;
}

For the full VQL syntax — operators, relative dates, subqueries, JOINs — see VQL.

---

User & Group Service

userAndGroupService resolves users and groups in the system — for example to check who created an entity or to assign a user to a task.

const user = ctx.services.userAndGroupService.findUserById(account.info.createdFrom);
ctx.services.logger.info('Created by: ' + user.username);

---

DTO Factory

In VARIO Cloud, entity services like accountService.getNewDto() create the top-level entity object, but not the nested objects within it. When you need to add an address, a contact, a business relationship, or similar sub-objects to an entity, you must create them separately via dtoFactory and then attach them — typically by assigning to a field or pushing into an array.

The factory covers all DTO types in the system — addresses, contacts, business relationships, article identifiers, metrics, and many more. The naming follows the pattern create<TypeName>(). The full list is available via autocompletion in the script editor.

Adding Nested Objects to an Entity

const account = ctx.services.accountService.getNewDto();

// Create and assign the default address
const address = ctx.services.dtoFactory.createAccountAddress();
address.name1 = 'Mustermann GmbH';
address.street = 'Hauptstraße 1';
address.postcode = '50667';
address.city = 'Köln';
account.defaultAddress = address;

// Create contacts and push them into the address
const phone = ctx.services.dtoFactory.createContact();
phone.ctType = 'PHONE';
phone.ctLabel = 'Telefon';
phone.value = '[phone]';
account.defaultAddress.contacts.push(phone);

// Create the business relationship
const customer = ctx.services.dtoFactory.createCustomer();
customer.number = '10001';
account.customer = customer;

ctx.services.accountService.create(account);

---

Utilities

utils provides helper functions used across all scripting contexts — most importantly toApiReference() for reference fields, but also dateTimeNow(), concatLists(), and others.

API References

Any DTO field ending in Ref — such as paymentMethodRef, deliveryTermRef, taxSchemaRef, or productGroupRef — expects an API reference object. You cannot assign a plain ID string or entity directly. Use toApiReference() to convert an ID into the required format.

The recommended approach is to pass the ID directly:

article.taxSchemaRef = utils.toApiReference('1434873425719062528');
article.productGroupRef = utils.toApiReference(existingGroup[0].id);

When using a lookup service, you can also pass the resolved entity:

const deliveryMethod = ctx.services.deliveryMethodService.findByLabel('DL');
document.deliveryMethodRef = utils.toApiReference(deliveryMethod);

account.custom.myapp.syncedAt = ctx.services.utils.dateTimeNow();

---

Logger

logger writes log entries visible in the workflow execution log or batch import log. It provides info(), warn(), and error() methods.

ctx.services.logger.info('Account ' + account.number + ' updated successfully');
ctx.services.logger.warn('Missing field — using default value');
ctx.services.logger.error('Failed to update document ' + documentId);

---

Destructuring

When a script uses multiple services you can destructure them for readability:

const { documentService, accountService, paymentMethodService, utils, logger } = ctx.services;

const document = documentService.readById(documentId);
const account = accountService.readById(document.accountId);
logger.info('Processing document for account ' + account.number);

---