Main Forge modules

• Jira issue panel for users who link, refresh, unlink, preview, and open Notion pages.
• Jira admin page for OAuth, Smart Connected Items, Notion Automations, and configuration.
• Jira workflow post function named Notion workflow action.
• Five-minute scheduled trigger for background synchronization.
• Jira triggers for issue updates, issue creation, comments, and attachments.
• Webtriggers for Notion OAuth callback and optional Notion webhook delivery.

System responsibilities

• Notion OAuth grants access only to pages and data sources selected in the page picker.
• Forge storage keeps Smart Connected Items, automations, issue links, page links, and sync state.
• Forge secret storage is used for OAuth credentials and tokens when available.
• Indexed Jira issue properties expose selected Notion metadata for JQL search.

Who should install and configure

A Jira site administrator should install the app and complete configuration. The app needs access to Jira work items, project configuration, Jira users, Forge storage, and external Notion endpoints.

1. Install or deploy the Forge app to the Jira Cloud site.
2. Confirm the Marketplace license status is active when licensing is enforced.
3. Open the app admin page from Jira administration.
4. Complete Notion OAuth and create at least one Smart Connected Item.

What installation adds to Jira

• An issue panel titled Notion Connector for Jira.
• An admin page with Smart Connected Items, Notion Automations, and Configuration tabs.
• A workflow post function named Notion workflow action.
• Indexed issue metadata under the notionConnectorMetadata issue property.
• Background jobs and triggers that run as the app.

Create the public connection

1. Create a Notion public connection named Notion Connector for Jira.
2. Deploy or tunnel the Forge app and run forge webtrigger.
3. Copy the URL for notion-oauth-callback.
4. Paste that URL into the Notion OAuth redirect URI field.
5. Copy the OAuth client ID and client secret for the Jira admin page.

Required Notion capabilities

• Read content.
• Update content.
• Insert content.
• Read comments.
• Insert comments.
• User info only if future marketplace copy or mappings need user display names.

Step 1: scope and source

• Name the Smart Connected Item.
• Choose Display, 1 Way, 2 Way, or Custom Sync per Mapping.
• Select the Jira project and issue type where the item should appear.
• Choose a Notion data source or Notion page.
• Select Notion properties to preview in the issue panel.

Step 2: mappings and automation

• Map Jira fields to Notion properties.
• Choose field owners when using Custom Sync per Mapping.
• Enable status synchronization and optional status overrides.
• Enable conditional rules, auto-create, comments sync, and attachment sync.
• Save the item and monitor latest sync state in the admin table.

Notion values supported for display and sync

• Title and rich text become plain text.
• Number, checkbox, date, URL, email, and phone values are normalized.
• Select, multi-select, and status use option names.
• People values use Notion names or IDs.
• Formula, rollup, created time, edited time, created by, edited by, and unique ID are read for display.

Jira field handling

• Description and textarea-style fields are written as Atlassian Document Format.
• Labels become normalized string arrays.
• Number, date, datetime, boolean, option, priority, component, and version field shapes are handled.
• Complex Jira objects are converted to display names, values, email addresses, or compact JSON fallback text.

Default behavior

Admins choose a Notion status or select property. By default, the connector matches status names across systems, including common equivalents such as To Do, In Progress, and Done.

Optional overrides

Use overrides when the names differ. For example, a Notion value named Complete can map to a Jira transition whose target status is Done.

Rule ingredients

• A Notion property to evaluate.
• An operator: equals, not equals, is empty, is not empty, or contains.
• A value, when the selected operator needs one.
• A Jira status to use when the condition is met.
• An optional fallback status when the condition is not met.

Where rules apply

Rules are evaluated during Notion-to-Jira sync and auto-create checks. They can steer a linked Jira issue into a configured status and can also decide whether unmatched Notion pages should still create Jira issues.

Jira to Notion

Jira comment events create Notion page comments when the linked Smart Connected Item has comments sync enabled. The connector includes the Jira author display name when available.

Notion to Jira

Scheduled sync and manual refresh can copy eligible Notion page comments into Jira. The app reads comments in pages and stops at the configured sync limit.

Jira to Notion

Jira attachment events download the attachment, upload it through the Notion File Upload API, and add a Notion page comment with the uploaded file and connector marker.

Notion to Jira

Scheduled sync and manual refresh inspect Notion file properties, file-like blocks, and comment attachments. Fetchable files are attached to the linked Jira issue and a Jira notice comment is added.

Supported triggers

• When a Jira issue is created.
• When a Jira issue reaches a selected workflow status.

Created Notion page options

• Create in a selected Notion data source.
• Use a selected Notion template or create a blank page.
• Set the Notion title property from a template such as {{issue.summary}}.
• Optionally add a Jira comment containing the created Notion page link.

What Jira users see

• Smart Connected Items that apply to the current Jira project and issue type.
• Warnings when Notion OAuth, licensing, scheduled sync, or link sync needs attention.
• The linked Notion page title, preview properties, and last sync timestamp.
• Actions to refresh, open in Notion, unlink, or search and link a page.

What determines visibility

The panel only shows enabled Smart Connected Items that match the current issue's Jira project key and issue type ID. If no matching item exists, the panel shows an empty state.

When they are created

Auto-managed links are created when the connector creates Jira issues from Notion pages, when Notion Automations create pages for Jira events, or when workflow post functions create and link Notion pages.

How users should treat them

Auto-managed links represent automation-owned relationships. Users should use the issue panel to inspect or open the Notion page, while admins adjust the responsible automation or Smart Connected Item when behavior needs to change.

Stored configuration

• OAuth status, workspace identity, redirect URI, and authorization settings.
• Smart Connected Item definitions and sync state.
• Notion Automation definitions and created page links.
• Issue-to-page link records and page-to-issue reverse lookup records.
• Comment, attachment, field, status, error, and webhook processing state.

Secret and API handling

• Client IDs, client secrets, access tokens, and refresh tokens use Forge secret APIs where available.
• The Notion client sends Notion-Version: 2026-03-11 on API calls.
• Expired access tokens are refreshed when Notion returns an authorization failure and a refresh token exists.
• Notion rate-limit responses with Retry-After are retried with bounded backoff.

Jira and Forge scopes

• read:jira-work for reading issues, fields, comments, and attachments.
• write:jira-work for updating issues, transitions, comments, and attachments.
• manage:jira-project and manage:jira-configuration for project and admin setup.
• read:jira-user for user display context.
• storage:app for Forge app storage and sync state.

External fetch domains

• https://api.notion.com and https://www.notion.so.
• https://file.notion.so, https://attachment.notion.so, and https://secure.notion-static.com.
• Configured S3 domains used by Notion-hosted file URLs.
• Additional signed file hosts may need to be added for specific Notion workspaces.