Difference between revisions of "External Lookups"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
 
(33 intermediate revisions by the same user not shown)
Line 1: Line 1:
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:
==About External Lookups==
:* Get a single record to copy data from.
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 connect to either of the following, or both:
:* Get multiple records, and let the user select the record to copy from.
:* A ''lookup service'' that returns a single record from which data is used.
:* A ''search service'' that returns multiple records, from which the user selects the record to use.


;Prerequisite: A Web Service must be configured.
;Prerequisite: A Web Service must be configured.


===How an External Lookup Works===
===How a Lookup Service Works===
;Operation: 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]].
When an object record is added or updated, fields contained in the object record are used to fetch a target record from a Web Service. Data from that record can then be displayed read-only fields in the platform object record (like [[Lookup-Dependent Fields]]). Those fields can then be used in a [[Rule]] condition or [[Document Template]], for example.


;Considerations:
:;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.
::* 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.
::* 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.
::* External Lookup-dependent fields are available for use in HTML, Word, and PowerPoint document templates. They are not available for use in JSP-based templates.
:* An External Lookup is executed when a record is accessed. If the Web Service fails, an error message is displayed.
::* 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.
:;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.


{{Tip|<br>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]].}}
{{Tip|<br>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===
===How a Search Service Works===
A Search Service displays a popup that lets a user search for and select a record from a list returned by an external [[Web Service]].


===Settings===
When a Search Service is selected, a search field can be dragged into place in an object [[Form]]. When the user clicks the Lookup icon next to that field, ([[File:Lookupicon.gif]]) a popup is launched that allows the user to search the foreign data source.
 
The popup contains fields designated as Web Service inputs--some of which may come from the form, others which may be entered by the user. Those fields are followed by a '''[Search]''' button and a horizontal bar.
 
When the button is clicked, a set of records is retrieved from the service and displayed a grid, under the horizontal bar. The user can than select the record to reference. (Clicking a record selects it.)
 
==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''
:* '''Web Service -''' Choose a [[Web Service]] that has been configured for use in this application.
:* '''Lookup Service -''' Choose a [[Web Service]] that returns a single record.
<!--
:* '''Search Service -''' Choose a [[Web Service]] that returns a list of records for a user to choose from.<!--
FUTURE SEARCH-FUNCTION SEMANTICS
FUTURE SEARCH-FUNCTION SEMANTICS
:* '''Lookup Display Type -''' DropDown list or Popup Window, as for other [[Lookup]] fields
:* '''Lookup Display Type -''' DropDown list or Popup Window, as for other [[Lookup]] fields
Line 44: Line 52:
-->
-->
:* '''Always Required -''' Clicking this checkbox prevents a record from being saved until this field has a value.
:* '''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.  
:* '''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.
 
===Lookup Service Configuration===
This section appears when a '''Lookup Service''' is selected.
:* '''Input Mapping -''' Specify mappings for Web Service inputs.
:: 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.


====External Lookup Configuration====
:* '''Output Mapping -''' Specify mappings for values returned from the Web Service.
:* '''Input Mapping -''' Specify one mapping for each Web Service input.
:::* '''Ignore -''' Disregard the value returned from the web service.
:::* '''Read-only Field -''' The value becomes a read-only 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 '''Search Service''' is selected.
:*;Record Element: In the hierarchy of data returned from the Web Service, specify the element that contains data for a single record.
 
:* '''Input Mapping -''' Specify a 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:
:: 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 Object Field -''' Use a Record field value for a Web Service input
Line 53: Line 79:
:::: (This is the only option available when '''onFormLoad''' is specified.)
:::: (This is the only option available when '''onFormLoad''' is specified.)
:::* '''Use Expression -''' Specify an expression using any combination of the above
:::* '''Use Expression -''' Specify an expression using any combination of the above
<!--
FUTURE
:::* '''User Input -''' Ask the user to enter a value.
:::* '''User Input -''' Ask the user to enter a value.
:::: (This option is available only for a Popup display.)
:::: (This option is available only for a Popup display.)
::::  (Before the Web Service is contacted, a dialog containing all User Input fields is displayed.)
::::  (Before the Web Service is contacted, a dialog containing all User Input fields is displayed.)
END FUTURE
-->
::: Click the [+] and [-] icons to add or remove items.
::: Click the [+] and [-] icons to add or remove items.


:* '''Output Mapping -''' Specify one mapping for each value returned by the Web Service.
:* '''Output Mapping -''' Specify mappings for values returned from the Web Service.
<!--  
:::* '''Current Field (PK)''' The current field is the search field in the record form, That field has the Lookup icon next to it/ The icon triggers the search when the user clicks it. The ideal value to map to this field is the record's ''Primary Key'' -- the unique value that identifies the record. That choice improves performance, and uniquely identifies the record that was chosen.
FUTURE
:::* '''Map to Object Field -''' Map the returned value to one of the fields in the record.
:::* '''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.)
::::* The field need not be displayed in the form.
END FUTURE
:::* '''Selector Grid Field-''' The value is displayed in the Search dialog, with the label you specify. It helps the user determine which record to select.
-->
:::* '''Ignore -''' Disregard the value returned from the web service.
:::* '''Display -''' The value is displayed to the user, with the label you specify.<br>(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.
::: Click the [+] and [-] icons to add or remove items.


====Search Service Configuration====
:*;Dialog Order:
:*: Specify the order in which input fields appear at the top of the popup (above the Search button), and the order of the columns in which the output fields appear below the button.
 
{{Best|Always map the record-retrieval key to the '''Current Field''' output.}}


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

Latest revision as of 23:59, 23 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 connect to either of the following, or both:

  • A lookup service that returns a single record from which data is used.
  • A search service that returns multiple records, from which the user selects the record to use.
Prerequisite
A Web Service must be configured.

How a Lookup Service Works

When an object record is added or updated, fields contained in the object record are used to fetch a target record from a Web Service. Data from that record can then be displayed read-only fields in the platform object record (like Lookup-Dependent Fields). Those fields can then be used in a Rule condition or Document Template, for example.

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-based 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

A Search Service displays a popup that lets a user search for and select a record from a list returned by an external Web Service.

When a Search Service is selected, a search field can be dragged into place in an object Form. When the user clicks the Lookup icon next to that field, (Lookupicon.gif) a popup is launched that allows the user to search the foreign data source.

The popup contains fields designated as Web Service inputs--some of which may come from the form, others which may be entered by the user. Those fields are followed by a [Search] button and a horizontal bar.

When the button is clicked, a set of records is retrieved from the service and displayed a grid, under the horizontal bar. The user can than select the record to reference. (Clicking a record selects it.)

Settings

Basic Information

  • Label - The name of the field. The user clicks in this field to select a record.
  • Field Type - External Lookup
  • Lookup Service - Choose a Web Service that returns a single record.
  • Search 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.

Lookup Service Configuration

This section appears when a Lookup Service is selected.

  • Input Mapping - Specify mappings for Web Service inputs.
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 mappings for values returned from the Web Service.
  • Ignore - Disregard the value returned from the web service.
  • Read-only Field - The value becomes a read-only 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 Search Service is selected.

  • Record Element
    In the hierarchy of data returned from the Web Service, specify the element that contains data for a single record.
  • Input Mapping - Specify a 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
  • 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 mappings for values returned from the Web Service.
  • Current Field (PK) The current field is the search field in the record form, That field has the Lookup icon next to it/ The icon triggers the search when the user clicks it. The ideal value to map to this field is the record's Primary Key -- the unique value that identifies the record. That choice improves performance, and uniquely identifies the record that was chosen.
  • 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.
  • Selector Grid Field- The value is displayed in the Search dialog, with the label you specify. It helps the user determine which record to select.
Click the [+] and [-] icons to add or remove items.
  • Dialog Order
    Specify the order in which input fields appear at the top of the popup (above the Search button), and the order of the columns in which the output fields appear below the button.

Thumbsup.gif

Best Practice:
Always map the record-retrieval key to the Current Field output.

Description Information

  • Optionally, include a description of the field.