Reference Field

How to create a new form field

This field, as its name implies, allows you to reference existing records from other Apps. This means that you will be able to select either a single record or multiple ones from those that already exist within the selected App. 

In this article we'll cover the following topics:

1. How to Configure a Reference Field
2. Create and Edit Records Within a Field
3. Configure a Dropdown Card View
4. Reference Qualifiers
   • Dynamic Reference Qualifiers
   • Configuring a Reference via Multi-Select Field

A Reference Field is a great way to enable your team to, for example, select the main point of contact for an opportunity from those that exist in your Contacts App. 

It also includes a Multi Select version that will allow you to select multiple records from the selected App. This can be used to identify all contacts that belong to the same team within an organization, ie. Support team, or Management. 

Let's get started.

Navigate to Form Fields

Go to Settings > Apps, select the app you'd like to add the field to and select the 'Form Fields' tab.

Configuring a Reference Field

Give your field a name and add a field hint if desired. You can then select the section in which the field will be created or keep the default option.

The field type must be set to 'Reference'.

Then you will need to specify the App you will be referencing under Reference Object. This field will include all your existing Apps.

Now define the Reference Qualifiers needed for your field. Review the ‘Reference Qualifiers’ section of this tutorial for more information.

If desired, you can set a default value for all new records. Team members will have the option to override the default value if needed. 

Set the 'Required' dropdown to 'yes' if the information for this field is mandatory. If you enable this option, every time a team member creates a new record, they will need to input the information for this field in order to save it. 

If you enable the 'Lock After Create' as its name implies, the field will be locked once the new record is saved and the value of the field will not be editable afterward. 

Once you are done setting your field, click the save button. 

Note: All new fields are added at the bottom of the form. 

Create and Edit Records Within a Field

You now have the ability to create and edit records on an ad-hoc basis directly within a Reference Field. When you create or edit a Reference Field you will see two options:  ‘Allow Add’ and ‘Allow Update Existing,' both of which are 'Yes/No' choices.

Select 'Yes' to activate either function.  These functions are independent of each other and do not have to be used concurrently.  

If 'Allow Add' is enabled, anytime a Reference Field appears and you click into the empty field you will see an option directly below the field to 'Create New.'

If 'Allow Update Existing' is enabled and you select an existing record within your Reference Field you will now see the option to 'Edit' directly below the field.

You simply need to click on the blue text below and a window to Create or Edit a record will appear.  Fill out the appropriate fields, click Save, and you've just updated or created a record on the fly from a Reference Field.

Note: Creating and editing records in a Reference Field are still role dependent, the same permissions from the source Reference Field will apply.

Configure a Dropdown Card View

FreeAgent CRM now allows you to configure a Reference Field to show Cards within an App dropdown field.  Once set up, Cards populate automatically for instant information beyond just a title field.  



First, you'll want to make sure you've formatted the Card that will appear in your dropdown window.  Refer to the Card Configuration tutorial to achieve this. 

Next, create a new Form Field within your App.  Name your Field then select 'Reference Field' in Field Type.  Choose the 'Reference' and 'Reference Qualifier' that match the corresponding card that will populate the dropdown window. 

In the 'Show Cards' field, select 'Yes.'  Click 'Save' to create the Card Dropdown functionality.  Now this given field will display your custom card information in real-time as soon as you click on it.

Reference Qualifiers

You can specify a Reference Qualifier to limit the options available in the dropdown.

*The options available will vary depending on the app you a referencing and will show only fields of type Choice List, Choice List Multi Select, Reference, and Reference Multi Select.

If you want to add a reference to the records that belong to a team member, for example, the 'Reference Qualifier' will be the record's owner and the 'Qualifier Value' will be the name of the team member.  

Role Reference Qualifier

This qualifier will limit the list of Team members displayed on the field to show Team Members assigned to a specific Role only. Within the Qualifier options, you will have all the existing Roles for your Team members or simply select 'Current Role' as the qualifier value.

This will update the list of team members available in the dropdown to those who share the same role as the team member who is creating or editing the record

In the fields list, you will be able to identify the value of the reference under the 'Reference Info' column. 

When you create or edit a record, you will notice that the available options in the dropdown will be limited, only those records where the current user is the owner will be displayed in the dropdown. You can find other examples of Qualifiers in the following tutorial: 
Reference Qualifiers

Dynamic Reference Qualifiers

Use the Dynamic Reference Qualifiers when you need to return specific options to select from according to the reference fields set up in other apps.

First, you will need to specify the Dynamic Reference Field. It will be used to limit the information in your Reference field. Think of it as the first data filter.  It lets the system know where to go and “look” for that data.

Then, you need to select your qualifier under ‘Dynamic Reference Field Qualifier’. This is the field that will be used to show the available options in your Reference field.

Dynamic Reference Qualifiers can be used in combination with Reference Qualifiers to narrow down the available options of your Reference field to only those needed in your form.

Dynamic Reference Qualifier Example

Quote Champion. Allows you to limit the list of contacts available to select from depending on the Account they belong to when creating a new Quote.
In your Quotes App, you will need to create a new Reference field with the following configuration:

With this configuration, the Champion field in your Quote will only show the contacts that belong to the Account you specified when creating your Quote.

If on top of all this, you also want to show only those contacts that are labelled as ‘Decision Makers’ then all you have to do is add a Reference Qualifier.

Note: The 'Is Decision Maker?' field is a boolean field available in the Contacts App.

Configuring a Reference - Multi-Select Field

Follow the same steps described in the section above, the only difference should be the type, which must be set to 'Reference - Multi Select'.