State Mappings
State mappings provide a specialized way to send alerts when work items transition between specific workflow states. While a regular trigger using the state_changed event fires on every state change, a state mapping lets you target a precise transition --- for example, alerting reviewers only when a work item moves from "In Progress" to "In Review".
State mappings are managed at the workspace level under Workspace Settings > Reminders > State Mappings.
What state mappings are
A state mapping is a rule that binds a specific state transition to a notification template and a set of recipients. It consists of four components:
| Component | Required | Description |
|---|---|---|
| From state | Optional | The state the work item is leaving. If omitted, the mapping matches any source state. |
| To state | Yes | The state the work item is entering. |
| Template | Yes | The email template used to format the notification. |
| Recipients | Yes | Who receives the notification (assignees, creator, subscribers, or specific users). |
When a work item's state changes, the system evaluates all active state mappings. If the transition matches a mapping's from/to state combination, the notification is dispatched to the configured recipients through their enabled channels.
From state behavior
The "from state" field is optional and supports two modes:
- Specific state: The mapping fires only when the work item is leaving this exact state. For example, "In Progress" to "In Review" fires only for that specific transition.
- Any state (blank): The mapping fires whenever the work item enters the "to state" regardless of what state it was in before. For example, "Any" to "Done" fires whether the item was in "In Progress", "In Review", or "Blocked".
Creating a state mapping
Step 1: Open state mappings
- Navigate to Workspace Settings > Reminders > State Mappings.
- Click Create Mapping.
Step 2: Configure the transition
- From state --- Select a specific source state from the dropdown, or leave it blank to match any source state.
- To state --- Select the destination state. This field is required.
The dropdown lists all states defined across your workspace's projects. States are grouped by project for clarity.
Step 3: Select a template
Choose the email template for the notification. The State Change template is the recommended default, but you can use any template that fits your notification style.
Step 4: Define recipients
Select who should receive the notification:
| Recipient type | When to use |
|---|---|
| Assignees | The person responsible for the work item should know about the transition |
| Creator | The requester should be informed about progress |
| Subscribers | All stakeholders following the work item |
| Specific users | Designated reviewers, leads, or other roles who need to act on specific transitions |
You can combine multiple recipient types. Deduplication ensures each user receives only one notification per channel.
Step 5: Save and activate
Click Save. The mapping is created in an active state and begins evaluating state transitions immediately.
Use cases
State mappings are particularly effective for workflows with well-defined review gates, handoff points, or escalation paths.
Code review notification
Transition: Any state to "In Review" Recipients: Specific users (designated code reviewers) Template: State Change
This mapping notifies your review team whenever a work item is ready for review, regardless of which state it came from (development, bug fix, hotfix, etc.).
QA handoff
Transition: "In Review" to "QA Testing" Recipients: Specific users (QA team members) Template: State Change
When code review is complete and the item moves to QA, the testing team is automatically notified.
Deployment readiness
Transition: "QA Testing" to "Ready for Deploy" Recipients: Specific users (DevOps lead, Release manager) Template: State Change
The deployment team learns when items have passed QA and are queued for release.
Blocked item escalation
Transition: Any state to "Blocked" Recipients: Assignees, Creator, Specific users (Project manager) Template: State Change
When a work item becomes blocked, the assignee, creator, and project manager are all notified so the blocker can be resolved quickly.
Completion notification to stakeholders
Transition: Any state to "Done" Recipients: Creator, Subscribers Template: Issue Completed
When a work item reaches the final "Done" state, everyone who requested or follows the item is notified.
Managing state mappings
Viewing mappings
The State Mappings page displays all configured mappings in a table:
| Column | Description |
|---|---|
| From state | Source state (or "Any") |
| To state | Destination state |
| Template | Template name |
| Recipients | Summary of recipient types and specific users |
| Status | Active or Disabled |
| Created | Creation date |
Editing a mapping
- Click on any mapping row to open the editor.
- Modify the from state, to state, template, or recipients.
- Click Save.
Changes apply to future state transitions. Already-dispatched notifications are not affected.
Enabling and disabling
Toggle the status switch in the table to enable or disable a mapping without deleting it. Disabled mappings are preserved but do not evaluate transitions.
Deleting a mapping
Click the delete icon and confirm. Deletion is permanent.
WARNING
Deleting a state mapping is irreversible. If you might need the mapping again, disable it instead of deleting it.
Relationship with regular triggers
State mappings and state_changed triggers are complementary. They serve overlapping but distinct purposes:
| Feature | State mapping | state_changed trigger |
|---|---|---|
| Granularity | Specific from/to state pair | Any state change (with optional condition filter) |
| Configuration | Dedicated UI with state dropdowns | General trigger form with event type selection |
| Conditions | Implicit (state transition is the condition) | Explicit condition fields (project, priority, label, etc.) |
| Best for | Known workflow transitions | Broad state change monitoring with additional filters |
Both can coexist. If a state transition matches both a state mapping and a state_changed trigger, both fire independently. The recipient deduplication system ensures users do not receive duplicate notifications per channel.
TIP
Use state mappings when you have a clear workflow with defined handoff points. Use state_changed triggers when you need to combine state awareness with other conditions like priority or labels.
Cross-project state mappings
State mappings apply across all projects in the workspace. If different projects use different state names, a mapping only fires for projects that have the matching state.
For example, if you create a mapping for "Any to In Review", it fires when:
- Project A transitions a work item to its "In Review" state.
- Project B transitions a work item to its "In Review" state.
- Project C is unaffected if it does not have an "In Review" state.
TIP
When designing state mappings, use consistent state names across projects to ensure mappings work predictably. See Work item states for guidance on standardizing states.
Limits
| Limit | Value |
|---|---|
| Maximum state mappings per workspace | 50 |
| Maximum specific user recipients per mapping | 50 |
| Maximum recipient types per mapping | All 4 types can be combined |
Performance considerations
- State mappings are evaluated on every state change. Keep the number of active mappings reasonable.
- Mappings with "Any" as the from state are evaluated more frequently than specific from-state mappings.
- If you have many mappings targeting the same to-state, consider consolidating them into a single mapping with combined recipients.
- State mapping evaluation happens after regular trigger evaluation. Both systems process independently.
Frequently asked questions
Can I create a mapping that fires on any state to any state? No. The "to state" field is required. A mapping with "Any" as the from state and a specific to state is the broadest configuration possible. If you need to be notified on every state change regardless of the destination, use a state_changed trigger instead.
What happens if I rename a state after creating a mapping? The mapping references the state by its internal ID, not its display name. Renaming a state does not break existing mappings.
Can I use state mappings with state groups? State mappings work with individual states, not state groups. If you want a mapping to fire when entering any state in a group (e.g., any "Completed" group state), create separate mappings for each state in the group.
Related pages
- Alerts overview --- Introduction to the alert system
- Triggers --- Configure event-based notification triggers
- Templates --- Email template catalog and variable reference
- Notification preferences --- Per-user channel configuration
- Alert history --- View send logs and delivery status
- Best practices --- Design an effective notification strategy
- Work item states --- Configure workflow states for projects