Lookup Helper Admin Guide

Menu; Settings

Create a New Lookup. Use the Lookup Helper interface to easily create new lookups.

View Existing Lookups. View, Edit, Delete, Schedule, or Activate/Deactivate existing lookups.

Enable Real Time. Use the Lookup Helper interface to deploy real-time triggers.

View Health Check. Allows you to check on Lookup Helper’s status, view a risk level assessment for any issues, and suggest action items to resolve any issues. See the Health Check section below for more information.

View Lookup Helper Errors. See all Lookup Helper errors based on Setting. Let’s you know the number of occurrences and last date the error occurred.

Help and FAQ. Includes in-app resources such as:

• Admin Guide
• Frequently Asked Questions
• Troubleshooting Tips
• Update Links

Get Help from the Community. Join our Lookup Helper Community to share ideas, get questions answered, help others, and keep up-to-date with new use cases or release notes that are posted. Then, access the community from within the app.

Deploy Pre-Built Lookups. Deploy pre-built use cases from the Use Case Deployment page and visit our Use Case Library for more inspiration.

Export Lookup Settings. Choose which Lookup settings you want to be exported to a .CSV file.

All Lookup Settings

From the All Lookup Settings tab, you can view all of the Lookup Helper settings, activate/deactivate settings, create a new setting or run/edit/delete settings.

Run Mode: Displays the manner in which your rollups will process.

• Real Time -  In addition to the lookup being active, this icon will only display if an active trigger is deployed for the lookup's source object AND parent object. This icon will not display if "Disable Realtime" is checked for the lookup or "Disable Trigger" is enabled for either the parent or child trigger
• Asynchronous Real Time Enabled For This Lookup
• Real Time Disabled On Source Object Or Trigger
• Scheduled
• Criteria Matching Mode

Parent/Child Filter: Clicking on the parent or child filter link will allow you to view the filter criteria without first going to the lookup.

Active: Allows you to activate/deactivate lookups individually.

Action:

• Run: Manually run your lookup.
• Schedule: Create or Edit a schedule for your lookup.
  • Run Every: Determine how frequently you would like the lookup to run.
  • Last Run: Displays the last time this scheduled lookup ran.
  • Next Run: Displays the next time this schedule will run.
    1. Click the button next to the text box to auto populate the Next Run time with the current time.
  • Clear/Save Schedule buttons will activate/deactivate the schedule.
• Edit: Edit either the lookup, the filter, or both.
• Delete: Delete the lookup.

Settings (gear icon at the top of the page): In the settings pane you will find various Lookup Helper settings as well as the ability to change the running user for Lookup Helper. The settings will be explained in further detail in the “Custom Settings” section below. 

Set… As Running User: The “Run As” user is the user that scheduled lookups will process as. To change it, you can take the following steps:

• Go to your setup page.
• Search “Setup” for “Scheduled Jobs” (or in Classic, navigate to it via Monitor > Jobs > Scheduled Jobs from the left-hand column).
• Delete the scheduled job named Lookup Batch Agent - Hourly (you should be able to see that the “Submitted By” is set to the current “Run As” user, which is likely “Lookup Helper” as that is the default if the Run As user has not been changed.
• On the All Lookup Settings page, click the “Run As…” button at the bottom of the window that pops up.
• Your All Lookup Settings page should now say “Running as [Your User]” at the bottom of the lookup display table, and if you were to return to the scheduled jobs page, you should now see a “Lookup Batch Agent - Hourly” job scheduled with the Submitted By user as your user.

Create a Lookup Setting

Before beginning the creation of the setting, it is important to understand the criteria by which you would like to match records. For some use cases, there is a little pre-work required to have the correct data in fields so that Lookup Helper can use the data in the matching process. If for example you had a Custom Object for Reporting Month and wanted a related list of Closed Opportunities on the Reporting Month records, you would need to use a Formula Field on Opportunity to extract the month and year from the Closed Date.

Opportunity Page Layout showing an example of a Formula Field (Reporting Month Formula) used by Lookup Helper to populate a Lookup Field (Reporting Month).

Step 1: Select Child Object

This is the object that you want to populate a Lookup Field on and whose items you want to see in a Related List on another object.

Step 2: Select/Create Lookup Field to be Used

Note: If creating a new Lookup Field from within the App, field level security and page layouts must be adjusted to make the new Lookup Field visible. Because of this, it is recommended to create the field on the object first in setup and then select the new field in the "Select or Create Lookup Field" step unless you are comfortable with remembering to change field level security after creating your new Lookup Helper setting.

Select the lookup field you would like Lookup Helper to populate or click the “Create New Lookup Field” button to create a new lookup field.

If creating a new lookup field:

1. Select the Object that you want to relate the child to.
2. Name the Lookup Field.

Step 3: Select Lookup Setting Type

Select the fields on the Child and Parent that you would like Lookup Helper to use to match records.

Most of the time, it is preferable to match based on the Record Name or ID. There may be some times that it is not possible. For example, if there is an external system storing Orders under an Account Number rather than Account Name, Lookup Helper could match the Account Number after the Order has been loaded into Salesforce to the Account Number on the Account and populate the Account Name on the Order.

Configure new category records

• • Click this button if you would like to configure options for creating new category records or new parent records.
  • Enable creation of category records?
    • Check this box if you would like Lookup Helper to create new Parent Records if they don’t already exist.
  • Populate field values for new (Your Parent Object) records that are created by Lookup Helper (Optional).
    • Select the field you would like Lookup Helper to update upon record creation.
    • Select equals value or equals field.
    • Enter desired criteria.
    • Note: if the parent object has any required fields they will be added to the list automatically and need to be edited in order to be populated with a value.

Step 4: Save and Run Setting

Save and Run the setting. This will populate a value in the Lookup Field on all Child Records from the Object defined in the Lookup Setting. After the initial run, Realtime will keep the records up to date.

Advanced Settings

• Allow Overwrite of Existing Lookup Field Information
  • Selected by default.
  • If you are using a field that was pre-existing and has values populated on some records, this will allow Lookup Helper to overwrite the values in that field. You can deselect this option if you do not want fields to be overwritten, however, Lookup Helper will then only populate records with a null value in the field.
    • You could create a new field to use for testing purposes and once satisfied with the results, move the Lookup Helper Setting to the new field. Then, delete the one that was used for testing.
  • Allow Clearing of Existing Lookup Field Information
    • Selected by default.
    • With this option selected, Lookup Helper will clear out an existing value in a lookup field, replacing it with a blank value if no matching Parent record is found. If you do not want existing values to be cleared, deselect this option.

Setting Name. Use this field to name the Lookup Helper setting something meaningful like “Opportunities by Sales Rep Territory.”

Field Security. If you selected the option to create a new Lookup Relationship Field from within the app, go to Salesforce Setup to configure your field security and page layouts.

Parent Filtering

The new parent filtering feature allows users to apply additional matching criteria to the parent object. This helps narrow down the amount of matching parents, which gives the user more control! While creating or editing a setting, users can either create a new parent filter, or assign a previously created parent filter.

To create a new parent filter:

1. Click "Add Parent Filter"
2. Optionally: create a name for your filter
3. Optionally: Add a sort and/or offset for your parent records
   • Click on the Sort and Offset Options accordion to open the Sort and Offset section.
   • Skip __ parent records: Enter the amount of parent records you would like to skip. This step can be skipped if the parent records do not need to be sorted.
   • Specify Sort Order: This step can be skipped if the parent records do not need to be sorted.
     
     • Select the field you would like Lookup Helper to use to sort your records by. When creating a sort on a foreign-key relationship field, you will be prompted to select a field on the related object.
     • Select the sort order. Descending will return the newest or largest results or from Z to A alphabetical sort. Ascending will return the oldest or smallest results or from A to Z alphabetical sort.
4. Choose a field on the parent object to filter on (eg. Name)
5. Choose an operator (eg. Equals)
6. Choose/Enter criteria (eg. 'John Smith')
7. Click 'Submit' to add criteria to the parent filter record
8. Click 'Save' to save the parent filter record

You now have a parent filter attached to your Lookup Helper Setting!

The difference parent filtering makes:

• Previously, if there were two Accounts that could qualify (eg. matching to an Account where the billing city = 'Chicago', and we have two Accounts based in Chicago), Lookup Helper would choose the first account it finds.
• Now, if you have 2 accounts in Chicago, one named 'John Smith' and one named 'Roger Williams', Lookup Helper will choose the Account named 'John Smith' because of the parent filter!

Filter Logic feature:

Continuing on this example, we add an additional filter criteria (Name = 'Jane Smith').

• We can change the filter logic to: 1 AND (2 OR 3)
• The parent filter will now match Accounts named 'John Smith' OR 'Jane Smith' but will still not match to the Account named 'Roger Williams'.

Reusable filters:

• The filter we just created can now be re-used for any setting with the same parent object type (Account in this case).
• To re-use the filter, simply click on the drop-down list, and choose an available filter.  Click 'Edit' to view details for the filter you just selected.

NOTE: Lookup Helper settings cannot both create category records, and have a parent filter.  Users must choose one or the other.

Child Filtering

The child filtering feature allows users to apply additional matching criteria to the child object. This helps narrow down the amount of matching children, which gives the user more control. While creating or editing a setting, users can either create a new child filter, or assign a previously created child filter.

To create a new child filter: 

1. Click 'Add Child Filter'
2. Optionally: create a name for your filter
3. Choose a field on the child object to filter on (eg. Billing City)
4. Choose an operator (e.g. Equals)
5. Choose/Enter criteria (e.g. 'Chicago')
6. Click 'Submit' to add criteria to the child filter record
7. Click 'Save' to save the child filter record

You now have a child filter attached to your Lookup Helper Setting!

The difference child filtering makes:

• Previously, if there were two Contacts that could qualify (e.g. matching Contacts to an Account where the mailing state of a Contact = 'Illinois' and the billing state of an Account = 'Illinois', and we have two Contacts based in Illinois), Lookup Helper would populate the lookup field for both Contacts.
• Now, if you have two Contacts in Illinois, one located in 'Chicago' and one located in 'Rockford', Lookup Helper will only populate the lookup field on the Contact located in 'Chicago' because of the child filter.

Filter Logic feature:

Continuing on this example, we add an additional filter criteria (Name = 'Springfield').

• We can change the filter logic to: 1 AND (2 OR 3)
• The child filter will now populate the lookup field on the Contacts located in 'Chicago' OR 'Springfield' but will still not populate the lookup field on the Contacts located in 'Rockford'.

Reusable filters:

• The filter we just created can now be re-used for any setting with the same child object type (Contact in this case).
• To re-use the filter, simply click on the drop-down list, and choose an available filter.  Click 'Edit' to view details for the filter you just selected.

Criteria Matching

The criteria matching feature allows users to create Lookup Helper Settings that match records if they meet the child and parent filter conditions, regardless of whether the matching fields on the records are equal.

To enable Criteria Matching on a Lookup Helper setting:

• Create a Lookup Helper setting as you normally would.
• After selecting the lookup field, and before selecting fields to match: check the checkbox near the top of the page, next to 'Criteria Matching Mode' to enable Criteria Matching Mode for this setting.
• Create/assign a child filter for this setting.
• Create/assign a parent filter for this setting.
• Save your setting.
• You now have a criteria matching enabled Lookup Helper setting!

The difference criteria matching makes:

Criteria matching enables the user to create Lookup Helper settings that relate records even without fields matching each other. For example, a user could match all Opportunities with an amount less than 10,000 to a small business Account Executive. Previously, a formula field would need to be created on the Opportunity object to hold the Boolean value of “less than 10000.” With criteria matching, one less field is used toward field limits.

Realtime Enablement

Navigate to the "Enable Real Time" menu link within the Lookup Helper Menu tab to enable real time functionality on your custom objects.

• Select the “Enable Real Time” menu link.
• Click “Select” next to the object that you want to enable real time for.
• Click on the button that says Deploy to start the real time enablement process.

Deploy a trigger

The list of triggers available to deploy is based on Lookup Helper settings that you have created. If you don’t see the object you would like to deploy a trigger on, verify that you have created and saved a Lookup Helper setting for that object.

Out of the box, Lookup Helper comes with triggers on Account, Case, Contact, Event, Task, and Account For Contact (Foreign Key) as a part of the managed package and do not have to be deployed. For Salesforce Professional Edition orgs, these triggers will work. To add any additional triggers in a Professional Edition environment, an Apex package would need to be purchased from Salesforce.

Triggers can be enabled for both the Child and Parent Objects depending on when you want the setting to fire.

Foreign Key Triggers. There are times when a change to a field Lookup Helper is using will not cause the lookup setting to fire (i.e. Matching based on a Formula Field). In this situation you could enable a foreign key trigger on the Object the Formula Field is getting it’s information from. (Populate a field on Account when a Task is updated).

Deploy a trigger

• Select Deploy next to the Object you would like to enable the trigger on.
• Click the Deploy (Your Object Name) Trigger
• Do not leave the page while the trigger is deploying.
• To check deployment status
  • Open a new tab
  • Setup>Deploy>Deployment Status
• Once the deployment is complete, a “Deployment Complete” message will appear in the blue box at the top of the Real Time Triggers page in Lookup Helper.

Remove a trigger

To Remove a Lookup Helper trigger, click “Select” next to the desired object and follow the same steps as above with the Remove (Your Object Name) Trigger button.

Enable/disable Lookup Helper triggers

Once Deployed any Lookup Helper Real Time Trigger can be disabled instead of removed. Note, while the Real Time Triggers that come with Lookup Helper cannot be removed, they can be disabled.

To disable a deployed Real Time Trigger follow the above instructions for deploying a trigger except instead of clicking Deploy or Remove button, click the “Disable (Your Object Name) Trigger” button.

To re-enable the trigger repeat the steps clicking the “Enable (Your Object Name) Trigger” button.

Exception monitoring

Setup email alerts

• From the Lookup Helper Menu, click “View Lookup Helper Errors”
• Click “Submit Exception Monitor Job” to schedule the monitor job. If this is already set up, you will not see this link and can move on to the next steps. 
• Go to Setup, and then go to “Custom Settings”
• Click “Manage” for Lookup Helper App Settings
• Enter the contact email you want to be alerted in the “Email to send exceptions” field
• A daily summary email will be sent to the email provided

View exceptions

• From the Lookup Helper Menu, click “View Lookup Helper Errors”
• Select the setting you want to view Lookup Helper exceptions on

Health Check

HEALTH CHECK allows you to check on Lookup Helper’s status, displays a risk level assessment for any issues, and offers action items to resolve any issues.

• Risk Level: Risk assessment for the issue found.
• Issue Found: Identifies what the issue was.
• Issue Summary: Summarizes the issue into a category and includes help text about the issue.
• Action: Recommended course of action to resolve the issue.

Queue Management

Allows you to check on items filtered by object in the Lookup Helper Queue and their status, as well as the ability to delete any stuck queue items.

Page Features:

• Select a Child Object: Sort by object using this dropdown list.
• Refresh: Click this button to refresh the table containing your queue items.
• Queue Item Table
  • ID: Id of the Queue record.
  • Name: Name of the Queue record.
  • Created Date: CreatedDate of the Queue record, formatted for readability.
  • Status: Status of the Queue record. Possible values include Failed, Queued, Processing and Processed.
  • Action: Clicking the Delete button deletes the queue item.

Schedule Management

Allows you to check on scheduled Lookup Helper Settings and their next fire time, as well as the ability to edit the next fire time and schedule intervals (hours, days, etc.)

• Lookup Name: Name of the scheduled Lookup Helper Setting.
• Next Fire Time: The next time that the scheduled Lookup Helper Setting will run.
• Interval/Interval Unit: The amount of time between each run of the scheduled Lookup Helper Setting.
• Delete: Clears the schedule of the scheduled Lookup Helper Setting.Importing / Exporting Lookups

Importing/Exporting Lookups

Importing

1. Navigate to the setup menu and type Data Import Wizard in the quick find/search bar. Click on the link Data Import Wizard.
2. On the Data Import Wizard page, click on the large green button that says Launch Wizard.
3. You should now be on the Import your Data in to Salesforce page. In the first column, select the tab that says Custom Object. In the list that shows up, scroll down and select Lookup Exports (there should be a green checkmark that shows up).
4. Once the center box shows What do you want to do?, select the top option Add new records. Leave the Match by: and Which User field designates record owners? drop-downs as None.
5. On the third box, you can either select the Lookup Helper export CSV file from your computer and drag it to the Drag CSV file here to upload box, or click on the CSV link and click on Choose File to select the CSV file. Leave the other settings at the default values and click on the green Next button at the bottom right of the page.
6. You should see the Edit Field Mapping: Lookup Exports page. Map the three fields from our CSV file. The first field to map is Type__c to Type. Then map LookupData__c to LookupData and LookupKey__c to LookupKey.
7. Click on the green Next button at the bottom right corner of the page which will take you to the Review & Start Import page. If everything looks good here (3 columns mapped), click on the green Start Import button on the bottom right corner of the page and your lookups and filters should begin importing without any issues.

Exporting

1. Navigate to the Export Lookup Helper Settings button from the All Lookup Settings page.
2. Click the checkbox next to each lookup that you would like to export and then click on Export Selected. Alternatively, you can also click on the Export All button to select all of them for export.
3. Review all of the lookups that are set to be exported in the Lookups To Be Exported list. Once you have confirmed that they are the lookups that you want to export, select Download. This should open up a save dialog from your browser. Select a folder to save the CSV to and you're done.

If you are not creating parent/category records with your Lookup Helper setting, you can also use any data export tool, such as Data Loader or Dataloader.io, to export your Lookup Helper settings. Below are instructions regarding how to use Data Loader to export Lookup Helper settings:

1. Download and install Data Loader
2. Open Data Loader
3. Click the Export Button and select the Lookup_Helper_Setting__c object from the list (NOT Lookup_Helper_App_Settings__c)
4. Choose your target for extraction
5. Select all fields, add any filters you desire, and click Finish

Pre-Built Use Case Deployment

Allows you to view and deploy pre-built Lookup Helper use cases within a few clicks.

• To begin, navigate to the Use Case Deployment tab or Deploy Pre-Built Lookups tile in Lightning.
• The page will display a list of Lookup Helper use cases which can be deployed as lookups directly into your org.
  • Use Cases can be filtered by child object, which includes Account, Contact, and Case.
• Once the desired use case is chosen, click Deploy next to the setting.
• A custom field will then need to be created and used as the lookup field for the use case.
• Click Deploy Field.
  • Field Level Security settings will need to be adjusted for the lookup field in order to gain visibility to the field.
• After deploying the field, click to deploy the setting. This will create a lookup and associated filter if applicable for that use case.
• You will then be redirected to the All Settings page and be able to see the use case deployed as a lookup setting.
  • Click “Back to Use Case Deployment” on the top right of the All Settings page to return to the Use Case Deployment page.

Custom settings

To view or manage your Lookup Helper Custom Settings in Classic go to: Setup>Develop>Custom Settings>Lookup Helper App Settings>Manage. For Lightning, go to: Setup>Custom Settings>Lookup Helper App Settings>Manage.

Record Scope: This defines how many records will be processed per batch when Lookup Helper is running Asynchronously. If left blank, Lookup Helper defaults to 200 records.

Exception Monitor Can Disable Settings: If enabled, allows the exception monitor to disable lookup settings in which it detects issues.

Run All Local Tests on Trigger Creation?: If enabled, will run all local tests in an org when deploying Lookup Helper realtime triggers, instead of just the ones relating to the trigger.

Max Flex Queue Utilization Percent: Sets the maximum percentage of the Flex Queue limits Lookup Helper is allowed to use.

Email To Send Exceptions: A daily summary email of any exceptions will be sent to the email provided.

Prevent Automatic Setting Deactivation?: When checked, prevents Lookup Helper from disabling Settings when errors are encountered during a realtime or manual run.

Usage % of Limits: Determines the percentage of limit usage at which Lookup Helper should switch to asynchronous processing. It is generally not recommended to lower this value below 60%, and the default is 90%.

Enable Single Category Record Processing: If this is checked, Lookup Helper will prevent duplicate parent category records from being created.

Suppress Warning Level Errors: If this is checked, Lookup Helper will disable warning level Lookup Helper Errors from being inserted into the system.

Update Converted Leads: Lookup Helper, by default, does not update fields on Leads once they have been converted. Checking this option changes that behavior so it will affect all leads, whether or not they have been converted.

Disable Async Record Lock Retry: If Lookup Helper encounters a Record Lock error while processing, it attempts to rerun the setting for the records that encountered the error a minute later. Checking this setting disables the retry logic so any Record locks encountered are logged as errors. This should only be enabled if you are having problems with the record lock retry functionality and have talked to our support team.

Best practices

• When creating Lookup Helper settings, consider when you would like the records to update, when a child record is added/modified/deleted, when a parent record is added/modified/deleted or both and be sure to enable real-time for the appropriate object.
• If you are creating a new Lookup field from within the app during Lookup Helper Setting creation, be sure to go to Setup and set field level security and adjust page layouts.
• When using “Create New Category Record”, consider whether this could cause duplicate records to be created based on User input/different spellings.
• If you are using Lookup Helper to update an existing field that is already populated with data:
  • Consider creating a new field if there is data that you would like to retain.
  • Use the Advanced Settings on the Lookup Helper Settings creation:

• • • “Allow Overwrite of Existing Lookup Field Information” can be de-selected if you do not want Lookup Helper to overwrite existing data in a field.
    • “Allow Clearing of Existing Lookup Field Information” can be de-selected if you do not want Lookup Helper to clear out a populated value if the setting does not find a match.

Support

• Access the Lookup Helper Training Site
• Email Support

Resources

• Lookup Helper Release Notes
• Lookup Helper FAQs
• Lookup Helper Success Community
• Salesforce Object Relationship Overview

For any additional assistance, please email: support@passagetech.com