--- title: "Import Jira epics" description: "Import Jira epics into Deck as Projects, so delivery work can link to customer evidence." url: "/docs/agents/workflows/import-jira-epics" --- This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth. # Import Jira epics — agent workflow * **Use it when:** the user says "import our Jira epics", "bring the Jira roadmap into Deck" or "add our epics to Deck". * **Outcome:** the Jira epics that the user picked are Deck Projects, each linked to its epic. Nothing changes in Jira. * **Needs:** Deck MCP and Jira connected to Deck. Only organization admins connect integrations, in Settings → Integrations. Any member can import an epic. Imports spend no credits. ## 1. Probe Deck MCP Call `get_user_context`. This must be a real tool call. * 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop. * No Deck tools: fetch and follow [https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md](https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md). Stop this workflow until the tools work. ## 2. Check the Jira connection Call `explore_integrations` with `integration_type: "JIRA"`. Read the state. If the state is `not_connected` or `needs_attention`, tell the user that an organization admin must connect or reconnect Jira in Settings → Integrations. Give them the link from the result. Stop until Jira is connected. ## 3. Set the scope Ask the user which epics to look at. Typical answers are one Jira project key, a text search, or all epics. Deck uses Jira projects as containers for epics. A Deck Project links to one Jira epic, not to a Jira project. ## 4. List the epics Call `list_projects` with `importable_from: "jira"` and `kind: "epic"`. * Add `project_key` for one Jira project. * Add `query` for a Jira text search of epics. * Set `limit` to 50 or less. When `page_info.has_more` is true, call again with `cursor` set to `page_info.next_cursor`. * Do not add the Deck Project filters, such as `status` or `owner`. Deck returns `VALIDATION_ERROR` for them. A row with `already_linked_project_id` is already in Deck. Its `deck_url` opens it. Do not import it again. If the result has `status: "not_connected"`, go back to step 2. ## 5. Find Deck Projects that already cover an epic Call `list_projects` with no `importable_from`. Compare titles with the epic rows. When a Deck Project already covers an epic that is not linked, propose a link instead of an import. A link keeps the Deck Project and avoids a duplicate. ## 6. Show the plan and get a yes Show one table: epic key, title, status, owner, and "already in Deck", "link" or "import". Ask the user: * Which epics to import. * Which segments to apply. Call `explore_segments` for the segment IDs. * Which Deck initiative each epic belongs to, if any. Call `list_initiatives` for the IDs. To group epics under a new initiative, propose `create_initiative` and get a yes for it too. ## 7. Run the imports Run one call for each epic: * Import: `import_project_from_jira_or_linear` with `provider: "jira"`, `artifact_type: "epic"`, `external_id`, optional `initiative_id` and optional `segment_ids` (at most 20). Then call `explore_build_projects` with `result.project_id`. * Link: `link_project_jira_or_linear` with `project_id`, `external_url` (the Jira epic URL) and `fetch_from_provider: true`. To move an imported Project under an initiative later, call `set_project_initiative`. Handle these errors: * `ALREADY_LINKED`: the epic is already in Deck. Skip it and report it. For a link, `details.linked_project_id` names the Deck Project that has it. * `PROVIDER_NOT_CONNECTED`: go back to step 2. * `PROVIDER_ARTIFACT_NOT_FOUND` on a link: the epic URL is wrong. Ask the user for the correct URL. ## 8. Check the result Call `list_projects` with `external_provider: "jira"`. Run step 4 again. Each imported epic now shows its linked Deck Project. Report the epics that you imported, linked and skipped, each with its `deck_url`. ## Rules * Show the plan and get a yes before you call write tools. * Use only `external_id` values from `list_projects`. Never invent Jira epics. * Imports read Jira and create Deck records only. Deck tools do not create or change anything in Jira. To create an epic, use the Deck web app or your own Jira tools, then call `link_project_jira_or_linear`. * An identical import within 24 hours returns the first result and creates nothing new. * Deck refreshes the title, status and owner of linked epics daily. Deck does not fill or sync Jira start and target dates. Documents and evidence stay in Deck. * Quote Deck's numbers. Do not compute your own. * If the user has more than one Deck organization, call `select_organization` first and pass `org_id` on every call. ## Done when * Each epic that the user picked is imported, linked or reported as skipped, with a reason. * Each imported Project has a Deck link and the parent initiative that the user chose. * The user knows the next step: link customer evidence with the [roadmap evidence check](/docs/agents/workflows/roadmap-evidence-check). See also: [Jira](/docs/integrations/jira), [Projects](/docs/features/projects), [Initiatives](/docs/features/initiatives) and [Model Context Protocol](/docs/integrations/mcp). --- [View full sitemap](/docs/sitemap)