Bucket Modifier — Value Template Guide

In a bucket (Static, LDAP/AD, API, TI, Reference), 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.

1. How the Modifier works

Every modifier row has three main parts:

How it runs for each 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

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/AD 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 is designed for Threat Intelligence (TI), STIX and API buckets, since each key in those buckets typically holds multiple fields (IP, Country, ThreatType, Score, etc.).

Example — Pull the country from a TI list:

Result: If the TI list returns {IP: ..., Country: "TR", Score: 85, ...} for the key, only "TR" is written.

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

Constant value: $add '<text>'

"Don't check anything, always write this fixed text."

Example — Add a fixed tag to every 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 name of the bucket that enriched it.

Example — Label a log with the matching bucket's name:

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 (without brackets)

This form is a silent failure: the $value token is ignored and the template is interpreted as plain $add, which simply copies the Key Field into the target. No error is raised, but the expected table lookup does not happen.

Incorrect example:

What happens: Source.DepartmentName ends up holding the same content as Source.UserName (the username), instead of the value from the table.

Correct form: use $value on simple buckets, or $value[ColumnName] on multi-column buckets.

❌ Using $value[value] on a simple bucket

Static and LDAP/AD 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.

Correct form: on simple buckets always use plain $value (no brackets). Use $value[Field] only on multi-column buckets such as TI / STIX / API.

❌ 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.

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 contains a copy of the Key Field rather than the expected value — that is the classic $add $value (without brackets) mistake. Change the template to $value.

6. Summary — three golden rules

1. On simple buckets (Static, LDAP/AD): use plain $value.
2. On multi-column buckets (TI, STIX, API): use $value[ColumnName].
3. Never use $add $value without brackets — it does not do a lookup, it copies the field.

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