Business Rules

Follow

Business rules are a way for users to build their own business processes in Uniconta without using Microsoft Visual studio.

Please note that Uniconta support doesn’t answer any questions regarding this area. We advise that you talk to your reseller.

Uniconta A/S will over time add business rules which can be use and changed by Uniconta users.

Business rules can be selected from Tools/Business rules.

Business Rules & User Plugins

Audience This document is split into two parts:

  • End users / configuratorswho create and maintain Business Rules in the UI
  • Developerswho implement custom Business Rule functions (User Plugins)

The content has been verified against actual runtime behavior where possible.

Part I – Business Rules (End‑User Guide)

1. What Business Rules Are (in Practice)

A Business Rule is a script that runs for a specific page or table when a defined trigger fires.

In the client:

  • Business Rules are loaded for the current page/table
  • Trigger handlers decide ifand when a rule is executed

A rule only runs when all of the following are true:

  1. The rule is linked to the active page or table
  2. The selected trigger actually fires
  3. The rule is enabled and contains valid script

2. Step‑by‑Step: Create Your First Business Rule

Step 1 — Open Business Rules

  1. Navigate to Business Rules
  2. Select Addto create a new rule
  3. Enter a clear, descriptive comment/name
    • Example: Debtor-Invoice-ValidateVAT

Step 2 — Select Trigger Type

Choose RuleType based on when your logic should run:

  • PageOpen– When the page opens
  • Button– When the user clicks a custom rule button
  • Insert– Before / during saving a new record
  • Update– Before / during saving an existing record
  • Upsert– Shared logic for insert and update
  • Delete– When a record is deleted
  • FieldsCheck– Mandatory‑field validation flow (returns message text)
  • PropertyChanged– When one or more fields change
  • Clicked– Pre/post hook for menu or ribbon actions
  • RowChanged– When the selected row changes

Step 3 — Configure Trigger Settings

Trigger‑specific configuration depends on the selected RuleType.

Button
  • Caption– Button text
  • Image– Icon
  • Group– Ribbon group placement
  • RecordSelectMode
    • FocussedRow
    • GridSelection
    • All
  • TabPageCaption– Optional tab scope
PropertyChanged
  • Fields– One or more fields to listen to
    • Supports *wildcard for all fields
  • LoadOnPageLoad– Also run when the page opens
RowChanged
  • DataObjectSource
    • NewRow– Newly selected row
    • OldRow– Previously selected row

Step 4 — Write the Script

  1. Open the script editor pane
  2. Use the Function Explorerto browse available functions
    • Double‑click a function to insert it
  3. Save the rule

Tip The Function Explorer is generated from registered function classes and their Documentation() output (description, parameters, examples). It is the authoritative source for function signatures.

Step 5 — Choose Execution Mode

  • SynchronousRuns inline. Use when order or timing is critical (validation, blocking actions).
  • AsynchronousRuns on the async path.

The UI may display hints suggesting a switch to synchronous execution when probably required.

Step 6 — Save and Test

  1. Save the rule
  2. Trigger the event on the target page
  3. Validate behavior in the UI and logs
  4. Refine the script and retest if needed

3. Trigger Guide (When to Use Which Trigger)

Trigger

Typical Scenario

What Fires It

Data Object Available

PageOpen

Set defaults

Page open handler

Focused row

Button

Custom user action

Rule button click

Depends on RecordSelectMode

Insert

Validate/default on create

Insert pipeline

Inserted record

Update

Validate/update on save

Update pipeline

Updated record

Upsert

Shared insert/update logic

CRUD helper

Current record

Delete

Protect or clean up

Delete pipeline

Record being deleted

FieldsCheck

Block save with message

Mandatory‑field check

Current record

PropertyChanged

React to edits

Property‑change event

Sender/current record

Clicked

Hook menu/ribbon action

Pre/post action dispatcher

Dispatcher‑selected object

RowChanged

React to navigation

Row selection changed

New or old row

Important Details

  • Clickeduses action names from _Settings, split by , / ;
  • PropertyChangeduses configured fields or *
  • FieldsCheckcan return text shown as a validation message

4. Common Business Rule Recipes

Recipe A — Validate Before Save (Insert / Update / Upsert)

  1. Create a rule with RuleType = Insert, Update, or Upsert
  2. Add validation logic
  3. For blocking behavior:
    • Run synchronous
    • Return message text
  4. Save and test

Recipe B — React to Field Changes

  1. Create a rule with RuleType = PropertyChanged
  2. Set Fields(specific fields or *)
  3. Optional: enable LoadOnPageLoad
  4. Save and test

Recipe C — Add a Custom Action Button

  1. Create a rule with RuleType = Button
  2. Configure caption, icon, and group
  3. Set RecordSelectMode
  4. Add script and save
  5. Click the button and verify behavior

Recipe D — Respond to Row Navigation

  1. Create a rule with RuleType = RowChanged
  2. Choose NewRowor OldRow as DataObjectSource
  3. Save and test by navigating rows

5. Helper Functions Available in Rule Scripts

All available functions are listed in the Function Explorer. Below is a categorized overview with short, practical descriptions.

CRUD Functions

  • CopyRecord– Creates a copy of the current record.
  • CreateRecord– Creates a new record in the specified table.
  • CreateRecordWithMaster– Creates a new record linked to a master record.
  • DeleteRecord– Deletes the current record.
  • DeleteSelectedRecord– Deletes one or more selected grid records.
  • GetRecordFromSqlCache– Retrieves a cached record loaded via SQL.
  • InsertBuffer– Inserts a record buffer without immediately saving.
  • InsertRecord– Inserts and saves a new record.
  • ReadRecord– Reads a single record by key.
  • RecordExists– Checks whether a record exists.
  • SetFieldValueOnRecord– Sets a field value on a specific record.
  • UpdateBuffer– Updates a record buffer.
  • UpdateFieldOnChildRecords– Updates a field on related child records.
  • UpdateFieldOnRelatedTable– Updates a field on a related table.
  • UpdateList– Updates a list of records.
  • UpdateRecord– Updates and saves the current record.

Data Functions

  • Any– Checks if a collection contains any items.
  • CancelInsertOrUpdate– Cancels the current insert or update operation.
  • CheckUnsavedData– Detects unsaved changes on the page.
  • ClearFieldValues– Clears one or more field values.
  • CopyFieldToField– Copies a value from one field to another.
  • CreateLookupListSingleField– Creates a lookup list from one field.
  • CreateLookupListTwoFields– Creates a lookup list from two fields.
  • DefaultValue– Returns a default value if input is null or empty.
  • DictionaryClear– Clears a rule-local dictionary.
  • DictionaryContains– Checks if a dictionary key exists.
  • DictionaryCreate– Creates a new dictionary.
  • DictionaryGet– Retrieves a value from a dictionary.
  • FieldValuePair– Creates a key/value field pair.
  • FieldsHaveValue– Checks if fields contain values.
  • FindFirst– Finds the first matching record in a collection.
  • GetAppEnumValue– Resolves an application enum value.
  • GetCalculatedFieldValue– Gets a calculated field result.
  • GetFieldFromTableCache– Reads a field from cached table data.
  • GetFieldValue– Gets the value of a field on the current record.
  • GetForeignKeyRecord– Retrieves a related foreign key record.
  • GetForeignKeyRecords– Retrieves multiple related foreign key records.
  • GetGridAdvancedFilterString– Gets the active grid filter expression.
  • GetMasterRecord– Retrieves the master record of a detail view.
  • GetRecord– Retrieves a record by table and key.
  • GetRecordFromTableCache– Retrieves a cached table record.
  • GetRecords– Retrieves multiple records.
  • GetRecordsForMaster– Retrieves records related to a master record.
  • GetRecordsFromTableCache– Retrieves cached records.
  • GetReferenceRecord– Retrieves a referenced record.
  • GetSelectedRecord– Gets the currently selected record.
  • GetSelectedRecords– Gets all selected grid records.
  • GetVariable– Reads a shared rule variable.
  • IsNewRecord– Checks whether the record is new.
  • KeyValuePair– Creates a generic key/value pair.
  • Lookup– Performs a lookup on a table.
  • MasterTableName– Returns the master table name.
  • NewGUID– Generates a new GUID.
  • SelectAllGridRecords– Selects all records in a grid.
  • SelectGridRecords– Selects records matching criteria.
  • SetDefaultValue– Sets a default value if empty.
  • SetFieldValue– Sets a field value on the current record.
  • SetVariable– Stores a shared rule variable.
  • SplitString– Splits a string into parts.

Events & Utility Functions

  • BlockMenuAction– Cancels a menu or ribbon action.
  • ChangedProperty– Gets the name of the changed property.
  • CheckMandatoryFields– Checks mandatory field completion.
  • CheckPropertyChanged– Verifies whether a property changed.
  • ClickedMenuAction– Returns the clicked menu action name.
  • ClosePage– Closes the current page.
  • ConvertOfferToOrder– Converts an offer into an order.
  • ConvertWebPTopJpg– Converts WebP images to JPG.
  • CreateAttachement– Creates and attaches a document.
  • CurrentUserFunction– Gets the current user function/role.
  • CurrentUserName– Gets the current user name.
  • DateIsNullOrMin– Checks for null or minimum date values.
  • Delay– Delays execution for a specified time.
  • EnableDisableFieldChanges– Enables or disables field editing.
  • EnableDisableFieldChangesForfield– Enables or disables a specific field.
  • ExecuteFunctionsInOrder– Executes multiple functions sequentially.
  • FormatString– Formats a string.
  • GetTableName– Returns the current table name.
  • GetWeekNumber– Calculates the ISO week number.
  • KeySequencePressed– Detects key sequences.
  • LoadFileBytes– Loads file content as bytes.
  • MandatoryFieldHasValue– Checks a mandatory field.
  • NameOfControl– Gets the UI control name.
  • OpenUrl– Opens a URL in the browser.
  • Parameter– Reads a runtime parameter.
  • RecalcCostPrices– Recalculates cost prices.
  • ShortCutKeyPressed– Detects shortcut key presses.
  • ToArray– Converts input to an array.
  • ToJason– Converts an object to JSON.
  • ToList– Converts input to a list.

User Interaction Functions

  • FileName– Prompts or resolves a file name.
  • InfoLogError– Writes an error message to the info log.
  • InfoLogInfo– Writes an informational log message.
  • InfoLogWarning– Writes a warning log message.
  • LocalizeLabel– Resolves a localized label.
  • ShowDeleteDialog– Displays a delete confirmation dialog.
  • ShowMessage– Shows a message dialog to the user.
  • Sleep– Pauses execution temporarily.

User Interface Functions

  • BeautifyFieldGroups– Improves field group layout.
  • ContinueOkCancel– Shows a Continue/OK/Cancel dialog.
  • DisableButton– Disables a button.
  • DisableFields– Disables one or more fields.
  • DisableFieldsInGroup– Disables all fields in a group.
  • EnableButtons– Enables buttons.
  • EnableFields– Enables one or more fields.
  • GridBased– Switches logic to grid context.
  • GridSort– Sorts a grid.
  • HideFieldGroups– Hides field groups.
  • HideFields– Hides fields.
  • MoveToFirstRow– Navigates to the first grid row.
  • MoveToLastRow– Navigates to the last grid row.
  • MoveToNextCell– Moves to the next cell.
  • MoveToNextRow– Moves to the next row.
  • MoveToPreviousCell– Moves to the previous cell.
  • MoveToPreviousRow– Moves to the previous row.
  • PerformRibbonAction– Executes a ribbon action programmatically.
  • Refresh– Refreshes the page or grid.
  • RemoveButtonActions– Removes button actions.
  • SaveRecords– Saves current records.
  • SetGridFilterString– Applies a grid filter.
  • ShowFieldGroups– Shows field groups.
  • ShowFields– Shows fields.

6. Practical Best Practices

  1. Start with one trigger and one small script
  2. Use clear, consistent naming conventions
  3. Prefer FieldsCheckfor user‑facing validation
  4. Use Synchronousexecution when rules must complete before continuing
  5. Keep PropertyChanged field lists narrow unless *is intentional
  6. Test with new records, existing records, and multi‑selection
  7. Document purpose, inputs, and outputs internally

Part II – User Plugins (Developer Guide)

7. Implementing Custom Business Rule Functions

This section targets developers creating custom Business Rule functions.

Scope

  • Applies to built‑in and plugin‑provided functions
  • Not intended for end‑user script authors

8. Required Interface and Runtime Expectations

Custom functions must implement IUnicontaBusinessRuleFunction and:

  • Be non‑abstract
  • Not be sealed
  • Have a public parameterless constructor

Required Members

  • Name (string)Visible function name (must be unique)
  • Evaluate(object[] operands)
    • Must be exception‑safe
    • Must tolerate null and invalid operands
  • GetResultType(Type[] operands)Used for expression engine type inference
  • RuleArgs (BusinessRuleArgs)Runtime context injected by Uniconta
  • MinOperandCount / MaxOperandCountOperand metadata for validation
  • Category (BusinessRuleFunctionCategory)
  • Description (string)
  • IsValidOperandCount(int count)
  • IsValidOperandType(int index, int operandCount, Type type)

Functions are auto‑discovered when the type is assignable to IUnicontaBusinessRuleFunction.

9. Naming Constraints

  • Null or empty names prevent function metadata tracking
  • Duplicate names may overwrite existing entries (last write wins)
  • Always keep function names unique

10. How RuleArgs Is Populated

Before evaluation, the runtime populates BusinessRuleArgs with:

  • Current page
  • API instance
  • ExtraArguments
  • Current DataObject

Accessible properties include:

  • Api
  • FocussedRow
  • CurrentRow
  • DataObject
  • ExtraArguments
  • Vars(shared variable store)

Guidance

  • Always null‑check RuleArgs and nested properties
  • Expect different shapes depending on trigger context

11. Recommended Implementation Pattern

  • Start from BusinessRuleFunctionBasewhen possible
  • Set a unique Name
  • Parse operands defensively
  • Implement GetResultType accurately
  • Define coherent operand limits and validators
  • Provide meaningful Description / Documentation

Test with:

  • Empty operands
  • Null operands
  • Incorrect types
  • Valid types
  • Trigger contexts with and without DataObject

12. Pre‑Release Checklist

☐ Public parameterless constructor exists ☐ Name is non‑empty and unique ☐ Evaluate handles nulls and type mismatches safely ☐ GetResultType matches actual return type ☐ Operand limits and validators are consistent ☐ RuleArgs usage is null‑safe and not persisted ☐ Documentation is meaningful to end users