Add documentation for aggregate view of saved objects by tenant in Dashboards

_security-plugin/access-control/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Access control
-nav_order: 10
+nav_order: 30
 has_children: true
 has_toc: false
 redirect_from:

_security-plugin/audit-logs/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Audit logs
-nav_order: 90
+nav_order: 40
 has_children: true
 has_toc: false
 redirect_from:

_security-plugin/multi-tenancy/mt-agg-view.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: Multi-tenancy aggregate view for saved objects
+parent: OpenSearch Dashboards multi-tenancy
+nav_order: 60
+---
+
+# OpenSearch Dashboards multi-tenancy aggregate view for saved objects
+
+Aggregate view for saved objects is an experimental feature released in OpenSearch 2.4. Therefore, we do not recommend enabling the feature in a production environment at this time. For updates on the progress of aggregate view for saved objects, or if you'd like to leave feedback that could help improve the feature, see the [Dashboards object sharing](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/2249) GitHub issue. For a more comprehensive view of the proposed future development of multi-tenancy, see the [Dashboards object sharing](https://github.com/opensearch-project/security/issues/1869) issue.
+{: .warning}
+
+Aggregate view for saved objects allows a user who has access to multiple tenants to see all saved objects associated with those tenants in a single view without having to switch between tenants to do so. This includes both tenants created by the user and tenants shared with the user. Aggregate view introduces a Tenant column in the Saved Objects table that gives the user the option to filter by tenants and make visible their associated saved objects.
+
+Once you identify a saved object of interest, you can then switch to that tenant to work with the object.
+
+To access saved objects, expand the top menu and select **Management > Stack Management > Saved Objects**. The Saved Objects window opens. By default, all tenants the user has permissions for are displayed along with all saved objects associated with the tenants.
+
+<img src="{{site.url}}{{site.baseurl}}/images/Security/agg-view-saved-objects.png" alt="Dashboards Saved Objects view with tenant object aggregation" width="700">
+
+As an experimental feature, aggregate view for saved objects is kept behind a feature flag and must be enabled in the `opensearch_dashboards.yml` file before the feature is made available. See [Enabling aggregate view](#enabling-aggregate-view-for-saved-objects) for more information.
+{: .note }
+
+### Feature benefits
+
+- Implementing an aggregate view for all saved objects on one screen allows you to quickly locate an object of interest and determine which tenant is associated with it. Once you locate an object, you can select the appropriate tenant and work with the object.
+- This feature also adds a Tenant column to the Saved Objects table, which allows you to filter the view by tenants and their associated saved objects.
+
+### Plans for future development
+
+In subsequent releases, we plan to expand the functionality of this feature to include the ability to perform actions directly from aggregate view and share items without having to first select a specific tenant. In the longer term, OpenSearch plans to evolve multi-tenancy so that it becomes a much more flexible tool for sharing objects among users and employs a more sophisticated way of assigning the roles and permissions that facilitate sharing. To learn more about the features being proposed for future releases, see the GitHub issue [Dashboards object sharing](https://github.com/opensearch-project/security/issues/1869).
+
+### Known limitations
+
+In this first experimental phase of development, there are some limitations that should be observed before enabling the feature and using it in a test environment:
+
+* The feature can only be used in a new cluster. At this time, the feature is not suported by clusters already in use.
+* Also, the feature should be used only in a test environment, not in production. 
+* Finally, once the feature has been enabled and used in a test cluster, the feature cannot be disabled for the cluster. Disabling the feature once it has been used to work with tenants and saved objects can result in the loss of saved objects and have an impact on tenant-to-tenant functionality. 
+
+These limitations will be addressed in upcoming releases.
+
+## Enabling aggregate view for saved objects
+
+By default, the aggregate view in the Saved Objects table is disabled. To enable the feature, add the `opensearch_security.multitenancy.enable_aggregation_view` flag to the `opensearch_dashboards.yml` and set it to `true`:
+
+`opensearch_security.multitenancy.enable_aggregation_view: true`
+
+After enabling the feature you can start the new cluster and then launch Dashboards. 
+
+## Working in aggregate view
+
+Select the Tenant dropdown arrow to display the list of tenants available to the user. You can select multiple tenants while the menu is open. Each time you select a tenant in the menu, the list of saved objects is filtered by that tenant and any others with a check mark beside their name.
+
+<img src="{{site.url}}{{site.baseurl}}/images/Security/tenant_column.png" alt="Dashboards Saved Objects view with emphasis on Tenants column" width="700">
+
+After you finish specifying tenants, select anywhere outside the menu to collapse it. The Title column displays the names of the available saved objects. The Tenant column displays the tenants associated with the saved objects. Also, the number of tenants selected for filtering is shown in a red box beside the Tenant dropdown menu label.
+
+<img src="{{site.url}}{{site.baseurl}}/images/Security/ten-filter-results.png" alt="Dashboards Saved Objects tenant filtering" width="700">
+
+Use the Type dropdown menu to filter saved objects by type. The behavior of the Type dropdown menu is the same as the behavior of the Tenant dropdown menu.
+
+### Selecting and working with a saved object
+
+After identifying a saved object that you would like to work with, follow these steps to access the object.
+
+1. Note the tenant associated with the object in the Tenant column.
+1. In the upper-right corner of the window, open the user menu and select **Switch tenants**.
+<img src="{{site.url}}{{site.baseurl}}/images/Security/switch_tenant.png" alt="Switching tenants in the user menu" width="425">
+1. In the **Select your tenant** window, choose either the Global or Private option, or one of the custom tenant options, to specify the correct tenant. Select the **Confirm** button. The tenant becomes active and is displayed in the user menu.
+1. After the tenant is active, you can use the controls in the Actions column to work with saved objects associated with the tenant.
+<img src="{{site.url}}{{site.baseurl}}/images/Security/actions.png" alt="Actions column controls" width="700">
+
+When a tenant is not active, you cannot use the Actions column controls to work with its associated objects. To work with those objects, follow the preceding steps to make the tenant active.
+{: .note }
+

_security-plugin/access-control/multi-tenancy.md → _security-plugin/multi-tenancy/multi-tenancy-config.md

@@ -1,33 +1,12 @@
 ---
 layout: default
-title: OpenSearch Dashboards multi-tenancy
-parent: Access control
-nav_order: 30
+title: Multi-tenancy configuration
+parent: OpenSearch Dashboards multi-tenancy
+nav_order: 55
 ---
 
-# OpenSearch Dashboards multi-tenancy
 
-*Tenants* in OpenSearch Dashboards are spaces for saving index patterns, visualizations, dashboards, and other OpenSearch Dashboards objects. Tenants are useful for safely sharing your work with other OpenSearch Dashboards users. You can control which roles have access to a tenant and whether those roles have read or write access. By default, all OpenSearch Dashboards users have access to two independent tenants:
-
-- **Private** - This tenant is exclusive to each user and can't be shared. You can't use it to access routes or index patterns made by the user's global tenant.
-- **Global** - This tenant is shared between every OpenSearch Dashboards user. 
-
-The global tenant is not a *primary* tenant such that any action done within the global tenant is not replicated to a user's private tenant. If you make a change to your global tenant, you won't see that change reflected in your private tenant. Some example changes include, but are not limited to:
-
-- Change advanced settings
-- Create visualizations
-- Create index patterns
-
-You might use the private tenant for exploratory work, create detailed visualizations with your team in an `analysts` tenant, and maintain a summary dashboard for corporate leadership in an `executive` tenant.
-
-If you share a visualization or dashboard with someone, you can see that the URL includes the tenant:
-
-```
-http://<opensearch_dashboards_host>:5601/app/opensearch-dashboards?security_tenant=analysts#/visualize/edit/c501fa50-7e52-11e9-ae4e-b5d69947d32e?_g=()
-```
-
-
-## Configuration
+# Multi-tenancy configuration
 
 Multi-tenancy is enabled by default, but you can disable it or change its settings using `config/opensearch-security/config.yml`:
 
@@ -166,3 +145,4 @@ The security plugin scrubs these index names of special characters, so they migh
 {: .tip }
 
 To back up your OpenSearch Dashboards data, [take a snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshots/snapshot-restore/) of all tenant indexes using an index pattern such as `.kibana*`.
+

_security-plugin/multi-tenancy/tenant-index.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: OpenSearch Dashboards multi-tenancy
+nav_order: 50
+has_children: true
+has_toc: false
+redirect_from:
+  - /security-plugin/multi-tenancy/
+---
+
+# OpenSearch Dashboards multi-tenancy
+
+*Tenants* in OpenSearch Dashboards are spaces for saving index patterns, visualizations, dashboards, and other OpenSearch Dashboards objects. Tenants are useful for safely sharing your work with other OpenSearch Dashboards users. You can control which roles have access to a tenant and whether those roles have read or write access. By default, all OpenSearch Dashboards users have access to two independent tenants:
+
+- **Private** - This tenant is exclusive to each user and can't be shared. You can't use it to access routes or index patterns made by the user's global tenant.
+- **Global** - This tenant is shared between every OpenSearch Dashboards user. 
+
+The global tenant is not a *primary* tenant such that any action done within the global tenant is not replicated to a user's private tenant. If you make a change to your global tenant, you won't see that change reflected in your private tenant. Some example changes include, but are not limited to:
+
+- Change advanced settings
+- Create visualizations
+- Create index patterns
+
+You might use the private tenant for exploratory work, create detailed visualizations with your team in an `analysts` tenant, and maintain a summary dashboard for corporate leadership in an `executive` tenant.
+
+If you share a visualization or dashboard with someone, you can see that the URL includes the tenant:
+
+```
+http://<opensearch_dashboards_host>:5601/app/opensearch-dashboards?security_tenant=analysts#/visualize/edit/c501fa50-7e52-11e9-ae4e-b5d69947d32e?_g=()
+```
+
+## Next steps
+
+To get started with tenants, see [Multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security-plugin/multi-tenancy/multi-tenancy-config/) for information on enabling multi-tenancy, adding tenants, and assigning roles to tenants.   
+