TaskPort Documentation

Current status

This documentation supports an active ArdSaor Marketplace app. Start from the product page for current positioning and Marketplace links, then use this guide for operating details.

Supported Products

Jira Software (Cloud)
Jira Service Management (Cloud)
Jira Work Management (Cloud)
Works in both Company‑managed and Team‑managed projects
Notion: any workspace where the TaskPort integration is authorized

Permissions & Data

Required scopes: read:jira-work, write:jira-work, read:jira-user, storage:app
Data handled: Notion titles/properties and (for Smart Mode) relevant page content to draft Jira fields; Jira project metadata and created issue keys
Hosting: Atlassian Forge app runtime with documented backend egress to ArdSaor Core for Notion authorization, encrypted token handling, and content resolution
Storage: Forge app storage holds connection status, template mappings, filter presets, run history, audit logs, and duplicate-tracking metadata. ArdSaor Core stores encrypted Notion tokens and short-lived Notion resolution cache rows.

Installation

Install TaskPort from the Atlassian Marketplace (Jira Cloud).
After install, open TaskPort — Create Jira Issues from Notion from the Jira Apps menu.
First-time setup: open TaskPort Admin (advanced) from the Apps menu to connect Notion and set your defaults.

First-Time Setup: Connect Notion

Before creating Jira issues, you must connect TaskPort to your Notion workspace. Follow these steps:

Step 1: Open TaskPort Admin (advanced)

In Jira, click the Apps menu in the top navigation bar.
Select TaskPort Admin (advanced) from the dropdown.
You will see the TaskPort Setup page with a "Connect workspace" button.

Step 2: Authorize TaskPort in Notion

Click the Connect workspace button.
A new window opens showing the Notion authorization page.
Select your Notion workspace from the dropdown (if you have multiple).
Choose which pages and databases TaskPort can access:
- Select specific pages/databases you want to create Jira issues from, or
- Select all pages if you prefer broader access.
Click Allow access to complete the connection.
Close the Notion window and return to Jira. TaskPort will automatically detect the connection.

Step 3: Verify Connection

The TaskPort Admin (advanced) page should now show "Connected" status with your workspace name.
If the status doesn't update, click the Refresh button.

How to Get a Notion Link

TaskPort requires a Notion link to create Jira issues. Here's how to get one:

For a Notion Page

Open the Notion page you want to convert to a Jira issue.
Click the Share button in the top-right corner.
Click Copy link to copy the page URL.
Paste this link into TaskPort's "Notion link" field.

For a Notion Database

Open the Notion database you want to create Jira issues from.
Click the ... (three dots) menu in the top-right corner.
Select Copy link from the menu.
Paste this link into TaskPort's "Notion link" field.

Share with TaskPort Integration

If TaskPort cannot read your page or database, you may need to share it with the integration:

In Notion, open the page or database.
Click the ... (three dots) menu in the top-right corner.
Click Connections (or find it under "Add connections").
Search for "TaskPort" and select it.
The TaskPort integration can now read this content.

Prepare Notion Database (Optional)

For the best experience with bulk imports, set up your Notion database with these recommended properties:

Title (required): The name/summary for each Jira issue.
Description (rich text): Detailed content for the Jira issue description.
Labels (multi-select): Tags that map to Jira labels.
Assignee (People, optional): Map to Jira assignees if names match.
Ready (checkbox) or Status (select): Use to gate which rows are ready to create.
Jira Key (text, optional): If you already maintain Jira keys in Notion, TaskPort can read them for duplicate detection. TaskPort does not write created issue keys back into Notion.

Quick Start (Smart Mode)

Open TaskPort from Jira’s Apps menu.
Connect your Notion workspace when prompted.
Paste a Notion page link (or a small database with ≤25 items after filters).
Select the Jira project and issue type (defaults can be set in Admin).
TaskPort drafts Title and Description automatically; edit anything before sending.
Click “Create issue” to submit. Links to created issues are shown immediately.

Notes: Smart Mode uses AI to draft fields for small inputs; you can always overwrite or turn off the AI suggestion per item.

Bulk Mode (Databases)

Paste a Notion database link. TaskPort estimates the row count and switches to Bulk Mode when more than 25 items are detected.
Choose a gating rule (Ready checkbox or Status value) so only ready rows are auto‑selected.
Add filters (status, select, multi‑select, checkbox, or text) to narrow scope. Runs are capped at 100 items per batch.
Edit templates for Title, Description, and Labels using your Notion properties; save them for reuse per database/project/issue type.
Click “Preview” to see the rendered titles/descriptions/labels before creating. Export the preview to CSV if you need offline review.
Start the bulk run. Progress shows created/skipped/failed counts with live updates.
If there are more rows, choose “Continue next batch”; if some rows failed, use “Retry failed only”.

Templates & Tokens

Use template fields to control how Title, Description, and Labels are built from Notion properties.
Templates are saved per database, project, and issue type so teams can reuse consistent mappings.
An optional “AI polish” toggle can tidy bulk titles locally without changing your deterministic template.

Previews, Dedupe & Safety

Preview rows show the exact text and labels that will be sent to Jira; rerun preview after changing templates, filters, or gating.
Rows already linked to Jira are flagged as duplicates and skipped by default.
Not Ready rows stay visible with reasons so you can adjust filters or gating rules.
CSV export provides an audit-friendly snapshot of the preview.

Run History & Monitoring

Recent runs appear in the Run Log with status, counts, and timestamps.
Bulk runs are chunked; you can leave the page and return to continue where you left off.
Telemetry highlights Smart vs. Bulk usage and helps spot slowdowns or failures.

Best Practices

Use Smart Mode for one-off pages; switch to Bulk after you have a clean template and filters.
Start bulk runs with a Ready gate and a narrow filter, then widen as needed.
Save templates once per database/project so titles and labels stay consistent.
Refresh previews after Notion changes to avoid stale mappings.

Troubleshooting

Cannot connect Notion / "App is not authorized" error

If you see an error about authorization when first setting up, confirm the Forge install lifecycle has completed and refresh the TaskPort page. TaskPort tenant binding is created through the install lifecycle, not by Notion connect/start.
Ensure you authorized TaskPort for the correct Notion workspace and the database is shared with it.
If the error persists, try disconnecting and reconnecting from TaskPort Admin (advanced).

Nothing shows after pasting a link

Use a public or shared Notion link (Copy Link). Private links without sharing cannot be read.
Share the page/database with the TaskPort integration via Notion's Connections menu.

"Create instantly" button is disabled

You must paste a Notion link before the button becomes active.
Select a Jira project from the dropdown.
Ensure your Notion workspace is connected (check TaskPort Admin (advanced)).

Bulk run stops early

Check the Run Log for skipped/failed rows and retry failed only. Reduce filters if you hit the 100-item cap.

Duplicates appear

Use TaskPort's duplicate preview and avoid selecting rows that already show a Jira key or existing issue association. A Jira Key column is optional if your team already maintains it in Notion.

Security & Privacy

TaskPort is not a Runs on Atlassian/no-egress app. It runs in Forge and uses ArdSaor Core egress for Notion OAuth, token storage, and content resolution.
Only the minimum needed Notion fields and page content are processed to create issues selected by the user.
Operational logs are designed to avoid raw Notion page bodies, rich text metadata, Jira descriptions, secrets, and opaque Notion pagination cursors.
Stored data is limited to configuration, templates, filter presets, run history, audit logs, encrypted Notion tokens, duplicate-tracking metadata, and short-lived Core resolution cache rows; Notion page bodies are not persisted to the shared Core cache.
Uninstall stops future processing and triggers a Core tenant purge for encrypted Notion tokens and short-lived cache rows. Forge storage follows the documented retention/deletion support process until automatic Forge-storage purge is implemented and verified.

FAQ

Does TaskPort work with Jira Service Management?

Yes. It supports Jira Software, Service Management, and Work Management (Cloud).

Can I override AI suggestions?

Yes. Smart Mode drafts fields but you can edit before creating. Bulk templates are fully deterministic, with optional local AI polish for titles.

Will TaskPort change anything in Notion?

No. It reads selected Notion content and writes approved Jira issues only. It does not stamp Jira keys back into Notion or run a two-way sync.

How are duplicates avoided?

TaskPort tracks Notion page IDs and existing Jira keys; duplicates are flagged in preview and skipped unless you explicitly select them.

Support

Need help or have a feature request? Contact us via the Marketplace listing support link. Include your Jira site URL, the Notion link you were using, and whether you were in Smart or Bulk mode.

TaskPort for Jira — Documentation