View source for Lookups

[[File:lookupexample.png|right|thumb]]
__TOC__
==About Lookups==
A ''Lookup'' is a type of [[Field]] in an [[Object]].

Lookup fields establish relationships between objects, which enables the creation of very complex data models in applications. For example, in the Orders object, a Lookup field references the Customers object. This is a One-to-Many relationship, where a single Customer can have many Orders.

In addition to pointing to a target record, you can use the Lookup relationship to create:
:*'''Lookup-Derived Fields'''
:: Read-only fields that echo data from the target record, as though they were part of the current object record.
:: ''Learn more:'' [[#Lookup-Derived Fields|Lookup-Derived Fields]]

''See also:'' [[Multi Object Lookup]]

:*'''Lookup-based "Auto-Copy" Fields''' 
:: Fields in the current object record that are pre-filled with data copied from the Lookup target, but whose values can be modified by the user.
:: ''Learn more:'' [[#Lookup Field Configuration|Lookup Field Configuration]]

;Considerations:
:* By creating a Lookup field in an object, a corresponding [[Related Information]] section is created automatically in the related object. For a given target record in the related object, that section lists all records in the current object that Lookup to the target record.
::: ''Learn More:'' [[Object Relationships]]

{{Note|In addition to the standard Lookup fields that can be selected when creating or editing a Field definition, there are:
:* [[Multi Object Lookup]] - Another field type that lets the user select the Lookup-object, and then select a specific record within that object.
:* [[Multi Value Lookup]] - A field that automatically appears in the Form's field list whenever two objects are joined by a many-to-many relationship. (Such fields are ''not'' displayed in the the '''Fields''' tab.)}}

===Lookup on a Many-to-Many Relationship===
{{:Common:Many-to-Many Lookup Considerations}}

===About Objects in Lookup Fields===
{{:About Objects in Lookup Fields}}

===Fields (Column Headings) in a Related Information Section===
By creating a Lookup field in an object, a corresponding [[Related Information]] section appears in a second object. The appearance of the columns in the Related Information Section are predefined, and can be modified.

;Example:In the Movies object (A), add a lookup to the Customer object (B), which creates a one-to-many relationship (one Customer to many Movies)

The columns displayed in the Related Information section (of Object B) are auto-selected, based on the type of object:
:*In Lookups to {{Type|}}s, the following fields are displayed as column headings:
::*The first three fields of the object, selected based on date of creation
:*In Lookups to {{Type}}s, the following fields are displayed as column headings:
::*Name
::*Created By
::*Date Created

==Create a Lookup Field==
To add a Lookup field:
#Visit '''[[File:GearIcon.png]] > Customization > Objects > {object} > Fields'''
#Click '''[Add Field]'''
#Fill in the [[#Field Properties|Field Properties]], shown below.

==Field Properties==
This section describes the properties you can set when creating a Lookup field. (Some the sections do not appear until you have selected and object.)

;Summary:
# [[#Basic Information|Basic Information]]
# [[#Display Attributes|Display Attributes]]
# [[#Default Value|Default Value]]
# [[#Lookup Field Configuration|Lookup Field Configuration]]
# [[#Lookup Display Type|Lookup Display Type]]
# [[#Record Selection Information|Record Selection Information]] - Specify selection criteria for the records to display in the [[Lookup Window]]
# [[#Post Selection JavaScript|Post Selection JavaScript]] - Perform optional data validation, messaging or actions after the lookup record is selected
# [[#Role-Based Field Visibility|Role-Based Field Visibility]] - Show or Hide this field in the [[Form]], based on the selected [[Role]]
# [[#Description Information|Description Information]] - Add a description of the field or the Extended Metadata

=== Basic Information ===
:;Label:Label that is displayed in data entry forms; ''Learn more: [[#About Display Labels|About Display Labels]]

:;Display Type:Select ''Lookup''

:;Master Detail Relationship:
::* This option appears only for legacy Lookup fields that specified the (now deprecated) master-detail relationship.
:::''Learn more: [[Master-Detail relationship]]''

:;Object Name:Choose an object (Customers, in this example)
::''Learn more: [[#About Objects in Lookup Fields|About Objects in Lookup Fields]]

:;Always Required:Click the checkbox to make the field required.

:;Field Name:Name of the field, used internally in the database

===Display Attributes===
:;Section: Select the section in the default [[Form]] where the Lookup field should appear.
:;Required: Check this box if a value is always required to create a record.

=== Default Value ===
:Paste in a [[record ID]], or create a function expression that resolves to a string that contains one. 
:;Considerations:
::*If the string does not match a valid record, the field remains empty.
::*Default values do not trigger [[Post Selection JavaScript]]
{{:Common:UseLOOKUPFunctionToGetRecordID}}

<span id="Lookup_Field_Configuration"><!--GUI Label that should have been changed--></span>
=== Lookup Settings ===
<blockquote>
====Record Selection====
:* '''Popup:''' A separate window appears showing the lookup data. (default)
:* '''Drop Down:''' A drop down list appears at the current field in the user's window.

:;Considerations:
::* The Drop Down option is available for User objects and Custom objects. It may not be available for other standard objects.
::* A Drop Down list is limited to 200 entries. If the lookup data is longer than that, a runtime error occurs.
::* A Drop Down list should only be used for a list that is short enough to be scanned at a glance. For longer ::lists a Popup is preferable, because the user can type one or more initial characters to navigate the list.

====Additional Fields to Display====
The Additional Fields are displayed in a [[Lookup Window]] when the Lookup [[File:lookupicon.gif|link=]] icon is selected from a record. Select the fields to display. Use the arrow buttons to move the objects to the Selected Fields list.

====Copy Data====
When the user chooses a target record, you can automatically copy data in the target fields to fields in the current record, prefilling them with data.

;To copy data: 
# Choose a field to copy from the target record, and select the field to copy to in the current record.
# Click '''[+ Add More]''' to specify additional fields to copy.

:;Considerations:
::* Not all data types are supported. In general, you can copy the simple data types like text, number, and field. But you can't copy more complex data like formulas and attachments.
::* For more extensive operations, use [[#Post Selection JavaScript]]

When you choose this option, the dropdown list shows you the fields that can be copied.
::* Fields are only copied when they are part of a form. If a form does not contain an auto-copy field, then selecting a Lookup target does not copy data to that field. 
:::* The field can be present in the form, but hidden. In that case, the auto-copy happens.
:::* To be sure that such fields are created in future forms, consider making the auto-copy field ''Always Required''.
::* When adding a record, if the user enters data into a copied-data field and then does the lookup, the field is overwritten. To minimize the chance of that happening, make sure that such fields come after the Lookup field, they way they do in the Default Form. (You can also make the field read-only, if the user never really needs to change it.)
::* When updating a record, the auto-copy only happens when the Lookup target record changes (or is re-selected).
::* Copied data in the current record does ''not'' change when the lookup-target record changes. (If the sales tax changes for a state, for example, the change does not affect records that already copied the previous tax rate.)
::* When updating a record, copied data in the current record is only changed if:
:::# A new record is selected on the form for the Lookup field
:::# The current form contains the field (even if it is hidden).
::: (For fields that are updated whenever the current record is updated, use [[#Lookup-Derived Fields|Lookup-Derived Fields]].)
::* Auto-Copy is not supported in the [[User]] object)
::* The built-in [[Standard Fields]] like <tt>created_by</tt> and <tt>workflow_state</tt> can never be the target of an auto-copy.
::*There are restrictions on the field mappings that are allowed.<br>''Learn more:'' [[Auto-Copy Field Mappings]]
</blockquote>

===Record Filtering===
When the user clicks the icon next to a Lookup field, the platform's [[Lookup Window]] is displayed, allow the user to choose a record. This section determines how that window appears.

;Sort Options: These options appear for {{type|}}s when the Record Selection Type is "Standard".

:;Sort by: Select the column on which the records will be sorted, when displayed to the user for choosing.

:;Sort Order: Specify '''Ascending''' or '''Descending''' sort.

;Filtering Criteria: If the target of the lookup is a {{typenolink}}, this section does not appear. For other lookups, this section can be used to add filters using [[#Fixed String Values|Fixed String Values]] or [[#Dynamic Filters|Dynamic Filters]] as criteria to determine the records to display in a [[#Lookup Window|Lookup Window]].

====Fixed String Values====
Fixed string values define a query with specific, fixed criteria
:*Use fixed string values when a simple lookup is needed for record selection criteria
:*This method "hard codes" the criteria, meaning that only the specified values are used
::*Over time, the string values may need to be changed, so it is important to consider how this criteria is maintained for the long term

:;Examples:
::*Display records with Zipcode = 90210 and Lastname begins with 'B' 
::*Display records with Membership Status = Lapsed
::*Display records with State = CA

====Dynamic Filters====
{{:Dynamic Filters}}

===Post Selection JavaScript===
{{:Using Post Selection JavaScript}}

===Role-Based Permission Control===
For each of the [[Roles]] available, choose whether the field is Visible or Hidden. All fields are set to Visible by default. [[Default Roles]] are installed with the platform and can be modified.

===Description Information===
Optionally, include text that will appear as a [[Field Hint]] when the field is displayed.

==Using the Lookup Icon==
{{:Lookup Icon}}

===Lookup Window===
{{:Lookup Window}}

==Lookup-Derived Fields==
{{:Lookup-Derived Fields}}

==Self Reference Lookup==
{{:Self Reference Lookup}}
<noinclude>

[[Category:Core Concepts]]
[[Category:Design]]
</noinclude>