Bucket Modifier — Value Template Guide

In a bucket (Static, LDAP/AL, API, and the Threat Intelligence / STIX lists), the Value field inside the Modifier section is a small template language that tells Logsign what to do with each incoming log. This article helps you pick the right template for the job. The Type selector displays LDAP/AD buckets as LDAP/AL. Buckets are managed under Settings › Alerts & Incidents › Buckets.

1. How the Modifier works

Every modifier row has three main parts:

Key Field is picked from the field list and is optional (a row without it is only useful for constant values, see below). Modify Field and Value are typed into the two inputs on the same line, separated by :. The row can also carry a Buckets selection; when one or more buckets are selected there, the lookup is made against those buckets instead of the bucket you are editing.

How a lookup template runs for a matching log:

1. A log arrives → Logsign reads the Key Field from the log (e.g. Source.UserName = "ahmet")
2. It looks up that value in the bucket's key/value table (e.g. the LDAP list maps ahmet → "Customer Experience")
3. If found, it produces a result from the Value template and writes it to the Modify Field

Lookup templates ($value, $value[...], $add $value) only fill an empty Modify Field; if the log already carries a value there, it is left as is. The other $add templates (a constant, a field copy or $add $description) append instead: if the Modify Field already holds something, the new value is added as a comma-separated item (duplicates are skipped). When the selected Key Field is a numeric type, these templates sum the values.

2. The most common templates

Simple lookup: $value

"If the key exists in the table, write the value next to it into the target field."

This is the most common and correct usage for Static List and LDAP/AL List buckets.

Example: Map UserName to Department

Result: When a log arrives with Source.UserName = "ahmet" and your LDAP list maps ahmet to "Customer Experience", the field Source.DepartmentName is set to "Customer Experience".

Multi-column lookup: $value[FieldName]

"If the table row is not a single value but an object containing multiple fields, pull just the column you want."

This form applies to Threat Intelligence (TI) and STIX lists, and to API buckets, when a lookup result contains multiple fields. The built-in Threat Intelligence lists expose the indicator itself (for example External.IP, URL.Domain or Object.Hash) together with Info, Type and ListID. For API buckets the column names come from the API response.

Example: Pull the indicator type from a TI list

Result: If the TI list returns {External.IP: ..., Info: ..., Type: ..., ListID: ...} for the key, only the Type column is written.

⚠ In plain Static List and LDAP/AL List buckets each key has exactly one value, so you do not need $value[Field]. A plain $value is enough.

Constant value: $add '<text>'

"Write this fixed text for each log that matches the bucket conditions."

Example: Add a fixed tag to each matching log

Result: Source.Tag is set to "internal-user".

Conditional constant: $add '<text>' with Key Field

"If the key exists in the table (we only check existence, not the actual value), write this fixed text."

Example: Tag only known admin users as "PRIVILEGED"

Used on an Admin User List bucket, this sets Source.Tag = "PRIVILEGED" only on logs whose user name exists in the list.

Field copy / alias: $add (with Key Field)

"Don't look anything up, just copy the value from Key Field into Modify Field."

Example: Duplicate UserName into another field

Result: Source.AccountName = Source.UserName (verbatim copy). The bucket table is not consulted.

Write the bucket description: $add $description

"If the key exists in the table, write the bucket's own Description field into the target field."

Useful for tagging a log with the description of the bucket that enriched it. The text written is the Description entered in the bucket's Definition section.

Example: Label a log with the matching bucket's description

Result: If Source.UserName is in the "VIP Users" list, Source.MatchedBucket = "VIP Users".

3. Quick reference: "I want X, which template do I use?"

4. Common mistakes

$add $value and $value

In version 6.4.121, $add $value performs the same table lookup as $value. It does not copy the Key Field.

Example:

What happens: The lookup writes the table value to Source.DepartmentName when the field is empty.

Recommended form: use $value on simple buckets, or $value[ColumnName] on multi-column buckets. This syntax states the lookup clearly.

❌ Using $value[value] on a simple bucket

Static and LDAP/AL buckets store one plain string per key, not an object. In those buckets $value[value] or $value[anyName] writes nothing, because the column-extraction logic expects an object. The only exception is when the name in brackets is exactly the Key Field (for example $value[Source.UserName] with Key Field Source.UserName): then the Key Field's own value is copied for keys found in the table.

Correct form: on simple buckets always use plain $value (no brackets). Use $value[Field] only when the lookup result has that field, such as in a TI or STIX list or an API bucket.

❌ Wrong Key Field name

If the field you put in Key Field does not exist in the incoming log (wrong case, missing parent path), the modifier silently does nothing. Watch out for case-sensitive differences such as Source.UserName versus Source.username. Field names are case-sensitive, but the values looked up in LDAP/AL buckets are matched case-insensitively, so Ahmet and ahmet find the same entry.

5. How to verify your modifier works

To test:

1. After saving the bucket, open the Search page
2. Find a recent event that should trigger the bucket (e.g. search for Source.UserName:* over the last 15 minutes)
3. Inspect the event's detail view and check that the Modify Field is populated with the value you expect

If the Modify Field is empty:

• Is the key actually in the bucket table? (For Static buckets check the list entries; for LDAP check that the sync has run.)
• Is the Key Field name spelled correctly?
• Is the template correct? (See section 4.)
• Could the bucket's Match Conditions be filtering out the log?

If the Modify Field keeps a value you did not expect, check whether the log already carried that value before the bucket ran: $value lookups never overwrite a filled field. If it contains a copy of the Key Field rather than the table value, check whether the template is plain $add. Use $value for a table lookup.

6. Summary: three golden rules

1. On simple buckets (Static, LDAP/AL): use plain $value.
2. For multi-field lookup results (TI or STIX list, API bucket): use $value[ColumnName].
3. Prefer $value over $add $value. Both perform a table lookup in version 6.4.121.

For more advanced scenarios (conditional constants, writing the bucket description, multi-bucket lookups through the Buckets selection) see the sections above or contact our support team.