↑↓ selectEnter openEsc close

    1. Elbuz

    How to calculate a field value in a trigger with a formula

    12 min readUpdated

    Elbuz calculates a field value for each record: instead of a fixed “VIP”, the rule writes “VIP if the total exceeds 10,000, otherwise standard”. A broken formula leaves the field unchanged.

    When you need this:

    • A tag depends on the order total — @if picks a value by condition.
    • A total with a markup or discount — @calc calculates it from document fields.
    • A task title with the customer and order number — @concat joins text from fields.
    • The customer’s phone in the document — @field takes it from the contact card.

    Where to start: rule card → “Change document data” command → field value: a formula starting with @.

    What formulas can do

    • @if — picks one of two values based on a condition.
    • @calc — does arithmetic with record fields.
    • @concat and @field — join text and copy values from one record to another.
    • @json — reads values from the additional fields of a document or contact.
    • Nested formulas — logic that a single function can’t express.
    • Check on save — broken syntax won’t be saved, and an error on real data won’t damage the field.

    How it works

    When a rule fires, Elbuz takes each “field — value” pair from the command and looks at the first character of the value. If it’s @, the value is evaluated as a formula. If not, it’s written as is.

    Parsing always follows the same pattern: @ is followed by the function name, then immediately by an opening parenthesis, and the last character of the value must be a closing parenthesis. Inside the parentheses are comma-separated parameters. Elbuz then replaces source.field references with data and returns the result.

    Errors are caught twice. First, when you save the command: Elbuz does a dry run of each formula, substituting 1 for every field. This catches broken syntax, unknown functions and stray characters in @calc — the command isn’t saved, and a red “Condition not saved: formula error” message appears for 6 seconds, listing what was rejected.

    Second, when the rule fires on a real record. What can’t be checked on save (an empty field, text instead of a number, a zero divisor) only shows up here.

    In this case the field isn’t changed at all — the old value stays, and the general “Operation log” (Account → Operation log) gets a “Formula could not be evaluated, field left unchanged” line with the rule name, the command and the formula itself; the record number is in the “Object ID” column.

    The “Operations log” tile in the document card doesn’t show it: that tile opens the field change history. The other fields of the command are written as usual.

    Two points where a formula can break, with two different results: in the first, the command isn’t saved; in the second, the field silently stays unchanged
    NoYesNoYesYesNo: text instead of anumber,empty field, division by zeroField value in the commandFirst character is “@”?Written as plain textParsed as a formulaIs the syntax valid?Check on save:1 is substituted for every field“Condition not saved:formula error”.The command isn’t savedCommand savedThe rule fired on a record:the formula uses real dataDid the calculation succeed?The value is written to the fieldThe field keeps its old value.The record’s operation log line —“Formula could not be evaluated,field left unchanged”
    • Action or result
    • Decision: the path depends on the answer

    A value that starts with @ but isn’t a formula will also be evaluated — and the command won’t save. If you need to write text like @shop to a field, put a space or any other character in front of it.

    Seven commands that support formulas

    A formula is evaluated not in any rule field, but only where a command writes a value to a record field:

    • “Change document data” and “Create document”;
    • “Change contact data” and “Create contact”;
    • “Create organization” and “Change organization data”;
    • “Add task”.

    The other commands don’t support formulas at all. In “Send mail”, “Send SMS” and “Perform HTTP request”, record data is inserted with macros in curly braces — {Document: Document number} or the short form {{d.document_number}}, {{pc.name}}, {{cn.name}}. There @ stays plain text. The “Run flow” command sets no field values at all — it only selects the flow.

    Two fields in these commands behave differently, and this applies to formulas too:

    • the posting field in document commands doesn’t write text, it posts the document (how a rule posts a document). You can’t enter a formula there: in the builder it’s a “Yes / No” list, not an input field;
    • the document type field in the “Create document” command sets which type to copy into. You can enter a formula, but don’t: a formula that returns empty silently stops the command — nothing gets created.

    “Create contact” without a name and “Add task” without a title stop silently in the same way. This protects against empty cards, but it looks like “the rule didn’t work”.

    Where a formula gets its data

    Data comes from three sources, referenced with a dot:

    • document.field — the document that triggered the event;
    • contractor.field — its contact (or the contact itself if the event was on a contact);
    • company.field — your organization from the document.

    All three sources are available in all seven commands.

    There’s no field. source in triggers, even though old examples mention it. Any field.something always returns an empty string, and inside @calc it counts as zero. There’s no user. source either.

    A source can also be empty legitimately: if the event fired on a contact, there’s no document, and every document. returns empty. The same goes for company. if the document has no organization of yours set.

    Where to get field names

    The builder’s left list shows human-readable field names, but a formula needs the system name — the same one used in short HTTP request macros ({{d.document_number}}). The most common ones:

    • document: document_number — number, document_sum — total, description — note, tag — tag, delivery_price — delivery cost, email, phone, custom_field_ext — additional fields, document_status_name — status, contractor_name — contact name;
    • contact and organization: name — name, phones and email — contact details, description — description, discount_percent — discount, customer_type — customer type, contractor_group_name — group, code_iin — tax ID.

    Elbuz won’t notice a name that doesn’t exist: document.nonexistent quietly returns an empty string. The check on save doesn’t catch it either: to the check, a nonexistent field looks like any other. Test with one run on a test record — if the field was filled with an empty value, the name is almost always the cause.

    The due date field in the “Add task” command is a special case: besides formulas, it accepts date placeholders — {current_date}, {current_date+3day}, {current_date+1week}. The units are the same as in rule conditions: minute, hour, day, week, month, year.

    Five functions and ready-made formulas

    @if — condition

    Syntax: @if(condition, value_if_true, value_if_false). The condition is written strictly as source.field operator value, and spaces around the operator are required. Operators: equals, contains, >, <, >=, <=, !=.

    Any condition that can’t be parsed counts as false — Elbuz silently takes the third parameter. That’s why @if(document.document_sum>5000, 'VIP', 'Standard') without spaces always returns “Standard”, even though it looks correct.

    contains searches for a substring case-sensitively: contains 'urgent' won’t find “URGENT”. equals compares loosely, so '5' and 5 are equal to it.

    There’s no separate “field is empty” check: write equals ''. This works for text, but zero in a numeric field doesn’t count as empty.

    @calc — arithmetic

    Syntax: @calc(expression). Allowed: digits, decimals with a dot, parentheses and the + - * / signs. Field references are replaced with values before calculation, so @calc(document.document_sum * 1.2) on a total of 1000 gives 1200.

    Three cases where @calc refuses to calculate — the command doesn’t stop, this field just stays unchanged:

    • the field contains text, not a number: @calc(document.description * 2) gives the error «Поле document.description не число» (field document.description is not a number);
    • division by zero: @calc(100 / document.delivery_price) if the delivery cost is zero;
    • functions and other characters: no percent signs or function names — only the four operations.

    A comma instead of a dot doesn’t cause an error, but everything after the comma is dropped: @calc(document.document_sum * 1,2) calculates the total multiplied by 1. Always use a dot for decimals.

    An empty field isn’t an error: it counts as zero. @calc(document.document_sum + contractor.discount_percent) on a contact without a discount simply returns the document total.

    @concat — join text

    Syntax: @concat(part, part, …), with any number of parts. Text goes in single quotes, field references without quotes. Spaces inside quotes are kept; spaces between parameters are not.

    @concat('Order from ', contractor.name, ' for ', document.document_sum) gives “Order from Acme Ltd for 1000”.

    @json — get a value from JSON

    Syntax: @json(source.field, 'key'). Use it to read fields that contain JSON — first of all, the additional fields of a document or contact. If the field holds {"16":"test1","17":"443355"}, then @json(document.custom_field_ext, '17') returns 443355.

    Only the top level is read: dot-separated nesting isn’t supported. If the key is missing or the field isn’t JSON, the result is an empty string, with no error.

    @field — just the field value

    Syntax: @field('source.field'), and the path must be in quotes. It’s the shortest way to copy a value from one record to another: @field('contractor.phones') puts the contact’s phone into the field.

    Without a dot in the path (@field('name')) the function returns empty — the source is required.

    A formula inside a formula

    The @if branches and the arguments of @concat, @json and @field can themselves be formulas. This lets you build logic that one function can’t express:

    • @if(contractor.customer_type equals 'VIP', @calc(document.document_sum * 9 / 10), document.document_sum) — a ten percent discount for VIP customers only;
    • @concat('Customer: ', contractor.name, @if(document.document_sum > 5000, ' (large)', '')) — a note added only to large orders.

    Only the branch chosen by the condition is evaluated. So the other branch can contain an operation that’s impossible on this record — for example, dividing by a field that is zero on some records: as long as the condition doesn’t lead there, there’s no error.

    Ready-made formulas

    Everything below has been tested and works as written.

    • Mark large orders: “Tags” field → @if(document.document_sum >= 10000, 'VIP', 'Standard').
    • Urgent orders by note: “Tags” field → @if(document.description contains 'urgent', 'Urgent', 'Normal').
    • Copy the customer’s phone into the document: “Phone” field → @field('contractor.phones').
    • Build a task title: “Task title” field → @concat('Call back: ', contractor.name, ' · ', document.document_number).
    • Get a code from additional fields: @json(document.custom_field_ext, '17').
    • Calculate the total with a twenty percent markup: @calc(document.document_sum * 1.2).
    • Copy the payment status into the delivery note: @concat('Payment: ', document.payment_status_name).
    • Discount for regular customers only: @if(contractor.customer_type equals 'Regular', @calc(document.document_sum * 0.95), document.document_sum).
    • Clear a field: the value null without any @ — Elbuz deliberately writes an empty value.

    Several commands write to the same field

    Elbuz doesn’t block overwriting and doesn’t warn about it: the field keeps whatever was written last. Which write is last depends on where the competing values are.

    • Two lines with the same field in one command. Lines are processed top to bottom, and the bottom value is written. If the bottom line’s formula fails, the top value is written.
    • Several commands of one rule. Commands run in turn by “Execution order”, each writing its own fields — the field keeps the value of the command that ran last. Note: all formulas of a rule use record data read when the rule started. If the first command wrote “VIP” to the note, document.description in the second command’s formula returns the old note, not “VIP”.
    • Two different rules on the same event. Rules run in turn by “Execution order”, and by name when the order is equal. Each next rule re-reads the record, so its condition and formulas see what the previous rules wrote. The field keeps the value of the rule that ran last.

    A practical tip follows: if a formula must rely on a value written by another command, move it to a separate rule on the same event with a higher “Execution order”.

    Pitfalls

    A space at the end of the value. A formula must end with a parenthesis: if a space follows it, the formula isn’t parsed. Such a space easily sneaks in when copying and is invisible — but the command won’t save, and the message will show your whole formula.

    A condition without spaces around the operator. This is the only error the check on save misses: @if(document.document_sum>5000, …) is syntactically valid, it just always takes the “otherwise” branch. You can only spot it by the result.

    A formula in a field filled from a list. Document status, payment type, currency, posting — in the builder these are drop-down lists, not input fields: you can’t type a formula there. Formulas only go in text and numeric fields.

    And the quietest of all: a command whose formula failed on a real record still counts as executed. The rule remembers it has already run on this document and won’t touch it again — even after the formula is fixed. So test the fix on a new record, not the same one.

    If a formula has already written the wrong value

    Elbuz doesn’t keep the field’s previous value: the log shows that the command ran, but not what the field held before. There’s no “restore” button — fixing means writing the correct value over the wrong one.

    1. Turn off the rule with the “Active” toggle so it doesn’t affect new records while you’re fixing things.
    2. Find the affected records. Open “Account” → “Operation log” and in the “Info” column filter lines by Trigger #number rule name — that’s how each command run line starts. Always include the name: the filter searches for a match, and Trigger #7 without a name also finds rules #70, #71 and so on. Document or contact numbers are in the “Object ID” column.
    3. Sort out what you found. Lines starting with “Failed!” mean the command didn’t run. Lines with “Formula could not be evaluated, field left unchanged” mean the field kept its old value. The rest are records where the formula wrote a value. For “Create document” and “Add task”, the line is on the source record and ends with the number of the created one: document_created #… or task_created #…. This line doesn’t show whether the created document is posted — check that in the document itself.
    4. Fix the formula. Just saving the corrected command isn’t enough: the rule remembers which records each command has already run on, and won’t run it on them again.

    To make the rule overwrite the field on affected records, delete the command and add it again with the correct formula. Its “already executed” marks go with it, so the new command runs on each record at its next event — if the record matches the rule condition. Deleting the whole rule clears the marks of all its commands.

    Scenarios

    Mark large orders without erasing the manager’s tags

    “Change document data” command, “Tags” field → @if(document.document_sum >= 10000, '+VIP', '+'). A value starting with a plus adds the tag to those already on the document, and a lone + leaves the tags as they are. Without the plus ('VIP'), the formula replaces all document tags with a single “VIP”, and an empty result erases them completely.

    What won’t happen: if the document total changes later, the tag on this document won’t be recalculated — the command has already run on it and won’t run again.

    Copy the customer’s phone into the document

    “Change document data” command, “Phone” field → @field('contractor.phones'). The document gets the phone from the contact card. What won’t happen: there’s no “is there a phone” check. If the contact card has no phone, the formula returns empty and erases the document’s phone. If that’s possible, add a “contact has a phone” check to the rule condition.

    Create a call-back task for a manager

    “Add task” command: “Task title” → @concat('Call back: ', contractor.name, ' · ', document.document_number), “Due date” → {current_date+1day}. The task appears as a card on the organizer’s first active board, in its first column (if “Board (ID, empty — first active)” and “Column (ID, empty — first)” are blank), and is linked to the document.

    In Account → Operation log, the run line ends with task_created # and the card number. The due date is saved as a date without time, even if the placeholder uses hour or minute.

    What won’t happen: if the title comes out empty or the organizer has no active board, the task isn’t created and the log shows a “Failed!” line. No “executed” mark is set then, so the command tries again at the next event on this document.

    What to do when a formula didn’t work

    “Condition not saved: formula error”
    the formula couldn’t be parsed. Check: the first character is @, the last is ), the function is one of the five allowed, there’s no trailing space. The message lists the formulas that were rejected.
    The field kept its previous value
    the formula failed on the record. The reason is in the “Formula could not be evaluated, field left unchanged” line in Account → Operation log (not in the document card’s “Operations log” tile). Most often it’s @calc on a text field or division by zero.
    @if always returns the second value
    the condition couldn’t be parsed and counts as false. Usually because of missing spaces around the operator or a wrong field name.
    @json returns empty
    either the key isn’t on the top level, or the field isn’t JSON. The function doesn’t read nested keys.
    The document wasn’t created
    the formula in the document type field returned empty. The type is required, and a fixed value is better.

    FAQ

    Which rule fields accept formulas?

    Only the field values of seven commands: “Change document data”, “Create document”, “Change contact data”, “Create contact”, “Create organization”, “Change organization data” and “Add task”. Formulas don’t work in the rule condition, in emails, SMS or HTTP requests.

    How do I know a formula has an error?

    Broken syntax shows right away: the command won’t save, and a red message listing the rejected formulas appears for 6 seconds. Data errors — division by zero, text instead of a number — go to Account → Operation log as a “Formula could not be evaluated, field left unchanged” line.

    Does @calc handle decimals?

    Yes: @calc(document.document_sum * 1.2) on a total of 1000 gives 1200. Use a dot for decimals. An empty field in the expression counts as zero, while text in a field and division by zero cause an error — the field then stays unchanged.

    Why doesn’t user.field from the examples work?

    There’s no such source in triggers — just like field.. Only document., contractor. and company. are available.

    Are there date, rounding or text replacement functions?

    No. There are only five functions: @if, @calc, @concat, @json, @field. A formula also can’t read document line items (document. sees only the header), stock levels or other records.

    Do price and catalog field formulas — CASE, IF, MySQL functions — work here?

    No, that’s a different mechanism with different syntax. It’s described in the articles on price formulas and catalog field formulas; triggers support only the five @ functions.

    Where to find it and who has access

    Formulas have no window or menu item of their own. They live inside a rule command — in the condition builder, read differently: the field on the left, the value to write on the right. The middle operator isn’t used here. Below the builder is a cheat sheet with source names and four examples.

    Other ways in
    “Automatic rules” → pencil on the rule → “Command” section → pencil on the command
    Access right
    the same as for the rules window — formulas have no separate right
    Prepare
    a rule with a command that changes or creates a record

    From zero to a working formula

    1. Open the rule card and go to the commandAutomatic rules
    2. Choose the field to fill on the leftCommand settings
    3. Write a formula starting with @ in the valueCommand settings
    4. Click “Save condition” and test on one recordCommand settings
    The «Edit command - Change document data» window with three field-and-formula rows and the formula hint below
    1Field to fill
    2Formula value
    3Formula hint
    1. The list on the left chooses which document field the command fills in.
    2. A value starting with @ is a formula, typed as text instead of picked from a list.
    3. The hint explains how to write fields and shows examples of @calc, @if, @concat and @json.

    How the rule itself works — the event, the condition, the order of commands and protection against firing twice — is covered in the automatic rules guide. This article is only about what to write in a field value.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free