DOC-11398 sample bucket loading status

modules/introduction/partials/new-features-76.adoc

@@ -45,6 +45,10 @@ See xref:rest-api:rest-auditing.adoc[Configure Auditing].
 * You can add one or more arbiter nodes to a cluster.
 include::learn:partial$arbiter-node-benefits.adoc[]
 
+* The `sampleBuckets/install` REST API method now returns a JSON object containing the list of tasks Couchbase Server started to load the buckets.
+In addition, the `/pools/default/tasks` REST API endpoint now takes an optional `taskId` parameter to view details about a sample bucket loading task.
+See xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-rest-api[Install Sample Buckets with the REST API] for more information.
+
 === Backup and Restore
 
 * The Role-Based Access Control (RBAC) REST API has a new `backup` endpoint that lets you backup and restore user and user groups. See xref:rest-api:rbac.adoc#backup-and-restore-users-and-groups[Backup and Restore Users and Groups].

modules/manage/pages/manage-settings/install-sample-buckets.adoc

@@ -1,5 +1,5 @@
 = Sample Buckets
-:description: Sample buckets contain scopes, collections, and documents that are ready to be experimented with.
+:description: You can install buckets containing example scopes, collections, and documents that you can experiment with.
 :page-aliases: settings:install-sample-buckets
 
 [abstract]
@@ -8,45 +8,20 @@
 [#configuring-sample-buckets]
 == Sample Buckets
 
-Sample buckets contain data for experimental use.
-Sample buckets are referred to in code and command-line examples throughout Couchbase-Server documentation.
-
-Full and Cluster administrators can install sample buckets with xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-ui[Couchbase Web Console] and the xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-rest-api[REST API].
+Full and Cluster administrators can install sample buckets using the xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-ui[Couchbase Server Web Console] and the xref:manage:manage-settings/install-sample-buckets.adoc#install-sample-buckets-with-the-rest-api[REST API].
 
 [#scopes-collection-and-sample-buckets]
 === Scopes, Collections, and Sample Buckets
 
-Couchbase Server Version 7.0 introduces xref:learn:data/scopes-and-collections.adoc[Scopes and Collections], which allow data within a bucket to be organized according to type.
-Buckets created and used on previous versions of the server, after upgrade to 7.x, initially have all their data within the _default_ collection, which is itself within the _default_ scope.
-From this point, data can be selectively migrated from the default collection into other, administrator-defined collections.
-
-Each sample bucket provided with 7.x contains its data _either_:
-
-* Entirely within the default scope and collection.
-These buckets are `beer-sample` and `gamesim-sample`.
-
-* Within multiple scopes and collections that have been pre-defined to exist in addition to the default scope and collection; _and_ within the default scope and collection also.
-This is the configuration provided for the `travel-sample` bucket.
-In total, _seven_ scopes exist within this bucket:
-
-** `_default`.
-This contains the `_default` collection; within which all documents reside.
-The `_default` collection therefore itself contains all documents that existed in pre-7.0 versions of the `travel-sample` bucket.
-
-** `inventory`.
-This also contains all documents that existed in pre-7.0 versions of the `travel-sample` buckets, but in a different configuration: here, the documents are distributed, according to type, across five collections; which are named `airline`, `airport`, `landmark`, `hotel`, and `route`.
+xref:learn:data/scopes-and-collections.adoc[Scopes and Collections] let you organize data within a bucket by type.
+The  `beer-sample` and `gamesim-sample` sample buckets store all of their data in the default scope.
+The `travel-sample` bucket contains data in six scopes in addition to the `_default` scope.
+These additional scopes define several collections. 
+The `inventory` scope has collections that organize travel data such as airlines and airports.
+The data within the `tenant_agent_00` through `tenant_agent_04` scopes let you experiment with multi-tenancy applications.
 
-** `tenant_agent_00` to `tenant_agent_04`.
-Each of these five scopes contains two collections; which are named `users` and `bookings`.
-
-Since all three sample buckets contain, in their default collection, all data they held in pre-7.0 versions of Couchbase Server, programs written to access this data in its original locations will be able to continue doing so with minimal adjustment.
-All three buckets can also be used for experiments with _migration_, whereby the data is selectively redistributed into administrator-created collections.
-See xref:manage:manage-xdcr/replicate-using-scopes-and-collections.adoc#migrate-data-to-a-collection-with-the-ui[Migrate Data to a Collection with the UI].
-
-The `travel-sample` bucket contains travel-related data already in migrated form, within the collections in the scope `inventory`.
-The bucket can thus be used for immediate experimentation with application-access to scopes and collections.
-
-The `travel-sample` bucket also contains data within the `tenant_agent` scopes, which is appropriate for experimentation with _multi-tenancy-based_ application access.
+NOTE: The `_default` scope of the `travel_sample` bucket duplicates all of the data stored in the `inventory` and `tenant_agent_00` through `tenant_agent_04` scopes.
+This duplication makes the bucket compatible with scripts and applications written for versions of Couchbase Server earlier than 7.0 that did not support scopes and collections.
 
 [#install-sample-buckets-with-the-ui]
 == Install Sample Buckets with the UI
@@ -56,9 +31,9 @@ The *Sample Buckets* screen now appears, as follows:
 
 image::manage-settings/settings-samples.png[,720,align=left]
 
-Note that if one or more sample buckets have already been loaded, they are listed under the *Installed Samples* section of the page.
+If one or more sample buckets are already loaded, they're listed under the *Installed Samples* section of the page.
 
-For information on assigning roles to users, so as to enable them to access sample buckets following installation, see xref:manage:manage-security/manage-users-and-roles.adoc[Manage Users and Roles].
+See xref:manage:manage-security/manage-users-and-roles.adoc[Manage Users and Roles] to learn how to assign roles to users to grant access to the sample buckets.
 
 To install, select one or more sample buckets from the displayed list, using the checkboxes provided.
 For example, select the `travel-sample` bucket:
@@ -69,8 +44,8 @@ If there is insufficient memory available for the specified installation, a noti
 
 image::manage-settings/insufficientRamWarning.png[,290,align=left]
 
-For information on configuring memory quotas, see the information on xref:manage:manage-settings/general-settings.adoc[General] settings.
-For information on managing (including deleting) buckets, see xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets].
+For information about configuring memory quotas, see xref:manage:manage-settings/general-settings.adoc[General] settings.
+For information about managing (including deleting) buckets, see xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets].
 
 If and when you have sufficient memory, click [.ui]*Load Sample Data*.
 
@@ -83,15 +58,37 @@ See xref:manage:manage-buckets/bucket-management-overview.adoc[Manage Buckets],
 [#install-sample-buckets-with-the-rest-api]
 == Install Sample Buckets with the REST API
 
-To install sample buckets with the REST API, use the `POST /sampleBuckets/install` HTTP method and URI, as follows:
+To install sample buckets with the REST API, use the `POST /sampleBuckets/install` HTTP method and URI.
+For example:
+
+[source,console]
+----
+include::rest-api:example$install-sample-bucket.sh[]
+----
+
+If successful, the call returns a JSON dictionary that lists the tasks Couchbase Server started to load the buckets:
+
+[source,json]
+----
+include::rest-api:example$sample-bucket-install-response.json[] 
+----
+
+You can monitor the status of these tasks using the `/pools/default/tasks` REST API endpoint. 
+Pass it the `taskId` value from the task list returned by the call to `sampleBuckets/install`:
+
+[source,console]
+----
+curl -s -u Administrator:password  -G http://localhost:8091/pools/default/tasks \
+     -d taskId=439b29de-0018-46ba-83c3-d3f58be68b12 | jq '.' 
+----
+
+The command returns the current status of the task:
 
+[source,json]
 ----
-curl -X POST -u Administrator:password \
-http://10.143.194.101:8091/sampleBuckets/install \
--d '["travel-sample", "beer-sample"]'
+include::rest-api:example$beer-sample-task-status.json[] 
 ----
 
-If successful, the call returns an empty list.
+For more information about using the REST API, including details of how to retrieve a list of available sample buckets, see xref:rest-api:rest-sample-buckets.adoc[].
+For information about deleting buckets (including sample buckets), see xref:rest-api:rest-bucket-delete.adoc[].
 
-For further information on using the REST API, including details of how to retrieve a list of currently available sample buckets, see xref:rest-api:rest-sample-buckets.adoc[Managing Sample Buckets].
-For information on _deleting_ buckets (including sample buckets), see xref:rest-api:rest-bucket-delete.adoc[Deleting Buckets].

modules/rest-api/examples/beer-sample-task-status.json

@@ -0,0 +1,9 @@
+[
+    {
+      "task_id": "439b29de-0018-46ba-83c3-d3f58be68b12",
+      "status": "running",
+      "type": "loadingSampleBucket",
+      "bucket": "beer-sample",
+      "bucket_uuid": "not_present"
+    }
+]

modules/rest-api/examples/install-sample-bucket.sh

@@ -0,0 +1,3 @@
+curl -X POST -u Administrator:password \
+     http://localhost:8091/sampleBuckets/install \
+     -d '["travel-sample", "beer-sample"]' | jq .

modules/rest-api/examples/sample-bucket-install-response.json

@@ -0,0 +1,14 @@
+{
+  "tasks": [
+    {
+      "taskId": "439b29de-0018-46ba-83c3-d3f58be68b12",
+      "sample": "beer-sample",
+      "bucket": "beer-sample"
+    },
+    {
+      "taskId": "ed6cd88e-d704-4f91-8dd3-543e03669024",
+      "sample": "travel-sample",
+      "bucket": "travel-sample"
+    }
+  ]
+}

modules/rest-api/examples/sample-bucket-tasks.json

@@ -0,0 +1,18 @@
+[
+    {
+      "statusId": "e36859e44fb7c226c180b4610313f074",
+      "type": "rebalance",
+      "subtype": "rebalance",
+      "status": "notRunning",
+      "statusIsStale": false,
+      "masterRequestTimedOut": false,
+      "lastReportURI": "/logs/rebalanceReport?reportID=af5b2ac96af031218bae6e3411b007b5"
+    },
+    {
+      "task_id": "439b29de-0018-46ba-83c3-d3f58be68b12",
+      "status": "running",
+      "type": "loadingSampleBucket",
+      "bucket": "beer-sample",
+      "bucket_uuid": "not_present"
+    }
+]

modules/rest-api/examples/sample_bucket_load_status.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+echo -e "Executing command:\ncurl -s -X POST -u Administrator:password http://node1:8091/sampleBuckets/install -d '[\"travel-sample\", \"beer-sample\"]'"
+
+taskIds=$(curl -s -X POST -u Administrator:password http://node1:8091/sampleBuckets/install -d '["travel-sample", "beer-sample"]' \
+        | jq . | tee install_output.json | jq '.tasks[] | .taskId' | tr -d '"' )
+
+cat install_output.json
+
+echo -e "\ntaskIds: $taskIds\n\n"
+
+sleep 2
+
+echo -e\n\nFull task list:
+
+curl -s -u  Administrator:password  -X GET  http://localhost:8091/pools/default/tasks | jq 
+
+for id in ${taskIds}; do
+    echo -e "\ntaskId: $id"
+    echo "Running command: curl -s -u Administrator:password  -G http://localhost:8091/pools/default/tasks -d \"taskId=$id\" | jq '.' "
+    curl -s -u Administrator:password  -G http://localhost:8091/pools/default/tasks -d "taskId=$id" | jq '.' 
+done