Multi Object Lookup

From AgileApps Support Wiki

GearIcon.png > Customization > Objects > {object} > Fields > [New] / [Edit] > Display Type > Multi Object Lookup

A Multi Object Lookup lets you reference records in multiple objects. Instead of having a fixed target object, as for a normal Lookup, the target object can be specified before a target record is selected.

In use, a Multi-Object Lookup is a two-stage lookup. First you select the object to use for the Lookup, and then you select a record from that object.

For example, a distributor might take orders for products that come from different catalogs, where each catalog is provided by a different supplier. The Multi-object Lookup field type makes it possible for the order taker to first choose the catalog the product is in, and then choose the product from that catalog.


  • Multi Object Lookup fields can be created only in Custom Objects
  • In the GUI, the value shown in the Lookup field is the Record Locator value for the selected record--the identifying information displayed for the record. But the value actually stored in the record consists of the object ID and the record ID.
  • Therefore, to specify a value for a Multi Object Lookup field when doing a Search, you do not specify the value displayed in the GUI. Rather specify the target record using this format:
  • The syntax requires an object ID, followed by a colon (:), and the record id.
  • The object's ID must be specified. An object name will not work.
  • The record's ID must be specified, not the record locator value displayed in the GUI.
Note: For the moment, it is not possible for most users to search on a mult-object lookup field, since only admins and programmers will have access to the information needed to formulate the query.
  • The value for a multi-object lookup field must similarly be specified as
  • The object designated in the imported record must match one of the objects designated as a possible target for the multi-object lookup. Otherwise, the field is left empty in the imported record.
  • That format generated by a Data Export is the same as that required for import:
  • In a Form, it is not possible to include a Multi Object Lookup field in the criteria for a Layout Rule. (Only the Record ID is stored in the current record, so there is no value for the Layout Rule to compare to.)
  • For the same reason, Multi Object Lookup fields cannot be used for Template Variables in, for example, Document Templates and email templates
  • Like other Lookup fields, Multi Object Lookup fields are not available for use in
  • in a computed field
  • for sorting
  • for color coding
  • When doing a Mass Update of Data, it is not possible to specify a value for a Multi Object Lookup field.
  • Multi Object Lookup field is not eligible for Indexes.

Field Properties

This section describes the properties you can set when creating a Multi Object Lookup field.

Basic Information

  • Label - The field label the user will see in the GUI.
  • Display Type - Multi Object Lookup
  • Always Required - If checked, a value must be specified when adding or updating a record.
  • Field name - The field name that will be used in the internal code.
  • Lookup Targets
  • All Objects - The Lookup field can target any object that is currently defined or added in the future
  • Selected Objects - Use the arrow buttons to move entries between the two lists:
  • Available Objects - The objects defined in the platform.
  • Selections - The objects that will be available for the user to choose.

Default Value

  • Enter text or a formula that returns a string, where the text string is of the form: {object_id}:{record_id}
    (An Object ID and a record ID, joined by a colon.)
  • If the string does not match a valid record, the field remains empty.
  • Default values do not trigger Post Selection JavaScript


You can use the LOOKUP function to return the record_id field for a record that matches specified criteria. (For the User object, the LOOKUP function returns a text string--which is what you need, in this context. For all other objects, it returns a number. To convert that numeric value to a string, wrap the LOOKUP function in a TEXT function: TEXT(LOOKUP(...)).)

Post Selection Javascript

Use JavaScript to perform additional operations after the user chooses a Lookup target record in an object Form.

  • Add a validation to confirm that the record targeted by the Lookup is consistent with data in the current record.
  • Copy data from the target record to the current record.
Learn more: Post Selection JavaScript

Creating Related Information Sections in Target Objects

Unlike other Lookups, an object that is the target of a Multi Object Lookup does not have Related Information section generated automatically, for that relationshop.

A Related Information section can be manually created, however.

Learn more: Optional Related Information Sections


Multi Object Lookups can be manipulated using these REST APIs: