External Lookups

An External Lookup field retrieves data from a Web Service. Returned data is then mapped to one or more fields in the current record.

Prerequisite

A Web Service must be configured.

Operation

An External Lookup field references a data provided by a foreign data source, accessed using a Web Service. When an object record is added or updated, fields contained in the object record are used to identify the Lookup target. Thereafter, the fields returned from the foreign data source are available as read-only fields in the platform object record (like Lookup-Dependent Fields). For example, they can be used in a Rule condition or Document Template.

Considerations

• The field(s) used to identify the target record should constitute a unique key in the foreign data, so that only one record is return. If multiple records are returned as target candidates, the last one returned is used.
• If no records are returned, the dependent fields remain empty.
• External Lookup-dependent fields are available for use in HTML, Word, and PowerPoint document templates. They are not available for use in JSP templates.

Settings

Basic Information

• Label - The name of the field. The user clicks in this field to select a record.
• Field Type - External Lookup
• Web Service - Choose a Web Service that has been configured for use in this application.
• Lookup Display Type - DropDown list or Popup Window, as for other Lookup fields

Dropdown

Typically used for a fixed list. For example, a list of countries or states. No filtering values are sent to the Web Service that could be used to filter the records it returns.

• Execution

A DropDown needs to be populated before it can be displayed. This choice determines when values are retrieved for that purpose:

• onFormLoad - Pre-load the values when the form is first loaded.

(Introduces a small delay when the form is loaded, but the data is there when the user gets to the field.)

• onFirstClick - Load the data when the field is clicked, and cache it in memory in case the user clicks there again.

(Introduces a small delay when the field is clicked, unlike other fields. Most useful when the field may not be clicked at all.)

• onEveryClick - Load the data whenever the field is clicked.

(Introduces a small delay every time the field is clicked. Useful for data that changes regularly--for example, to get the latest exchange rate.)

Popup Window

Typically used to display a list of data records for the user to choose from.

• Always Required - Clicking this checkbox prevents a record from being saved until this field has a value.
• Field Name - This value is pre-filled based on the field label, but can be modified when the field is first created, if desired.

External Lookup Configuration

• Input Mapping - Specify one mapping for each Web Service input.

The input fields allow filtering data to be sent to Web Service, so it can return an appropriate set of records for the user to choose from, rather than all records in the server's collection. The choices are:

• Use Object Field - Use a Record field value for a Web Service input
• Use Fixed Value - Specify a value.

(This is the only option available when onFormLoad is specified.)

• Use Expression - Specify an expression using any combination of the above
• User Input - Ask the user to enter a value.

(This option is available only for a Popup display.)

(Before the Web Service is contacted, a dialog containing all User Input fields is displayed.)

Click the [+] and [-] icons to add or remove items.

• Output Mapping - Specify one mapping for each value returned by the Web Service.

• Map to Self - The returned value is displayed as the value of the External Lookup field.

(Only one returned value may be used for that purpose.)

• Map to Object Field - Map the returned value to one of the fields in the record.

(The field need not be displayed in the form.)

• Ignore - Disregard the value returned from the web service.
• Display - The value is displayed to the user, but not stored in the record.

(Useful to help the user confirm that they have made the right choice.)

Click the [+] and [-] icons to add or remove items.

The remaining configuration options work the same as a normal Lookup field.