Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Merged branch "DOC0001122" into parent

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

Info

Business rules can use scenarios scripts 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.
  • execution of a server-side script of the rule.
  • displaying a message on the client side.
  • creating system events to send e-mail notifications or run other server-side scripts.
  • interrupting database transactions.

To view all business rules navigate to System Settings Business Rules.

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

  1. Navigate to the list or form view of the table. 
  2. Select ConfigureBusiness Rules from the burger menu.

Business rules types


Depending on the business task you are solving, use one of the following types of business rules:

  • before
  • after
  • async after

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 conditionscondition:

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

Async after rules run conditionscondition:

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

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

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:

The following scheme illustrates when the before, after, and async after rules run. All rules are executed after the start of an action on a record (insert, update, or delete).

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

 Image Added 

Business rules creation


Tip

Role required: admin.

To create a new business rule, perform the steps below:

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

Business rules form fields

Anchor
business rule fields
business rule fields

FieldMandatoryDescription
NameY
Business rule name
Specify a name for the business rule.
TableY
Table on which a
Select the table for which the business rule
will run
is executed.
DescriptionN
A
Add a brief description of the action
description
.
ActiveNSelect this checkbox to
make
activate the business rule
active
.
InheritanceNSelect this checkbox to apply this business rule to all child tables of the
table defined in the
specified Table
field
.
AdvancedNSelect this checkbox to display the Script field and advanced settings such as the type of the business rule (the When field in the When to Run tab).
When to Run tab
WhenN
Defines

Select the moment of the business rule execution:

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

Specify the order of the business rule execution. If there are

several

multiple business rules of the same type (before, after, async after), they

will perform

are executed in the ascending order.

info

This field

is available

appears when

the

the Advanced checkbox is selected and

the

the When

field

 field value is set to before

or

 or after.

PriorityN
Defines

Specify the

importance

priority of the business rule

.info

. If there are multiple business rules with the same Order, they are executed in the descending order according to their Priority.

This field

is available

appears when

the

the Advanced checkbox is selected and

the

the When

field

 field value is set to before

or

 or after.

Action
Insert
insertNSelect this checkbox to execute the business rule
when inserting
when a new record is inserted.
Action
Update
updateNSelect this checkbox to execute the business rule when
updating
a record is updated.
Action
Delete
deleteN

Select this checkbox to execute the business rule when

deleting

a record is deleted.

info

This field

is available

appears when

the

the Advanced checkbox is selected.

Filter
Conditions that allows using static and dynamic filters
conditionsN
A condition builder

Specify the conditions for the business rule execution. After specifying

a table in

the Table

field

, all fields of this table

will be

are available in the

constructor

condition builder.

Info

Use the dynamic filter conditions like is (dynamic) or is not (dynamic) when

composing conditional expressions

setting up conditions to make your business rules more versatile.


Action tab

Info

The Action tab is not available for the async after business rules.


Set
Value
valueN

Select a column and define the value you need.


Available columns depend on the

table specified in the Table field.

specified Table.

  • 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 in the script:

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


Warning

To avoid recursion, you should use the current.update() object only in the after business rules. See below in more detail.


Abort action

Anchor
abort action
abort action

Abort Action

N

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 for the interruption of the action

abortion

. Select the Add

Message

message checkbox and

type

add the text in the Message field.

If

the

no message is

not

specified,

only

the standard

'Saving error' message  will occur

message is displayed when the action

aborts

is aborted:

Image Modified

If the abort conditions cannot be set using

the 

the Filter Conditions

 field

field,

you can

use the script with the setAbortAction and ss.addErrorMessage methods

in the script

. In this case, the Abort

Action

action checkbox should be cleared.

Warning
Add Message

When you use the setAbortAction() to abort a transaction, the script is not executed after calling this method.


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

Enter the message

text

you

want

need to show to a user when

a

the business rule is performed. The

message will appear in the bottom right corner. 
Tooltip
onlyIcontrue
appendIconinfo-filled
iconColorblue

Image Removed

Here, you can also copy the value of a

message is displayed as a flash message

To enable localization of the messages, use the values of the  Source Message (source_message)

record

records from the app category (determined by the value in the Category column). See

the Interface Localization article to learn more

Localization and Multi-Language Support to learn more.

Do not use variables and dynamic links to other records in this message. In order to add a message with variables or dynamic links, select the Advanced checkbox and configure the script in the tab of the same name.

Info

The Message 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

Add a script that determines the actions to be executed when

a

the business rule is launched

,

. The previous and current variables are available:

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

You can call the REM attributes in

your

the business

rule

rules of before type

,

. In this case, while

your

the business rule is

processed

processing, you

will

get the current attribute values, before the transaction occurs.

Info

The previous object is available only for the update action.

Warning

When the async after business rule is triggered, the action of the rule is sent to the queue. Because of this, there may be a slight delay between the triggering of the business rule and execution of the action. The current and previous objects in the async after business rules contain the state of the object at the time the business rule action is executed.

Warning

Anchor
recursion_warning
recursion_warning

  • Avoid
It is strongly recommended to avoid
  • using current.update()
with
  • in the before or async after business rule
.It is strongly recommended to
  • scripts, as 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.It is strongly recommended to avoid using the setAbortAction method with async
  • , add a run condition for the rule that is not satisfied after the first execution of the rule. Otherwise, recursion is inevitable.
  • Avoid using the setAbortAction method with the async after business rules.
  • If a business rule script inserts or updates records in other tables, use the after business rule type. Otherwise, if a business rule fails during a transaction, the before rule inserts/updates a record in other tables which leads to data inconsistency.

This field appears when the Advanced checkbox is selected.


Note

The server-side business logic may not work for system tables if the creation or updating of records is initiated by the backend. For example, an Impor Set is created as part of loading an Import Source, or an Email is created as a result of a notification rule, and so on.

Example of tables for which server-side business logic may not work:

  • Main Log (sys_log)
  • Script Log (sys_log_script)
  • Exception Log (sys_log_exception)
  • Record Deletion Log (sys_record_deletion_log)
  • Import Set (sys_import_set)
  • Activity Feed Item (sys_activity_feed_item)
  • Email (sys_email)

Abort business rules 
Anchor
abort business rule
abort business rule


The abort business rules terminate the following processes: Business

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

Info

: business rules,

Notifications

notifications,

Approval Rules, etc.

approval rules, and others.

See Approval Management 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 Actionaction checkbox.
  4. In the When to Run tab, check that the When field has the is set to 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 exit to apply the changes.

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


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

  • For applications other than Simple it is sufficient enough to copy an "out-of-the-box" rule using the Make a copy action and deactivate the original rule. Then you You can determine define the required logic in the copy of the rule.
  • For the Simple application the majority of the , most rules are delivered with Protection Policypolicy = Protected, thus so you can not simply deactivate them. However, the rules of the When=before type can be overridden by rules of a higher order 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 fieldthe Subject field. The order of the rule is 999. To change the value generation logic, it is sufficient enough to make a copy of the rule using the Make a copy action, determine define a specific logic and set Order = 1000. If the value in the field must should remain unchanged, use the rule triggered by an Action Updateupdate 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')subject = previous.getValue('field_name')subject;
  }
})(current, previous);


Table of Contents