Notion Integration
GuideMode integrates with Notion to track work items stored in Notion databases. This integration enables flexible column mapping, team-based organization, and syncs Notion database entries as issues in GuideMode.
What You Get
Section titled “What You Get”- Multi-Database Support: Connect multiple Notion databases to GuideMode
- Flexible Column Mapping: Map any Notion property to GuideMode fields
- Team-Based Organization: Organize issues by team using Notion properties
- Issue Tracking: Sync Notion database entries as trackable issues
Prerequisites
Section titled “Prerequisites”Before setting up the Notion integration, you’ll need:
- A Notion account with access to the databases you want to sync
- Admin permissions in your GuideMode tenant
Setup Overview
Section titled “Setup Overview”The Notion integration requires:
- OAuth Connection - For authentication and database access
- Database Selection - Choose which databases to sync
- Column Mapping - Configure how Notion properties map to GuideMode fields
Step 1: Connect with Notion
Section titled “Step 1: Connect with Notion”- Navigate to Settings > Integrations > Notion in GuideMode
- Click Connect with Notion
- In Notion’s authorization screen, select the pages and databases to share with GuideMode
- Click Allow access
- You’ll be redirected back to GuideMode once connected
Important: Only databases you explicitly share during authorization will be visible to GuideMode. You can update access later in Notion’s settings.
Step 2: Select Databases
Section titled “Step 2: Select Databases”After connecting, configure which databases to sync:
- Go to Settings > Integrations > Notion
- Click the Databases tab
- You’ll see all databases shared with GuideMode
- Click on a database to configure its mapping
Sample Data Preview
Section titled “Sample Data Preview”When configuring a database, GuideMode shows sample entries to help you understand the data structure and verify your mapping configuration.
Step 3: Configure Column Mapping
Section titled “Step 3: Configure Column Mapping”Each database requires column mapping to sync correctly. GuideMode needs to know how your Notion properties correspond to issue fields.
Required Mappings
Section titled “Required Mappings”Four fields must be mapped before sync can be enabled:
| Field | Purpose | Supported Notion Types |
|---|---|---|
| Title | Issue title | Title, Text |
| Status | Issue state (open/in_progress/closed) | Status, Select |
| Type | Issue category (feature/bug/chore/etc.) | Select |
| Team | Team assignment | Multi-select |
Optional Mappings
Section titled “Optional Mappings”| Field | Purpose | Supported Notion Types |
|---|---|---|
| Body | Issue description | Text, Rich text |
| Created At | When the issue was created | Date, Created time |
| Closed At | When the issue was closed | Date |
| Creator | Who created the issue | Person, Created by |
| Assignee | Who is assigned | Person |
Configuring Mappings
Section titled “Configuring Mappings”- Select a database from the Databases tab
- For each required field, select the corresponding Notion property
- Configure value mappings for Status, Type, and Team fields
- Click Save Mapping
Step 4: Configure Value Mappings
Section titled “Step 4: Configure Value Mappings”For Status, Type, and Team fields, you need to map Notion values to GuideMode categories.
Status Value Mappings
Section titled “Status Value Mappings”Map your Notion status values to GuideMode canonical states:
| GuideMode State | Map Notion Values Like |
|---|---|
open |
Not Started, Backlog, To Do |
in_progress |
In Progress, In Review, Doing |
closed |
Done, Complete, Closed |
Type Value Mappings
Section titled “Type Value Mappings”Map your Notion type/category values to GuideMode canonical issue types:
| GuideMode Type | Map Notion Values Like |
|---|---|
feature |
Feature, Enhancement, Story |
bug |
Bug, Defect, Fix |
chore |
Chore, Task, Maintenance |
discovery |
Spike, Research, Discovery |
incident |
Incident, Urgent, Emergency |
other |
Any unmatched values |
Team Value Mappings
Section titled “Team Value Mappings”Map your Notion team values to existing GuideMode teams. This allows you to organize issues by team based on a multi-select property in Notion.
Step 5: Enable Sync
Section titled “Step 5: Enable Sync”Once all required fields are mapped:
- GuideMode validates your configuration
- The Enable Sync toggle becomes available
- Toggle sync on for the database
- Click Sync to perform the initial sync
Validation
Section titled “Validation”Before enabling sync, GuideMode validates that:
- All four required fields have property mappings
- Status, Type, and Team fields have value mappings configured
- The mapped properties exist and are accessible
If validation fails, you’ll see guidance on what needs to be configured.
Sync Operations
Section titled “Sync Operations”Sync Types
Section titled “Sync Types”| Sync Type | What It Does |
|---|---|
| Full | Syncs all enabled databases and their issues |
| Databases | Discovers and syncs database metadata only |
| Issues | Syncs issues for all enabled databases |
Triggering a Sync
Section titled “Triggering a Sync”- Go to Settings > Integrations > Notion
- Click the Org Sync tab
- Click Sync to start a full sync
- Monitor progress in real-time
Sync Progress
Section titled “Sync Progress”During sync, you’ll see:
- Current step (databases, issues)
- Number of items processed
- Any errors encountered
You can cancel a running sync if needed.
Managing Multiple Databases
Section titled “Managing Multiple Databases”GuideMode supports syncing multiple Notion databases:
- Each database has independent mapping configuration
- Enable/disable sync per database
- Different mapping rules for different databases
- All synced issues appear in your GuideMode projects
Troubleshooting
Section titled “Troubleshooting”Cannot See Databases
Section titled “Cannot See Databases”- Ensure databases were shared with GuideMode during OAuth authorization
- To add more databases, go to Notion > Settings > Connections > GuideMode
- Re-authorize if needed by disconnecting and reconnecting
Validation Fails
Section titled “Validation Fails”- Verify all four required fields are mapped (Title, Status, Type, Team)
- Ensure value mappings are configured for Status, Type, and Team
- Check that the selected Notion properties exist and have values
Sync Fails
Section titled “Sync Fails”- Review the error message in sync status
- Verify your Notion connection is still active
- Check that the database and its properties still exist
- Ensure you have access to all shared databases
Issues Not Appearing
Section titled “Issues Not Appearing”- Verify sync is enabled for the database
- Trigger a manual sync from Settings > Integrations > Notion
- Check that entries match your mapping configuration
Incorrect Issue Data
Section titled “Incorrect Issue Data”- Review your column mappings in the database configuration
- Verify value mappings match your Notion property values
- Check sample data to ensure properties contain expected values
Limitations
Section titled “Limitations”Supported Property Types
Section titled “Supported Property Types”GuideMode supports most Notion property types for mapping:
- Title, Text, Rich text
- Select, Multi-select, Status
- Date, Created time, Last edited time
- Person, Created by, Last edited by
- Number, Checkbox, URL, Email, Phone
Formula, Relation, and Rollup properties have limited support.
One Workspace Per Tenant
Section titled “One Workspace Per Tenant”Each GuideMode tenant can connect to one Notion workspace. To change workspaces, disconnect the current connection first.
Manual Sync
Section titled “Manual Sync”Notion does not support webhooks for external integrations. Changes in Notion require manual sync to appear in GuideMode.
Related Documentation
Section titled “Related Documentation”Core Concepts
Section titled “Core Concepts”Analytics
Section titled “Analytics”- Delivery Flow - Issue metrics and cycle time
- How It Works - DX² methodology