From 070b379b695aa16c221df197888c176694a1a3b7 Mon Sep 17 00:00:00 2001
From: abbyhu2000 <abigailhu2000@gmail.com>
Date: Thu, 1 Dec 2022 20:41:51 +0000
Subject: [PATCH] Add readme for global query persistence

Signed-off-by: abbyhu2000 <abigailhu2000@gmail.com>
---
 .../docs/global_query_param.md                | 89 +++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 src/plugins/opensearch_dashboards_utils/docs/global_query_param.md

diff --git a/src/plugins/opensearch_dashboards_utils/docs/global_query_param.md b/src/plugins/opensearch_dashboards_utils/docs/global_query_param.md
new file mode 100644
index 000000000000..2a405f32e1a0
--- /dev/null
+++ b/src/plugins/opensearch_dashboards_utils/docs/global_query_param.md
@@ -0,0 +1,89 @@
+### Global query parameters
+
+Current there are five plugins that have implemented global data persistence ability in Opensearch Dashboards, and they are visualize, discover, timeline, dashboards, and vis-builder. Global query parameters include globally pinned filters, time range and time refresh intervals. These parameters are not only persisted across the action of refresh, but also persisted among all the plugins that have global data persistence ability. 
+
+For example, we set a specific time range and time refresh interval when trying to a new visualization. When we navigate to the dashboard page, we can see the previous time range and time refresh interval that are set within the visualization app are still there. However, when we create a filter, it will only be persisted within that specific plugin since it is not a global filter. We can make a filter become a global filter by selecting 
+`Pin across all apps`. Only global filters are persisted across all other globally persistent plugins within the application.
+
+### Steps to add global data persistence ability to a plugin
+
+1. Add `createOsdUrlStateStorage` in the set up function within public/plugin.ts 
+    * declare two private variables: `appStateUpdater` observable and `stopUrlTracking()`
+    ```ts
+    private appStateUpdater = new BehaviorSubject<AppUpdater>(() => ({}));
+    private stopUrlTracking?: () => void;
+    ```
+    * within the `setup()` function in the plugin class, call `createOsdUrlStateStorage` by passing in the corresponding baseUrl, defaultSubUrl, storageKey, navLinkUpdater observable and stateParams. StorageKey should follow format: `lastUrl:${core.http.basePath.get()}:pluginID`. 
+      - `this.appStateUpdater` is passed into the function as `navLinkUpdater`. 
+      - return three functions `appMounted()`, `appUnMounted()` and `stopUrlTracker()`. Then class variable `stopUrlTracking()` is set to be `stopUrlTracker()`
+    * call `appMounted()` in the `mount()` function
+    * call `appUnMounted()` in return of `mount()`
+    * call `stopUrlTracking()` in `stop()` function for the plugin
+
+```ts
+const { appMounted, appUnMounted, stop: stopUrlTracker } = createOsdUrlTracker({
+          baseUrl: core.http.basePath.prepend('/app/vis-builder'),
+          defaultSubUrl: '#/',
+          storageKey: `lastUrl:${core.http.basePath.get()}:vis-builder`,
+          navLinkUpdater$: this.appStateUpdater,
+          toastNotifications: core.notifications.toasts,
+          stateParams: [
+            {
+              osdUrlKey: '_g',
+              stateUpdate$: data.query.state$.pipe(
+                filter(
+                  ({ changes }) =>
+                    !!(changes.globalFilters || changes.time || changes.refreshInterval)
+                ),
+                map(({ state }) => ({
+                  ...state,
+                  filters: state.filters?.filter(opensearchFilters.isFilterPinned),
+                }))
+              ),
+            },
+          ],
+          getHistory: () => {
+            return this.currentHistory!;
+          },
+        });
+        this.stopUrlTracking = () => {
+          stopUrlTracker();
+        };
+```
+
+2. Set osdUrlStateStorage service 
+    * when setting the plugin services, set osdUrlStateStorage service by calling `createOsdUrlStateStorage()` with the current history, useHash and withNotifyErrors
+
+```ts
+
+```
+
+3. Syncing query state with URL in public/app.tsx
+    * import `syncQueryStateWithUrl` from data plugin and call it with query service and osdUrlStateStorage service that we set in step 2
+
+```ts
+    export const VisBuilderApp = () => {
+  const {
+    services: {
+      data: { query },
+      osdUrlStateStorage,
+    },
+  } = useOpenSearchDashboards<VisBuilderServices>();
+  const { pathname } = useLocation();
+
+  useEffect(() => {
+    // syncs `_g` portion of url with query services
+    const { stop } = syncQueryStateWithUrl(query, osdUrlStateStorage);
+
+    return () => stop();
+
+    // this effect should re-run when pathname is changed to preserve querystring part,
+    // so the global state is always preserved
+  }, [query, osdUrlStateStorage, pathname]);
+  ```
+
+  4. If not, add query services from data plugin
+    * in public/plugin_services.ts, add query services
+    ```ts
+    export const [getQueryService, setQueryService] = createGetterSetter<DataPublicPluginStart['query']>('Query');
+    ```