diff --git a/api-reference/epics/get-epic-detail.mdx b/api-reference/epics/get-epic-detail.mdx new file mode 100644 index 0000000..9ce095b --- /dev/null +++ b/api-reference/epics/get-epic-detail.mdx @@ -0,0 +1,20 @@ +--- +title: Retrieve an epic +description: Retrieves the details of an existing epic by its ID. +api: GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/epics/{epic_id}/ +--- + +## Path parameters + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + The unique identifier for the project. + + + + The unique identifier for the epic. + + diff --git a/api-reference/epics/list-epics.mdx b/api-reference/epics/list-epics.mdx new file mode 100644 index 0000000..936a6af --- /dev/null +++ b/api-reference/epics/list-epics.mdx @@ -0,0 +1,26 @@ +--- +title: List all epics +description: Returns a list of all epics in a project. +api: GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/epics/ +--- + +## Path parameters + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + The unique identifier for the project. + + +## Query parameters + + +Number of results to return per page. + + + +Number of results to skip for pagination. + + diff --git a/api-reference/epics/overview.mdx b/api-reference/epics/overview.mdx new file mode 100644 index 0000000..c79c13b --- /dev/null +++ b/api-reference/epics/overview.mdx @@ -0,0 +1,169 @@ +--- +title: Overview +--- + +Epics help you group related tasks into a larger work item, providing a hierarchical structure for managing complex projects. Use epics to break down major objectives into smaller, manageable pieces while keeping everything organized. +[Learn more about Epics](https://docs.plane.so/core-concepts/issues/epics). + +## The Epics object +**Attributes** + +- `id` string + + Unique identifier for the epic. + +- `name` string + + Name of the epic. + +- `description` object + + JSON representation of the epic description. + +- `description_html` string + + HTML-formatted description of the epic. + +- `description_stripped` string + + Plain text version of the description. + +- `description_binary` string + + Binary representation of the description. + +- `state` string + + ID of the state (status) of the epic. + +- `priority` string + + Priority level. Possible values: `none`, `urgent`, `high`, `medium`, `low`. + +- `assignees` array + + Array of user IDs assigned to the epic. + +- `labels` array + + Array of label IDs applied to the epic. + +- `type` string + + ID of the work item type for the epic. + +- `estimate_point` string + + ID of the estimate point, or null if not estimated. + +- `point` integer + + Point value for the epic, or null. + +- `start_date` string + + Start date of the epic in YYYY-MM-DD format. + +- `target_date` string + + Target completion date in YYYY-MM-DD format. + +- `parent` string + + ID of the parent work item, or null if no parent. + +- `sequence_id` integer + + Auto-generated sequential identifier for the epic within the project. + +- `sort_order` number + + Auto-generated sort order for display purposes. + +- `is_draft` boolean + + Whether the epic is a draft. + +- `completed_at` timestamp + + Time at which the epic was completed, or null if not completed. + +- `archived_at` timestamp + + Time at which the epic was archived, or null if not archived. + +- `project` string + + ID of the project containing this epic. + +- `workspace` string + + ID of the workspace containing this epic. + +- `external_id` string + + External identifier if imported from another system, or null. + +- `external_source` string + + Name of the source system if imported, or null. + +- `deleted_at` timestamp + + Time at which the epic was deleted, or null if not deleted. + +- `created_at` timestamp + + Time at which the epic was created. + +- `updated_at` timestamp + + Time at which the epic was last updated. + +- `created_by` string + + ID of the user who created the epic. + +- `updated_by` string + + ID of the user who last updated the epic. + + +```json EPICS OBJECT +{ + "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "name": "Develop Mobile Application Framework", + "description": {}, + "description_html": "

Create a cross-platform mobile application framework that supports all core system functionalities with native-like performance and user experience

", + "description_stripped": "Create a cross-platform mobile application framework that supports all core system functionalities with native-like performance and user experience", + "description_binary": null, + "state": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "priority": "medium", + "assignees": [], + "labels": [ + "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + ], + "type": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "estimate_point": null, + "point": null, + "start_date": "2025-02-28", + "target_date": "2025-06-20", + "parent": null, + "sequence_id": 57, + "sort_order": 605535.0, + "is_draft": false, + "completed_at": null, + "archived_at": null, + "project": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "workspace": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "external_id": null, + "external_source": null, + "deleted_at": null, + "created_at": "2025-03-01T21:23:54.645263+05:30", + "updated_at": "2025-03-03T10:38:44.667276+05:30", + "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "updated_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +} +``` + \ No newline at end of file diff --git a/api-reference/initiative/overview.mdx b/api-reference/initiative/overview.mdx index a721134..be71d3b 100644 --- a/api-reference/initiative/overview.mdx +++ b/api-reference/initiative/overview.mdx @@ -6,7 +6,7 @@ Initiatives are high-level strategic goals that help organize and track work acr [Learn more about Initiatives](https://docs.plane.so/core-concepts/projects/initiatives) -## The Initiative object +## The Initiatives object **Attributes** diff --git a/mint.json b/mint.json index 0c9ebf9..334e606 100644 --- a/mint.json +++ b/mint.json @@ -358,6 +358,14 @@ "api-reference/worklogs/delete-worklog" ] }, + { + "group": "Epics", + "pages": [ + "api-reference/epics/overview", + "api-reference/epics/list-epics", + "api-reference/epics/get-epic-detail" + ] + }, { "group": "Initiatives", "pages": [ diff --git a/self-hosting/govern/database-and-storage.mdx b/self-hosting/govern/database-and-storage.mdx index 833c050..e28e838 100644 --- a/self-hosting/govern/database-and-storage.mdx +++ b/self-hosting/govern/database-and-storage.mdx @@ -6,7 +6,12 @@ sidebarTitle: External database and storage The Prime CLI lets you easily configure your Commercial Edition instance, providing options to customize the PostgreSQL database, Redis, external storage, and other advanced settings. -1. Run the Prime CLI with ↓: + +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. + + +1. Run the Prime CLI with ↓: + ```sudo prime-cli``` 2. Once the CLI is running, enter `configure`, which will guide you through a step-by-step form where you can specify the following: diff --git a/self-hosting/govern/oidc-sso.mdx b/self-hosting/govern/oidc-sso.mdx index ef96148..27c19f9 100644 --- a/self-hosting/govern/oidc-sso.mdx +++ b/self-hosting/govern/oidc-sso.mdx @@ -48,7 +48,7 @@ Go to `/god-mode/authentication/oidc` on your Plane app and find the configs ↓ - Copy the `User info URL` from your IdP and paste it into the field for it on `/god-mode/authentication/oidc/`. - Used to get an authenticating user's `email`, `first_name` and the `last_name` values from the IdP, this too can be copied over from the `.well-known/` directory. + Used to get an authenticating user's information from the IdP. Plane requires the `email` field for user authentication. The `first_name` and `last_name` fields are optional but recommended for a complete user profile. This URL can be copied from the `.well-known/` directory. - Copy the `Authorize URL` over from the `.well-known/` directory and paste it into the field for it on Plane's `/god-mode/authentication/oidc/`.\ This is the URL that Plane's login screen redirects to when your users click `Sign up with ` or `Login with `. diff --git a/self-hosting/govern/reverse-proxy.mdx b/self-hosting/govern/reverse-proxy.mdx index 33c17a2..e124c5d 100644 --- a/self-hosting/govern/reverse-proxy.mdx +++ b/self-hosting/govern/reverse-proxy.mdx @@ -25,6 +25,10 @@ Make sure to update the following environment variables in your plane.env file. ```bash sudo prime-cli restart ``` + + +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. + ## Proxy setup diff --git a/self-hosting/govern/saml-sso.mdx b/self-hosting/govern/saml-sso.mdx index d9cd150..1cf2f78 100644 --- a/self-hosting/govern/saml-sso.mdx +++ b/self-hosting/govern/saml-sso.mdx @@ -43,6 +43,11 @@ By default, your IdP will send the value listed under `Property`. You have to ma | user.lastName | last_name | | user.email | email | + +**first_name** and **last_name** are optional but recommended for complete user profiles. If these are not provided, Plane will create the user account with just the email address. + + + Depending on your IdP, you will have to find both the `Name ID format` and the three other user identification properties on different screens. Please refer to your IdP's documentation when configuring these up on your IdP. Additionally, you may have to configure the IdP to sign assertions. Irrespective of that, you have to copy the signing certificate from the IdP. diff --git a/self-hosting/manage/backup-restore.mdx b/self-hosting/manage/backup-restore.mdx index 91b7563..9019664 100644 --- a/self-hosting/manage/backup-restore.mdx +++ b/self-hosting/manage/backup-restore.mdx @@ -7,6 +7,10 @@ Backing up your data regularly helps prevent data loss and allows you to restore ## Backup data + +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. + + Create a backup of your Plane data with ↓: ```bash sudo prime-cli backup diff --git a/self-hosting/manage/migrate-plane.mdx b/self-hosting/manage/migrate-plane.mdx index 7312ea9..30a7773 100644 --- a/self-hosting/manage/migrate-plane.mdx +++ b/self-hosting/manage/migrate-plane.mdx @@ -27,6 +27,10 @@ Create a backup of your Plane instance with ↓: ``` This command will generate a backup file in the path: `/opt/plane/backups`. + + **Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. + + 3. **Set up Plane on the new server** Follow the [installation guide](/self-hosting/methods/docker-compose#install-plane) to deploy Plane on the new instance. diff --git a/self-hosting/manage/prime-cli.mdx b/self-hosting/manage/prime-cli.mdx index f4b7112..153b950 100644 --- a/self-hosting/manage/prime-cli.mdx +++ b/self-hosting/manage/prime-cli.mdx @@ -7,12 +7,13 @@ Our command-line tool is here to make managing your Plane instance simple. You c ## Prime CLI • Commercial Edition - -If you are on the Community edition and want to upgrade to the Commercial edition, see [Upgrade to Commercial Edition](/self-hosting/upgrade-from-community). - The Prime CLI provides commands for common tasks like configuring services, monitoring health, managing backups, and upgrading your Plane instance. + +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. + + Bring up the Prime CLI with ```sudo prime-cli``` from any directory on your machine. - The three operators you will use the most are: diff --git a/self-hosting/manage/upgrade-plane.mdx b/self-hosting/manage/upgrade-plane.mdx index 64d368a..f2b52f5 100644 --- a/self-hosting/manage/upgrade-plane.mdx +++ b/self-hosting/manage/upgrade-plane.mdx @@ -21,6 +21,8 @@ You can quickly check your Plane version by clicking the **?** icon on the sideb For Commercial Edition v1.13.0, ensure you're using the **latest version of Docker Compose**. Check your Docker Compose version with `docker-compose --version` and update if needed. + +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. diff --git a/self-hosting/manage/view-logs.mdx b/self-hosting/manage/view-logs.mdx index 798eb9b..7564e58 100644 --- a/self-hosting/manage/view-logs.mdx +++ b/self-hosting/manage/view-logs.mdx @@ -13,6 +13,10 @@ This brings up a table where you can select which container logs you want to vie ![Container logs](/images/view-logs/container-logs.webp) + +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. + + Here’s how to view logs for any service in Plane Community Edition, whether it’s the API, Worker, Redis, or others. This can be really helpful when troubleshooting or just getting insights into how each service is running. diff --git a/self-hosting/troubleshoot/license-errors.mdx b/self-hosting/troubleshoot/license-errors.mdx index 4ddad10..3bbb683 100644 --- a/self-hosting/troubleshoot/license-errors.mdx +++ b/self-hosting/troubleshoot/license-errors.mdx @@ -4,6 +4,12 @@ title: License errors This guide is designed to help you resolve common issues encountered while activating the license key for a workspace. Each section includes potential causes and step-by-step solutions for identified problems. +## Before troubleshooting + +**Try syncing your plan first.** Many license issues resolve automatically when your workspace pulls the latest subscription information from the Prime server. See [Sync plan](/workspaces-and-users/manage-licenses#sync-plan) for details. + +If the issue persists after syncing or you see other errors, continue with the specific error troubleshooting below. + ## License is invalid