Lookup Block

Use a Lookup Block to retrieve data from selected fields within an Entity according to lookup criteria that you specify. This Block retrieves data to use in a formula or to populate a field in another entity that may not be in your initial query. See Lookup Block Example for a detailed use case scenario.

Note: If you have enabled Batch Processing on any Blocks in your Map, Lookup Blocks are not recommended. Using Lookup Blocks causes batching of records to be interrupted and reduces overall performance. See Lookups And Batch Processing.

Block Properties — General Tab

From the Block Properties General Tab, you can change the Block Label, add a description, enable caching, and select the entity to use for this operation.

Caching

Improve the performance of the Map by enabling the caching option labeled, Cache the results of this operation. When enabled, Lookup results are cached by the Agent until the end of the Map making the data available for reuse without having to retrieve it again.

Data is cached as it is looked up instead of caching all of the data in the entity being searched. For example, if you are running a query that has to do with currency, when the Map needs to know the value of a specific currency, such as US Dollars, the Lookup operation requests the value of that single currency and caches it. When the Map needs to know the value of Euros, the Lookup operation requests the value and caches it along with the value of US Dollars. The cache grows as each new piece of information is added. When a request is repeated, such as asking for US Dollars a second time, the cached data is used.

If data changes during the time the Map is run, the cached data is used and the changes are not taken into account. If you know that the values of the data retrieved by the Lookup Block may change during the execution of the Map, you may not want to enable caching. The default setting for this option is disabled.

Note: If the Lookup results are very large, they may not be cached. The maximum size of the cache is 10 MB.

Block Properties — Lookup Criteria Tab

Use the Lookup Criteria tab to specify one or more criteria used to find the record in the target that corresponds to the current source record.

  1. On the Lookup Criteria tab, select Add . A lookup criterion row displays.
  2. Select the blank cell under Field to display a drop-down list of the fields in the entity that can be used for the lookup. Select the field to lookup from the drop-down list.
  3. Under Operator, select an operation, such as equals.
  4. Under Value, enter a value for the match for the lookup. TIBCO Scribe® Online uses this value to match records between the source Entity and the Entity specified for this Block.

    On the Value field select the Formula icon to open the formula editor to include a formula, another field, or a previously specified operation. See Formula Editor.

  5. If needed, select Add again to create an additional lookup criterion.

    After you select Add , the And/Or column displays. Select and or or from the drop-down list to determine how to combine lookup criteria. When the Map runs, the criteria is evaluated in order from top to bottom.

  6. To delete a row, select the row and from the Gear menu select Delete.
  7. When you are done, continue defining this Block or select OK to close the Properties dialog and return to the workspace.

Tip: The Lookup Block is not supported with the Text Source Connector. Use the Fetch Block instead.

Note: When using a formula for lookup criteria, the rules are similar to those for filtering criteria. For more information, see Filtering Notes.

Lookup Criteria Examples

In the examples shown below TIBCO Scribe® Online looks up Contacts that meet the selected criteria for use later in the Map.

Example 1

And/Or

Field

Operator

Value

 

CompanyName

equals

Customers.CompanyName

and

Active

equals

TRUE

or

ContactName

equals

Customers.ContactName

These settings are interpreted by TIBCO Scribe® Online as follows: 

((CompanyName=CompanyName AND Active=TRUE) OR ContactName=ContactName)

To include the Contact in the lookup, one of the following must be true:

Example 2

And/Or

Field

Operator

Value

 

ContactName

equals

Customers.ContactName

or

Active

equals

TRUE

and

CompanyName

equals

Customers.CompanyName

These settings are interpreted by TIBCO Scribe® Online as follows: 

((ContactName = ContactName OR Active=TRUE) AND CompanyName = CompanyName)

To include the Contact in the lookup, both of the following must be true:

Block Properties — Field List Tab

Use the Field List tab to specify the fields you want returned for every record that meets the lookup criteria.The fields you specify are available to use in formulas in subsequent Blocks. Select only the fields you need to reduce the time needed to return the data to the Map.

Note: You must select at least one field in the Lookup Block.

Selecting Fields

From the Field List tab, select the checkbox for each field you want to return. The following rules apply:

Block Properties — Error Handling Tab

Use the Error Handling options to enable or disable processing this record when a Block operation encounters a problem.

For the Lookup Block, errors can be logged as follows:

See Block Properties Error Handling Tab for additional information.

Note: If your lookup criteria causes more than one record to be matched, and you do not flag this as an error condition, TIBCO Scribe® Online only returns data from the first record that matches your criteria. In this situation, there is no guarantee which of the multiple records will be returned first to TIBCO Scribe® Online, which could cause the wrong record to be used in subsequent Blocks.

Block Properties — Errors And Warnings Tab

If there are any errors or warnings for this Block, the Errors and Warnings tab displays the number of errors or warnings in the tab name. See Block And Map Errors And Warnings.

Once you have corrected the errors, select the Validate button to update the Errors and Warnings tab.

Related Topics

Lookup Block Example

Working With Blocks

Mapping Blocks

Block Properties Error Handling Tab

Viewing Execution History