# Creating Signal Mapping Rules

> Source: https://docs.trailspark.ai/docs/creating-signal-mapping

## Getting Started

There are two ways to create a rule:

**From the Signal Queue (recommended):**

1. Navigate to **Signal Mapping** > **Signal Queue**
2. Find a signal group in the **Unmapped** tab and click **Create Rule**
3. The form pre-fills with the signal's source, event type, and matching conditions

**From scratch:**

1. Navigate to **Signal Mapping** > **Signal Rules**
2. 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 |

> [!TIP]
> 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 |

> [!NOTE]
> 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.

> [!WARNING]
> 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:

1. **Add Condition** — Select a field from the dropdown, choose an operator, and enter a value
2. **Add Condition Group** — Create nested groups for complex logic (e.g., "match A AND (B OR C)")
3. **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_url` that 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.

## Next Steps

- [Editing Signal Mapping Rules](/docs/editing-signal-mapping)
- [Signal Explorer](/docs/signal-explorer)
- [Signal Groups](/docs/signal-groups)