The lookup field gives you special power to work with data from other tabs inside your GraceBlocks Zone. Lookups allow you to "look up" fields from related records and bring them into the tab, either directly or in an aggregated fashion. These lookup fields are always presented to users in read-only mode. For example, let's say that you have a Block that tracks your customers in one tab and where where you track each Project SOW and its value with each customer in a second tab. These two tabs are related to one another, as each project is tied to a customer using a related record. By having this relationship established, a builder can add lookup fields to pull in data related to the projects with the customers, including looking up project names or how many projects are associated with each customer, or could even calculate the customer's lifetime value as represented by the sum of all SOWs associated with the customer. All of this can be done using lookup fields. To create a lookup filed, a builder must choose the Lookup field type when managing fields.

This article reviews the properties of lookup fields and provides tips to aid in user adoption of this type of field.

You can view the available properties for lookup fields on the Edit field properties modal when you select Field type of Lookup.

Properties of lookup fields

After specifying a Field name (which controls how this field is referenced inside the tab) and that the field is of the type Lookup, you need to define what it is that you are looking up. Based on this selection, the options for More field attributes will vary slightly, as described in the steps below.

Step	Action	Visual
1	Select a value from the Relational field in this tab list. Choose the tab that contains the relational fields for which you want to look up data. The next dropdown populates with all of the available fields you can look up from the selected tab. 🔔 A tab must have at least one relational field before you can complete this step. If there are no relational fields established, there will be nothing to select in this field.
2	Select the Lookup field to specify the field you wish to look up. Based on the type of field you have selected, the More field attributes area may auto-expand to suggest possible selections; the selections vary as described in the following steps: 3a: Numeric field 3b: Date fields 3c: Single and Multi-select fields
3	Private field	Use this setting if only authorized users should be able to access this field. If this is applied, the field will be locked out from the user's view entirely unless they are authorized to access private fields. This setting works in conjunction with the security access control tab setting: View private fields. If a field is private, only users authorized to view private fields will be able to view, edit, see history, filter, or download this data. Click here to learn more.
4a	If a number, counter, or system ID field is selected for lookup: The More fields attributes area will auto-expand, and you can choose from the following lookup options: Option Description Show all values (This is the default selection.) This option presents a comma-separated list of each individual number associated with a corresponding related record. Show unique values This option presents a comma-separated list of each individual unique number associated with corresponding related records. Show specific value Choose this option to choose from the options below: Newest: Provides the value associated with the newest of all related records. Oldest: Provides the value associated with the oldest of all related records. Most recently updated: Provides the value associated with the most recently updated of all related records. Count of all values: Tells how many related records have values provided. Count of distinct values: Tells how many unique values are provided across all related records. Sum: Sums the total of all values provided across the related records. Average: Provides the average of all values provided across the related records. Min: Provides the minimum value number across all the related records. Max: Provides the highest value number across all the related records.
4b	If a date, added on, or updated on field is selected for lookup: The More fields attributes area will auto-expand, and you can choose from the following lookup options: Option Description Show all values (This is the default selection.) This option presents a comma-separated list of each individual date associated with a corresponding related record. Show unique values This option presents a comma-separated list of each individual unique date associated with corresponding related records. Show specific value Choose this option to choose from the options below: Newest: Provides the date value associated with the newest of all related records. Oldest: Provides the date value associated with the oldest of all related records. Most recently updated: Provides the date value associated with the most recently updated of all related records. Count of all values: Tells how many related records have the date value provided. Count of distinct values: Tells how many unique dates are provided across all related records. Min: Provides the earliest date value number across all the related records. Max: Provides the most recent date value across all the related records.
4c	If a single select field type is selected for lookup: The More fields attributes area will auto-expand, and you can choose from the following lookup options: Option Description Show all values (This is the default selection.) This option presents a comma-separated list of each individual value associated with a corresponding related record. Show unique values This option presents a comma-separated list of each individual unique value associated with corresponding related records. Show specific value Choose this option to choose from the options below: Newest: Provides the value associated with the newest of all related records. Oldest: Provides the value associated with the oldest of all related records. Most recently updated: Provides the value associated with the most recently updated of all related records. Count of all values: Tells how many related records have values provided. Count of distinct values: Tells how many unique values are provided across all related records. Min: Provides the first (highest in the list) value across all the related records, based on their rank order in the select list of values in the single select field configuration. Max: Provides the last (lowest in the list) value across all the related records, based on their rank order in the select list of values in the single select field configuration.
4d	If a short text, long text, relational, multiple select, added by, updated by, email, phone number, URL, or Checkbox field is selected for lookup: The More fields attributes are will auto-expand, and you can choose from the following lookup options: Option Description Show all values (This is the default selection.) This option presents a comma-separated list of each value associated with a corresponding related record. Show unique values This option presents a comma-separated list of each individual unique value associated with corresponding related records. Show specific value Choose this option to choose from the options below: Newest: Provides the value associated with the newest of all related records. Oldest: Provides the value associated with the oldest of all related records. Most recently updated: Provides the value associated with the most recently updated of all related records. Count of all values: Tells how many related records have a value provided in the field. Count of distinct values: Tells how many unique values are provided across all related records.
4e	If an Attachment field type is selected for lookup, there are no additional value options to select. Any attachments tied to the selected field for the related records are pulled through and made available as read-only attachments.
5	If you enter any text into the Field callout textbox, the information (i) icon appears to the left of the field name, and the text you entered displays when users move the cursor over this icon. Enter text here if you want to provide information to help the user learn more about how to use the field.
6	Click Save to save the field settings for the lookup field.

Examples in action

🔔 Lookup fields are presented as read-only values to users. Colors indicate the type of lookup:

• Gray indicates that all or unique values are displayed.
• Yellow indicates that a specific value (oldest, newest, min, max, count, sum, average) is displayed.

The illustration below includes two related records and three lookup fields. They are explained further in the table below the illustration.

Scenario	Lookup example illustration
Example 1: On this Clients tab, the primary contact for the first client in the list is Anthony Glenn. This individual was selected from the list of contacts (inside the CRM Block, Contacts tab). The lookup field, called Primary contact phone is looking up Anthony's phone number from the CRM Block/Contacts tab, allowing display of the phone number of the primary contact for each customer. The value appears in gray and is using the show all values option.
Example 2: On this Clients tab, each client can have one or more Projects and SOWs associated. These are tracked on the Projects and SOWs tab inside this Block. For the first customer in the list, two projects are related: Recruiting and Ops and Recruiting Transformation. These two records were selected from the list of Projects and SOWs (inside this Block). The lookup field, called Value, is looking up the dollar value that is associated with each project/SOW and summing it up. The value appears in yellow because it is a show specific value option, which in this case, is using the Sum feature.
Example 3: This example is an extension of example two, but in this case, it is looking up the attachments that are associated with the Project and SOWs for Recruiting and Ops and Recruiting Transformation. These attachments are presented and accessible. From this tab, they are read-only. 🔔 If a builder configures lookup attachments, GraceBlocks recommends that you give a visual cue to users using the Field callout feature. (See step 4 from the action table above.) This cue will help users understand why the attachments are not editable.

🔔 Lookup fields inherit the formatting of the field they are derived from. For example, if you want currency values to show in a lookup, be sure to configure the original number field with a currency format first. You cannot change the format of a lookup field after you have created it. Instead, you will need to remove and re-add the lookup for it to inherit the format.

🔔 It is not possible to delete a field if it is being looked up. You will need to remove the lookups first before you can delete the original field.

🔔 If you delete a relational field, you will also delete any lookups that are being derived from that field.

🔔 Only the field label and callout text of lookup fields can be edited after they have been saved. To change the nature of a lookup, delete it and then add it again in the way that you want to render it.