Check Scanning UI Configuration

Configuring Columns and Fields in the Check Scanning Grid

Configuring the Check Scanning User Interface

The next step in the Check Scanning Configuration process allows Salesforce Administrators to streamline the Accounts Receivable process. The settings will determine what fields will be displaying in the check scanning grid, which objects will be read from, and which objects and values will be written to.

An Introduction to the Check Grid

Before an Administrator can begin configuring the check scanning user interface, he/she must first understand the data model behind the check scanning grid. The Payology Check Scanning Check Grid consists of two data sets (two objects), both of which are most commonly generated with the installation of Payology Lite.

Object	Description
Check	The Check object, by default, contains general values associated with the check. For example, it includes the account number, routing number, check number, and amount. For each check scanned within the Payology Check Scanning App, the values for all corresponding fields will be saved to this type of object. The check image, front and back, and all corresponding images (remittance items or documents) will also be related/saved to this record. When configuring the check scanning user interface, Salesforce Administrators must be cognizant of which custom values or fields they will save to this object. For example, non-profit organizations may determine that Donor data (i.e. Donor ID, Campaign ID, Fund ID, etc.) is saved within the Check as there can only be one of those values per check scanned. In comparison, for a general service-based business, solely the payee data (i.e. account - client) will be saved to the Check record.
Check Allocation	The Check Allocation object, by default only holds one field: the check allocation amount. However, this object after its customization holds all values needed to apply a check. For example, for non-profit organizations, it may hold the gift type (i.e. one-time gift, pledge, matching gift, etc.), soft credit contact, honors contact, or note. In comparison, for a general service-based business, the object most commonly includes fields for the invoice. The most significant difference between a Check and a Check Allocation is that there may be more than one Check Allocation for each check record. The most frequent example is one check will be applied to multiple invoices or one check to multiple gift types (i.e. one-time gift + pledge).

Important Notes

The Payology Lite App is not required. The Check and Check Allocation object can be custom objects created by Salesforce Administrators. However, if not using the Payology Lite App, Salesforce Developers must create transmission scripts to submit all Check items to the Check21.com gateway or other third parties (i.e. processors, aggregators, etc.). Keep in mind, that as part of the activation fee of the check scanning solution, Check21.com will provide up to 10 hours of configuration time. In many cases, clients will not have to configure Payology Lite or Payology Check Scanning themselves.

Configuring Field Settings

To complete the second step of the configuration process, we must:

1. Navigate to the App Launcher
2. Type and Click on "Payology Check Scanning"
3. Click "Payology Check Configurations"
4. Click "Field Settings"
5. Using the guide below, configure all the necessary fields required for the accounts receivables process.
6. Click the "Save" button

Configuration Guide

The Field Settings configuration consists of three functions:

1. Choosing the Batch, Check, and Check Allocation objects
2. Choosing the Auto-Fill Class to be used
3. Choosing the fields to display within the Check Grid

Batch, Check, and Check Allocation Object Selection

When a check scanning batch is saved or closed, all data found within the check grid is saved to three objects: the Batch, Check, and Check Allocation objects.

When clicking on the "Field Settings" tab, a metadata search of all Salesforce objects is initiated. However, the metadata search does not seek to find specific object names but the fields necessary within the Salesforce objects to facilitate the batch saving process.

For example, when searching for possible Batch objects which can be used, the Payology Check Scanning App searches for any object which has batch status, batch count, and batch amount fields. It will then list all possible objects which can be used. The same types of search are initiated for Check and Check Allocation objects. If only one object is found, the object will be pre-selected and greyed out to the Salesforce Administrator.

Building and Selecting the Auto-Fill Class

The Auto-Fill Class is an APEX Class which streamlines the check scanning process. It most commonly allows for the pre-population of data chosen on the check scanning user interface. Similar to the metadata search which is initiated on "Field Settings" selection, the Payology Check Scanning App searches for APEX Classes within the Org that use the method required. The APEX Class created will then appear in the Auto-Fill Class picklist.

General Service-Based Example: Upon the scanning of a check item, an APEX Auto-Fill Class for a general service-based business may:

1. Determine whether the check routing number and account number matches a previous payee.
2. If it does, it will prepopulate the payee field with the account or contact previously selected.
3. Determine whether the payee has any open invoices.
4. If it does, it will select the oldest to newest invoices, creating a check allocation (choosing the invoices) for each invoice until the total amount of the check is equal to the total amount of invoices selected.
5. Or, if no invoices exist, it will simply select "Prepayment" as the allocation type as this selection is most common when no invoices exist.

Non-Profit Based Example: Upon the scanning of a check item, an APEX Auto-Fill Class for a Non-profit organization may:

1. Determine whether the check routing number and account number matches a previous donor.
2. If it does, it will prepopulate the donor/household field with the account and contact previously selected.
3. Determine whether the donor has an existing pledge.
4. If it does, it will select the oldest to newest pledges, creating a check allocation for each opportunity until the total amount of the check is equal to the total amount of payments/opportunities which will be generated/updated.
5. Or, if no pledges exist, it will simply select "One-Time Gift" as the gift type as this gift is the most common when a check is received.

For instructions on how Salesforce Developers can develop the Auto-Fill Class, please contact your Check21.com Account Manager.

Sample Auto-Fill Class

The below code sample is an Auto-Fill Class built for NPSP and used in the Payology open extension.

NPSP Auto-Fill

public with sharing class c21NPSPAutoAllocation implements C21AutoAllocation{
    private checkforce2__Config__c configData;
    public Map<String, Object> getValues(String checkRow, String allocationRow) {
        Map<String, Object> result = new Map<String, Object>();
        Map<String, Object> check = (Map<String, Object>)JSON.deserializeUntyped(checkRow);
        Map<String, Object> allocationNew = (Map<String, Object>)JSON.deserializeUntyped(allocationRow);
        //Hash
    if(check.get('checkforce2__User_Routing_Number__c') != null && check.get('checkforce2__User_Account_Number__c') != null){
        String concat = (String)check.get('checkforce2__User_Routing_Number__c') + (String)check.get('checkforce2__User_Account_Number__c');
        String hashToCompare = C21Utils.checkIdentificationHash(concat);
        //Compare hash
        checkforce2__Check__c queryCheck = [SELECT Id, Household__c, checkforce2__Amount__c, checkforce2__CheckIdentificationHash__c
                                            FROM checkforce2__Check__c 
                                            WHERE checkforce2__CheckIdentificationHash__c =: hashToCompare
                                            LIMIT 1];
        if(queryCheck != null){
            result.put('Household__c', queryCheck.Household__c);
            //Get allocation
            List<Opportunity> oppHouseHoldList = [SELECT Name, Stage, AccountId, CampaignId
                                                  FROM Opportunity
                                                  WHERE AccountId =: queryCheck.Household__c];
            List<Map<String, Object>> listMapAll = new List<Map<String, Object>>();
            Map<String, Object> allocation = new Map<String, Object>();
            if(oppHouseHoldList != null && oppHouseHoldList.size() > 0){ 
                for(Opportunity opp : oppHouseHoldList){
                    if(opp.Stage === 'Pledged'){
                        allocation.put('Gift_Type__c', opp.AccountId);
                        listMapAll.add(allocation);
                    }
                    if(opp.CampaignId != null){
                        Id gauCampaign = [SELECT npsp__Campaign__c
                                          FROM npsp__Allocation__c
                                          WHERE npsp__Campaign__c =: opp.CampaignId
                                          LIMIT 1];
                        result.put('Campaign__c', opp.CampaignId);
                        result.put('General_Accounting_Unit__c', gauCampaign);
                        allocation.put('General_Accounting_Unit__c', opp.AccountId);
                        listMapAll.add(allocation); 
                    }             
                }
            }
            //Count Amount
            Decimal checkAmount = (Decimal)check.get('checkforce2__Amount__c');
            Decimal sub = 0;
            if(oppHouseHoldList != null){                                       
                for(Integer i = 0; i < oppHouseHoldList.size(); i++){
                    sub = checkAmount - oppHouseHoldList[i].Amount;
                    if(i == 0 && sub < 0) {
                        allocation.put('Employer_Name__c', oppHouseHoldList[i].AccountId);
                        allocation.put('Opportunity__c', oppHouseHoldList[i].Id);
                        allocation.put('checkforce2__Allocation_Amount__c', oppHouseHoldList[i].Amount);
                        result.put(this.configData.checkforce2__Check_Allocation_Object__c, allocation);
                        return result;
                    } else if (i >= 0 && sub > 0){
                        allocation.put('Employer_Name__c', oppHouseHoldList[i].AccountId);
                        allocation.put('Opportunity__c', oppHouseHoldList[i].Id);
                        allocation.put('checkforce2__Allocation_Amount__c', oppHouseHoldList[i].Amount);
                        listMapAll.add(allocation);
                    } else if(i > 0 && sub < 0){
                        break;
                    } 
                }
            }
            if(sub > 0){
                allocation.put('Employer_Name__c', oppHouseHoldList[i].AccountId);
                allocation.put('Opportunity__c', oppHouseHoldList[i].Id);
                allocation.put('checkforce2__Allocation_Amount__c', oppHouseHoldList[i].Amount);
                listMapAll.add(allocation);
            }
            result.put(this.configData.checkforce2__Check_Allocation_Object__c, listMapAll);
        } 
    }
        return result;
    }
    public C21AutoAllocation setConfigData(checkforce2__Config__c configData) {
        this.configData = configData;
        return this;
    }
    public String getDescription() {
        return 'Stantard Auto Allocation (SAMPLE)';
    }
}

Check Grid Configuration

For each field/column which will be displayed in the Check Grid, there are 8 sets of configuration options:

1. Column
2. Index
3. Column Info
4. Read Info From
5. Additional Picklist
6. Write Info To
7. Hidden Field
8. Filter and Relationship

The Column

The Column represents the name and type of each column which will be created within the check grid. The Check Grid column configuration has two fields which require values.

Field Name	Description
Column Name	The value found within the column name field will appear on the header of the Check Grid. This value is indicative of the name of the column within the header.
Allocation	If selected, all fields which appear within the column will be written to the Check Allocation object selected. * Please note that if Active, each time a check is applied to multiple allocations on the Check Grid, these fields within this column must be filled.

The Salesforce Administrator may add or remove columns that will be listed in the header by clicking on the "+" or "-" buttons displayed to the right of the column name.

The Index

The Index represents the order in which fields will be displayed within the column. The Check Grid index is auto-numbered/ordered based on the position of the field on the grid. The Salesforce Administrator may add or remove fields that will be listed in the column by clicking on the "+" or "-" buttons displayed to the right of the Index number.

The Column Info

The Column Info represents the name and type of field(s) which will be created and displayed within the column. It is also used to determine the width of the field in the check grid and the caption/name of the field.

The three fields within the Column Info configuration include:

Field Name	Description
Field Type	The field type includes the following options: Manual Picklist - A static set of picklist values that are not derived from Salesforce records. When selected, the Salesforce Administrator will not choose any read info fields and will be required to input values into Additional Picklist. Auto Picklist - A dynamic set of picklist values that are derived from Salesforce records. When selected, the Salesforce Administrator is required to fill the read info fields. The most common example of the auto-picklist may be a selection of invoices in picklist format on the check grid (i.e. the user will click on a picklist to display all invoices). Autocomplete - A dynamic set of data points derived from one or more Salesforce records/objects. When selected, the Salesforce Administrator is required to fill the read info fields. The most common example of autocomplete usage may be a selection of an account or contact on the check grid. Because many such records may exist, the most efficient user experience may be to type a few letters allowing the user to select from all matching records. Input Box - A static standard text box. When selected, the Salesforce Administrator will not choose any read info fields. The most common example for the usage of the Input Box within the check grid is for payment notes. Checkbox - A static, standard checkbox. When selected, the Salesforce Administrator will not choose any read info fields. An example of usage of the Checkbox may be to request approval of the check allocation prior to its transmission to the bank. Technically, this may open a Salesforce case on batch closure. Calendar - A static, standard calendar input box. When selected, the Salesforce Administrator will not choose any read info fields. A common example for the usage of the calendar is to select the date in which the check is received when in some instances it may be different than the day it was scanned. For non-profits and IRA administrators, this field is especially important as the checks are received at the end of the fiscal year and a determination of the tax year must be decided. Currency - A static, standard currency input box. When selected, the Salesforce Administrator will not choose any read info fields. A common example for the usage of the Currency field is for the check allocation amount. It is indicative of the amount of the check which will be applied to the allocation (i.e. invoice, one-time gift, account, etc.). Display Option - A dynamic set of data points derived from one or more Salesforce records/objects. When selected the Salesforce Administrator is required to fill the read info fields. The most common example of the Display Option usage is to display invoice line items for the invoice which may have been selected by the user. Another example is the insurance policy information of the policy to which the check is being applied.
Width	The width of the field in the check grid. Must be in pixel and formatted correctly (i.e. 100px).
Caption/Name/Placeholder	The name/caption within the field in the check grid. Because a column may have many fields and the fields do not appear in the header of the check grid, it is important that this field be filled. An example of a value may be "Enter Payee Name".

Read Info From

The Read Info From represents the object(s) and field(s) which will be used when an Autocomplete or Auto-Picklist field is selected for display in the check grid. It will also be used to determine which fields of an object may appear within an OCR scan line or barcode on a remittance item.

Similar to the Batch, Check, and Check Allocation selection, upon the clicking of the "Field Settings" tab, a metadata search of the Salesforce Org is initiated and each object and field found is displayed in the picklist fields within Read Info From. Therefore, it is important for Salesforce Administrators and/or Architects to determine which fields must exist in the Org prior to configuring the check grid user interface.

The four fields within the Read Info From configuration includes:

Field Name	Description
Object Name	Name of object(s) whose records will be searched when an autocomplete field or auto-picklist field is selected. An example of an object to read from for an Autocomplete may be "Accounts".
Field Name	Fields that will be displayed or recorded (but hidden) that belong to the object selected. An example of a field to display may be "Company Name". An example of a field to record (hidden) but not display may be the "ID" field.
Coded	Determines whether the field that has been selected will appear on a remittance advice. For example, in a general service-based business, the invoice number may be coded. As an example for the non-profit space, a Donor ID may appear on the remittance advice and must be coded.
Hidden	In many instances, the data which is read and is selected by the user during the check scanning process is insignificant for application. For example, the field "Company Name" may be displayed and selected by the user but only the Account.ID field is needed to create post-batch closure triggers. Therefore, the ID field will be selected but will be marked hidden as it serves no purpose if being displayed to the user in the check grid.

The Salesforce Administrator may add and remove objects/fields to read from by clicking on the "+" or "-" buttons displayed to the right of the "Hidden" checkbox. Salesforce Administrators should be aware that multiple objects can be selected (i.e. Accounts + Contacts). However, there must be a relationship between the two, and that such a relationship is configured in the "Filters and Relationships" section.

The Additional Picklist

The Additional Picklist is a static, standard picklist that is used only when the field type selected is either Manual Picklist or Auto-Picklist. The most common use of the field, when selecting Auto-Picklist as an example, is to add additional value to the picklist being returned by Salesforce. For example, if the auto-picklist was a picklist of invoices that were open in Salesforce, but an additional option was needed in the picklist for "prepayment", the Salesforce Administrator would enter this value in the Additional Picklist field. The visual for the check scanning user would be a picklist showing all open invoices plus an additional value they can choose from title "prepayment". Non-Profit organizations can use the Auto-Picklist to display all open pledges and provide options for, as an example, one time gifts, matching gifts, one-time gifts with soft credits, etc.

The Salesforce Administrator may add or remove picklist items to display by clicking on the "+" or "-" buttons displayed to the right of the "Additional Picklist" field.

The Write Info To

The Write Info To is required for all field types except "Display Icon". The purpose of the Write Info To configuration options is to determine what field values selected or entered by the user during the scanning process must be mapped to either the Check or Check Allocation objects on Save or Post-Batch Closure. These field values are used primarily to apply the check received to invoices, opportunities, cash receipts, accounts, etc.

The six fields within the Write Info To configuration include:

Field Name	Description
Object Name (To Read From)	In combination with Field Name (To Read From), this field will be used to determine which of the fields from the Read Info From will be saved to the Check or Check Allocation object (depending on whether the column type is "Allocation"). If the field type selected is not "Auto-picklist" or "Auto-Complete" this field will be grayed-out.
Field Name (To Read From)	In combination with Object Name (To Read From), this field will be used to determine which of the fields from the Read Info From will be saved to the Check or Check Allocation object (depending on whether the column type is "Allocation"). If the field type selected is not "Auto-picklist" or "Auto-Complete" this field will be grayed-out. For example, for general based businesses, although the Read Info From may have the invoice number, invoice amount, and open balance displayed, the only info which is required to be saved is the "ID" of the invoice record.
Field Name (To Map to)	Determines where the value of the Field Name (To Read From) will be mapped to in the Check or Check Allocation record on save or save and close. For field types that are not "Auto-Picklist" or "Autocomplete", there will be no Field Name (To Read From) option. Any value entered or selected by the user on the UI, will be automatically mapped to this field. This field is not grayed out and is required for all field types except "Display Icon".
Default Value	This field can be used to streamline the check scanning process by auto-selecting the default value to choose from.
Show Create New Record	Determines whether the user can add a new record directly from the Check Scanning UI. The most common use case, for non-profits as an example, is the creation of a new household or donor. When clicking on the donor autocomplete field in the check scanning user interface, in addition to the function of searching for a donor, an option titled "+Create New Record" will appear. This option will then open a new browser tab, directing the user to create a record.
Required	When selected/active, a value for this field will be required. If a value is not entered, the check validation status on the grid will appear with an error.

The Salesforce Administrator may add or remove field values to write/map to by clicking on the "+" or "-" buttons displayed to the right of the "Default" field.

The Hidden Field

The Hidden Field is especially useful when certain fields within the check grid must be hidden until another field or field value selected by the user during the check scanning process is matched. For example, non-profit organizations may want to display a field for "Soft Credit Contact" or "Soft Credit Amount" only if a "One Time Gift with Soft Credit" was selected by the user during the check scanning process. For a general service-based business, the option to choose the revenue type may be necessary when the user has selected "prepayment" as opposed to an invoice.

The Hidden Field configuration consists of four fields in an equation-like formula. Salesforce Administrators will most likely be familiar with this format as it is widely used across Salesforce. The four configuration fields are:

Field Name	Description
Object	In combination with Field, the Object selection is used to determine which field value will be used in the equation. In most cases, the object selected will be either Check or Check Allocation.
Field	In combination with Object, the Field selection is used to determine which field value will be used in the equation. In most cases, the field selected will be fields that were used in the "Write Info To" and appear in Check or Check Allocation.
Mathematical Equation	Unless told otherwise by Check21.com Account Managers, Salesforce Administrators should limit the selection of options to "Contains", "Does Not Contain", "Equals To" and "Does Not Equal To". These options will be used to determine whether the Value selected meets the value of the Field.
Value	The expected value(s) of the Field selected.

The Salesforce Administrator may add or remove the matching criteria of hidden fields by clicking on the "+" or "-" buttons displayed to the right of the "Value" field. Salesforce Administrators should also be cognizant of the "(", ")", "AND", "OR" options which can be used to combine multiple matching criteria. Please speak with your Check21.com Account Manager for a detailed description of its usage.

Filter and Relationship

The Filter and Relation Configuration serves two purposes:

1. To filter the results of "Read Info From"
2. To create a relationship between two objects within the "Read Info From"

The Filter and Relationship configuration consists of either four or five fields in an equation-like formula. Salesforce Administrators will most likely be familiar with this format as it is widely used across Salesforce. The field options are as follows:

Field Name	Description
Object (To Read From)	In combination with Field (To Read From), this field is used to determine the read object. It most commonly points to a field in the Check or Check Allocation Record, objects found with Read Info From, or fields displayed in the Check Scanning Grid.
Field (To Read From)	In combination with Object (To Read From), this field is used to determine the read field. It most commonly points to a field in the Check or Check Allocation Record, objects found with Read Info From, or fields displayed in the Check Scanning Grid.
Mathematical Equation	The difference between the mathematical equation option listed within this picklist and those common to the Salesforce ecosystem is: 1) Related to Field on Screen - The selection of this option creates a relationship between an object/field selected within Read Info From and a field displayed within the check scanning grid. An example of this option would be creating a relationship between an account selected and the bills which correspond to the account. For non-profits, this would be the relationship between a household/donor selected on the check grid and their open pledges/opportunities. 2) Related to Object Field - The selection of this option creates a relationship between an object/field selected within Read Info From and a field within the Check or Check Allocation objects. 3) Master-Detail - The selection of this option creates a relationship between two objects/fields selected within Read Info From. For example, if the Administrator selected to combine an account with a contact and display it in an Autocomplete field, there would be a master-detail between Account.Account_ID and Contact.Account_ID.
Object (To Match Against)	In combination with Field (To Match Against), this field is used to determine the matching object. It most commonly points to a field in the Check or Check Allocation Record, objects found with Read Info From, or fields displayed in the Check Scanning Grid.
Field (To Match Against)	In combination with Object (To Match Against), this field is used to determine the matching field. It most commonly points to a field in the Check or Check Allocation Record, objects found with Read Info From, or fields displayed in the Check Scanning Grid.
Value	If not using Master-Detail, Related to Object Field, or Related to Field on Screen, this field will be displayed. The field is most commonly used for filtering purposes only. It is not used to create relationships between objects/fields. An example of the use of the value field would be when the Read Info From points to an Account object and the Administrator wants to filter the results of the Account to a "client" Record Type.

The Salesforce Administrator may add or remove the filtering/relationship criteria of the field by clicking on the "+" or "-" buttons displayed to the right of the "Value" or Field (To Match Against) field. Salesforce Administrators should also be cognizant of the "(", ")", "AND", "OR" options which can be used to combine multiple filtering/relationship criteria.

Previewing the Check Grid

Upon completion of the Check Grid Configuration, Salesforce Administrators must click the "Next" button on the bottom right side. After doing so, the Administrator can go back to the "Field Settings" tab and click the "Preview" button on the bottom right side. This will allow Administrators to preview the Check Grid without the use of a scanner.

Streamlining Check Grid Configuration Promotion to UAT or Production

To streamline the promotion of the configuration settings from Sandbox to UAT or Production, each step of the configuration process includes an "Upload" and "Download" button. When clicking the "Download" button, a JSON file will be provided to the user. This JSON file can then be uploaded in UAT or Production environments by clicking on the configuration step and selecting the "Upload" button, choosing the downloaded file as the final step. Please ensure you are uploading and downloading the correct JSON file for each step of the configuration process.

Next Steps

To continue the configuration process, Salesforce Administrators can optionally choose to configure the batch save pop-over. For detailed information on the configuration of the pop-over, please see the next section, labeled Batch Save Pop-Over Configuration.