Versions Compared

Old Version 5

changes.mady.by.user Nikolay Nikitin

Saved on

compared with

New Version 6

changes.mady.by.user Nikolay Nikitin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Business A business rule is a an action run on the server-side script running at the moment of after submission of a record form (when inserting, updating , or deleting a record).  Business Business rules are used for such tasks as conditionally automatic value change in the form fields or event creation for email notifications and script actionsexecuted within a database transaction, irrespective of the interface used to initiate the transaction (user submitting a form, execution of a server-side script, REST request, execution of a Workflow Activity block). The action of a rule can be executed both on the current record and on other records.

Info

Business rules can use scenarios to perform actions with records in the database. Even so, there There are several other options of the script actions available, such as client-side scripts and UI-actions.

The scheme below illustrates when before, after,andasync after rules run. All rules execute after an action record start (insert, update, or delete).

Business rules are used for:

  • changing values in the fields of a record that caused the rule to run when certain conditions are met;
  • executing a server-side script of the rule;
  • displaying a message to the client side;
  • creating system events for sending e-mail notifications or running other server-side scripts;
  • aborting transactions with the database.

To view all business rules navigate to System Definition → Business Rules.

To view business rules related to a table, complete the following steps:

  1. Navigate to the list or form view of the table;
  2. Select Configure → Business Rules from the burger menu.

Business rules types

Depending on the business task to be completed, you can use one of the following types of business rules:

  • before;
  • after;
  • async after.

Each type of business rules has its own run conditions.

Process starts with a form action: if it is the update action, data source is the database, and therefore the record has the previous block. The previous block represents form condition before action (form submission – insert, update, or delete), and the current blocks represent a form condition after the action is completed. Form submission can be performed by a user, script, or REST API request.

Image Removed

Before rules run conditions:

  • After record action start (insert, update, or delete).
  • Before the system performs server updates (before the database transaction is completed).

After rules run conditions:

  • After the system performs server updates (after the database transaction is completed).

Async after rules run conditions:

  • After all business rules of other types (after all after business rules).
Info

Async after business rules run after before and after business rules, so first, a user receives the form with all changes, and then async after rules run. Thus, using async after business rules, you can optimize system response time – use async after rules for resource-intensive scripts that take a lot of time.

The scheme below illustrates when before, after,andasync after rules run. All rules execute after an action record start (insert, update, or delete).

Process starts with a form action: if it is the update action, data source is the database, and therefore the record has the previous block. The previous block represents form condition before action (form submission – insert, update, or delete), and the current blocks represent a form condition after the action is completed. Form submission can be performed by a user, script, or REST API request.

Image Added


Tip

Role required: admin.

Business rules creation

You can create business rule that will be running when inserting, updating or deleting a record.

To create it, please perform the following steps:

  1. Navigate to System Definition → Business Rules.
  2. Click New and fill in the fields.
  3. Click Save or Save and Exit to apply changes.

Business rules form fields

Anchor
business rule fields
business rule fields

FieldMandatoryDescription
NameYBusiness rule name.
TableYTable on which a business rule will run.
DescriptionNA brief action description.
ActiveNSelect this checkbox to make the business rule active.
InheritanceNSelect this checkbox to apply this business rule to all child tables of the table defined in the Table field.
AdvancedNSelect this checkbox to display the Script field and advanced settings such as type of the business rule (the When field in the When to Run tab).
When to Run tab
WhenN

Defines the moment of business rule execution:

  • before – execution prior to the operation of the business rule launch trigger (prior to the updating, inserting or deleting a record)
  • after – execution after to the operation of the business rule launch trigger (after the updating, inserting or deleting a record).
  • async after – execution is carried out after all preceding business rules are completed: the system returns the form with all changes and then runs async after business rules in the background. Using async after business rules, you can optimize system response time.
OrderN

Defines the order of the business rule execution. If there are several business rules of the same type (before, after, async after), they will perform in the ascending order.

Info

This field is available when the Advanced is selected and the When field value is before or after.


PriorityN

Defines the importance of the business rule.

Info

This field is available when the Advanced is selected and the When field value is before or after.


Action InsertNSelect this checkbox to execute the business rule when inserting a new record.
Action UpdateNSelect this checkbox to execute the business rule when updating a record.
Action DeleteN

Select this checkbox to execute the business rule when deleting a record.

Info

This field is available when the Advanced is selected.


Filter ConditionsN

A condition builder that allows using static and dynamic filters. After specifying a table in the Table field, all fields of this table will be available in the constructor.

Info

Use dynamic filter conditions like is (dynamic) or is not (dynamic) when composing conditional expressions to make your business rules more versatile.


Action tab

Info

Action tab is not available for async after business rules.


Set ValueN

Select a column and define the value you need.
Available columns depend on the table specified in the Table field.

Info
  • The values from the Set value field are applied at the moment of the rule running. The current object state in the script is equal to the state after applying the Set value template.

  • Application of the Set value template occurs automatically in the before business rules. To use the template in the after business rules you should call update() for the current object to the script:

    Code Block
    languagejs
    themeConfluence
    linenumberstrue
    (function executeRule(current, previous /*null when async*/) {
    current.update();
})(current, previous);



Abort ActionN

Select this checkbox to interrupt the transaction (insert, update, or delete) when all conditions are met.

Tip

A It is a good practice is to specify the reason of action abortion. Select the Add Message checkbox and type the text in the Message field.

If the no message is not specified, only the standard 'Saving error' message  will occur will be displayed when the action aborts:

If abort conditions cannot be set using the Filter Conditions field, you can use script with the setAbortAction and ss.addErrorMessage methods in the script. In this case, the Abort Action checkbox should be cleared.

Warning

Keep in mind that when you use the setAbortAction() to abort a transaction, the script after this method is called will not be executed.


Add MessageNSelect this checkbox to display the Message text field if you want to show a message to a user when a business rule is performed.
MessageN

Enter the message text you want to show to a user when a business rule is performed. The message will appear in the bottom right corner. 

Tooltip
onlyIcontrue
appendIconinfo-filled
iconColorblue

Here, you can also copy the value of a Source Message You can use values from the Source Messages (source_message) recordtable as values of the Message field, which allows localizing the messages displayed. See the Localization and Multi-language Support article to learn more.

Info

The field appears when the Add Message checkbox is selected.


Advanced tab
ScriptN


Info

This field is available when the Advanced is selected.

The action sequence that will be executed when a business rule is launched, previous and current variables are available:

  • previous – the state of a record object before insert, update, or delete.
  • current – the state of a record that will be inserted, updated, or deleted. The current object is still available after record is deleted.
When a record is inserted
  • previous is null.
  • current is equal to the SimpleRecord object that will be inserted.
When a record is updated
  • previous is equal to the SimpleRecord object as it was before transaction started.
  • current is equal to the SimpleRecord object at the moment when the rule execution starts.
When a record is deleted
  • previous is null.
  • current is equal to the SimpleRecord object at the moment when the rule execution starts.


Note
  • You can call REM attributes in your business rule of before type, In this case, while your business rule is processed, you will get the current attribute values, before the transaction occurs.
  • At the moment of triggering the async after business rule, the rule action is sent to the queue. Because of this, there may be an insignificant lag between the triggering of the business rule and execution of the action. The current and previous objects in async after business rules contain the state of the object at the moment of execution of business rule action.


Info

The previous object is available only for the update action.


Warning
  • It is strongly recommended to avoid Avoid using current.update() with before in business rule .It is strongly recommended to scripts, since it may cause recursion. If you cannot avoid using current.update() with asyncasync after business rules. It may cause unpredictable system behavior. business rules. It may cause unpredictable system behavior., add a run condition for the rule which stops being satisfied after the first run of the rule. Otherwise, recursion is unavoidable.
  • Avoid It is strongly recommended to avoid using the setAbortAction method with async after business rules.
  • If a business rule script inserts or updates records in other tables, use the after run type Если в скрипте бизнес правила производится создание/обновление записей в других таблицах, используйте тип запуска after. В противном случае, если в процессе выполнения транзакции одно из бизнес правил выполнится с ошибкой, правило запускаемое на before создаст/обновит запись в других таблицах, что приведет к несогласованности данных.


Abort business rules 
Anchor
abort business rule
abort business rule

It is possible to perform business rules that terminate the follow-up actions and processes.

Info

The abort business rules terminate the following processes: Business rules, Notifications, Approval Rules, etc.

See Approvals to learn more about approval rule rejection.

To make your business rule abort the follow-up processes, complete the steps below:

  1. Open a business rule record you need.
  2. In the When to Run tab, define the abort conditions.
  3. In the Action tab, select the Abort Action checkbox.

  4. In the When to Run tab, check that the When field has the before field.

    Tooltip
    onlyIcontrue
    appendIconinfo-filled
    iconColorblue

    The When field is displayed when the Advanced checkbox is selected.


  5. Click Save or Save and Exit to apply changes.

Out-of-the-box business rules override 
Anchor
override
override

If necessary, some out-of-the-box business rules can be overridden.

  • For applications other than Simple it is sufficient to copy an out-of-the-box rule using the Make a copy action and deactivate the original rule. Then you can determine the required logic in the copy of the rule.
  • For the Simple application the majority of the rules are delivered withProtection Policy = Protected, thus you can not simply deactivate them. However, the rules of the When=before type can be overridden by rules with the same start conditions of a higher order. For example, an out-of-the-box rule with the before type generates a value in a field. The order of the rule is 999. To change the value generation logic it is sufficient to make a copy of the rule using the Make a copy action, determine a specific logic and set Order = 1000. If the value in the field must remain unchanged, use the rule triggered by an Action Update event with the following script:
Code Block
languagejs
themeConfluence
titleExample
linenumberstrue
(function executeRule(current, previous = null /*not null only when action is update*/) {
  if (previous) {
    current.getValue('field_name') = previous.getValue('field_name');
  }
})(current, previous);

Бизнес правила

Бизнес правило представляет собой действие, запускаемое на серверной стороне после отправки формы записи (при создании, обновлении или удалении). Бизнес правила выполняются в рамках транзакции с БД, вне зависимости от интерфейса, через который была инициирована транзакция (отправка формы пользователем, выполнение серверного скрипта, REST запрос, выполнение блока Workflow Activity). Действие правила может выполнятся как в отношении текущей записи, так и в отношении других записей.

Бизнес правила используют для:

  • изменения значений в полях записи вызвавшей срабатывание правила при соблюдении определённых условий;
  • выполнения серверного скрипта правила;
  • выведения сообщений на сторону клиента;
  • создания системных событий для отправки уведомлений по электронной почте или выполнения других серверных скриптов;
  • прерывания выполнения транзакции с БД.
Переход в список бизнес правил через пункт навигатора System Definition -> Business Rules. Для просмотра списка бизнес правил, связанных с таблицей необходимо:
  1. перейти на список или форму таблицы;
  2. выбрать пункт бургер меню Configure -> Business Rules.

В зависимости от решаемой бизнес задачи, используют соответствующий тип бизнес правил:

  • before;
  • after;
  • async after (асинхронные).
Тип бизнес правила задаётся на вкладке When to Run в поле When (для отображения расширенного набора полей необходимо активировать атрибут Advanced/Расширенная настройка). Значение параметра When по умолчанию равно before, поле When скрыто с формы.
  • Правила с типом before (When=before) запускаются до завершения транзакции с БД.
  • Правила с типом after запускаются после завершения транзакции.
  • Правила с типом async after (асинхронные бизнес правила) выполняются после блока after правил без обеспечения очерёдности.

Последовательность выполнения бизнес правил разных типов в контексте отправки формы:

Image Removed

Объекты доступные в скрипте правила

В скрипте бизнес правила доступны объекты записи, вызвавшей срабатывание правила – previous и current.

  • previous – объект класса SimpleRecord, который является состоянием записи в БД до срабатывания правила. В бизнес правилах на Action Insert и Action Delete previous равен null.
  • current – объект класса SimpleRecord, который хранит состояние записи в момент срабатывания правила. В бизнес правилах на Action Delete – содержит состояние объекта до удаления. Особенность работы асинхронных бизнес: в момент срабатывания бизнес правила, действие правила отправляется в очередь. Другими словами, возможен незначительный простой между срабатыванием бизнес правила и выполнением действия. Поэтому в асинхронных бизнес правилах current содержит состояние объекта на момент выполнения действия правила.

Запуск бизнес правил влияет на производительность приложения. Для оптимизации выполнения запросов при отправке формы задавайте условия срабатывания бизнес правил через поле Filter Conditions.
Например, в задаче Task существует поле caller. Поле ссылается на запись пользователя User. Если у пользователя значение поля Active меняется на true, устанавливать всем задачам пользователя поле Active равным true. И наоборот, если пользователь становится неактивным (Active=false) – активность его задач должна меняться на false. Скрипт бизнес правила, запускаемого после обновления записи User будет иметь вид:
(function executeRule(current, previous /*null when async*/) {
    if (previous.active != current.active) { // значение в поле active меняется?
        const task = new SimpleRecord('task');
        task.addQuery('caller', current.sys_id);
        task.addQuery('active', '!=', current.active); // исключить из выборки записи, для которых не нужно менять значение
        task.query();
        task.setMultipleValue('active', current.active);
        task.updateMultiple();
    }
})(current, previous);

В таком виде бизнес правило будет срабатывать при каждом обновлении текущей записи, вне зависимости от того, изменилось ли значение активности. Для оптимизации, условие срабатывания должно if (previous.active != current.active) быть вынесено в поле Filter Conditions:

Image Removed
Бизнес правила могут использоваться для прерывания выполнения транзакции с БД.
Существует два сценария настройки бизнес правила для прерывания транзакции:

  1. No/Low-code сценарий. Применим если условие запуска правила может быть задано через поле Filter Condition. 
    Параметры бизнес правила:
      • When: before
      • Filter Condition: {условие запуска правила}
      • Abort Action: активно
      • Message: {текст сообщения с причинами прерывания}
  2. Pro-code сценарий, если условие запуска не может задано через Filter Condition
    Параметры правила:
    • When: before
    • Advanced: активно
    • Abort Action: не активно
    • Script: {скрипт с вызовом метода ss.addErrorMessage() для вывода сообщения с причиной прерывания + вызов метода setAbortAction()}

Рекомендации по использованию бизнес правил

  • Используйте поле Filter Conditions для задания условия срабатывания правила. Это позволит оптимизировать работу приложения, сократив количество запускаемых правил.
  • Избегайте использования current.update() в скрипте бизнес правила т.к. это может привести к рекурсии. Если без вызова current.update() не обойтись – добавьте условие срабатывания для правила, которое перестанет выполняться после первого запуска правила. В противном случае рекурсия неизбежна.
    • Если бизнес правило используется для прерывания транзакции – обязательно добавляйте вывод сообщения для пользователя с причинами прерывания. По умолчанию, прерывание транзакции сопровождается сообщением с текстом Saving error / Ошибка сохранения:
    Используйте для вывода сообщения поле Message или метод ss.addErrorMessage() в скрипте правила.
  • Если в скрипте бизнес правила производится создание/обновление записей в других таблицах, используйте тип запуска after. В противном случае, если в процессе выполнения транзакции одно из бизнес правил выполнится с ошибкой, правило запускаемое на before создаст/обновит запись в других таблицах, что приведет к несогласованности данных.

    • Особенности использования бизнес правил

    1. Значения из поля Set value применяются в момент срабатывая правила. Состояние объекта current в скрипте правила равно состоянию после применения шаблона Set value.
    2. Применение шаблона Set value происходит автоматически в правилах типа before. Для применения шаблона в правилах с типом after необходимо добавлять в Script вызов метода update() для объекта current:
       
      (function executeRule(current, previous /*null when async*/) {
          current.update();
      })(current, previous);
    3. Для прерывания транзакции необходимо использовать правила с типом before. Прерывание возможно реализовать, активируя поле Abort Action. В таком случае условия прерывания нужно задавать через поле Filter Condition. Если условие не может быть задано через Filter Condition – необходимо использовать метод SimpleRecord setAbortAction() для объекта current в скрипте правила: 
      (function executeRule(current, previous /*null when async*/) {
        if (String(current.serial_number).length != 10) {
         ss.addErrorMessage('Serial Number should be 10 characters length');
         current.setAbortAction(true);
        }
      })(current, previous);
    4. Используя метод прерывания транзакции setAbortAction() необходимо учитывать, что скрипт написанный после вызова метода не будет выполнен.
    5. В качестве значения для поля Message могут использоваться значения из справочника Source Message (source_message), что позволит локализовать выводимые сообщения.
    6. Системные поля записи: ID (sys_id), Updated by (sys_updated_by), Updated at (sys_updated_at), Created by (sys_created_by), Created at (sys_created_at), Table (sys_db_table_id) заполняются после создания (вставки) записи. Соответственно, в бизнес правилах с типом before срабатывающих при вставке, значения системных полей будут недоступны. Для получения значений системных полей (кроме sys_id) используйте методы
        • ss.getUserID()
        • new SimpleDateTime().getValue()
        •       new SimpleRecord('sys_db_table').get('name', current.getTableName()).sys_id;
    7. В бизнес правилах на Action Delete объект current содержит состояние объекта до удаления.
    8. В момент срабатывания асинхронного бизнес правила, действие правила отправляется в очередь. Поэтому возможен незначительный простой между срабатыванием бизнес правила и выполнением действия. Объекты current и previous в асинхронных бизнес правилах содержит состояние объекта на момент выполнения действия правила.

    Отладка правил

    Историей срабатывания конкретного бизнес правила доступна на форме бизнес правила в связанном списке Script Log:

    Image Removed

    По умолчанию, логирование серверных скриптов отключено. Для включения перейдите в список системных свойств System Properties и укажите значение true для записи системного свойства simple.logs.enable_script_logging.

    Выполнение каждого серверного скрипта логируется в таблицу Script Logs [sys_log_script]. Переход в список через навигатор –  System Logs -> Script Logs.

    Выполните фильтрацию логов по документу, для которого необходимо проанализировать транзакцию, укажите промежуток выполнения транзакции +- 10 секунд и добавьте сортировку по полю Start time:
    Image Removed