Add or manage Search Field

Create and manage Search Fields to extract business-critical values from integration messages. Search Fields enable self-service monitoring, end-to-end tracking, and business intelligence across your integration landscape.

New to Search Fields? Read What is a Search Field? to understand the concepts before diving into configuration.

A Search Field applies to Log Events in all Log Databases and can target specific Message Types for precise data extraction.

Understanding the Search Field Configuration

A Search Field is configured in layers: the Search Field itself (name and data type), one or more Search Field Expressions that say how to extract the value per Message Type, and optional Search Field Links. After you save, the Logging Service extracts values from new Log Events; a re-index applies the Search Field to Log Events that are already logged.

Diagram: define the Search Field and its expressions (blue), test until the result is right (yellow), add optional links (teal), save and re-index (orange), and the values become searchable in Log Views (green). Each step has its own section below.

Add a New Search Field

Navigate to the Search Fields Overview in the Administration section and click the Add Search Field button.

The Add Search Field button in the Search Fields Overview.

Tip

You can also create Search Fields directly from Log Views using the Search Field Wizard. This provides context-aware setup with sample data from the current view.

Configure Basic Properties

Enter a unique, business-friendly name and select the Data Type that matches your data. Optionally, add a Description and Web Site link.

Only the Name is required; the Data Type hint warns about changing it after the Search Field is used in Log Views.

Mandatory Fields

Optional Fields

Data Type Options

The data type determines which operators are available for filtering.

Naming Best Practices

• Use business terms: "Order Number", not "OrderID_Field"
• Be consistent: use the same terminology across all Search Fields
• Avoid abbreviations unless universally understood
• Examples: "Customer ID", "Invoice Number", "Transport Booking Number"

Important

Choose the most specific data type for your data. Using "Text" for numbers prevents range queries (>, <). Using "Integer" for GUIDs causes extraction failures. You can change the Data Type later, but changing it after the Search Field is used in Log Views may cause errors when those Log Views load.

Add Search Field Expressions

Click the Edit button in the Search Field Expressions section to add or manage expressions.

Click the Edit button to add or manage expressions for this Search Field.

Each configured expression on the right shows its type, expression, and Message Type.

Click the Actions button to edit or delete a selected expression.

The Actions menu edits or deletes the selected expression.

Search Field Expressions define how values are extracted from your integration messages. A single Search Field can have several expressions, typically one per Message Type or data format. Pick the plugin with the table in Choose a plugin: XPath for XML, JSON Path for JSON, RegEx for EDI and other text, Flat File CSV for delimited files, Message Context Key for context properties, and Formula to combine or transform values.

Tip

Start with the simplest expression type for your data format. Use Formula only when you need to combine multiple sources or transform data.

Expression Properties

Message Type Assignment

Message Types are set on each expression, not on the Search Field. Click a Message Type name to jump to its definition in the Repository Model.

• Global – Apply to all Message Types

  • Use for universal fields like "Message ID" or "Timestamp"
  • Caution: Adds processing overhead to every message
  • Performance tip: Use targeted expressions instead of complex global ones

• Specific Message Types – Apply only to selected types

  • Use for most scenarios—better performance and clearer debugging
  • Example: Separate expressions for "Invoice from SAP" vs "Invoice from Shopify"
  • Extract only values someone will search for: every expression adds processing time to each message of its Message Types, and a poorly written RegEx is especially expensive, both at runtime and during a re-index

• Optional Flag

  • Enabled (checked): No value = normal processing, no warning
  • Disabled (unchecked): No value = warning logged
  • Use when fields may legitimately be absent (e.g., "Return Reason" on non-return orders)

A message body larger than the MessageProcessingMaxBodySize System Parameter isn't processed, so body-based expressions extract nothing from it. For EDIFACT messages, the EDIMessageTypeParseString System Parameter builds the Message Type name and so decides which expressions apply.

Test Your Expression

Use the Test Expression tab to validate with real data from your Log Databases.

Processing States

✅ OK (Green)	⚠️ Warning (Yellow)	❌ Error (Red)
Expression successfully extracted values	No value found - check syntax or mark as Optional	Expression failed - check syntax or data format

Tip

Always test expressions before saving! Use real data from your Log Databases to ensure accurate extraction.

Test in the Wizard with the Right Encoding

Click Wizard while you edit a Search Field to test the expression against a sample message. On the wizard's Test step, an Encoding dropdown controls how the sample message is read. ^{New 7.11} It opens on the message's resolved encoding: the ExtendedProperties/1.0#Encoding context property, else an encoding named in the XML declaration of the body, else the Endpoint Character encoding, else the Message Type Character encoding. Pick another encoding and click Reload message body to compare. The Logging Service uses the resolved encoding during processing, so a test that passes here also extracts correctly at runtime.

The Encoding dropdown next to Reload message body, preset from the Message Type.

See How to use the Search Field Wizard for the full walkthrough, and Character Encoding for how the resolved encoding is chosen.

Add Search Field Links (Optional)

Search Field Links transform extracted values into clickable links to external business systems. Users can click Search Field values in Log Views to jump directly to CRM, ERP, or other systems.

Example: A clickable Search Field Link in a Log View.

Click the Edit button in the Search Field Links section to configure one or more links.

Each row is one link; the button next to the URL tests it with the Test Value.

URL Template Examples

• Simple: https://crm.company.com/orders/{value}
• With query parameter: https://erp.company.com/search?orderId={value}&view=full
• If Search Field contains "12345", becomes: https://crm.company.com/orders/12345

For a worked example that opens another logged message in Nodinite, see BizTalk Message Id.

Tip

You can configure multiple links for the same Search Field. Example: A "Customer ID" field might link to both your CRM (customer profile) and ERP (account balance).

Testing Links

Enter a sample value in Test Value and click the link button on a row to test navigation before you click Confirm or Confirm and close. Verify:

• URL is constructed correctly
• Target system loads the correct record
• Authentication/permissions work for end users

Save and Re-Index

Click the Update button to save expression changes, then click Save to finalize all Search Field configuration.

Update button saves expression-level changes.

Save and Close button finalizes Search Field configuration.

Important

After clicking Update for expressions, you must also click Save to persist all changes to the Search Field itself.

Re-Index Historical Data (Optional)

After saving, you can re-index to apply this Search Field to existing messages in your Log Databases.

^{New 7.10.11} The Reindex Search Field button stays disabled until you save your changes. A re-index always uses the saved Search Field, never unsaved edits.

Re-indexing selected Message Types to apply the new Search Field to historical data.

How a Re-Index Runs

^{New 7.10.11} A re-index is built to run safely alongside normal logging, even on large Log Databases:

• Batched: The Log Events of each Message Type are flagged for re-index in batches. Each batch is committed on its own, so a long re-index does not lock the Log Database tables or block the Log API.
• Resumable: If a re-index stops, run it again. It picks up where it stopped. An event is never flagged twice.
• Parallel and isolated: Log Databases are re-indexed in parallel, one step at a time per database. A step that deadlocks is retried, and a failing Log Database does not stop the others.
• Latest saved definition: Values are rebuilt from the latest saved Search Fields.
• Skipped events and databases: Read-only Log Databases are skipped and reported. Events whose body and context have both been removed are not flagged.

While events wait to be processed, they have the Processing State Reindexing.

Where to Find the Result

• Web Client: When the re-index finishes while you wait, the result lists any Log Databases that were left out.
• Log Audits: Every re-index writes its result to the Log Audits: how many events were flagged, and which Log Databases were skipped, unreachable, or failed. A large re-index keeps running in the background; the Web Client tells you to look in the Log Audits for the result.

When to Re-Index

• ✅ You added a new Search Field and want to search historical data
• ✅ You modified an expression and need to recalculate existing values
• ✅ You're preparing for compliance audits requiring retroactive search
• ❌ You're just testing—wait until production-ready to avoid overhead

Best Practices

• Plan ahead: Re-indexing can be time-consuming on large databases. Schedule during low-traffic periods.
• Be selective: Only re-index the Message Types that need it. Don't select "All" unless necessary.
• Cannot abort: Once started, re-indexing runs to completion. Test thoroughly before starting.
• Read-only databases: Automatically skipped and reported in the result.
• Monitor progress: Search for Log Events with the Processing State Reindexing, and read the result in the Log Audits. Check the Logging Service logs for errors.

Tip

If adding multiple Search Fields, configure all of them first, then do one re-index at the end instead of re-indexing after each field.

Next Steps

Add or manage Log View
Add or manage Message Types
Formula Expression Plugin
How to use the Search Field Wizard

Related Topics

What is a Search Field?
Search Fields Overview
Search Field Expressions Overview
XPath Expression Plugin
RegEx Expression Plugin
JSON Path Expression Plugin
Repository Model
Logging Service
Message Type Overview
Log Views
Character Encoding
Allowed XPath expressions
BizTalk Message Id - Search Field Link example
Log Audit Search
Find an order by Order Id - How business users search on a Search Field