Web Service Lookup

Inherits From Lookup Specification Namespace Grooper.Cloud

Performs a lookup by calling a web service to retrieve, validate, or enrich data in Grooper.

Remarks

The Web Service Lookup class enables Grooper to connect to external web services for real-time data retrieval, validation, and enrichment of Data Fields and Data Models. It is a type of Lookup Specification designed to integrate REST or SOAP APIs into your data extraction and validation workflows.

Overview

Use Web Service Lookup to automate the process of querying external systems—such as CRMs, ERPs, or custom APIs—directly from Grooper. This allows you to:

Populate fields with authoritative data from remote sources.
Validate user-entered or extracted values against live data.
Retrieve lists or reference data for dropdowns and picklists.

The lookup is performed by sending an HTTP request (GET or POST) to a specified endpoint, optionally including parameters or a request body. The response is parsed (as JSON or XML), and data is extracted using selector expressions to populate or validate Grooper fields.

How It Works

Configuration:
- Specify the web service URL, HTTP verb, message format, authentication, and any required headers or request body.
- Define how to extract records and values from the response using selector expressions.
Execution:
- When triggered, Grooper sends the configured request to the web service.
- The response is parsed, and records are selected using a JSONPath or XPath expression.
- Value selectors extract specific data points from each record, which are mapped to Grooper fields or included in the lookup results.
Integration:
- Results are used to populate, validate, or suggest values for Data Fields in your data model.
- Errors, timeouts, or authentication failures are logged for review and troubleshooting.

Supported Scenarios

Data Enrichment:
Automatically fill in missing or supplemental data by querying external APIs (e.g., address validation, customer info).
Validation:
Ensure field values match authoritative sources by validating against live data.
Reference Data:
Retrieve lists of valid values (such as codes, names, or categories) for use in dropdowns or picklists.

Authentication and Security

Supports multiple authentication schemes, including Basic, token-based, and custom HTTP Authentication Methods.
Secure sensitive information (such as API keys) using headers or authentication properties.
Always review the web service's documentation for required authentication and security best practices.

Error Handling and Diagnostics

If the web service returns an error, times out, or returns an unexpected response, an exception is raised.
Diagnostic output is available to review request and response details, including headers, payloads, and timing.
Use diagnostics to troubleshoot configuration issues, test selectors, and verify integration.

Diagnostic Artifacts

Request Log: HTTP method, URL, and headers sent to the web service.
Request Body: The full payload sent (for POST requests).
Response Body: The raw response received from the web service.
Response Headers: All headers returned by the web service.
Timing Information: Elapsed time for the request/response cycle.
Row Count: Number of records extracted from the response.

Best Practices

Test your configuration using diagnostic output to ensure requests and selectors are correct.
Use variables in the URL and request body to dynamically insert field values.
Map value selectors carefully to ensure extracted data matches your data model.
Set appropriate timeouts to handle slow or unreliable web services.
Secure all sensitive data and review API documentation for compliance.

Example Workflow

Configure a Web Service Lookup on a Data Model or Data Section.
Set the URL, HTTP verb, message format, and authentication as required by the API.
Define a record selector (JSONPath or XPath) to identify records in the response.
Add value selectors to extract and map data points to Grooper fields.
Trigger the lookup during data extraction or validation to retrieve and apply results.

Properties

Name Type Description

General

Description

String

►

An optional description for this lookup operation.

Request

URL

String

►

The URL to be invoked.

Specifies the web service endpoint that will be called when performing a lookup.

Configuration

Enter a static URL or use a template with @variables to dynamically insert values from Data Fields or Data Columns.
Variables are replaced at runtime with the current field values, allowing for parameterized requests.

Example:

https://api.example.com/lookup?id=@FieldName

Usage Guidance

Use @VariableName to merge field or column values into the URL for dynamic queries.
Ensure the URL matches the requirements of the target web service, including any required path or query parameters.
For POST requests, the URL typically identifies the endpoint, while data is sent in the request body.

> Tip: Use diagnostic output to verify the final URL sent to the web service, especially when using variables.

Message Format

MessageFormats

►

The message format for requests and responses.

Can be one of the following values:

Name	Value	Description
JSON	0	JavaScript Object Notation The request and response body will be in JSON format. Record and value selectors should be specified using JSONPath syntax.	►
XML	1	eXtensiable Markup Language The request and response body will be in XML format. Record and value selectors should be specified using XPath syntax.	►

Determines the data format used for both sending requests and interpreting responses from the web service.

Options

JSON:
- Use JSONPath expressions for selectors.
- Request and response bodies are formatted as JSON.
XML:
- Use XPath expressions for selectors.
- Request and response bodies are formatted as XML.

Configuration Guidance

The same format is used for both request and response; it is not possible to send XML and receive JSON, or vice versa.
Choose the format required by the web service API.
Ensure that all selector expressions (for records and values) match the chosen format.

> Note: Incorrect format selection may result in parsing errors or failed lookups.

Verb

HttpVerbs

►

The HTTP verb to use for the request.

Can be one of the following values:

Name	Value	Description
GET	0	Uses an HTTP GET operation. Data may be passed in the URL as path segments or parameters.	►
POST	1	Uses an HTTP POST operation. Data may be passed in the URL as path segments or parameters, or as JSON in the body of the request.	►

Specifies the HTTP method (GET or POST) used to send the request to the web service.

Options

GET:
- Data is sent as URL parameters.
- Use for simple queries or when the API expects parameters in the URL.
POST:
- Data is sent in the request body (see 'Request Body').
- Use for APIs that require complex payloads or when sending sensitive data.

Configuration Guidance

Select the verb required by the web service API.
For POST requests, configure the 'Request Body' property to define the payload.
For GET requests, ensure all required parameters are included in the URL.

> Tip: Review the web service documentation to determine which verb to use and how to structure requests.

Request Body

String

►

When Verb is set to POST, defines the XML or JSON payload to be sent with the request.

Specifies the content to send in the body of a POST request to the web service.

Configuration

Enter a template for the request body, using the appropriate format (JSON or XML) as required by the web service.
Use @variables to merge values from Data Fields or Data Columns into the payload.
The format must match the selected 'Message Format'.

Example (JSON)

{
  "id": "@FieldName",
  "type": "customer"
}

Usage Guidance

Only used when the HTTP verb is set to POST.
Ensure all required fields and structure match the web service's API specification.
Use diagnostic output to review the final request body sent.

> Tip: Test your request body with sample data to verify correct variable substitution and formatting.

Headers

String

►

A list of HTTP headers to include with the request.

Specifies additional HTTP headers to send with the web service request.

Configuration

Enter headers as key-value pairs, one per line.

Example:

Authorization=Bearer 378417346873687237673643
Content-Type=application/json

Usage Guidance

Use headers to provide authentication tokens, content types, custom API keys, or other required metadata.
Ensure header names and values match the requirements of the web service.
Sensitive information (such as API keys) should be secured and not hard-coded when possible.

> Tip: Review the web service documentation for required and optional headers.

Authentication

HTTP Authentication Method

►

The authentication method to use when connecting to the web server.

Can be one of the following types:

Value	Description
Exchange OAuth	Implements OAuth 2.0 authentication for connecting Grooper to Microsoft Exchange Online (Office 365) using Azure AD.
OAuth Service Login	Implements OAuth 2.0 authentication using the client credentials flow for secure server-to-server access in Grooper.
Anonymous Authentication	Implements HTTP authentication where no credentials or identity are provided to the server.
Auto Authentication	Authenticates HTTP requests using the credentials of the current Windows user.
Basic Authentication	Implements Basic HTTP Authentication for connecting to external content platforms in Grooper.
NTLM Authentication	Implements NTLM (Windows Integrated) Authentication for connecting to external content platforms in Grooper.
OneDrive OAuth	Implements OAuth 2.0 authentication for connecting Grooper to Microsoft OneDrive and SharePoint Online using a Microsoft account.
SharePoint OAuth	Implements OAuth 2.0 authentication for connecting Grooper to SharePoint Online (365) using Azure AD.

Selects the authentication scheme used to connect to the web service.

Options

Supports Basic, token-based, and custom HTTP Authentication Methods.
Choose the method required by the web service API.

Usage Guidance

Configure authentication properties as needed (e.g., username, password, token).
For advanced scenarios, implement a custom authentication method.
Always secure sensitive credentials and avoid exposing them in plain text.

> Tip: Consult the web service documentation for supported authentication types and required configuration.

Response

Record Selector

String

►

A JSONPath or XPath expression that selects records from the web service response.

Value Selectors

Value Selector[]

►

Defines the values to extract from each record and how to map them to Grooper fields.

Timeout

Int32

►

The amount of time, in seconds, to wait for a response from the web service before raising a timeout error.

Lookup Options

Trigger Mode

TriggerModes

►

Controls when the lookup is executed.

Can be one of the following values:

Name	Value	Description
Auto	0	Trigger automatically when the value of a lookup field changes. Use `Auto` mode for fully automated lookups. The lookup will execute any time a referenced field value changes, ensuring that data is always validated or populated in real time. When to Use When you want immediate feedback or validation as users enter or modify data. For fields that must always be kept in sync with external data sources. Example Scenario As soon as a user enters a customer ID, the lookup automatically retrieves and populates the customer's details. > Tip: Use with caution if lookups are resource-intensive or if frequent changes could cause excessive requests.	►
Conditional	1	Trigger automatically when the value of a lookup field changes, only if the target fields are currently empty. Use `Conditional` mode to avoid overwriting existing data. The lookup will only execute if the target fields are blank, making it ideal for initial population scenarios or when you want to preserve user-entered or previously populated values. When to Use When you want to auto-populate fields only if they have not already been set. To prevent overwriting data that may have been entered manually or by another process. Example Scenario When a user enters a product code, the lookup fills in the product description only if it is currently empty. > Tip: This mode is useful for onboarding, data entry, or import workflows where initial values are needed but should not replace existing data.	►
Manual	2	Must be triggered manually by a user. Use `Manual` mode when lookups should only occur on explicit user action, such as clicking a button or selecting a menu command. This is useful for scenarios where automatic lookups are not desired, or where user review and control are required before executing a lookup. When to Use When lookups are resource-intensive or should only be performed on demand. When users need to review or confirm data before triggering a lookup. Example Scenario A user reviews extracted data and clicks a "Validate" button to perform the lookup and check for errors. > Tip: Use this mode to give users full control over when lookups are performed.	►
Custom	3	The trigger condition will be defined by the Trigger expression. Use `Custom` mode for advanced scenarios where a custom code expression determines when the lookup should execute. The expression, set in the 'Trigger' property, must evaluate to `true` for the lookup to run. When to Use When lookup execution depends on complex business logic, multiple field values, or workflow state. To implement conditional logic that cannot be achieved with the standard modes. Example Scenario Run the lookup only if both a status field is "Active" and a required amount is greater than zero: `@Status == "Active" && @Amount > 0` > Tip: Use the property grid's expression editor for code completion and validation when entering custom trigger expressions.	►

The TriggerModes enumeration determines the conditions under which a lookup operation is performed in Grooper. This setting allows you to control whether lookups are executed automatically, only under certain conditions, manually, or based on a custom expression. Choosing the appropriate trigger mode is essential for balancing automation, user control, and data integrity in your solution.

Trigger

String

►

Specifies the conditions required for this lookup to execute when 'Trigger Mode' is set to Custom.

The 'Trigger' property allows you to define a custom code expression that determines whether the lookup operation should run. This enables advanced, data-driven control over lookup execution, beyond the standard automatic, conditional, or manual modes.

How It Works

The expression must evaluate to true or false.
The lookup will only execute if the expression returns true at runtime.
The expression can reference Data Fields, Variable Definitions, or other context-specific values using the @FieldName or @VariableName syntax.
This property is only used when 'Trigger Mode' is set to Custom.

Configuration Guidance

Enter a Boolean expression using Grooper's expression syntax.
Use logical operators (&&, ||, !), comparisons, and field/variable references to build complex conditions.
If the expression is empty or evaluates to false, the lookup will not execute.

Example Expressions

Only run the lookup if both fields are populated:
```
@FieldA != null &amp;&amp; @FieldB != null
```
Run the lookup if a status field is "Active":
```
@Status == "Active"
```
Run the lookup if a numeric field is greater than zero:
```
@Amount &gt; 0
```

Usage Scenarios

Conditionally execute lookups based on user input, extracted values, or workflow state.
Prevent unnecessary lookups when required data is missing or when certain business rules are not met.
Implement advanced logic for multi-stage validation or population workflows.

> Tip: Use the property grid's expression editor for code completion and validation when entering trigger expressions.

Miss Disposition

MissDispositions

►

Specifies what happens if the lookup returns no results.

Can be one of the following values:

Name	Value	Description
Normal	0	Flag the lookup fields and clear the target fields. Sets an error status on the lookup fields and clears any values in the target fields. When to Use When you want to alert users that no matching data was found and remove potentially invalid or stale values. For scenarios where data integrity is critical and unmatched values should not be retained. Example Scenario If a lookup for a customer ID returns no results, the "Customer Name" and "Address" fields are cleared and an error is shown. > Tip: Use this option to ensure that only validated data remains in your data model.	►
Flag	1	Flag the lookup fields. Sets an error status on the lookup fields but leaves target field values unchanged. When to Use When you want to notify users of a problem but preserve any existing data for review or correction. For workflows where user intervention is expected after a failed lookup. Example Scenario If a lookup for a product code fails, the "Product Description" remains, but an error is flagged for user review. > Tip: Use this to prompt users to correct or confirm unmatched values without losing their input.	►
Clear	2	Clear the target field values. Clears the values of the target fields without flagging an error. When to Use When you want to silently remove data that could not be validated, without alerting the user. For automated workflows where missing data should be cleared but not flagged as an error. Example Scenario If a lookup for a vendor number fails, the "Vendor Name" field is cleared, but no error is shown to the user. > Tip: Use this for background processes or data cleansing scenarios where user notification is not required.	►
Ignore	3	Do nothing. Behave as though no lookup is defined. No action is taken if no results are found. The current values and status remain unchanged. When to Use When missing data is acceptable and should not interrupt the workflow or user experience. For optional lookups or informational fields where validation is not required. Example Scenario If a lookup for an optional reference field fails, the field remains unchanged and no error is shown. > Tip: Use this to minimize disruption in workflows where missing data is not critical.	►

The MissDispositions enumeration determines how Grooper responds when a lookup operation does not return any matching records from the external data source. This setting controls whether errors are flagged, target fields are cleared, or no action is taken.

Usage Guidance

Select the option that best fits your data integrity, user experience, and workflow requirements.
Use to control how missing or unmatched data is handled during validation or population.
Consider the impact on downstream processes and user review when configuring this setting.

For more information on error handling and lookup configuration, see the documentation for Lookup Specification.

Conflict Disposition

ConflictDispositions

►

Specifies what happens if the lookup returns multiple results.

Can be one of the following values:

Name	Value	Description
Normal	0	Flag the lookup fields and clear the target fields. Sets an error status on the lookup fields and clears the target fields. When to Use When ambiguous or conflicting data should not be used and must be resolved before proceeding. For scenarios where data integrity is paramount and only a single, unambiguous result is acceptable. Example Scenario If a lookup for an invoice number returns multiple matches, all related fields are cleared and an error is shown. > Tip: Use this to prevent the use of potentially incorrect or conflicting data.	►
Flag	1	Flag the lookup fields. Sets an error status on the lookup fields but leaves the target fields unchanged. When to Use When you want to alert users to a conflict but preserve existing data for review or correction. For workflows where user intervention is required to resolve ambiguity. Example Scenario If a lookup for a part number returns multiple results, the "Part Description" remains, but an error is flagged for user review. > Tip: Use this to prompt users to resolve conflicts without losing their input.	►
Accept	2	Use the first row in the result set. Accepts the first result returned by the lookup and populates the target fields with its values. When to Use When it is acceptable to use the first match, even if multiple results are found. For scenarios where the external data source is known to return results in a reliable order. Example Scenario If a lookup for a serial number returns several matches, the first result is used to populate the fields. > Tip: Use with caution, as this may introduce ambiguity if the order of results is not guaranteed.	►
Ignore	3	Do nothing. Behave as though no lookup is defined. No action is taken if multiple results are found. The current values and status remain unchanged. When to Use When conflicts are not critical and should not interrupt the workflow or user experience. For informational lookups or optional fields where ambiguity is acceptable. Example Scenario If a lookup for a reference field returns multiple results, the field remains unchanged and no error is shown. > Tip: Use this to minimize disruption in workflows where data conflicts are not critical.	►

The Conflict Dispositions enumeration controls how Grooper handles situations where a lookup operation returns more than one matching record from the external data source. This setting determines whether errors are flagged, data is cleared, the first result is accepted, or no action is taken.

Usage Guidance

Select the option that best fits your data quality, business rules, and user experience requirements.
Use to control how ambiguous or conflicting data is managed during validation or population.
Consider the risk of data ambiguity and the need for user intervention when configuring this setting.

For more information on conflict handling and lookup configuration, see the documentation for Lookup Specification.

Field Population

PopulationMethod

►

Specifies how target fields are populated with the lookup results.

Can be one of the following values:

Name	Value	Description
Overwrite	0	Populate the target fields. Overwrites the values of the target fields with the results from the lookup, regardless of whether they are currently empty or already populated. When to Use When the lookup source is authoritative and should always set the field values. For scenarios where you want to ensure the most current or accurate data is always present. Example Scenario After a successful lookup, the "Customer Name" and "Address" fields are always updated with the latest values from the external system, even if they were previously filled. > Tip: Use with caution if you want to preserve user-entered or previously extracted data.	►
Supplement	1	Populate the target fields if they are empty. Only sets the value of a target field if it is currently blank. Existing values are preserved and will not be overwritten by the lookup. When to Use When you want to supplement missing data without replacing user-entered or previously populated values. For initial data population, onboarding, or import scenarios where some fields may already be set. Example Scenario If the "Product Description" field is empty, the lookup fills it in; if it already contains a value, the lookup leaves it unchanged.	►
None	2	Do not populate any fields. The lookup will not update any target fields. Use this mode for validation-only scenarios, where you want to check values against an external source but not change them. When to Use When the lookup is used solely to validate existing data, not to populate or update fields. For compliance or audit scenarios where data must be checked but not altered. Example Scenario The lookup verifies that the entered "Account Number" exists in the external system, but does not update any fields with returned data. > Tip: Use this method to enforce data integrity without modifying user or extracted values.	►

The PopulationMethod enumeration controls whether and how the results of a lookup operation are written to the target fields in Grooper. This setting determines if lookup results will overwrite existing values, supplement only empty fields, or leave all fields unchanged.

Usage Guidance

Choose the method that matches your data entry and validation requirements.
Use to control whether lookups act as authoritative sources, provide supplemental data, or serve only for validation.
Consider the impact on user-entered data and downstream processes when selecting a population method.

For more information on lookup population strategies, see the documentation for Lookup Specification and related error handling options.

Lookup Info

Lookup Fields

String

►

The list of fields and variables used as lookup criteria.

Target Fields

String

►

The list of fields that will be populated by the lookup operation.

Used By

Data Lookup

Web Service Lookup

Remarks

Overview

How It Works

Supported Scenarios

Authentication and Security

Error Handling and Diagnostics

Diagnostic Artifacts

Best Practices

Example Workflow

Properties

Configuration

Usage Guidance

Options

Configuration Guidance

Options

Configuration Guidance

Configuration

Example (JSON)

Usage Guidance

Configuration

Usage Guidance

Options

Usage Guidance

Configuration

Usage Guidance

Configuration

How It Works

Usage Guidance

Configuration

Usage Guidance

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

How It Works

Configuration Guidance

Example Expressions

Usage Scenarios

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

Usage Guidance

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

Usage Guidance

When to Use

Example Scenario

When to Use

Example Scenario

When to Use

Example Scenario

Usage Guidance

See Also

Used By