ArdSaor

TaskPort for Jira — Documentation

TaskPort turns Notion pages and databases into Jira issues with smart drafting for small inputs and deterministic bulk runs for large ones.

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: Built on Atlassian Forge
  • Storage: Minimal app storage for connection status, template mappings, filter presets, run history, and audit logs

Installation

  1. Install TaskPort from the Atlassian Marketplace (Jira Cloud).
  2. After install, open TaskPort — Create Jira Issues from Notion from the Jira Apps menu.
  3. 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)

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

Step 2: Authorize TaskPort in Notion

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

Step 3: Verify Connection

  1. The TaskPort Admin (advanced) page should now show "Connected" status with your workspace name.
  2. 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

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

For a Notion Database

  1. Open the Notion database you want to sync.
  2. Click the ... (three dots) menu in the top-right corner.
  3. Select Copy link from the menu.
  4. 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:

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

Prepare Notion Database (Optional)

For the best experience with bulk syncs, 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 sync.
  • Jira Key (text): TaskPort can write the created issue key here for traceability.

Quick Start (Smart Mode)

  1. Open TaskPort from Jira’s Apps menu.
  2. Connect your Notion workspace when prompted.
  3. Paste a Notion page link (or a small database with ≤25 items after filters).
  4. Select the Jira project and issue type (defaults can be set in Admin).
  5. TaskPort drafts Title and Description automatically; edit anything before sending.
  6. 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)

  1. Paste a Notion database link. TaskPort estimates the row count and switches to Bulk Mode when more than 25 items are detected.
  2. Choose a gating rule (Ready checkbox or Status value) so only ready rows are auto‑selected.
  3. Add filters (status, select, multi‑select, checkbox, or text) to narrow scope. Runs are capped at 100 items per batch.
  4. Edit templates for Title, Description, and Labels using your Notion properties; save them for reuse per database/project/issue type.
  5. Click “Preview” to see the rendered titles/descriptions/labels before creating. Export the preview to CSV if you need offline review.
  6. Start the bulk run. Progress shows created/skipped/failed counts with live updates.
  7. 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, close the page and try again after a few seconds. TaskPort automatically registers your workspace on first use.
  • Ensure you authorized TaskPort for the correct 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

  • Make sure your database has a Jira Key column and that rows are marked Ready only once per issue.

Security & Privacy

  • Runs entirely on Atlassian Forge; TaskPort does not host external servers.
  • Only the minimum needed Notion fields and page content are processed to create issues.
  • Stored data is limited to configuration, templates, run history, and audit logs; no Notion page bodies are persisted for bulk runs.

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 Notion content and writes Jira issues only.

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.