Skip to content

Commit

Permalink
update workspace documention
Browse files Browse the repository at this point in the history
  • Loading branch information
@ruanyl
ruanyl authored Jul 31, 2024
1 parent 606ea40 commit 690c324
Showing 1 changed file with 35 additions and 101 deletions.
136 changes: 35 additions & 101 deletions src/plugins/workspace/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,18 @@
# Workspace
Workspace is a significant feature in OpenSearch-Dashboards, allowing users to create customized workspaces by
selecting specific features and plugins that align with their particular use cases. This feature helps users
organize visual assets, such as saved_objects like dashboards and visualizations, in a structured manner within
dedicated workspaces. This approach aims to improve efficiency and manageability, making it a valuable tool for
OpenSearch-Dashboards users who want a more precise and flexible workflow.
The workspace feature allows users to customize their OpenSearch-Dashboards experience with curated use cases, for example, user can create a workspace particularly for observability use case so that they can concentrate on observability related functionaties. Also, workspace helps users organize visual assets, such as dashboards and visualizations, such assets are isolated by workspace. This makes it a valuable tool for OpenSearch-Dashboards users who want a more precise and flexible workflow.

## 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.
The workspace only cares about data stored via saved objects(OSD metadata). The management of data stored by plugins that maintain their independent data stores within their own OpenSearch indexes is OUT OF THE SCOPE.

## Workspace data model
The Workspace data model defines the fundamental structure for managing isolated environments dedicated to metadata
management within OpenSearch Dashboards.
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
}
```

Expand All @@ -39,38 +22,24 @@ interface 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:**
**Workspace object example**
```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
name: "Observability team",
description: "Observability team workspace",
features: ["use-case-observability"],
}
```

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.
The above object defines a workspace with name `Observability team` that's create with `observability` features by specifying an use case `use-case-observability`. An use case maps to multiple predefined OSD features, only the defined features will be available within the workspace. Use case strings are predefined, there are five types of use cases, except `use-case-all` which all features are available, the other four types of use cases have curated features defined:
1. `use-case-observability`
2. `use-case-security-analytics`
3. `use-case-search`
4. `use-case-analytics`
5. `use-case-all`

## 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.
Expand All @@ -79,8 +48,7 @@ each serving a specific purpose or team. This association not only simplifies th
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.
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 showed up in the associated workspaces.

The follow example shows the dashboard object is associated with workspace which id is `M5NqCu`
```typescript
Expand All @@ -91,45 +59,37 @@ The follow example shows the dashboard object is associated with workspace which
}
```

Saved object can also be associated with multiple workspaces, this is useful in scenarios where a saved object is relevant
to multiple teams, projects, or use cases.
Saved object can also be 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:
Consider the following example, where a data source is associated with multiple workspaces:
```typescript
{
type: "visualization",
type: "data-source",
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).
By allowing saved objects to be linked with multiple workspaces, this enables users to share and collaborate on resources across various workspaces(teams).

## Non-workspace saved objects
While the introduction of workspaces in OSD provides a powerful framework for organizing and managing saved objects, it's
important to note that not all saved objects are necessarily associated with workspaces. Some saved objects, by their
nature or purpose, may exist independently of workspaces.
While the introduction of workspaces in OSD provides a powerful framework for organizing and managing saved objects, it's important to note that not all saved objects are necessarily associated with workspaces. Some saved objects, by nature or purpose, may exist independently of workspaces.

For example, the global UI settings object. This object contains configurations and settings that apply globally across
OSD, affecting the overall user interface and user experience. These settings are not tied to any specific workspace
because they are intended to impact the entire OSD. Such objects won't have `workspaces` attribute.
For example, the global UI settings object. This object contains configurations and settings that apply globally across OSD, affecting the overall user interface and user experience. These settings are not tied to any specific workspace because they are intended to impact the entire OSD. Such objects won't have `workspaces` attribute.

The coexistence of workspace-associated saved objects and those without workspace association ensures that OSD strikes
a balance between context-specific customization and system-wide consistency.
The coexistence of workspace-associated saved objects and those without workspace association ensures that OSD strikes a balance between context-specific customization and system-wide consistency.

## Duplicate saved objects among workspaces
While associating saved objects with multiple workspaces links a single object instance to multiple places, duplicating saved
objects takes a different approach. When duplicating objects, it creates hard copies of the objects in the target workspace,
regardless of their original workspaces.
When duplicating objects, it creates hard copies of the objects in the target workspace, regardless of their original workspaces.

For example, if duplicate this object to `<target-workspace>`
For example, if duplicate the following 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
{
Expand All @@ -138,45 +98,19 @@ Then a new object will be created with new `id` and associated with `<target-wor
workspaces: ["<target-workspace>"]
}
```

### Handling Dependencies
A significant aspect of duplicating 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 duplicating process is not limited to the saved object itself. The user has the flexibility to choose whether
or not to duplicate the entire dependency tree. If duplicating the entire dependency hierarchy, all dependencies
will be duplicated. 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 global 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, such as
index management, security configuration, snapshot management, 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.
A significant aspect of duplicating 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 duplicating process is not limited to the saved object itself. The user has the flexibility to choose whether or not to duplicate the entire dependency tree. If duplicating the entire dependency hierarchy, all dependencies will be duplicated. 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.

Please note that when multiple data source is enabled, duplicating saved objects to another workspace will not take the data source into consideration. Data source is a special type of object that cannot be duplicated but can only be manually assigned to a workspace.

## Appendix
1. The PR the introduce [object access control](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/5083)
2. The [PR](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633/files) of the design doc for saved object access control
3. Future Vision for Dashboards: [Issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/4298)
3. Future Vision for Dashboards: [Issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/4298)

0 comments on commit 690c324

Please sign in to comment.