Web Service Lookup

Use this property to provide a human-readable explanation of the lookup's purpose, configuration, or any special instructions. This description is displayed in the property grid and can help other users understand the intent and behavior of the lookup.

Specifies the web service endpoint to call.

• Enter a static URL, or use a template with @variables to merge field data into the URL.
• Example: https://api.example.com/lookup?id=@FieldName

> Tip: Use @VariableName to insert values from Data Fields or Data Columns into the URL.

Can be one of the following values:

Selects the format for both sending data and interpreting responses.

• JSON: Use JSONPath for selectors.
• XML: Use XPath for selectors.

The same format is used for both request and response.
It is not possible to send XML and receive JSON, or vice versa.

Can be one of the following values:

Determines how data is sent to the web service.

• GET: Data is sent as URL parameters.
• POST: Data is sent in the request body (see 'Request Body').

Choose the verb required by the web service API.

Enter a template for the request body.

• Use @variables to merge values from Data Fields or Data Columns.
• The format (JSON or XML) must match the 'Message Format'.

Example (JSON):

Specify additional headers as key-value pairs, one per line.

Example:

Authorization=Bearer 378417346873687237673643.

Can be one of the following types:

Choose the authentication type required by the web service.

Use the Record Selector to define which parts of the web service response should be treated as individual records for data extraction.

• For JSON responses, enter a JSONPath expression.

  • If the selector matches an array, each element is treated as a separate record.
  • If the selector matches one or more objects, each object becomes a record.
  • Leave this property blank to select the root object or array.

• For XML responses, enter an XPath expression.

  • Each XML element matched by the selector is treated as a record.
  • Leave this property blank to select the root element as a single record.

Examples:

• JSONPath: $.results[*] selects all items in the results array.
• XPath: /Response/Items/Item selects all <Item> elements under <Items>.

> Tip: Use the diagnostic output to review the raw response and test your selector for accuracy.

Value Selectors specify which data points to extract from each record identified by the Record Selector, and optionally map them to fields in your data model.

• Add one or more value selectors to extract multiple values from each record.
• For each value selector, configure:
  • The path or expression to extract the value (using JSONPath or XPath, depending on the response format).
  • The target Grooper field to populate (optional).
  • The data type and column name for the extracted value.

How it works:

• Each value selector runs against every record found by the Record Selector.
• If a target field is specified, the extracted value is mapped directly to that field.
• If no target field is specified, the value is included in the results table for review or further processing.

Common uses:

• Extracting multiple fields from a single record (e.g., Name, Address, ID).
• Populating Grooper fields automatically from web service data.
• Returning additional data for validation or review.

> Tip: Use multiple value selectors to build a complete mapping from the web service response to your data model.

Sets the maximum time to wait for a response.

• If the web service does not respond within this period, a timeout error occurs.
• Enter a value between 1 and 300 seconds.

Can be one of the following values:

Determines the conditions under which a lookup operation is triggered. Use this to control automation, user interaction, or custom logic for lookup execution.

Enter a code expression that evaluates to true or false. The lookup will only execute if the expression returns true. This allows for advanced, data-driven control over when the lookup fires. Example:@FieldA != null && @FieldB == "Active"

Can be one of the following values:

Determines the behavior of the lookup operation when no matching records are found in the external data source. Configure this to control user feedback and data clearing.

Can be one of the following values:

Controls the behavior when the lookup query returns more than one matching record. Choose the option that best fits your data integrity and workflow needs.

Can be one of the following values:

Controls whether and how the results of a lookup operation are written to the target fields. Choose the method that matches your data entry and validation requirements.

This property displays a comma-separated list of all Data Fields and Variable Definitions that are used as input for the lookup query. These are the values that will be sent to the external data source to perform the lookup.

This property displays a comma-separated list of all Data Fields that will be set or validated by the results of the lookup. These are the target fields that will receive values from the external data source.