Skip to main content

Guided Matching rule types

When creating custom Guiding Matching rules, you need to choose first a specific Rule Types. The available Rule Types depend on the transaction field to which the new rule applies. The rule editor only limits the types depending on the selected field. The rules are either for matching or enrichment.

note

If you are using the Enhanced Online Experience with FinDock's Payment API v2, Guided Matching takes on a broader role in handling inbound payment data. For further information, please see Processing and reconciling online payments

Rule Type: Constant

Use this rule type to set the value of a transaction field to a constant value. Guide Matching constant rule

Constant setup

SettingDescription
ConstantThe constant value for the transaction field

Rule Type: Regular Expression

Use this rule type to extract a value from a transaction field according to a regular expression. If the regular expression rule is used for a checkbox field, the checkbox field is checked if a match can be found. For example, let’s say you want to mark all transactions with the word ‘GIFT' in the payment reference. First, you create a ‘Has Gift’ checkbox custom field on Transaction, and then, using the Regular Expression rule type, create a rule with regular expression ‘GIFT’. Guided Matching regular expression

Regular Expression setup

SettingDescription
Input FieldField from which a value is extracted using a regular expression.
Regular ExpressionA regular expression is a string that is used to match another string using a specific syntax. For further information, please refer to Oracle documentation. A nice tool and playground is RegExr.
Multi-Value?If checked, all matched patterns are returned comma separated. If the total string is longer than fits in the Results field, only what fits is stored.
Capturing GroupFinDock uses the REgEx outcome of the defined capturing group to store on the Transaction field. See this Salesforce developer doc
Example InputExample text for the regular expression and capturing group. This is for testing and verifying that the regular expression behaves as expected.
Capturing GroupsAll the resulting capturing groups given the specified regular expression and example input.
ResultThe result given the calculated capturing groups and the specified capturing group.

Rule Type: Query

Use this rule type when you want to find a value by using a query of Salesforce data. Generated SOQL is logged in the Guided Matching Log field, and the query execution time is logged as queryTimeMillis. If Guided Matching fails, check these logs. Slow queries can lower matching performance. Values above 500 are too high. Please refer to standard Salesforce query performance best practices to solve issues in this area.

note

You should only query indexed fields. Querying a non-indexed field significantly lowers search performance. To index custom fields, under the general options for the field, set External ID to true.

The queries can be defined for matching multiple dynamic criteria on transaction fields, where a field value on the query object is matched to a field value on the transaction record. For example, you can match transactions against installments that have the same contact and the same amount.

note

For query rules on Payment Profile, the new Primary Identifier field should be used.

Criteria against a transaction field are only available if the comparison operator is ‘equals.’ Only the first and mandatory criterion (Account = Account in the example below) is included in the generated SOQL query. All ‘value’ criteria (Status != “Collected” in the example screenshot below) are included in the generated SOQL query. However, other ‘field’ criteria (Amount = Amount and Originating Campaign = Campaign in the example) are not included in the generated SOQL query. These are filtered out by looping through the query result set.

Make sure you use the most specific comparisons first. Salesforce has a per-transaction governor limit of 50,000 for total number of records retrieved by SOQL queries. The Guided Matching Query rule type explicitly checks if the query returns more records than allowed by the Salesforce limit with the addition of LIMIT [Remaining Rows] to each generated query. If the number returned equals Remaining Rows, it is assumed that the governor limit has been exceeded, and the Transaction or Inbound Report records are set to Failed with a clear error message indicating the query limit was exceeded.

Guided Matching Query rule type

Query setup

SettingDescription
Multi-Value?The checkbox appears to the right of the first query criterion Transaction Field. If checked, the value in the Transaction Field is interpreted as a comma-separated list of values, and the query uses any of these values.
Multiple Results StrategyStrategy for what to do if the query returns more than one field. With Guided Review, the transaction record goes to guided review. Users are shown a table with all resulting records and need to select one of the records. Take First means the first record found is automatically selected. No Result sets the rule status to ‘Done, No Result’ and the next rule is processed. If the Take All option is selected and there are multiple results, the query result is written in field “Multiple Installment Ids” as a comma-separated list of records, and the Installment lookup is left empty. If there is just one result, the Installment lookup is filled with the result and “Multiple Installment Ids” is left empty.
Single Results StrategyStrategy for what to do if the query returns only one field. Guided Review sets the transaction record to go to guided review. Users are shown a table with all resulting records and need to select one of the records. Take Result means select the record that was found.
Object to Query, Return Field, Where and Order by FieldsTogether these fields are used to form a SOQL query. Note that for the where clause, SOQL is not case sensitive.
FilterA filter for the Object to Query drop-down list, which can be very long. This value is not saved in any way.
Result Fields to DisplayOnly if Multiple Results Strategy ‘Guided Review’ is selected. Use this field to define how the table in guided review is rendered.

Use this rule type to match Transactions or Inbound Reports to specific keywords. You can search for up to 500 keywords in a rule, but keep in mind the searching process is quite heavy. The searching stops on the first keyword found.

Before you can use Keyword Search rules, you need to have your keywords defined in Salesforce. You can do this with standard objects and fields or create a custom object for this purpose. The Keyword Search rule returns the selected field when matched, this could be a lookup to an object, a text field or any field. Below is an example rule that searches through keywords by ‘payment reference’ defined in the Keyword custom object and returns the Campaign object.

note

Keyword matching case insensitive.

Guided Matching keyword search setup

Guided Matching keyword search

Keyword Search setup

SettingDescription
Keyword ObjectSelect the object (custom or standard) where your keywords are defined.
FilterUse a filter to narrow the Keyword Object drop-down list, which can be very long. The filter value is not saved in any way.
Return FieldDefines which field on the Keyword Object contains the return value for a successful search. The Return Field value is added to the transaction field where the rule is used.
WhereSpecifies the conditions for applying the Keyword Search rule. Those records that fulfill a specified condition. Define where the keywords are found in the Keyword Object, where they are located in the transaction record, and what the matching relationship should be. Use the plus button to add additional conditions.
Order byUse Field and Sort Order to order the search results if needed.

Keywords as regular expressions

The Keyword Search rule based on regular expressions. That means your keywords are interpreted with regex logic. You can leverage this capability by, for example, adding regex constructs in your keyword values to cover a wider range or possibilities than exact one-to-one matches. For example, if you have run a campaign for supporting Syrian refugees and want to capture all possible transactions that have different spellings for “Syria,” you could have these in your keyword list:

  • Syr.a
  • Syr[iy]a
  • Syria|Syrya
  • Syr.*a
  • Syr.?a

Rule Type: Normalize

Use this rule type to change how a string is present. For example, the raw string for a campaign code could look like ‘Save THE TIGer.’ You can use a normalize rule to change that to ‘savethetiger.’

Guided Matching normalize rule

Normalize setup

SettingDescription
Case StrategyDefine how to handle capitalization. Select None to not normalize case. Select To Upper Case to change all characters to uppercase. Select To Lower Case to change all characters to lowercase
Whitespace StrategyDefine how to handle whitespace. Select None to ignore whitespace. Select Trim to remove whitespace at the start and end of the string. Select Remove All Whitespace to remove whitespace anywhere in the string.

Rule Type: Fixed Width Extract

Use this rule type to extract a value from a Transaction or Inbound Report field according to the position of the value in the field. There are many payment files which are structured according to fixed positions, such as CODA and N43.

Extracted values are trimmed of excess filler spaces by default.

Guided Matching Fixed Width Extract

Fixed Width Extract setup

SettingDescription
Input FieldField from which a value is extracted using fixed position parameters.
Line Starts WithA value will be extracted from the first line starting with this value. If this is left empty, extraction begins from the first line of the field.
Start PositionFirst position in the line of the value to be extracted. Note that the first position in a line is 1.
End PositionEnd position in the line of the value to be extracted. The characters between start and end position will contain the result of the extraction.
Only If Line Starts With, Start Position, End Position and ValueMany fixed length file formats have switches in the file. In order to make it easy to base logic on these switches, this rule includes an “Only if” refinement. The extraction rule is used only if Line Starts With, Start Position and End Position equals the Only If Value. If no “Only If” refinement is provided, the rule will be processed if the entry criteria are met.

Rule Type: Guided Review

If you know certain fields may need something from the user who conducting the review, use this rule type to define the manual actions for the reviewer.

Guided Matching guided review

Guided Review setup

SettingDescription
Guided Review TypeDefines the review action. Salesforce field: the Salesforce field is shown to the user in the Guided Review component in edit mode. The user can set the value. Search (only for reference type fields): guided review asks the user for a search query after which a SOSL query is performed on all fields to find related records. Users can select one of the results, after which guided matching continues. Combined Contact and Account Search (only on Contact): this is similar to Search, except that it allows searching Contact and Account at the same time.
Result Fields to DisplaySpecify which fields to display in the search results of the guided review component; only relevant for Search, Combined Contact and Account Search.
Prefill Search Box with Transaction FieldSelect a transaction field to prefill the search box and automatically do the first search based on the field value; only relevant for Search, Combined Contact and Account Search.
Max Number of ResultsSpecify how many results are displayed in the search results (range 1-50); only relevant for Search, Combined Contact and Account Search.
User GuidanceSpecial guidance for the guided review that is displayed to the reviewer.
Show “Skip & Continue” ButtonSelect this option to allow the user to just skip the current guided review rule and proceed to the next rule.

Rule Type: Create Record

Use this rule type to create a Record, Contact, Payment Profile or Installment. For Contact, Payment Profile and Installment, mapping is automatic wherever possible to ensure data is created in a way that FinDock supports. The auto-mapping is described clearly in the rule setup section. For the Create Payment Profile rule, you can also map the correct record type.

Enforce uniqueness should be enabled (FinDock general settings) if you use a create Payment Profile rule. The Payment Profile enforce setting is enabled by default for FinDock installations after the June 2020 release. You can use a create rule for Payment Profile without enabling enforce uniqueness. However, processing this rule may lead to duplicate records in some cases. In the example below, a record is created based on information in the processed file.

Guided Matching Create Record

Create Record setup

SettingDescription
MappingEach field of the created object can be mapped. A field can be either mapped to a constant value or to a Transaction field.
Upsert FieldUnder advanced settings, select this option if you want the rule to use an upsert operation, instead of insert, using the selected field as key. Upserting ensures there is no chance of duplicate records being created. A deduplication approach using a query rule to first find existing records and then only create if not found catches most duplication scenarios. However, this approach cannot 100% guarantee no duplications because of the parallel processing characteristics of Guided Matching.

Rule Type: Update Record

Use this rule type to update any object. This rule can be added to any lookup or master-detail field.

The rule will be skipped if no record is related to the Transaction or Inbound Report record. In all other cases, it will update the related record according to the mapping you have defined.

Guided Matching update record

Update Record setup

SettingDescription
MappingEach field of the related object can be mapped. A field can be either mapped to a constant value (mapping type: Value) or to a Transaction or Inbound Report field (Mapping type: Field). If the “Only If Blank” checkbox is selected, the field will only be updated if does not already have a value.

Special update rule for Campaign

The Update Campaign Member rule is a special update case because Salesforce does not allow lookups to Campaign Member. The Update Campaign Member rule instead acts on the text field “Campaign Member Id” which comes pre-shipped from FinDock on Transaction and Inbound Report.

Rule Type: Manage Source

If you have NPSP as a source package, the Manage Source rule creates an NPSP Opportunity if no existing Installment (and thus Opportunity) was found. To create the Opportunity FinDock uses the mapping as defined in the NPSP Opportunity Installment mapper.

The Manage Source Rule Type is included in all managed rule sets and can not be added through the Guided Matching setup.

Rule Type: Find Duplicate

Every reference field on Transaction and Inbound Report records has the Find Duplicate rule type. For the purposes of this explanation, we use the Account reference field as the example.

Creating a new rule is mostly about mapping between Account and the Transaction or Inbound Report record. This mapping defines how an Account record is created in memory so that it can be checked for duplicates in Salesforce according to the active Duplicate Management rules (standard Salesforce functionality). The following screenshot shows a simple mapping to the Account Type field on Account.

Find Dupclicate rule setup mapping

The Find Duplicate rule type has Multiple Results Strategy, Single Result Strategy, and Result Fields to Display settings which behave the same way as they do for the Query rule type.

Find Dupclicate rule setup settings

Rule Type: Create Campaign Member

This rule behaves the same as the generic Create Record rule type, but is specifically for the Campaign Member object. The rule setup uses a lookup of the Campaign Member Id for Transaction or Inbound Report records.

Guided Matching Create Campaing Member rule type

If a lookup results in a new Campaign Member record, you can see the action in the Guided Matching Progress component.

New campaign member created

Rule Type: Process Installment

This rule is always included in the rule exception plan as the last step of Guided Matching using a three-step process as outlined here.

Step 1 - Installment Change Calculator

First the Process Installment rule calculates the required installment changes to fully match the Transaction or Inbound Report record. These changes are not applied to any record at this point.

The Installment Change Calculator takes as input:

  1. A Transaction or Inbound Report record
  2. A list of one or more identified installments (order is important for the calculation algorithm)

As output, the calculator determines the required installment changes to fully match the input record. An installment change can be:

  • New status for the installment
  • Amount for the first Payment record that needs to be calculated
  • If there is an overpayment, the amount for the second Payment record is calculated. (This is only for overpaid installment scenarios in which the overpaid part, the remaining amount, is inserted into the system as a separate Payment record.)
  • New Last Collection Date for the installment
  • New Last Reversal Date for the installment

The process continues until all the full transaction amount has been accounted for.

The Installment Change Calculator has two modes for overpaid installment handling:

  • Book Remainder On Next: A payment is created for the open amount, and if there are further identified installments, the remainder is booked against them. If there are no further identified installments, the transaction or inbound report always goes to Guided Review.
  • Book All On First: The full amount is booked against the first installment with two Payment records: (1) with the open amount, and (2) the remaining amount.

Using the Overpaid Installment Handling dropdown list, you can select which mode you want the Process Installment rule to use.

Overpaid handling setting for Process Installment

Step 2 - Guided Review Assessment

Based on the calculated changes, FinDock determines if processing can be done automatically or if manual validation is needed, in which case the record is put into Guided Review. There are six criteria for making this assessment, and they can be enabled as part of the Process Installment rule setup.

  • Always: The record is always put into Guided Review, regardless of matching status.
  • Multiple installment identified: If a previous query rule identified more than one installment, the record is put into Guided Review.
  • Multiple installments matched: If the calculated installment changes include more than one installment, the record is put into Guided Review.
  • Not all identified installments matched: If more installments were identified by an earlier query rule than have been matched, that is, not all identified installments have been used, the record is put into Guided Review.
  • One of the matched installments is overpaid: If more money was received than expected so that one installment is overpaid, the record is put into Guided Review.
  • One of the matched installments is underpaid: If less money was received than expected so that one of the installments is only partially paid, the record is put into Guided Review.

If FinDock determines that the Transaction or Inbound Report record does not need to go into Guided Review, the calculated changes from step 1 are processed, meaning that all affected installments are updated, and payments are created accordingly.

Step 3 - Guided Review

Transaction or Inbound Report records that go into Guided Review are presented as shown here:

Guided Review Process Installment results

By clicking on an installment record, you can expand the view to see details prefilled with calculated installment changes, as shown here:

Installmnent details in Guided Review

The first selected field in the configuration is displayed as the third field in the third row (empty in the above screenshot). Next selected fields are shown in further rows below.

The fields that are displayed in an installment row are configurable (see Installment Row Fields configuration screenshot below).

Installment row field configuration

The Installment lookup shows as default results all installments that:

  • Have the same Contact or Account as the matched record
  • Are not closed (status is not Collected, Reversed, Refunded, Rejected, Canceled or Failed).

Guíded Review installment search

The search box searches in all Installments fields and shows results as:

  • Title: Installment Name
  • Subtitle: Configurable (see Installment Subtitle Fields configuration screenshot above)

If + New Installment is used, a new tab opens to create a new installment. The New Installment form (pictured below) is prefilled with:

  • Contact, taken from the Transaction / Inbound Report record
  • Account, taken from the Transaction / Inbound Report record
  • Amount, remaining amount
  • Amount Open, remaining amount
  • Source: Default source
  • Status: New
  • Due Date: Date on the Transaction / Inbound Report record
  • Bank Statement Description: Payment Reference on the Transaction / Inbound Report record
  • Payment Method, Payment Processor, Target
    • If Transaction: Transaction Set > Default Payment, etc.
    • If Inbound Report: Directly from the Inbound Report
  • Payment Profile, taken from the Transaction / Inbound Report record
  • External ID: Prefilled with generated unique string

The New Installment form regularly polls if an installment has been created with the expected external Id. For this to work, the External Id field must be on the Installment page layout.

Polling for installments

Save & Continue is disabled until the full Transaction Amount has not been accounted for. After clicking Save & Continue, the form is processed, which is seen in the progress component which shows the payment amounts for the installments.

Guided Matching progress component with installment payment details

Process Installment decision matrix

The table below shows how FinDock decides what to do with a Transaction or Inbound Report record with regards to installment handling.

Transaction Debit / CreditInstallment Receivable / PayableOtherTransaction Status after ProcessingInstallment Status after ProcessingInstallment Amount Open after ProcessingPayments after Processing
CreditReceivableTransaction Amount = Installment Amount OpenMatchedCollected0New payment with Transaction Amount
CreditReceivableTransaction Amount < Installment Amount OpenMatchedPartially PaidInstallment Amount Open – Transaction AmountNew payment with Transaction Amount
CreditReceivableTransaction Amount > Installment Amount OpenMatchedCollectedInstallment Amount Open – Transaction AmountNew payment with Transaction Amount
DebitPayableTransaction Amount = Installment Amount OpenMatchedPaid0New payment with -1 * Transaction Amount
DebitPayableTransaction Amount < Installment Amount OpenFailedNot changedNot changedNot changed
DebitReceivableTransaction Amount = Installment Amount & Installment Status = Collected & Installment Amount Open = 0MatchedReversedInstallment AmountNew payment with -1 * Transaction Amount
DebitReceivableElseFailedNot changedNot changed
CreditPayableInstallment Amount Open after processing <= 0MatchedPaidInstallment Amount Open + Transaction AmountNew payment with Transaction Amount
CreditPayable0 < Installment Amount Open after processing < Installment AmountMatchedPartially PaidInstallment Amount Open + Transaction AmountNew payment with Transaction Amount
inCreditPayableInstallment Amount Open after processing >= Installment AmountMatchedOutstandingInstallment Amount Open + Transaction AmountNew payment with Transaction Amount