Transformations - Tracecat Docs

Add a field to an upstream result

Use FN.merge to combine an upstream result with new fields. Later objects in the list win on key conflicts:

- ref: enrich_alert
  action: core.transform.reshape
  args:
    value: ${{ FN.merge([ACTIONS.get_alert.result, {"triaged": True}]) }}

{
  "id": "A-001",
  "severity": "high",
  "triaged": true
}

Join a list of IDs to table rows

Look up one row per ID with for_each:

- ref: get_hosts
  action: core.table.lookup
  for_each: ${{ for var.host_id in TRIGGER.host_ids }}
  args:
    table: hosts
    column: id
    value: ${{ var.host_id }}

for_each returns one result per item, in input order. Build an ID-to-row mapping with FN.zip_map:

host_map: ${{ FN.zip_map(TRIGGER.host_ids, ACTIONS.get_hosts.result) }}

{
  "host_map": {
    "h-1": {"id": "h-1", "hostname": "api-1", "owner": "secops"},
    "h-2": {"id": "h-2", "hostname": "worker-1", "owner": "platform"}
  }
}

If you do not already have the IDs, project them off the rows with [*], then read an entry by key:

host_map: ${{ FN.zip_map(ACTIONS.get_hosts.result[*].id, ACTIONS.get_hosts.result) }}
host: ${{ ACTIONS.build_host_map.result["h-2"] }}

Dates and time windows

Current time as an ISO string. Pass "seconds" to drop microseconds:

local_now: ${{ FN.to_isoformat(FN.now(), "seconds") }}
utc_now: ${{ FN.to_isoformat(FN.utcnow(), "seconds") }}

{
  "local_now": "2026-08-24T17:20:00",
  "utc_now": "2026-08-24T21:20:00+00:00"
}

A search window starting N days ago:

start_time: ${{ FN.to_isoformat(FN.now() - FN.days(7), "seconds") }}
end_time: ${{ FN.to_isoformat(FN.now(), "seconds") }}

{
  "start_time": "2026-08-17T17:20:00",
  "end_time": "2026-08-24T17:20:00"
}

Midnight N days ago as a Python script:

- ref: window_start
  action: core.script.run_python
  args:
    inputs:
      days: 7
    script: |
      from datetime import datetime, time, timedelta

      def main(days):
          cutoff = datetime.now() - timedelta(days=days)
          return datetime.combine(cutoff.date(), time.min).isoformat()

Format, parse, and convert timezones. format_datetime takes a strftime pattern, to_datetime accepts ISO strings and epoch seconds, and set_timezone takes an IANA name:

day: ${{ FN.format_datetime(FN.now(), "%Y-%m-%d") }}
parsed: ${{ FN.to_isoformat(FN.to_datetime(TRIGGER.created_at), "seconds") }}
local: ${{ FN.to_isoformat(FN.set_timezone(TRIGGER.created_at, "America/New_York"), "seconds") }}

{
  "day": "2026-08-24",
  "parsed": "2026-08-10T09:30:00+02:00",
  "local": "2026-08-10T03:30:00-04:00"
}

Filter a list and count matches

A JSONPath filter returns the matching items as a list. When nothing matches it returns an empty list, never None:

high_alerts: ${{ TRIGGER.alerts[?(@.severity == "high")] }}
high_ids: ${{ TRIGGER.alerts[?(@.severity == "high")].id }}
no_matches: ${{ TRIGGER.alerts[?(@.severity == "critical")] }}

{
  "high_alerts": [{"id": "al-1", "severity": "high"}, {"id": "al-3", "severity": "high"}],
  "high_ids": ["al-1", "al-3"],
  "no_matches": []
}

Count matches with FN.length, and take a single value with FN.at:

high_count: ${{ FN.length(TRIGGER.alerts[?(@.severity == "high")]) }}
first_high_id: ${{ FN.at(TRIGGER.alerts[?(@.severity == "high")].id, 0) }}

{
  "high_count": 2,
  "first_high_id": "al-1"
}

FN.at indexes into a filter result; appending [0] to the path indexes into each matched value instead. See Common mistakes.

Rejoin mutually exclusive branches

When run_if sends a workflow down one of two branches, rejoin them with join_strategy: any on the downstream action. With the default all, a join with one skipped branch and one that ran is unreachable and the run fails:

- ref: block_ip
  action: core.http_request
  run_if: ${{ TRIGGER.severity == "high" }}
  args:
    url: https://firewall.example.com/block
    method: POST
    payload:
      ip: ${{ TRIGGER.src_ip }}
- ref: log_only
  action: core.transform.reshape
  run_if: ${{ TRIGGER.severity != "high" }}
  args:
    value:
      status: logged
- ref: update_case
  action: core.transform.reshape
  depends_on:
    - block_ip
    - log_only
  join_strategy: any
  args:
    value:
      outcome: ${{ ACTIONS.block_ip.result || ACTIONS.log_only.result }}

Referencing only the skipped branch’s result silently yields null; || reads whichever branch ran.

Insert rows without duplicates

Give the table a unique index, then insert with upsert: true:

- ref: store_iocs
  action: core.table.insert_rows
  args:
    table: seen_iocs
    rows_data: ${{ TRIGGER.iocs }}
    upsert: true

See Tables for creating the index and the constraints on it.

Apply a function to every item

Every FN function has a .map variant that applies it to each item in a list:

upper_tags: ${{ FN.uppercase.map(TRIGGER.tags) }}
timestamps: ${{ FN.to_isoformat.map(ACTIONS.whois.result.events[*].eventDate) }}

{
  "upper_tags": ["AUTH", "AUTH", "CRITICAL"],
  "timestamps": ["2015-03-20T00:00:00", "2030-01-01T00:00:00"]
}

Scalar arguments broadcast across the list, so ${{ FN.prefix.map(TRIGGER.tags, "tag-") }} prefixes every tag. Two lists of unequal length silently truncate to the shorter one: ${{ FN.add.map([1, 2, 3], [10, 20]) }} returns [11, 22]. core.transform.map applies a python_lambda to each item:

- ref: normalize_hostnames
  action: core.transform.map
  args:
    items: ${{ TRIGGER.hostnames }}
    python_lambda: "lambda h: h.strip().lower()"

See Common mistakes for the expression errors these recipes avoid.
See JSONPath for the full filter syntax used in the list recipes.
See Functions for the complete FN function reference.
See Python script for the core.script.run_python contract, dependencies, and SDK access.
See Tables for table schemas, column types, and search behavior behind the deduplication recipe.

​Add a field to an upstream result

​Join a list of IDs to table rows

​Dates and time windows

​Filter a list and count matches

​Rejoin mutually exclusive branches

​Insert rows without duplicates

​Apply a function to every item

​Related pages