Skip to content
Developerhome

Applying rules to transactions

  Less than to read

Banking Service supports providing transactions for reconciliation processes but also provides functionality for recognising banking transactions and suggesting how a transaction should be created. This is presented as the functionality to enable a consumer to create Rules within Banking Service to faciliate identifying types of transactions. When Banking Service recieves transactions, these rules can be applied using a rules engine to process user-suggested actions against the transactions.

Rules API endpoint

Full details of API Requests can be found in API reference but for specific illustration the API request endpoint for rules is:

api/v1/organisations/{organisationId}/companies/{companyId}/bankaccounts/{bankAccountId}/rules

This endpoint supports POST, GET, PUT, PATCH and DELETE operations.

A sample of the request body is as follows:

{
    "ruleName": "New rule 1",
    "ruleConditions": [{
        "ruleField": "transactionAmount",
        "ruleOperation": "gt",
        "ruleCriteria": "10"
    }],
    "ruleAdditionalFields": [],
    "ruleActions": [{
        "splitPercentage": 50,
        "accountantNarrative": "narrative 1",
        "accountsPostings": [{
            "type": "Main supplier",
            "code": "SUPP1"
        }]
    }, {

        "splitPercentage": 100,
        "accountantNarrative": "narrative 2",
        "accountsPostings": [{
            "type": "Account 2",
            "code": "ACC2"
        }]
    }]
}

Each rule must be given a unique name. The ruleConditions are used by the Banking Service rules engine to match against transactions. Multiple conditions can be captured in a rule and are applied in a logical and sequence.

The fields on a transaction that a rule condition can apply to are:

  • transactionNarrative
  • transactionAmount
  • datePosted
  • transactionType
  • checkNum
  • payee

Supported comparison operators

The supported comparison operators for different field types are as follows:

Rule Name Types Supported Description
eq String, Numeric, Date Equals
gt Numeric, Date Greater than
ge Numeric, Date Greater than or equal to
lt Numeric, Date Less than
le Numeric, Date Less than or equal to
contains String Contains
containsWords String Contains the specified, consecutive, words. e.g. ‘this exist’ in the string ‘does this exist anywhere’ would match
notcontains String Does not contain

Supported rule field combinations

Each rule field will only accept a subset of operations. The valid combinations are as follows:

Rule Field Valid _ruleOperation_ Values
transactionNarrative eq, contains, notcontains, containsWords
transactionAmount eq, gt, ge, lt, le
datePosted gt, ge, lt, le
transactionType eq
checkNum eq
currency eq
payee.payeeBankId eq
payee.payeeAccountId eq
$baseType eq

Rule matching

Where a rule matches a transaction, the rule actions are applied creating a collection of accounts postings against the transaction. The transaction amount is distributed in turn across the actions by applying the split percentage, with the residual amount given to the next rule action. The resulting accounts postings are then captured against the transaction.

Rules are applied when transactions are received into the Banking Service. To provide consumers the ability to dynamically define rules and apply them during Banking Reconciliation, however, Banking Service also provides a reprocess endpoint to trigger the rules to be ran against transactions on demand. This utilises the following:

  • POST reprocesstransactions - takes a collection of transactionIds to reprocess the rules, and starts the operation on the server; returning a URL to poll for progress.
  • GET reprocesstranasctions - used as the polling route; on completion returning the updated transactions with the rules applied.

Additional information

  • It is possible that multiple rules match against the same transaction, to help provide control and disambiguate, a rule rank property can be applied to a rule. The rule with highest rank will be considered the match and have the rule actions applied.
  • The Rule processing discussed in this section is referred to as Client Rules within our teams. Another type of rules processing exists for Accountants which involves redirecting Banking Transactions to an Accountant for rules processing, before then releasing them with verified accounts posting for actioning with Accounts products. Currently this feature is not widely adopted and is not covered further here.