- 10 minutes to read

How to use the Search Field Wizard

The Search Field Wizard creates or extends a Search Field straight from a logged message. You start from a real Log Event, so the wizard already knows its Message Type and uses its body and context as test data. Six steps take you from "I need to search on this value" to a saved, re-indexed Search Field.

  • ✅ Start from the message you're looking at in a Log View
  • ✅ Test the expression on that real message before you save
  • ✅ Read the sample in the right encoding, preset from the Log Event, Endpoint, or Message Type
  • ✅ Re-index so messages already logged get the value too

Create the Search Field Contoso: Order Total from an order message with the Search Field Wizard, a Real number with JSON Path $.orderTotal, animated walkthrough (7.12)
Animated walkthrough: from the order a customer sent to a saved Search Field, ready to re-index. The steps are below.

Wizard or editor? Use the wizard when you find a value you need to search on while analyzing logs. Use Add or manage Search Field for setup across many Message Types, for Global expressions, and for Search Field Links.


Understanding the Search Field Wizard

The wizard always works on one Message Type: the Message Type of the Log Event you start from, shown at the top of the wizard. What you add or change is a Search Field Expression for that Message Type.

graph TD A["Select event<br/>the sample Log Event"] --> B["Select Operation<br/>edit, add to, or new"] B --> C["Search Field Details<br/>name and data type"] C --> D["Test<br/>expression and encoding"] D --> E{"Expected<br/>result?"} E -->|No| D E -->|Yes| F["Summary<br/>save"] F --> G["Reindex<br/>apply to logged events"] style A fill:#2678BD,color:#fff style B fill:#2678BD,color:#fff style C fill:#2678BD,color:#fff style D fill:#FFD525,color:#000 style E fill:#FFD525,color:#000 style F fill:#93d16d,color:#000 style G fill:#93d16d,color:#000

Diagram: the six wizard steps. Blue steps choose what to change, yellow steps are the test loop, and green steps save and apply the Search Field.

Wizard vs the Search Field Editor

Feature Search Field Wizard Search Field editor
Start from A Log Event, or Wizard in the editor Search Fields Overview in Administration
Message Types The Log Event's Message Type Any selection, or Global
Test data The Log Event's body, context, and fields A Log Event you pick
Search Field Links ❌ Not available ✅ Configure in the editor
Re-index Last wizard step Reindex Search Field after saving

Prerequisites


Step 1: Select Event

  1. Open a Log View in the Web Client and search for the messages you want to extract data from.
  2. Open View message body on one of the Log Events.
  3. Click the Search Field Wizard button.

Search Field Wizard button (7.11)
The Search Field Wizard button, available when you view a message body.

New 7.12 A Log Event with more than one body opens the wizard on the body you viewed: from View message body #2, the wizard tests body 2. Diff message body, which shows two bodies side by side from With Selected, has no Search Field Wizard button, because it isn't one Log Event.

Administrators can also open the wizard from the Log Event details: click Advanced, then Search Field Wizard.

You can also open the wizard from Administration > Search Fields > edit a Search Field > Wizard. Then use the Select event step to pick the Log Event whose message the wizard uses as sample data.


Step 2: Select Operation

Choose what to do for the Message Type shown at the top of the wizard, then click Next.

Select Operation step with New Search Field selected (7.11)
The Select Operation step for the Hello.World.File/1.0 Message Type, with New Search Field selected.

Operation Use it when
Edit existing Search Field for this Message Type A Search Field already has an expression for this Message Type and you want to change it. The counter shows how many exist.
Add to existing Search Field The Search Field exists, for example "Order Number", but has no expression for this Message Type yet. You add one.
New Search Field No suitable Search Field exists. You create one.

Step 3: Search Field Details

For a New Search Field:

  1. Enter a unique, business-friendly Name, such as "Order Number" or "Customer ID". Users search with this name.
  2. Select the Data Type that matches the values: Text, Integer, Long Integer, Real number with 2 decimals, GUID, Double, Date time with offset, or Bitwise Integer. See Data Type Options.
  3. Optionally add a Description.

For Edit or Add to, select the existing Search Field; the wizard loads its configuration.

⚠️ Choose the Data Type carefully. "Text" for numbers prevents range queries (>, <), and "Integer" for GUIDs causes extraction failures. Changing the Data Type after the Search Field is used in Log Views may cause errors when those Log Views load.


Step 4: Test the Expression

On the Test step, write the expression and test it against the message you started from.

Test step with a JSON Path expression and one match (7.11)
Testing the JSON Path expression orderid against a JSON message: the Result shows one unique match, 123.

  1. Select the plugin in Type. Not sure which one? See Choose a plugin.
  2. Enter the Expression.
  3. Check the result. When the wizard can suggest expressions, it lists them under Resolvable Expressions, each with a Test button.
  4. Check the Result: the Number of unique matches and each extracted value, or an error.
  5. Adjust and test again until the result is what users should search for, then click Next.

The plugin's own checkboxes, such as Treat sub XML as a string and Global for XPath with RegEx, tick on the Test step as well:

Search Field Wizard Test step with Type XPath with RegEx and Treat sub XML as a string and Global ticked (7.12)
The plugin's checkboxes on the wizard's Test step.

The sample is shown on the Message Body, Message Context, and Field Values tabs, so you can see what a body or context expression reads.

Choose the Encoding of the Sample Message

The Encoding dropdown below the message body tells the wizard how to read the sample. New 7.11 It starts 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. The Logging Service uses the same encoding to extract values, so your test result matches what gets indexed.

If characters such as Å or é show as garbage, pick another encoding and click Reload message body. If another encoding fixes it, update the encoding on the Message Type or the Endpoint, as described in Character Encoding.

Encoding dropdown and Reload message body button on the Test step (7.12)
The Encoding dropdown on the Test step, preset to UTF-8 (without BOM) from the Message Type. Click Reload message body after you change it.

A Log Event without a Message Body

New 7.12 A Log Event can be logged without a message body or context. The wizard then opens the Test step with an empty Message Body and the note This Log Event was logged without a message body or context. Type or paste a body above to test the expression, or test it on the Field Values. Paste a sample message to test a body expression, or test on the Field Values tab.

Search Field Wizard Test step with an empty Message Body and the note that the Log Event was logged without a message body or context (7.12)
The Test step for a Log Event logged without a body: paste a sample, or switch to Field Values.

When the body exists but can't be read, the wizard shows Could not load the message body with the reason. The request returned Not Found (404). This can happen if the message body was removed. means the body is gone, for example after it was removed from the Log Databases. Pick another Log Event, or paste a sample.

Example: An Order Number from XML

Input

<Order>
  <OrderID>ORD-2024-12345</OrderID>
  <Customer>Contoso Corp</Customer>
</Order>

Expression

  • Type: XPath
  • Expression: /Order/OrderID

Result

ORD-2024-12345

Example: A Customer ID from JSON

Input

{ "order": { "orderId": "ORD-2024-12345", "customerId": "CUST-789" } }

Expression

  • Type: JSON Path
  • Expression: $.order.customerId

Result

CUST-789

Example: A Booking Number from Plain Text

Input

Shipment confirmed. Booking: TRN-2024-67890. Carrier: FedEx.

Expression

  • Type: RegEx
  • Expression: TRN-\d{4}-\d+

Result

TRN-2024-67890

RegEx returns the whole match. To return only part of a match, such as the value after Booking:, use RegEx with capturing groups.


Step 5: Summary

Review the Search Field and its expression for the Message Type, and save. From now on, the Logging Service extracts the value from new Log Events of this Message Type.

The wizard doesn't add the field to any Log View: add it yourself on the Log View's Search criteria tab, in the Default search setup or the Optional fields, or as a column on the Display result tab. A Log View only shows the values of the Search Fields it includes; see Which Search Field Values a Log View Shows and HideSearchFieldValuesInLogViews. An Optional field gets a column in the result list (with Display result on Default) and shows its values from the first search; users may also add it to their search.


Step 6: Reindex

Log Events logged before you saved don't have the value yet. Use the Reindex step to apply the Search Field to them.

Reindex the order events for Contoso: Order Total, then search order ORD-10001 in the Log View Contoso: Orders and see the Order Total column, animated walkthrough (7.12)
Animated walkthrough: the re-index fills the value on events logged before the save, and the Log View's Optional field shows it.

  1. The last step lists the Message Types whose logged events get the value, here O2C.Order.Received/1.0, ticked. Click Reindex.
  2. Reindex operation started says how many events will be reprocessed (here 40). The re-index runs in the background. Click Close.
  3. In the Log View Contoso: Orders, Contoso: Order Total is an Optional field. The wizard doesn't add the field for you; see Step 5.
  4. Type ORD-10001 in O2C - Order ID and click Search. The Contoso: Order Total column shows 99.95 on the order the customer sent. The other events show N/A, because their Message Types carry no order total.

New 7.10.11 The wizard waits for the save to finish before it starts the re-index, so the re-index always uses the saved Search Field. A re-index runs in batches, does not block logging, and can be run again if it stops. When it finishes, the result is written to the Log Audits. See 'How a Re-Index Runs'.

Tip

Re-indexing uses database resources. On large Log Databases, test the expression first and re-index outside peak hours.


Verify the Result

  1. Open a Log View that shows messages of the Message Type and includes the new Search Field.
  2. Filter on your new Search Field with a value you saw in the test, and search.
  3. Open a Log Event and check that the Search Field has the expected value.

While a re-index is running, events still to be processed have the Processing State Reindexing.


Troubleshooting

The Search Field Wizard Button Is Missing

  • Your account may lack permission to create or edit Search Fields; ask your administrator (see Roles and Permissions).
  • Open View message body on a Log Event; the button is on that view.

The Test Shows No Value

  • Check the expression syntax for the selected plugin (XPath and Allowed XPath expressions, JSON Path, RegEx).
  • Simplify the expression to find the failing part, for example /Order before /Order/Details/Item[1]/Price.
  • Check the Encoding: a sample read in the wrong encoding, or a leading byte order mark (BOM), can break the match.
  • For a value in a context property, use a context plugin such as Message Context Key; body plugins don't read the context.

The Value Is Blank in Log Views After Re-Indexing

  • The re-index may still be running: search for Log Events with the Processing State Reindexing, and read the result in the Log Audits.
  • The expression may not match every message of the Message Type; test it with another Log Event.
  • The Log View doesn't include the Search Field, so its value stays hidden there. Add it to the Log View (see Step 5).

Next Steps