From 50edb20716e08aaafaae525ae32a4b284592ae10 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 11:08:39 +0000 Subject: [PATCH 1/5] Add documentation page for creating work items via URL Adds a new page under Work Items that documents the /work-items/new URL endpoint for creating work items with pre-filled fields using query parameters. Covers all supported parameters including workspace, title, description, project, priority, assignee, start_date, and due_date. https://claude.ai/code/session_01NTCkVk8Kkqiesh3SksMhEu --- docs/core-concepts/issues/work-item-url.mdx | 179 ++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 180 insertions(+) create mode 100644 docs/core-concepts/issues/work-item-url.mdx diff --git a/docs/core-concepts/issues/work-item-url.mdx b/docs/core-concepts/issues/work-item-url.mdx new file mode 100644 index 0000000..dceff76 --- /dev/null +++ b/docs/core-concepts/issues/work-item-url.mdx @@ -0,0 +1,179 @@ +--- +title: Create work items via URL +description: Use a URL to trigger the creation of a new work item in Plane and pre-fill fields using query parameters +--- + +# Create a new work item via URL + +Plane provides a special URL that triggers the creation of a new work item in any browser. You can add query parameters to this URL to pre-fill work item fields, making it easy to create work items from external tools, bookmarks, or shared links. + +## Base URL + +``` +https:///work-items/new +``` + +When you visit this URL: + +1. You will be authenticated and redirected to your last active workspace. +2. The work item creation modal will automatically open. +3. Any query parameters provided will be used to pre-fill the form. + +## Pre-filling work item fields + +To pre-fill work item fields and properties: + +1. Add a `?` at the end of the URL. +2. Include the field or property you want to pre-set. +3. Add `=`. +4. Add the value you want to set. +5. Use `&` between each field when setting multiple properties. + +## Supported query parameters + +### `workspace` + +Redirects to the specified workspace instead of the default (last active workspace). + +- Accepts a valid workspace slug + +**Example:** + +``` +https://app.plane.so/work-items/new?workspace=plane +``` + +### `title` + +Pre-fills the work item title. + +- Use `+` or `%20` to indicate spaces in the title + +**Example:** + +``` +https://app.plane.so/work-items/new?title=Fix+login+bug + +https://app.plane.so/work-items/new?title=Implement%20new%20feature +``` + +### `description` + +Pre-fills the work item description. + +- Use `+` or `%20` to indicate spaces +- URL-encode content for complex descriptions + +**Example:** + +``` +https://app.plane.so/work-items/new?description=This+is+a+bug+description + +https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce +``` + +### `project` + +Pre-fills the project for the work item. + +- Can be set by project **identifier** (e.g., `PROJ`, `WEB`) +- Can be set by project **UUID** + +**Example:** + +``` +https://app.plane.so/work-items/new?project=WEB + +https://app.plane.so/work-items/new?project=MOBILE&title=New+feature +``` + +### `priority` + +Pre-fills the work item priority. + +- Supported values: `urgent`, `high`, `medium`, `low`, `none` +- Case-insensitive + +**Example:** + +``` +https://app.plane.so/work-items/new?priority=urgent + +https://app.plane.so/work-items/new?priority=high&title=Critical+fix + +https://app.plane.so/work-items/new?priority=Medium +``` + +### `assignee` + +Pre-fills the assignee(s) for the work item. + +- Can be set by user **UUID** +- Can be set by user **display name** +- Use `me` to assign to the current user (the person opening the URL) +- Use comma-separated values to assign multiple users + +**Example:** + +``` +https://app.plane.so/work-items/new?assignee=me + +https://app.plane.so/work-items/new?assignee=john + +https://app.plane.so/work-items/new?assignee=Erin+Baker + +https://app.plane.so/work-items/new?assignee=me,john,jane +``` + +### `start_date` + +Pre-fills the start date for the work item. + +- Accepts any valid date format that JavaScript `Date` can parse +- Recommended formats: `YYYY-MM-DD` or ISO 8601 + +**Example:** + +``` +https://app.plane.so/work-items/new?start_date=2024-03-15 +``` + +### `due_date` + +Pre-fills the due date (target date) for the work item. + +- Accepts any valid date format that JavaScript `Date` can parse +- Recommended formats: `YYYY-MM-DD` or ISO 8601 + +**Example:** + +``` +https://app.plane.so/work-items/new?due_date=2024-03-30 +``` + +## Combined examples + +### Simple work item with title and description + +``` +https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile +``` + +### Work item with project, priority, and assignee + +``` +https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug +``` + +### Fully populated work item + +``` +https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30 +``` + +## Notes + +- All query parameter values are case-insensitive where applicable (e.g., priority, project identifier). +- If a project identifier or user display name doesn't match any existing record, that parameter will be ignored. +- The user must be authenticated to use this URL. Unauthenticated users will be redirected to login first. +- After the modal opens, users can modify any pre-filled values before creating the work item. diff --git a/sidebars.ts b/sidebars.ts index ade9696..0cf3722 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -121,6 +121,7 @@ const sidebars: SidebarsConfig = { "core-concepts/issues/overview", "core-concepts/issues/properties", "core-concepts/drafts", + "core-concepts/issues/work-item-url", ], }, From 43b650ab2c72c9e3b5a1b80353f636bb17a779dc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 12:20:25 +0000 Subject: [PATCH 2/5] Update base URL to app.plane.so and add self-hosted note Use app.plane.so as the base URL and add a tip callout for self-hosted users to replace it with their own domain. https://claude.ai/code/session_01NTCkVk8Kkqiesh3SksMhEu --- docs/core-concepts/issues/work-item-url.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/core-concepts/issues/work-item-url.mdx b/docs/core-concepts/issues/work-item-url.mdx index dceff76..b295216 100644 --- a/docs/core-concepts/issues/work-item-url.mdx +++ b/docs/core-concepts/issues/work-item-url.mdx @@ -10,9 +10,13 @@ Plane provides a special URL that triggers the creation of a new work item in an ## Base URL ``` -https:///work-items/new +https://app.plane.so/work-items/new ``` +:::tip +If you are using a self-hosted instance of Plane, replace `app.plane.so` with your own domain (e.g., `https://plane.yourdomain.com/work-items/new`). +::: + When you visit this URL: 1. You will be authenticated and redirected to your last active workspace. From dbf1a6a83f476ae81922750985811a07b0689bc9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 12:25:02 +0000 Subject: [PATCH 3/5] Replace code blocks with inline code and table for consistency Use inline code formatting for URLs and parameter values, add a summary table for query parameters, and use bold-label bullet lists for combined examples to match the style of other docs pages. https://claude.ai/code/session_01NTCkVk8Kkqiesh3SksMhEu --- docs/core-concepts/issues/work-item-url.mdx | 129 +++++++------------- 1 file changed, 47 insertions(+), 82 deletions(-) diff --git a/docs/core-concepts/issues/work-item-url.mdx b/docs/core-concepts/issues/work-item-url.mdx index b295216..ea19ca8 100644 --- a/docs/core-concepts/issues/work-item-url.mdx +++ b/docs/core-concepts/issues/work-item-url.mdx @@ -9,9 +9,7 @@ Plane provides a special URL that triggers the creation of a new work item in an ## Base URL -``` -https://app.plane.so/work-items/new -``` +The base URL for creating a new work item is `https://app.plane.so/work-items/new`. :::tip If you are using a self-hosted instance of Plane, replace `app.plane.so` with your own domain (e.g., `https://plane.yourdomain.com/work-items/new`). @@ -35,80 +33,70 @@ To pre-fill work item fields and properties: ## Supported query parameters -### `workspace` +| Parameter | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------ | +| `workspace` | Redirects to the specified workspace instead of the default (last active workspace). Accepts a workspace slug. | +| `title` | Pre-fills the work item title. Use `+` or `%20` to indicate spaces. | +| `description`| Pre-fills the work item description. Use `+` or `%20` to indicate spaces. URL-encode complex content. | +| `project` | Pre-fills the project. Can be set by project **identifier** (e.g., `PROJ`, `WEB`) or by project **UUID**. | +| `priority` | Pre-fills the priority. Supported values: `urgent`, `high`, `medium`, `low`, `none`. Case-insensitive. | +| `assignee` | Pre-fills the assignee(s). Can be set by **UUID**, **display name**, or `me` for the current user. Use commas to assign multiple users. | +| `start_date` | Pre-fills the start date. Recommended format: `YYYY-MM-DD` or ISO 8601. | +| `due_date` | Pre-fills the due date (target date). Recommended format: `YYYY-MM-DD` or ISO 8601. | + +### workspace Redirects to the specified workspace instead of the default (last active workspace). - Accepts a valid workspace slug -**Example:** - -``` -https://app.plane.so/work-items/new?workspace=plane -``` +**Example:** `https://app.plane.so/work-items/new?workspace=plane` -### `title` +### title Pre-fills the work item title. - Use `+` or `%20` to indicate spaces in the title -**Example:** - -``` -https://app.plane.so/work-items/new?title=Fix+login+bug +**Examples:** +- `https://app.plane.so/work-items/new?title=Fix+login+bug` +- `https://app.plane.so/work-items/new?title=Implement%20new%20feature` -https://app.plane.so/work-items/new?title=Implement%20new%20feature -``` - -### `description` +### description Pre-fills the work item description. - Use `+` or `%20` to indicate spaces - URL-encode content for complex descriptions -**Example:** - -``` -https://app.plane.so/work-items/new?description=This+is+a+bug+description +**Examples:** +- `https://app.plane.so/work-items/new?description=This+is+a+bug+description` +- `https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce` -https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce -``` - -### `project` +### project Pre-fills the project for the work item. - Can be set by project **identifier** (e.g., `PROJ`, `WEB`) - Can be set by project **UUID** -**Example:** - -``` -https://app.plane.so/work-items/new?project=WEB - -https://app.plane.so/work-items/new?project=MOBILE&title=New+feature -``` +**Examples:** +- `https://app.plane.so/work-items/new?project=WEB` +- `https://app.plane.so/work-items/new?project=MOBILE&title=New+feature` -### `priority` +### priority Pre-fills the work item priority. - Supported values: `urgent`, `high`, `medium`, `low`, `none` - Case-insensitive -**Example:** - -``` -https://app.plane.so/work-items/new?priority=urgent - -https://app.plane.so/work-items/new?priority=high&title=Critical+fix +**Examples:** +- `https://app.plane.so/work-items/new?priority=urgent` +- `https://app.plane.so/work-items/new?priority=high&title=Critical+fix` +- `https://app.plane.so/work-items/new?priority=Medium` -https://app.plane.so/work-items/new?priority=Medium -``` - -### `assignee` +### assignee Pre-fills the assignee(s) for the work item. @@ -117,63 +105,40 @@ Pre-fills the assignee(s) for the work item. - Use `me` to assign to the current user (the person opening the URL) - Use comma-separated values to assign multiple users -**Example:** - -``` -https://app.plane.so/work-items/new?assignee=me - -https://app.plane.so/work-items/new?assignee=john - -https://app.plane.so/work-items/new?assignee=Erin+Baker - -https://app.plane.so/work-items/new?assignee=me,john,jane -``` +**Examples:** +- `https://app.plane.so/work-items/new?assignee=me` +- `https://app.plane.so/work-items/new?assignee=john` +- `https://app.plane.so/work-items/new?assignee=Erin+Baker` +- `https://app.plane.so/work-items/new?assignee=me,john,jane` -### `start_date` +### start_date Pre-fills the start date for the work item. - Accepts any valid date format that JavaScript `Date` can parse - Recommended formats: `YYYY-MM-DD` or ISO 8601 -**Example:** +**Example:** `https://app.plane.so/work-items/new?start_date=2024-03-15` -``` -https://app.plane.so/work-items/new?start_date=2024-03-15 -``` - -### `due_date` +### due_date Pre-fills the due date (target date) for the work item. - Accepts any valid date format that JavaScript `Date` can parse - Recommended formats: `YYYY-MM-DD` or ISO 8601 -**Example:** - -``` -https://app.plane.so/work-items/new?due_date=2024-03-30 -``` +**Example:** `https://app.plane.so/work-items/new?due_date=2024-03-30` ## Combined examples -### Simple work item with title and description - -``` -https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile -``` - -### Work item with project, priority, and assignee - -``` -https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug -``` +- **Simple work item with title and description** + `https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile` -### Fully populated work item +- **Work item with project, priority, and assignee** + `https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug` -``` -https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30 -``` +- **Fully populated work item** + `https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30` ## Notes From 54f4e6cca83ce18811f7d4b786f6867bb18012f1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 12:31:55 +0000 Subject: [PATCH 4/5] Present URLs as plain text instead of inline code URLs are now shown as readable plain text in the flow of paragraphs, matching the style used by Linear's docs. Parameter descriptions use bold and prose instead of code formatting. https://claude.ai/code/session_01NTCkVk8Kkqiesh3SksMhEu --- docs/core-concepts/issues/work-item-url.mdx | 101 +++++++------------- 1 file changed, 32 insertions(+), 69 deletions(-) diff --git a/docs/core-concepts/issues/work-item-url.mdx b/docs/core-concepts/issues/work-item-url.mdx index ea19ca8..95c70c7 100644 --- a/docs/core-concepts/issues/work-item-url.mdx +++ b/docs/core-concepts/issues/work-item-url.mdx @@ -9,10 +9,10 @@ Plane provides a special URL that triggers the creation of a new work item in an ## Base URL -The base URL for creating a new work item is `https://app.plane.so/work-items/new`. +The base URL for creating a new work item is https://app.plane.so/work-items/new. :::tip -If you are using a self-hosted instance of Plane, replace `app.plane.so` with your own domain (e.g., `https://plane.yourdomain.com/work-items/new`). +If you are using a self-hosted instance of Plane, replace `app.plane.so` with your own domain, e.g., https://plane.yourdomain.com/work-items/new. ::: When you visit this URL: @@ -35,110 +35,73 @@ To pre-fill work item fields and properties: | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------------------------------ | -| `workspace` | Redirects to the specified workspace instead of the default (last active workspace). Accepts a workspace slug. | -| `title` | Pre-fills the work item title. Use `+` or `%20` to indicate spaces. | -| `description`| Pre-fills the work item description. Use `+` or `%20` to indicate spaces. URL-encode complex content. | -| `project` | Pre-fills the project. Can be set by project **identifier** (e.g., `PROJ`, `WEB`) or by project **UUID**. | -| `priority` | Pre-fills the priority. Supported values: `urgent`, `high`, `medium`, `low`, `none`. Case-insensitive. | -| `assignee` | Pre-fills the assignee(s). Can be set by **UUID**, **display name**, or `me` for the current user. Use commas to assign multiple users. | -| `start_date` | Pre-fills the start date. Recommended format: `YYYY-MM-DD` or ISO 8601. | -| `due_date` | Pre-fills the due date (target date). Recommended format: `YYYY-MM-DD` or ISO 8601. | +| workspace | Redirects to the specified workspace instead of the default (last active workspace). Accepts a workspace slug. | +| title | Pre-fills the work item title. Use `+` or `%20` to indicate spaces. | +| description | Pre-fills the work item description. Use `+` or `%20` to indicate spaces. URL-encode complex content. | +| project | Pre-fills the project. Can be set by project identifier (e.g., PROJ, WEB) or by project UUID. | +| priority | Pre-fills the priority. Supported values: urgent, high, medium, low, none. Case-insensitive. | +| assignee | Pre-fills the assignee(s). Accepts UUID, display name, or `me` for the current user. Use commas for multiple. | +| start_date | Pre-fills the start date. Recommended format: YYYY-MM-DD or ISO 8601. | +| due_date | Pre-fills the due date (target date). Recommended format: YYYY-MM-DD or ISO 8601. | ### workspace -Redirects to the specified workspace instead of the default (last active workspace). +Redirects to the specified workspace instead of the default (last active workspace). Accepts a valid workspace slug. -- Accepts a valid workspace slug - -**Example:** `https://app.plane.so/work-items/new?workspace=plane` +For example, https://app.plane.so/work-items/new?workspace=plane. ### title -Pre-fills the work item title. - -- Use `+` or `%20` to indicate spaces in the title +Pre-fills the work item title. Use `+` or `%20` to indicate spaces in the title. -**Examples:** -- `https://app.plane.so/work-items/new?title=Fix+login+bug` -- `https://app.plane.so/work-items/new?title=Implement%20new%20feature` +For example, https://app.plane.so/work-items/new?title=Fix+login+bug or https://app.plane.so/work-items/new?title=Implement%20new%20feature. ### description -Pre-fills the work item description. +Pre-fills the work item description. Use `+` or `%20` to indicate spaces. URL-encode content for complex descriptions. -- Use `+` or `%20` to indicate spaces -- URL-encode content for complex descriptions - -**Examples:** -- `https://app.plane.so/work-items/new?description=This+is+a+bug+description` -- `https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce` +For example, https://app.plane.so/work-items/new?description=This+is+a+bug+description or https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce. ### project -Pre-fills the project for the work item. - -- Can be set by project **identifier** (e.g., `PROJ`, `WEB`) -- Can be set by project **UUID** +Pre-fills the project for the work item. Can be set by project **identifier** (e.g., PROJ, WEB) or by project **UUID**. -**Examples:** -- `https://app.plane.so/work-items/new?project=WEB` -- `https://app.plane.so/work-items/new?project=MOBILE&title=New+feature` +For example, https://app.plane.so/work-items/new?project=WEB or https://app.plane.so/work-items/new?project=MOBILE&title=New+feature. ### priority -Pre-fills the work item priority. +Pre-fills the work item priority. Supported values: **urgent**, **high**, **medium**, **low**, **none**. Values are case-insensitive. -- Supported values: `urgent`, `high`, `medium`, `low`, `none` -- Case-insensitive - -**Examples:** -- `https://app.plane.so/work-items/new?priority=urgent` -- `https://app.plane.so/work-items/new?priority=high&title=Critical+fix` -- `https://app.plane.so/work-items/new?priority=Medium` +For example, https://app.plane.so/work-items/new?priority=urgent or https://app.plane.so/work-items/new?priority=high&title=Critical+fix. ### assignee -Pre-fills the assignee(s) for the work item. - -- Can be set by user **UUID** -- Can be set by user **display name** -- Use `me` to assign to the current user (the person opening the URL) -- Use comma-separated values to assign multiple users +Pre-fills the assignee(s) for the work item. Can be set by user **UUID**, **display name**, or use **me** to assign to the current user (the person opening the URL). Use comma-separated values to assign multiple users. -**Examples:** -- `https://app.plane.so/work-items/new?assignee=me` -- `https://app.plane.so/work-items/new?assignee=john` -- `https://app.plane.so/work-items/new?assignee=Erin+Baker` -- `https://app.plane.so/work-items/new?assignee=me,john,jane` +For example, https://app.plane.so/work-items/new?assignee=me or https://app.plane.so/work-items/new?assignee=john or https://app.plane.so/work-items/new?assignee=Erin+Baker or https://app.plane.so/work-items/new?assignee=me,john,jane. ### start_date -Pre-fills the start date for the work item. +Pre-fills the start date for the work item. Accepts any valid date format that JavaScript `Date` can parse. Recommended formats: YYYY-MM-DD or ISO 8601. -- Accepts any valid date format that JavaScript `Date` can parse -- Recommended formats: `YYYY-MM-DD` or ISO 8601 - -**Example:** `https://app.plane.so/work-items/new?start_date=2024-03-15` +For example, https://app.plane.so/work-items/new?start_date=2024-03-15. ### due_date -Pre-fills the due date (target date) for the work item. - -- Accepts any valid date format that JavaScript `Date` can parse -- Recommended formats: `YYYY-MM-DD` or ISO 8601 +Pre-fills the due date (target date) for the work item. Accepts any valid date format that JavaScript `Date` can parse. Recommended formats: YYYY-MM-DD or ISO 8601. -**Example:** `https://app.plane.so/work-items/new?due_date=2024-03-30` +For example, https://app.plane.so/work-items/new?due_date=2024-03-30. ## Combined examples -- **Simple work item with title and description** - `https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile` +**Simple work item with title and description:** +https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile -- **Work item with project, priority, and assignee** - `https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug` +**Work item with project, priority, and assignee:** +https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug -- **Fully populated work item** - `https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30` +**Fully populated work item:** +https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30 ## Notes From 8169d4985826a0e650da62820cc5647e58b29426 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Thu, 5 Feb 2026 14:44:58 +0530 Subject: [PATCH 5/5] review fixes --- docs/core-concepts/issues/work-item-url.mdx | 168 +++++++++++++------- sidebars.ts | 2 +- 2 files changed, 114 insertions(+), 56 deletions(-) diff --git a/docs/core-concepts/issues/work-item-url.mdx b/docs/core-concepts/issues/work-item-url.mdx index 95c70c7..3efa7a4 100644 --- a/docs/core-concepts/issues/work-item-url.mdx +++ b/docs/core-concepts/issues/work-item-url.mdx @@ -1,111 +1,169 @@ --- title: Create work items via URL -description: Use a URL to trigger the creation of a new work item in Plane and pre-fill fields using query parameters +description: Use a URL to trigger the creation of a new work item in Plane and pre-fill fields using query parameters. --- -# Create a new work item via URL +# Create work items via URL Plane provides a special URL that triggers the creation of a new work item in any browser. You can add query parameters to this URL to pre-fill work item fields, making it easy to create work items from external tools, bookmarks, or shared links. ## Base URL -The base URL for creating a new work item is https://app.plane.so/work-items/new. +**For Plane Cloud** +`https://app.plane.so/work-items/new`. -:::tip -If you are using a self-hosted instance of Plane, replace `app.plane.so` with your own domain, e.g., https://plane.yourdomain.com/work-items/new. -::: +For self-hosted instances, replace `app.plane.so` with your domain, e.g., `https://plane.yourdomain.com/work-items/new`. -When you visit this URL: +When you visit this URL, Plane authenticates you, redirects to your last active workspace, and opens the work item creation modal. Any query parameters you include will pre-fill the corresponding fields. -1. You will be authenticated and redirected to your last active workspace. -2. The work item creation modal will automatically open. -3. Any query parameters provided will be used to pre-fill the form. +## Build a URL with parameters -## Pre-filling work item fields +Start with the base URL, add `?`, then append parameters in `name=value` format. Separate multiple parameters with `&`. +```bash +https://app.plane.so/work-items/new?title=Fix+bug&priority=high&assignee=me +``` -To pre-fill work item fields and properties: +A few formatting rules: -1. Add a `?` at the end of the URL. -2. Include the field or property you want to pre-set. -3. Add `=`. -4. Add the value you want to set. -5. Use `&` between each field when setting multiple properties. +- Use `+` or `%20` for spaces in text values. +- URL-encode special characters in descriptions. +- Separate multiple values (like assignees) with commas. -## Supported query parameters - -| Parameter | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------ | -| workspace | Redirects to the specified workspace instead of the default (last active workspace). Accepts a workspace slug. | -| title | Pre-fills the work item title. Use `+` or `%20` to indicate spaces. | -| description | Pre-fills the work item description. Use `+` or `%20` to indicate spaces. URL-encode complex content. | -| project | Pre-fills the project. Can be set by project identifier (e.g., PROJ, WEB) or by project UUID. | -| priority | Pre-fills the priority. Supported values: urgent, high, medium, low, none. Case-insensitive. | -| assignee | Pre-fills the assignee(s). Accepts UUID, display name, or `me` for the current user. Use commas for multiple. | -| start_date | Pre-fills the start date. Recommended format: YYYY-MM-DD or ISO 8601. | -| due_date | Pre-fills the due date (target date). Recommended format: YYYY-MM-DD or ISO 8601. | +## Query parameters reference ### workspace -Redirects to the specified workspace instead of the default (last active workspace). Accepts a valid workspace slug. +Overrides the default behavior of redirecting to your last active workspace. Pass a workspace slug to land in a specific workspace instead. -For example, https://app.plane.so/work-items/new?workspace=plane. +``` +https://app.plane.so/work-items/new?workspace=plane +``` ### title -Pre-fills the work item title. Use `+` or `%20` to indicate spaces in the title. +Sets the work item title. Replace spaces with `+` or `%20`. + +``` +https://app.plane.so/work-items/new?title=Fix+login+bug +``` -For example, https://app.plane.so/work-items/new?title=Fix+login+bug or https://app.plane.so/work-items/new?title=Implement%20new%20feature. +``` +https://app.plane.so/work-items/new?title=Implement%20new%20feature +``` ### description -Pre-fills the work item description. Use `+` or `%20` to indicate spaces. URL-encode content for complex descriptions. +Sets the work item description. For anything beyond simple text, URL-encode the content to handle special characters and line breaks. + +``` +https://app.plane.so/work-items/new?description=This+is+a+bug+description +``` -For example, https://app.plane.so/work-items/new?description=This+is+a+bug+description or https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce. +Combined with a title: + +``` +https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce +``` ### project -Pre-fills the project for the work item. Can be set by project **identifier** (e.g., PROJ, WEB) or by project **UUID**. +Assigns the work item to a project. You can use either the project identifier (the short code like `WEB` or `MOBILE`) or the project's UUID. + +``` +https://app.plane.so/work-items/new?project=WEB +``` -For example, https://app.plane.so/work-items/new?project=WEB or https://app.plane.so/work-items/new?project=MOBILE&title=New+feature. +``` +https://app.plane.so/work-items/new?project=MOBILE&title=New+feature +``` ### priority -Pre-fills the work item priority. Supported values: **urgent**, **high**, **medium**, **low**, **none**. Values are case-insensitive. +Sets the priority level. Accepts `urgent`, `high`, `medium`, `low`, or `none`. Values are case-insensitive, so `High`, `HIGH`, and `high` all work. -For example, https://app.plane.so/work-items/new?priority=urgent or https://app.plane.so/work-items/new?priority=high&title=Critical+fix. +``` +https://app.plane.so/work-items/new?priority=urgent +``` + +``` +https://app.plane.so/work-items/new?priority=high&title=Critical+fix +``` + +``` +https://app.plane.so/work-items/new?priority=Medium +``` ### assignee -Pre-fills the assignee(s) for the work item. Can be set by user **UUID**, **display name**, or use **me** to assign to the current user (the person opening the URL). Use comma-separated values to assign multiple users. +Assigns one or more team members to the work item. You can specify assignees by UUID, display name, or use `me` to assign to whoever opens the URL. For names with spaces, use `+` or `%20`. To assign multiple people, separate values with commas. + +Assign to yourself: + +``` +https://app.plane.so/work-items/new?assignee=me +``` + +Assign by display name: -For example, https://app.plane.so/work-items/new?assignee=me or https://app.plane.so/work-items/new?assignee=john or https://app.plane.so/work-items/new?assignee=Erin+Baker or https://app.plane.so/work-items/new?assignee=me,john,jane. +``` +https://app.plane.so/work-items/new?assignee=john +``` + +Assign by full name: + +``` +https://app.plane.so/work-items/new?assignee=Erin+Baker +``` + +Assign multiple people: + +``` +https://app.plane.so/work-items/new?assignee=me,john,jane +``` ### start_date -Pre-fills the start date for the work item. Accepts any valid date format that JavaScript `Date` can parse. Recommended formats: YYYY-MM-DD or ISO 8601. +Sets the start date. Use `YYYY-MM-DD` or ISO 8601 format for consistency, though any format that JavaScript's `Date` can parse will work. -For example, https://app.plane.so/work-items/new?start_date=2024-03-15. +``` +https://app.plane.so/work-items/new?start_date=2024-03-15 +``` ### due_date -Pre-fills the due date (target date) for the work item. Accepts any valid date format that JavaScript `Date` can parse. Recommended formats: YYYY-MM-DD or ISO 8601. +Sets the due date (also called target date). Same format rules as `start_date`. + +``` +https://app.plane.so/work-items/new?due_date=2024-03-30 +``` -For example, https://app.plane.so/work-items/new?due_date=2024-03-30. +## Examples -## Combined examples +**Bug report with title and description:** -**Simple work item with title and description:** +``` https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile +``` -**Work item with project, priority, and assignee:** +**High-priority task assigned to yourself:** + +``` https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug +``` **Fully populated work item:** -https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30 -## Notes - -- All query parameter values are case-insensitive where applicable (e.g., priority, project identifier). -- If a project identifier or user display name doesn't match any existing record, that parameter will be ignored. -- The user must be authenticated to use this URL. Unauthenticated users will be redirected to login first. -- After the modal opens, users can modify any pre-filled values before creating the work item. +``` +https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30 +``` + +## Things to know + +- **Authentication required** +Users must be logged in. If they're not, Plane redirects them to sign in first, then continues to the work item modal. +- **Invalid values are ignored** +If a project identifier or display name doesn't match an existing record, Plane skips that parameter and processes the rest. +- **Case doesn't matter** +Values like priority and project identifier are case-insensitive. +- **Users can still edit** +Pre-filled values aren't locked. After the modal opens, users can change any field before creating the work item. \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 0cf3722..994d1dc 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -120,8 +120,8 @@ const sidebars: SidebarsConfig = { items: [ "core-concepts/issues/overview", "core-concepts/issues/properties", - "core-concepts/drafts", "core-concepts/issues/work-item-url", + "core-concepts/drafts", ], },