Creating Signal Mapping Rules
Getting Started
There are two ways to create a rule:
From the Signal Queue (recommended):
- Navigate to Signal Mapping > Signal Queue
- Find a signal group in the Unmapped tab and click Create Rule
- The form pre-fills with the signal's source, event type, and matching conditions
From scratch:
- Navigate to Signal Mapping > Signal Rules
- Click Create New Rule
Creating from the Signal Queue is faster because TrailSpark auto-detects the signal pattern and pre-fills the form.
Step 1: Name This Signal
| Field | Required | Description |
|---|---|---|
| Rule Name | Yes | A descriptive name shown in activity timelines (e.g., "Downloaded Guide", "Viewed Pricing Page") |
| Signal Type | Yes | Category for scoring: Form Fill, Page View, or Product Activity |
| Description | No | Optional context about this signal, visible to the AI during evaluations |
| High Intent Signal | No | Toggle on to re-evaluate leads immediately when this signal is received, even if the lead was recently scored |
When creating from the Signal Queue, the rule name is auto-populated from the signal pattern. You can edit it to be more descriptive.
Step 2: Identify the Lead
Map fields from the signal payload to lead records. Each row shows a lead field, a dropdown of available paths from the payload, and an extract button to preview sample values.
Identifying fields are marked with (ID). You must map at least one:
| Field | Purpose |
|---|---|
| email (ID) | Primary lead identifier |
| map_id (ID) | Internal mapping ID |
| cdp_id (ID) | CDP/anonymous tracking ID |
| crm_id (ID) | CRM record ID |
| product_user_id (ID) | Product user ID |
| title | Job title |
At least one identifying field must be mapped for the signal to create or update a lead. cdp_id alone is not sufficient — it must be paired with another identifier.
Step 3: Review
This section shows the matching conditions that determine which incoming signals this rule will process.
When creating from the Signal Queue, conditions are pre-filled based on the signal pattern (e.g., event = "Form Filled", path = "/pricing"). A summary displays under "This rule will match signals where:" with each condition listed.
Preview Matches — Click to check how many existing signals in your queue match the current conditions.
Process existing signals — Toggle on to apply this rule to signals already in the queue. A background job processes matching signals after save.
Click Create Rule to save. The rule becomes active immediately for future incoming signals.
Advanced: Editing Matching Conditions
For most rules created from the Signal Queue, the pre-filled conditions work without modification. If you need to customize them, expand the Advanced: Edit matching conditions section in the Review step.
Advanced mode uses exact payload paths. If the signal source changes their payload structure, the rule may stop matching. Only modify conditions if the pre-filled defaults don't meet your needs.
Condition Builder
The condition builder lets you create rules with AND/OR logic:
- Add Condition — Select a field from the dropdown, choose an operator, and enter a value
- Add Condition Group — Create nested groups for complex logic (e.g., "match A AND (B OR C)")
- Match operator — Choose whether conditions in each group use ALL (AND) or ANY (OR) logic
Available operators:
| Operator | Description |
|---|---|
| equals | Exact match |
| contains | Contains substring |
| does not equal | Inverse match |
| does not contain | Does not contain substring |
| starts with | Begins with value |
| ends with | Ends with value |
| exists / does not exist | Field is present or absent in the payload |
| greater than / less than | Numeric comparison |
Field References
When selecting fields in the condition builder, you can use:
- Payload paths — Direct paths like
payload.event,payload.properties.form_name - Context fields — Smart fields like
context.page_urlthat search multiple payload locations automatically
Troubleshooting
Rule not matching signals — Use the Preview function to test conditions. If you customized conditions in Advanced mode, verify the field paths match your actual payload structure.
"Identifying field required" error — Map at least one identifying field (email, map_id, crm_id, or product_user_id) in Step 2.
Signals still in queue after rule creation — Enable "Process existing signals" in Step 3, or trigger manual processing from Signal Explorer.