Skip to main content

Configuring Guided Matching

Configuring Guided Matching involves modifying page components and layouts, and then customizing Guided Matching rules.

Add Lightning components and fields

You need to make modifications to Transaction and Transaction Set record pages to be able to use Guided Matching.

To configure Transaction and Transaction Set record page for guided Matching:

  1. Add the following Lighting components to the Transaction page:
    • Transaction Set Progress
    • Guided Review
    • Guided Matching Progress
  2. In Lightning App Builder, you can define what rules to show:
    • Hide Skipped Rules
    • Hide Done No Result
    • Hide Not Yet Processed
  3. For implementation and testing purposes, you can add the following fields to the Transaction page layout in your sandbox org:
    • Guided Matching Error
    • Guided Matching Job Id
    • Guided Matching Log
    • Guided Matching Nr of Rules Processed
    • Has Been In Guided Review
    • Start Guided Matching
    • Guided Matching Nr Of Retries
    • Matched by ProcessingHub
    • Guided Matching Installment Processed
    • Last Worked On Date
  4. Add the Transaction Set Progress Lighting component from step 1 to the Transaction Set page.
  5. Add the field ‘Guided Matching Setup’ to the Transaction Set page layout.

Customize matching rules

You can customize matching rules to improve Guided Matching performance for your specific business logic. Custom rules are defined in a Guided matching ‘setup,’ and each setup is only used for a given Target. The rules are linked to a specific field on the transaction record, and the result of the rule is stored in that particular field. For some payment extensions, FinDock provides predefined rules. For more information, see Guided Matching managed and suggested rules.

To configure custom Guided Matching rules:

  1. Launch the FinDock app and click Setup.
  2. If you cannot see a Guided Matching Setup tab, make sure the tab is visible for your profile. For further information on tab visilibity, see Salesforce Help.
  3. Click the Guided Matching Setup tab. guided-matching-setup
  4. Select a Target for the custom rule set from the drop-down list.
  5. Create a new rule for a field by clicking the ‘+’ icon or edit an existing rule by clicking on the rule name. guidedmatchingsetup_custom_rule_settings
    • TRANSACTION CUSTOM FIELDS: Most of the enrichment happens with these fields. This is where you typically start creating rules.
    • TRANSACTION ENRICHABLE STANDARD FIELDS: The standard fields (from FinDock) which are used for guided matching. Most of the execution and matching happens based on these fields.
    • TRANSACTION AND OTHER STANDARD FIELDS: Normally these fields should not be enriched, so this section usually remains unchanged.
    • Rule Execution Plan: the order in which the defined rules are processed. The order is calculated automatically and cannot be changed.
    • Settings: click the Active checkbox to apply the custom rule set for the selected Target. Job Size indicates the number of transaction records processed by a Guided Matching Apex job. For production and UAT environments, set this as high as possible, 200 ideally. For development and early testing, set the size as low as possible. This results in more specific error messages. If a Guided Matching job fails, all records for that are marked ‘Failed.’
  6. Create or modify a rule.
    Rule selector
    • Rule Type (required): Type of the rule. See Guided Matching rule types.
    • Rule Name (required): Name of the rule. This seen by the user in Guided Review and Guided Matching Progress Lightning Components.
    • ENTRY CRITERIA: Defines the criteria for applying the rule. The rule is only used when all criteria are true.
      • If empty: the rule is used only if the field is empty.
      • and not matched by ProcessingHub: the rule is skipped by default if ProcessingHub has already found a match. This is typically what you want: skip transactions that are already matched with an installment. However, if you also want to, for example, match the transaction to a campaign, mark the ‘Disabled’ checkbox to skip this criterion. You can also add custom criteria by clicking the ‘+’ symbol with ‘Equals’ or 'Not equals' as operators. If one of the criteria is an empty value (no value), leave the value field blank. Don't enter any text or variables.
    • RULE SETUP: see Guided Matching rule types.
    • ADVANCED: Sometimes a rule execution order cannot be calculated because of dependency cycles. In these cases, use the Forced Execute After Rule option to guide the rule execution order. The rule is executed immediately after the rule selected from the drop-down list. Select the Update And Refresh Before Processing option to update the current state of all transaction or inbound report records within the scope of the Guided Matching job (or the record in Guided Review) to the database and then re-query before processing the rule.
  7. Order rules for a field by clicking on the up and down arrows next to the rule name.
  8. Click Save to save the Guided Matching Setup for the selected Target.

Automated rule order calculation

The order of the rules is calculated automatically based on the following criteria:

  • Rules for which a ‘Forced Execute After Rule’ has been defined are processed after the selected rule without considering any other criteria.
  • In all other cases:
    • The order of rules within a field is never violated.
    • All rule field dependencies are respected.
    • Rule types without possible guided review (e.g. constant and regular expression) are processed as early as possible.

Recalculate formula fields after every rule execution

When a rule is executed, formula fields are recalculated so the most up to date values will be used in the next rule that is being executed. Formula fields can be used in Guided Matching rules and can be trusted to be up to date with previous rule results.


Here's a great best practice shared by one of our partners: use formula fields to implement complex business logic. Create a single Boolean formula fields with all business logic and use that for the entry criteria. They find this easier to maintain. It's a nice example of how Guided Matching and formula fields can be combined.

Guided Matching standard fields

The standard fields that FinDock uses for Guided Matching are described in the table below. This information is not necessarily needed to use Guided Matching, however, it is good to know, and can be useful troubleshooting possible errors in a matching run.

LabelNameDescriptionAllowed user actions
Guided Matching Errorcpm__Guided_Matching_Error__cContains the error in case Guided Matching failed for this transaction or inbound report.Check for troubleshooting.
Guided Matching Installment Processedcpm__Guided_Matching_Installment_Processed__cIf checked, the Process Installment rule has already been performed for this transaction and will not be processed again, even if retried.Can be unchecked if you want to force reprocessing of the Process Installment rule. The rule then also needs to be retried.
Guided Matching Job Idcpm__Guided_Matching_Job_Id__cId of the Async Apex Job that handled this matching run. This field is not updated with the Ids of the jobs that handle retries.None
Guided Matching LogGuided_Matching_Log__cDetailed logs for each rule, stored in JSON format.Check log for troubleshooting
Guided Matching Nr of RetriesGuided_Matching_Nr_Of_Retries__cNumber of times this transaction record has been retried. A transaction is retried in case of a Row Locking exception. For further information, see Salesforce helpNone
Guided Matching Nr of Rules Processedcbm__Guided_Matching_Nr_Of_Rules_Processed__cThe number of rules that have been processed. The initial value is 0, and the final value is total number of rules processedSet to a lower value if you want to reprocess from a previous rule for testing or debugging purposes.
Has Been In Guided Reviewcpm__Has_Been_In_Guided_Review__cChecked if this transaction has been in guided review at least once.Key field for calculating automated matching percentages.
Last Worked On Datecpm__Last_Worked_On_Date__cThis field is set to NOW when the Next button is clicked on the Transaction Set Progress Lightning component.None
Matched By ProcessingHubcpm__Matched_By_ProcessingHub__cChecked if the Status of the transaction record was ‘Matched’ before guided matching started.None
Open Amountcpm__Open_Amount__cUnallocated amount if overpaid handling set to allow remainder on record.None
Processed Installmentscpm__Processed_Installment_Ids__cList of installments that have been changed by the record.None
Start Guided Matchingcpm__Start_Guided_Matching__cIf checked by the user, a guided matching job is placed in the queue. The transaction record will be reprocessed asynchronously in the background. This can also be handled through automation (trigger, process builder, etc.) that can mark this field to initiate a restart.Check if the record needs to be reprocessed asynchronously in the background. Note that you can also change ‘Guided Matching Nr of Rules Processed.’ Change it to the rule number you want to start the guided matching with again. Leave the number as is to start matching from the current rule.
Statuscpm__Status__c(See list below)Usually none. However, there may be cases in which you want to change the status to force a certain behavior.
Use Open Amountcpm__Use_Open_Amount__cIf checked, Guided Matching Process Installment rule allocates Open Amount to next matched installment in overpayment handling.None

Guided Matching states

There are several status options for incoming records. An end state means the Guided Matching processing is complete, with no further processing once that state is reached.

Status options:

  • Matched (end state): the record has been matched to an existing record (typically an installment) or custom rule processing is done
  • Partially Matched (end state): same as Matched, but the record has a remaining Open Amount
  • No Match (end state): the record cannot be matched to an installment
  • Ignored (end state): the record has been marked to be ignored
  • Failed (end state): an error (functional or technical) has occurred that needs to be resolved
  • New: a new record has been created, but ProcessingHub still needs to set it to Matched or No Match
  • Processing: the record is currently being processed by Guided Matching
  • Manual: default Guided Matching processing is complete; optional, additional custom matching logic proceeds according to your business processes
  • Guided Review: user action needed to complete matching the record to an installment