Add workspace documentation

Signed-off-by: Yulong Ruan <ruanyl@amazon.com>

docs/plugins/workspace.md

@@ -0,0 +1,171 @@
+# Workspace
+Workspace is a pivotal feature within OpenSearch-Dashboards, empowering users to craft distinct workspaces 
+by meticulously curating a selection of features and plugins tailored to specific use cases. This functionality
+not only facilitates clients in the systematic organization of visual assets, including saved_objects such as
+dashboards and visualizations, but also categorizes them logically within dedicated workspaces. This strategic
+approach enhances overall efficiency and manageability, making it an indispensable asset for OpenSearch-Dashboards
+users seeking precision and flexibility in their workflows.
+
+## Scopes
+In an OpenSearch cluster, when viewed from the perspective of OpenSearch Dashboards (OSD), data can be categorized
+into two primary types:
+
+1. OSD Metadata: This category includes critical OSD metadata, which is stored in a metadata store. Examples of OSD
+    metadata includes visualizations, dashboards, index patterns, UI settings, etc.
+2. Other OpenSearch Indices: In addition to OSD metadata, an OpenSearch cluster may contain various other OpenSearch
+    indices for storing data unrelated to OSD.
+
+The concept of a "workspace" in OSD is primarily concerned with the management and organization of OSD metadata (Type #1).
+Workspaces do not encompass the management of data stored by plugins that maintain their independent data stores within
+the OpenSearch cluster. If a plugin requires the creation of data specific to a workspace, it must store this data within
+the OSD metadata store using Saved Objects. Within OSD workspaces, our focus remains squarely on OSD metadata.
+
+## Workspace data model
+The Workspace data model defines the fundamental structure for managing isolated environments dedicated to metadata
+management within OpenSearch Dashboards.
+
+```typescript
+interface Workspace {
+  id: string
+  name: string
+  description?: string
+  features?: string[]
+  reserved?: boolean
+}
+```
+
+1. `id`: A unique identifier that distinguishes each workspace.
+2. `name`: The name of the workspace.
+3. `description`: A description providing context for the workspace.
+4. `features`: An array of application IDs associated with the workspace, derived from the plugins registered. These application IDs
+    are used to filter and display the relevant plugins in the left navigation menu when accessing the workspace. It serves as a visual
+    mechanism for organizing and presenting features.
+6. `reserved`: A boolean flag indicating whether the workspace is system-reserved. System-reserved workspaces may have certain operations
+    restricted for end users.
+
+
+**Workspace object example 1:**
+```typescript
+{
+  id: "M5NqCu",
+  name: "Sales team",
+  description: "dashboards of sale analytics",
+  features: ["dashboards", "visualize"],
+  reserved: false
+}
+```
+
+Example #1 represents a workspace typically created by a user, with the reserved flag set to false. This user-created workspace can be
+customized with specific features tailored to its purpose.
+
+**Workspace object example 2:**
+```typescript
+{
+  id: "management",
+  name: "Management",
+  description: "Management workspace for OSD admin",
+  features: ["@management", "dataSources", "dev_tools"],
+  reserved: true
+}
+```
+
+Example #2 is a system-reserved workspace, automatically generated by the workspace plugin for the user. The reserved flag is set to true.
+This workspace includes the `@management` category, which includes all features within that category. The `@` symbol indicates that it is a
+category. The `management` is the category id which the plugins specified when register applications.
+
+## Associate saved objects with workspaces
+Saved objects, such as dashboards, visualizations, and index patterns, form the backbone of data visualization and analysis in OpenSearch Dashboards.
+However, as the volume of saved objects grows, keeping them organized becomes increasingly challenging. Grouping saved objects into distinct workspaces,
+each serving a specific purpose or team. This association not only simplifies the process of finding and accessing relevant saved objects but also
+enhances security and access control (Please ref to this [DOC](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633) for more details
+about access control).
+
+A new attribute, `workspaces`, is being added to saved objects which type is an array of string. A saved object can be associated with one
+or multiple workspaces. The saved objects(dashboards, visualizations, etc) will only be displayed in the associated workspaces.
+
+The follow example shows the dashboard object is associated with workspace which id is `M5NqCu`
+```typescript
+{
+  type: "dashboard",
+  id: "da123f20-6680-11ee-93fa-df944ec23359",
+  workspaces: ["M5NqCu"]
+}
+```
+
+Saved object can also associated with multiple workspaces, this is useful in scenarios where a saved object is relevant
+to multiple teams, projects, or use cases.
+
+Consider the following example, where a visualization is associated with multiple workspaces:
+```typescript
+{
+  type: "visualization",
+  id: "da123f20-6680-11ee-93fa-df944ec23359",
+  workspaces: ["M5NqCu", "<TeamA-workspace-id>", "<Analytics-workspace-id>"]
+}
+```
+By allowing saved objects to be linked with multiple workspaces, this enables users to share and collaborate on resources
+across various workspaces(teams).
+
+## Copy saved objects among workspaces
+While associating saved objects with multiple workspaces links a single object instance to multiple places, copying saved 
+objects takes a different approach. When copying objects, it creates hard copies of the objects in the target workspace,
+regardless of their original workspaces.
+
+For example, if copy this object to `<target-workspace>`
+```typescript
+{
+  type: "visualization",
+  id: "da123f20-6680-11ee-93fa-df944ec23359",
+  workspaces: ["M5NqCu", "<TeamA-workspace-id>", "<Analytics-workspace-id>"]
+}
+```
+Then a new object will be created with new `id` and associated with `<target-workspace>`
+```typescript
+{
+  type: "visualization",
+  id: "<new-object-id>",
+  workspaces: ["<target-workspace>"]
+}
+```
+### Handling Dependencies
+A significant aspect of copying saved objects is the handling of dependencies. Many saved objects, particularly
+visual objects like dashboards and visualizations, often have a hierarchical structure with dependencies.
+For example, a dashboard may depend on multiple visualizations, and each visualization may rely on specific
+index pattern objects.
+
+The copying process is not limited to the saved object itself. Instead, it copies the entire dependency hierarchy
+associated with the saved object. For example:
+1. If the visualization depends on specific index pattern objects, these index pattern objects will also be duplicated
+    in `<target-workspace>`.
+2. If the dashboard depends on multiple visualizations, those visualizations and their associated index patterns will
+    be copied as well.
+
+This ensures that the copied saved object in <target-workspace> retains its functionality and context, with all necessary
+dependencies in place.
+
+## Reserved workspaces
+Reserved workspaces are created automatically by workspace plugin, they have pre-defined configurations, including features
+and permissions tailored to their intended purposes. Currently, workspace plugin creates three distinct reserved workspace:
+
+1. Global Workspace
+   - **Purpose**: The Global Workspace serves as a centralized environment for managing resources and configurations that apply
+      globally across OpenSearch Dashboards.
+   - **Features**: It includes features that are accessible to all users, regardless of their specific teams or projects.
+   - **Permissions**: All users have `read` and `write` permission to public workspace and its associated saved objects.
+2. Personal Workspace
+   - **Purpose**: The Personal Workspace is designed to provide individual users with a dedicated space for their personal work.
+      However, it's important to note that a **Personal Workspace will only be created if user/role information can be retrieved**.
+   - **Features**: Users have the flexibility to configure their Personal Workspace according to their preferences and requirements. 
+   - **Permissions**: Access to the Personal Workspace is limited to the user who owns it, ensuring data privacy and personalization.
+3. Management Workspace
+   - **Purpose**: The Management Workspace is dedicated to administrative tasks and configurations within OpenSearch Dashboards.
+   - **Features**: It encompasses features and tools necessary for system administrators to manage OSD advanced settings, data sources
+     , and other administrative functions such as security configuration, etc.
+   - **Permissions**: Initially, access to the Management Workspace is set to public during initialization, administrators have the
+      responsibility and privilege to restrict access and define permissions within the Management Workspace.
+
+
+
+
+
+