Difference between revisions of "External Lookups"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Line 1: Line 1:
==About External Lookups==
An ''External Lookup'' field retrieves one or more records from a [[Web Service]]. Returned data is then mapped to one or more fields in the current record. The External Lookup field can do either of the following, or both:
An ''External Lookup'' field retrieves one or more records from a [[Web Service]]. Returned data is then mapped to one or more fields in the current record. The External Lookup field can do either of the following, or both:
:* Get a single record to get data from.
:* Get a single record to get data from.
Line 20: Line 21:
===How a Search Service Works===
===How a Search Service Works===


===Settings===
==Settings==
<blockquote>
<blockquote>
====Basic Information====
===Basic Information===
:* '''Label -''' The name of the field. The user clicks in this field to select a record.
:* '''Label -''' The name of the field. The user clicks in this field to select a record.
:* '''Field Type -''' ''External Lookup''
:* '''Field Type -''' ''External Lookup''
Line 46: Line 47:
:* '''Field Name -''' This value is pre-filled based on the field label, but it can be modified as the field is being created, if desired.  
:* '''Field Name -''' This value is pre-filled based on the field label, but it can be modified as the field is being created, if desired.  


====External Lookup Configuration====
===External Lookup Configuration===
This section appears when a '''Get Record Service''' is selected.
This section appears when a '''Get Record Service''' is selected.
:* '''Input Mapping -''' Specify one mapping for each Web Service input.
:* '''Input Mapping -''' Specify one mapping for each Web Service input.
Line 74: Line 75:
::: Click the [+] and [-] icons to add or remove items.
::: Click the [+] and [-] icons to add or remove items.


====Search Service Configuration====
===Search Service Configuration===
This section appears when a '''Get Record List Service''' is selected.
This section appears when a '''Get Record List Service''' is selected.


====Description Information====
===Description Information===
:* Optionally, include a description of the field.  
:* Optionally, include a description of the field.  
</blockquote>
</blockquote>

Revision as of 01:42, 12 April 2014

About External Lookups

An External Lookup field retrieves one or more records from a Web Service. Returned data is then mapped to one or more fields in the current record. The External Lookup field can do either of the following, or both:

  • Get a single record to get data from.
  • Get multiple records, and let the user select the record to use.
Prerequisite
A Web Service must be configured.

How an External Lookup Works

An External Lookup field references 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 returned. 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.
  • An External Lookup is executed when a record is accessed. If the Web Service fails, an error message is displayed.
Sample Use
A customer record could contain a field that contains the customer ID from a SalesForce database. An External Lookup field can be used to automatically display data like contact information and credit score from that database, without having to maintain a separate copy of it in the platform.

Thumbsup.gif

Tip:
A single External Lookup field lets you add multiple display-only fields to an object record. That's ideal when you always want to see the latest information retrieved from a central location. (Say, customer contact information.) On the other hand, there are times when you want to retrieve information from a remote source and store it locally. For example, today's price for fish might be retrieved from a central source, but you would need to store it in the record, and retrieve that information only when a new record is added (and not when some extraneous field is updated). For that situation, you should invoke a Web Service from a Process.

How a Search Service Works

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 returns a single record.
  • Search Web Service - Choose a Web Service that returns a list of records for a 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 it can be modified as the field is being created, if desired.

External Lookup Configuration

This section appears when a Get Record Service is selected.

  • Input Mapping - Specify one mapping for each Web Service input.
The input fields allow filtering data to be sent to the Web Service. The combination of fields should produce exactly one record. (If more than one is returned, the last one is used.) The mapping 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
Click the [+] and [-] icons to add or remove items.
  • Output Mapping - Specify one mapping for each value returned by the Web Service.
  • Ignore - Disregard the value returned from the web service.
  • Display - The value is displayed to the user, with the label you specify.
    (It appears as a field that can be placed at the desired location in the record form.)
Click the [+] and [-] icons to add or remove items.

Search Service Configuration

This section appears when a Get Record List Service is selected.

Description Information

  • Optionally, include a description of the field.