diff --git a/docs/automations/custom-automations.md b/docs/automations/custom-automations.md index 0c3a52f4..70a554ee 100644 --- a/docs/automations/custom-automations.md +++ b/docs/automations/custom-automations.md @@ -156,14 +156,19 @@ Conditions let you filter which work items an automation acts on. You can combin Updates a field on the work item. -| Property | What you can do | -| ---------- | ---------------------------------------------------------------------- | -| Priority | Set, add, or remove a priority level (Urgent, High, Medium, Low, None) | -| State | Move the work item to a specific state | -| Assignees | Add or remove assignees | -| Labels | Add, remove, or replace all labels | -| Start date | Set, update, or remove the start date | -| Due date | Set, update, or remove the due date | +| Property | What you can do | +| ---------- | -------------------------------------------------------------------------------------------------- | +| Priority | Set, add, or remove a priority level (Urgent, High, Medium, Low, None) | +| State | Move the work item to a specific state | +| Assignees | Add or remove assignees | +| Labels | Add, remove, or replace all labels | +| Start date | Set, update, or remove the start date | +| Due date | Set, update, or remove the due date | +| Cycle | Assign the work item to a cycle, move it to a different cycle, or remove it from its current cycle | + +:::tip +When assigning a cycle, the cycle must belong to the work item's own project, and you cannot assign a work item to a cycle that has already ended. A work item can be in only one cycle at a time, so assigning a cycle moves the work item off any cycle it is currently in. +::: #### Add comment @@ -299,3 +304,5 @@ Some common things people use automations for. - **Contextual reminders.** Surface the right information at the right moment - for example, post an internal comment with a checklist when a work item enters "Ready for QA," or flag missing information when a work item is created without an assignee. - **Scheduled operations.** Run scripts on a timer to handle things that don't map to a single event - for example, sweep stale items weekly, sync data to an external tool nightly, or generate a status comment on open items every Monday morning. + +- **Sprint assignment.** Put work items into the right cycle automatically - for example, add a work item to the current cycle when its state changes to "In Progress," or remove it from its cycle when it moves to "Backlog." diff --git a/docs/core-concepts/issues/plane-query-language.md b/docs/core-concepts/issues/plane-query-language.md index a54643ba..7c94be09 100644 --- a/docs/core-concepts/issues/plane-query-language.md +++ b/docs/core-concepts/issues/plane-query-language.md @@ -5,7 +5,7 @@ description: Filter work items using text-based queries with Plane Query Languag # Plane Query Language (PQL) -Plane Query Language (PQL) lets you filter work items using text-based queries. Write structured expressions to quickly find exactly what you need. +Plane Query Language (PQL) lets you filter work items using text-based queries. Write structured expressions to quickly find exactly what you need, combine conditions with logic, call built-in functions, and sort and limit the results. ![PQL editor](https://media.docs.plane.so/issues/pql-editor.webp#hero) @@ -17,7 +17,7 @@ To switch to PQL mode, click **PQL** in the filter bar. When you start typing in the PQL field: -1. A dropdown shows available **fields** +1. A dropdown shows available **fields** and **functions** 2. After selecting a field, you see **operators** 3. Then you choose or type **values** 4. Continue building your query using **AND** or **OR** @@ -40,7 +40,7 @@ priority = High This returns all work items where priority is High. -You can also combine multiple conditions using logical operators like `AND` and `OR`. +You can also combine multiple conditions using the logical operators `AND`, `OR`, and `NOT`. **Using AND** @@ -58,12 +58,33 @@ state = Todo OR state = In Progress This returns work items that match either condition. +**Using NOT** + +``` +NOT hasNoAssignee() +``` + +This returns work items that do have an assignee. + **Combined:** ``` (priority = High AND state in (Backlog, In Progress, Todo)) OR (type in (Bug, Task, Improvements) AND assignee in (Ethan, Parker, Amanda)) ``` +## Sort and limit results + +You can sort results and cap how many are returned by adding `ORDER BY` and `LIMIT` clauses to the end of a query. + +``` +priority = High ORDER BY dueDate ASC LIMIT 20 +``` + +- **ORDER BY** sorts the results by a field. Add `ASC` (ascending, the default) or `DESC` (descending). +- **LIMIT** caps the number of results returned. The maximum is 1000. + +Fields you can sort by: `priority`, `state`, `title`, `assignee`, `label`, `module`, `startDate`, `dueDate`, `createdAt`, `updatedAt`, `sortOrder`, `rank`. + ## Save as view Once you've built your query, click **Save view** to preserve it for quick access later. See [Views](/core-concepts/views) for details. @@ -79,6 +100,40 @@ PQL is available wherever work items are listed: - Teamspace work items - Workspace views +The exact fields available in the editor depend on what is enabled for the project or workspace you are filtering. For example, `cycle` and `module` appear where those features are on, and custom properties appear when your work item types define them. + +## Fields reference + +### Text search + +| Field | What it searches | +| ------- | ----------------------------------------------------------------------- | +| `title` | The work item title (name) only | +| `text` | The work item title **and** description together, in a single condition | + +Use `text` when you want to match a term whether it appears in the title or the body of a work item. For example, `text ~ "login"` returns work items with "login" in the title or the description. + +### Common fields + +| Field | Filters on | +| ------------ | --------------------------------------------------------------- | +| `type` | Work item type | +| `state` | Workflow state | +| `stateGroup` | State group (Backlog, Unstarted, Started, Completed, Cancelled) | +| `priority` | Priority (Urgent, High, Medium, Low, None) | +| `assignee` | Assigned members | +| `label` | Labels applied | +| `cycle` | Cycle membership | +| `module` | Module membership | +| `milestone` | Milestone | +| `mention` | Members mentioned in the work item | +| `createdBy` | Who created the work item | +| `project` | Project the work item belongs to | +| `startDate` | Start date | +| `dueDate` | Due date | +| `createdAt` | Creation date | +| `updatedAt` | Last updated date | + ## Operators reference Each field supports different operators. The available operators depend on the field type. @@ -99,6 +154,14 @@ Each field supports different operators. The available operators depend on the f | `!=` | Title does not match | | `~` | Title contains text | +### text + +| Operator | Description | +| -------- | -------------------------------------------- | +| `=` | Title or description matches the text | +| `!=` | Title or description does not match the text | +| `~` | Title or description contains the text | + ### type | Operator | Description | @@ -331,14 +394,37 @@ The available operators depend on the property type. ## Built-in functions -PQL includes functions to filter work items based on common scenarios. These functions return a boolean value (`true` or `false`). - -| Function | Description | -| --------------------- | ----------------------------------- | -| `isOverdue` | Due date is past and state is open | -| `hasNoAssignee` | Work item has no assignee | -| `hasNoLabel` | Work item has no labels | -| `isTopLevel` | Not a sub-work item (has no parent) | -| `isSubWorkItem` | Is a sub-work item (has a parent) | -| `hasChildren` | Has at least one sub-work item | -| `hasStartAndDueDates` | Has both start and due dates | +PQL includes functions that cover common scenarios. Type `(` after a field, or start typing a function name, and the editor suggests the ones that fit. + +### Predicate functions + +These are standalone conditions that return true or false. Use them on their own (and combine with `NOT` to invert). + +| Function | Matches work items that | +| ----------------------- | -------------------------------------- | +| `isOverdue()` | Are past their due date and still open | +| `hasNoAssignee()` | Have no assignee | +| `hasNoLabel()` | Have no labels | +| `isTopLevel()` | Are not a sub-work item (no parent) | +| `isSubWorkItem()` | Are a sub-work item (have a parent) | +| `hasChildren()` | Have at least one sub-work item | +| `hasStartAndDueDates()` | Have both a start date and a due date | + +### Relation functions + +These match work items by their relationship to other work items. Each takes one or more work item identifiers (for example `PROJ-123`). + +| Function | Matches work items that | +| -------------------------- | --------------------------------------- | +| `blockedBy("PROJ-1", …)` | Are blocked by the given items | +| `blocks("PROJ-1", …)` | Block the given items | +| `linkedTo("PROJ-1", …)` | Are related to the given items | +| `duplicateOf("PROJ-1", …)` | Are marked duplicate of the given items | +| `childOf("PROJ-1", …)` | Are a child of the given items | +| `parentOf("PROJ-1", …)` | Are a parent of the given items | + +Example: + +``` +blockedBy("PROJ-42") +``` diff --git a/docs/core-concepts/pages/editor-blocks.md b/docs/core-concepts/pages/editor-blocks.md index b0461aaa..23708ce2 100644 --- a/docs/core-concepts/pages/editor-blocks.md +++ b/docs/core-concepts/pages/editor-blocks.md @@ -96,6 +96,32 @@ Use the slash command to insert the layout you need: Each column appears with an "Add content" placeholder where you can add any block type - text, lists, code, images, and more. +## Tabs + +Tabs let you organize content into a tabbed block within a page, so related sections can share one space and readers switch between them instead of scrolling. You can lay tabs out horizontally (along the top) or vertically (down the side). + +### Insert tabs + +Type `/tabs` in the editor and choose one of: + +- **Horizontal tabs** - the tab labels run along the top of the block. +- **Vertical tabs** - the tab labels run down the side of the block. + +A new block is inserted with two tabs, named "Tab 1" and "Tab 2". Each tab holds its own content, and you can put any editor content inside a tab, including text, lists, images, and other blocks. + +### Rename a tab + +Double-click a tab label, type the new name, and press Enter (or click away) to save. + +### Change the layout + +While editing, use the layout controls on the block to switch between horizontal and vertical orientation at any time. Your tabs and their content are preserved. + +### Notes + +- Tabs cannot be nested. You cannot insert a tabs block inside another tabs block. +- In read-only or published pages, readers can switch between tabs but cannot add, rename, delete, or edit them. + ## Video Embeds video content directly into your pages for rich multimedia documentation. diff --git a/docs/dashboards.md b/docs/dashboards.md index bd57ccac..e3f9deff 100644 --- a/docs/dashboards.md +++ b/docs/dashboards.md @@ -216,30 +216,44 @@ There is no x-axis property or grouping for number widgets - they compute a sing Note: the number widget supports all y-axis metrics except estimate points. If you need an estimate point total as a single number, use a table chart instead. -### Table chart +### Work items statistics -A table chart renders issues grouped by the x-axis property as rows, with a count column. -It presents the same data as a bar chart but in a structured grid format rather than a -visual chart. It is useful when the precise numbers matter more than the visual shape of -the distribution, or when you need to display many groups that would be hard to read as bars. +The work items statistics widget groups work items by a dimension you choose and shows the total for each group. Grouping by assignee gives a "work items by assignee" view, showing how work is distributed across your team. + +It is most useful for workload and distribution questions: how many work items each person has, how work splits across states or priorities, or how it spreads across projects. + +**Basic** + +Configure the widget with: + +- **Group by** - the dimension to group work items by: State, State group, Project, **Assignee**, Label, Work item type, Cycle, Module, Created by, or Priority. +- **Metric** - **Work item count**, **Estimate points**, or both. The first selected metric is the primary one. +- **Max rows** - between 1 and 100 (default 10). + +Style options: + +- **Show percentage** - display each group's share of the total. +- **Progress bar color** - the color of the group bars. + +### Two dimensional table + +A two dimensional table renders issues grouped by the x-axis property as rows, with a count column. It presents the same data as a bar chart but in a structured grid format rather than a visual chart. It is useful when the precise numbers matter more than the visual shape of the distribution, or when you need to display many groups that would be hard to read as bars. **Basic** -One row per group, with a count column. The y-axis metric is fixed to **work item count** -and cannot be changed - table charts always show a raw count. The appearance settings -(column color, legend, tooltip) match the bar chart config options. +One row per group, with a count column. The y-axis metric is fixed to **work item count** and cannot be changed - table charts always show a raw count. The appearance settings (column color, legend, tooltip) match the bar chart config options. ### Work Items Table -A work items table lists individual work items as rows with configurable columns. Unlike the table chart, which aggregates issues into groups and shows a count, the work items table renders one row per work item — giving you a live filtered spreadsheet view of your issues directly on a dashboard. +A work items table lists individual work items as rows with configurable columns. Unlike the table chart, which aggregates issues into groups and shows a count, the work items table renders one row per work item - giving you a live filtered spreadsheet view of your issues directly on a dashboard. -It is most useful when you need a quick-reference list of specific issues on a dashboard — for example, all open blockers, issues due this week, or unassigned high-priority work — without navigating to a project view. +It is most useful when you need a quick-reference list of specific issues on a dashboard - for example, all open blockers, issues due this week, or unassigned high-priority work - without navigating to a project view. **Basic** Rows display each matching work item with its identifier and name always visible. You choose which additional columns appear, how many rows to show per page, and navigate across pages directly on the widget. -The widget does not have an x-axis property, y-axis metric, or group-by dimension — it is a flat list, not a chart. Dashboard-level and widget-level filters control which work items appear. +The widget does not have an x-axis property, y-axis metric, or group-by dimension - it is a flat list, not a chart. Dashboard-level and widget-level filters control which work items appear. **Columns** @@ -269,6 +283,64 @@ The identifier, name, and project are always present. All other columns are opti Set between 1 and 100 rows per page (default 10). Use a lower number for a compact at-a-glance list and a higher number when you need to scan many items at once. +### Assigned to you + +The "Assigned to you" widget lists the work items assigned to whoever is viewing the dashboard. It is the same table as the work items table, but scoped automatically to the current viewer, so it always shows "my work." + +This makes it ideal for shared team dashboards: a single widget gives every team member their own personal task list, without each person needing their own dashboard or filter. + +**Basic** + +Rows display each work item assigned to you, with the identifier and title always visible. It is configured exactly like the work items table: + +- **Columns to display** - choose which additional columns appear. The available columns are State, Priority, Assignees, Due date, Start date, Labels, Cycle, Modules, Type, Estimate, Created by, Releases, Sub work items, Attachments, Links, Customer requests, and Customer. New widgets start with State, Priority, and Due date. +- **Max rows** - the number of rows per page, between 1 and 100 (default 10). Use the pagination control to move through pages. + +Dashboard-level and widget-level filters still apply, narrowing your assigned items further. + +Because the widget resolves to the current viewer, it shows results only for a signed-in user. On a published (public) dashboard, where there is no signed-in viewer, it has nothing to resolve to and shows no items. + +### Work items progress + +The work items progress widget shows progress broken down by work item type. Each row is a work item of the type or types you choose (for example, an Epic or any custom type), and its progress bar reflects the completion of that item's direct sub-items. + +It is most useful for tracking a set of large deliverables, such as all Epics in a project, and seeing how close each is to done in one view. + +**Basic** + +Each row shows the work item's name, its completion count, a distribution across state groups, and a percentage complete. Configure the widget with: + +- **Work item type** - one or more work item types whose items become the rows. At least one is required. +- **Metric** - what the progress measures: **Work item count** or **Estimate points**. +- **Rows per page** - between 1 and 100 (default 6). + +Style options: + +- **Progress bar type** - **Linear** (a single bar) or **State group breakdown** (a bar segmented by state group). +- **Progress color** - the bar color, used with the linear style. +- **Show completed** - count cancelled sub-items as completed. +- **Show empty items** - include rows that have no sub-items. +- **Show percentage** - display the percentage alongside the bar. + +### Cycle progress bar + +The cycle progress bar shows the progress of a single cycle at a glance. Unlike the chart widgets, it summarizes one cycle rather than plotting a data series, making it a compact status indicator for a dashboard. + +It is most useful for keeping a specific active cycle visible on a shared dashboard, so the team can see how far along it is without opening the cycle itself. + +**Basic** + +Pick the project, then the cycle within that project to summarize. The widget then shows + +- **Distribution** across state groups (backlog, unstarted, started, completed, cancelled), with a count and percentage for each +- **Work completed**, as a share of the cycle's total scope +- **Scope change**, reflecting work added or removed after the cycle started +- **Blocked items**, the count of work items with a blocking relationship +- **Time elapsed** and **days left** in the cycle +- The cycle's overall **status** and **total work item count** + +The widget reports on one cycle. To track several cycles, add one widget per cycle. + ## Configure a widget Open the configuration sidebar by clicking the widget or by clicking the pencil icon. @@ -477,8 +549,8 @@ Published dashboards are link-only. There is no password protection, no expirati While a dashboard is in **edit mode**: -- **Resize** — drag the resize handle at the bottom-right corner of a widget to change its height or width. -- **Reposition** — drag the widget by its header to move it to a different position on the grid. +- **Resize** - drag the resize handle at the bottom-right corner of a widget to change its height or width. +- **Reposition** - drag the widget by its header to move it to a different position on the grid. Positions and sizes are saved when you make a change. diff --git a/docs/importers/jira.md b/docs/importers/jira.md index 3578cb94..499103a3 100644 --- a/docs/importers/jira.md +++ b/docs/importers/jira.md @@ -3,126 +3,129 @@ title: Import data from Jira description: Import your projects and issues from Jira Cloud, Jira Server, or Jira Data Center into Plane. --- -# Jira importer (Cloud, Server, and Data Center) +# Jira importer -Plane supports importing from Jira Cloud, Jira Server, and Jira Data Center. Choose the import option that matches your Jira deployment. +Plane imports your projects, issues, and related data from Jira. There are two connectors, depending on your Jira deployment: + +- **Jira Cloud** for sites hosted at `*.atlassian.net`. +- **Jira Server / Data Center** for self-hosted Jira. Server and Data Center use the same connector and the same steps. + +Both connectors import into a Plane project you choose and run on the same import engine, so the data you get is the same. The differences are in how you connect and a few deployment-specific options, called out below. ::: info The Jira importer is available on Plane Cloud and on all plans of the Commercial Edition for self-hosted instances. ::: -## Import from Jira +## Before you begin -> **Role**: Workspace admins +- **Issue types**: To bring Jira issue types in as Plane work item types, enable the [Work Item Types](/work-items/project-work-item-types) feature on the target Plane project before importing. Without it, issues still import, but issue types are not created as work item types. +- **Jira access**: The account you connect with must be able to read the Jira project you are importing, along with its issues, statuses, priorities, issue types, and labels. -::: tip -To import issue types from Jira, make sure the [Issue types](/work-items/project-work-item-types) feature is enabled in your Plane project. -::: +## Choose your connector -To import Jira issues to a Plane project, follow these steps: +Go to **Workspace Settings → Imports**, then click **Import** in either the **Jira** section (for Jira Cloud) or the **Jira Server/Data Center** section (for self-hosted Jira). -1. Click the **∨** icon next to your workspace name on the sidebar and select **Workspace Settings**. +## Connect to Jira -2. Select **Imports** on the right pane and click the **Import** button in the Jira section. +Jira connects with a Personal Access Token. Provide three values: - ![Import from Jira](https://media.docs.plane.so/importers/jira/import-jira-cloud-server.webp#hero) +| Field | What to enter | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Personal Access Token** | An API token created at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens) or from your Jira Server / Data Center instance | +| **User email** | The email address linked to that token | +| **Jira domain** | Your Jira site URL, for example `https://your-site.atlassian.net` | -3. In the **Jira to Plane Migration Assistant** screen, enter your **Personal Access Token**, **User email** and the **Jira domain** to allow Plane access to your Atlassian account. +Click **Connect Jira** to link the accounts. Plane verifies the credentials before continuing. - ![Connect Jira](https://media.docs.plane.so/importers/jira/jira-plane-migration-assitant.webp#hero) +## Run the import -4. Click the **Connect Jira** button to link the accounts. +After connecting, work through the import steps. The steps are the same for all deployments, except that the **Import users** step appears only for Jira Cloud (Server and Data Center bring in users automatically). -5. Click the **Import** button. +1. **Select Plane project.** Choose the Plane project to import into. - ![Import Jira](https://media.docs.plane.so/importers/jira/import-jira-data.webp#hero) +2. **Configure Jira.** Choose the Jira site and the Jira project to import from. Optionally, add a **JQL** filter to import only the issues that match a query. Plane scopes your query to the selected project automatically. -6. **Configure Plane** - Select the Plane project where you want to import your Jira data and and click **Next**. +3. **Import users** _(Jira Cloud only)_. Choose how to bring in users: + - **Upload CSV** _(recommended)_. Upload a user export from Jira. See [Export users from a site](https://support.atlassian.com/organization-administration/docs/export-users-from-a-site/) for how to generate it. - ![Configure Plane](https://media.docs.plane.so/importers/jira/configure-plane.webp#hero) + Admin or Member users invited to your workspace count toward your billed seats immediately, but the importer treats them as active members only once they accept the invitation. So you have two options: let the importer create users (don't invite them manually first), or invite everyone first and wait for them to accept before importing. -7. **Configure Jira** - Choose the workspace and project in Jira from where you want to import data. + - **Skip user import.** Select **Skip Importing User data** and add users later. + ::: warning + If you skip user import, work items and comments show the name of the person who ran the migration, and the Assignees field is left empty. + ::: - ![Configure Jira](https://media.docs.plane.so/importers/jira/configure-jira.webp#hero) + For **Jira Server / Data Center**, there is no user step. Plane automatically syncs the users referenced by the imported issues. - ::: info Work item types - If you're on a paid plan (Pro or higher), issue types in Jira will be imported as work item types in Plane. On the free plan, issue types from Jira won't be imported. - ::: +4. **Map states.** Map each Jira status to a Plane state. Select **Auto create and map the remaining Jira states** to create and map anything you don't map by hand. -8. **Import users** +5. **Map priorities.** Map each Jira priority to a Plane priority. If there is no match, choose **None**. - Choose one of the following: - - **Upload CSV** - Click the **Upload CSV** button to import users to your Plane project. Refer to [Export users from a site](https://support.atlassian.com/organization-administration/docs/export-users-from-a-site/) to download the CSV file from Jira. _(recommended)_ +6. **Summary.** Review your mappings. Click **Back** to adjust, or **Confirm** to start the import. - Admin or Member role users invited to your workspace count toward your billed seats right away, but the importer only treats them as active members once they accept the invitation. So, when importing users, you have two options: - - Don't invite users to the workspace manually and let the importer handle user creation. - - Invite users first and wait for all of them to accept before running the import. +The import runs in the background and takes a few minutes to hours depending on the size of your Jira project. When it finishes, open **Work items** in your Plane project to confirm the data imported. - - **Skip user import** - You can select the **Skip Importing User data** checkbox and manually add users later. - ::: warning - If you skip user import, work items and comments will show the name of the person who performed the migration, and the Assignees field will be empty. - ::: - - ![Import users](https://media.docs.plane.so/importers/jira/import-users.webp#hero) +::: info Issue types and work item types +When the Work Item Types feature is enabled, Jira issue types are imported as Plane work item types. You do not map them; they are created automatically. On the Free plan (or with the feature off), issues still import but issue types are not created as work item types. +::: -9. **Map states** - 1. Map **Jira status** to their equivalent **Plane states**. - 2. Select the **Auto create and map the remaining Jira states** checkbox to automatically create and map any missing states. +## What gets imported - ![Map states](https://media.docs.plane.so/importers/jira/map-states.webp#hero) +| Jira | Plane | Notes | +| -------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Issues | Work items | Summary becomes the work item title. | +| Issue description | Work item description | Formatting is preserved. Inline images are re-uploaded to Plane. | +| Status | States | Mapped in the Map states step. | +| Priority | Priority | Mapped in the Map priorities step. | +| Issue types | Work item types | Requires the Work Item Types feature. Imported automatically, not mapped. Can be created at the project or workspace level. | +| Epics | Work item type | Imported as a regular work item type, not as Plane's dedicated Epics feature. | +| Labels | Labels | Every imported work item also gets a `JIRA IMPORTED` label so you can find migrated items easily. | +| Custom fields | Custom properties | Supported Jira custom and system fields become work item custom properties, with their options. Unsupported field types are skipped. Rich text custom fields require the rich text property feature. | +| Users | Members | Cloud: from your CSV, or skipped. Server / Data Center: synced automatically from the issues. | +| Reporter | Created by | Also stored as a "reporter" property on the work item. | +| Assignee | Assignees | Blank if you skip user import. | +| Comments | Comments | Includes author and timestamp. If you skip user import, comments show the person who ran the migration. | +| Attachments | Attachments | On both issues and comments. See [Attachments](#attachments) for a Server / Data Center note. | +| Sub-tasks and parent links | Parent-child relationships | Sub-tasks import as work items linked to their parent. | +| Linked issues | Relations | Blocks, blocked by, relates to, and duplicate. Jira link types with no Plane equivalent are created as custom relation types. Links across projects resolve once the other project is also imported. | +| Sprints | Cycles | Including the cycle's work items and start and end dates. | +| Components | Modules | Including the module's work items. | +| Fix versions / affected versions | Custom properties | Stored as work item properties. | +| Story points | Story points | From your configured story-points field. | +| Worklogs | Worklogs | Time tracking is enabled on the project when worklogs are imported. | +| Watchers | Subscribers | | +| Change history | Work item activity | | +| Start date / Due date | Start date / Due date | | +| Created date | Created at | | -10. **Map priorities** - Map the **Jira priorities** to the corresponding **Plane priorities**. If there's no match, select **None** in the **Plane priorities** list. +Every imported work item also gets a **Linked Jira Issue** link back to the original issue in Jira, and its original Jira key number is preserved. - ![Map priorities](https://media.docs.plane.so/importers/jira/map-priorities.webp#hero) +## Attachments -11. **Summary** - Review the mappings and make any changes if needed. Click **Back** to adjust, or click **Confirm** to start the migration. +Attachments on issues and comments are imported by default. - ![Review mappings](https://media.docs.plane.so/importers/jira/import-summary.webp#hero) +**Jira Server / Data Center behind SSO.** Jira Server and Data Center stream attachment files from a secure servlet (`/secure/attachment/...`). On instances where that servlet sits behind web SSO (SAML), it does not accept the personal access token the way the REST API does, so the download is redirected to your identity provider and Plane receives the login page instead of the file. When this happens, attachments fail to import. -12. The data migration begins and takes a few minutes to complete depending on the number of issues in your Jira workspace. +To work around it, expose a custom attachment download endpoint on your Jira instance (typically a ScriptRunner REST endpoint) that is not behind the SSO filter, and have Plane use it for attachment downloads. Follow the [attachment endpoint setup instructions](https://sites.plane.so/pages/4cfee57ef84d4b50bacfb110e37316e5). - ![Migration complete](https://media.docs.plane.so/importers/jira/jira-import-complete.webp#hero) +- On **self-hosted Plane**, set the download path (with an `{id}` placeholder for the attachment ID, for example `/rest/scriptrunner/latest/custom/downloadAttachment?id={id}`) in your integration service configuration. +- On **Plane Cloud**, contact Plane support to have the download path configured for your instance. -13. Once it's done, go to **Work items** in your Plane project to confirm that the data import is successful. +This applies to **Jira Server and Data Center only**. Jira Cloud is not affected and needs no workaround. -## Imported entities +## Re-run and resume an import -Here’s a quick look at what gets imported during the migration from Jira to Plane: +Open the import from **Workspace Settings → Imports** to manage it. -| Jira | Plane | Notes | -| ------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| Labels | Labels | | -| Status | States | | -| Issue priorities | Priorities | | -| Users | Users | | -| Issues | Work items | | -| Relations | Parent | Includes only parent-child relationships | -| Issue comments | Work item comments | Includes username and timestamp. If you skip user import during migration, comments will show the name of the user who performed the migration. | -| Issue attachments | Work item attachments | | -| Reporter | Created by | | -| Created | Created at | | -| Assignee | Assignees | If you skip user import during migration, this will be blank. | -| Issue types | Labels \| Prefix in Issue title | | -| Images in the Issue description | Images in the Work item description | | -| Summary | Work item title | | -| Start date | Start date | | -| Due date | Due date | | -| Linked Issues | Links | Includes backlinks to the original Jira issue. | -| Sprint | Cycles | Includes the work items, start and end date. | -| Components | Modules | Includes the work items. | +**Re-run** (all deployments). Re-running restarts the import for that project from the beginning, using the same configuration and filter. It is a full re-sync, not a changed-only sync, but it does **not** create duplicates: Plane matches items by their original Jira identity and updates existing work items in place while adding any new issues. Use re-run to bring across new and updated Jira issues after your initial import. -## Sync Jira to Plane +![Re-run import](https://media.docs.plane.so/importers/jira/rerun-import.webp#hero) -After the import, if there are any new or updated issues in Jira, you can easily sync these changes to Plane: +**Resume** (Jira Server / Data Center only). If a Server or Data Center import fails or times out, you can resume it. Resume continues from where the import stopped rather than starting over. It is available for a limited window (about 7 days) after the job stops; after that, use re-run instead. -1. Go to **Workspace settings**. -2. Select **Imports** on the right pane. -3. Click the **Re run** button next to the project you want to sync. +## Notes and limits - ![Sync Jira](https://media.docs.plane.so/importers/jira/rerun-import.webp#hero) +- **Reliability.** Server and Data Center imports track each batch of issues and automatically re-dispatch any batch that goes missing, and they detect and recover from stalls. This significantly reduces timeout and error failures on large imports. +- **Large instances.** Very large Jira projects import in batches and may take a while. If your Data Center instance rate-limits aggressively, imports still complete but run more slowly. +- **Cross-project links.** Links between issues in different Jira projects resolve only after both projects have been imported into Plane. +- **Unsupported custom field types** are skipped rather than failing the import.