docs for workspaces

Author: janmatzek

docs/content/en/latest/pipelines-overview.md

@@ -25,7 +25,7 @@ pip install gooddata-pipelines
 
 
 ## Examples
-Here are a couple of introductory examples how to manage GoodData resources using Pipelines:
+Here are a couple of introductory examples how to manage GoodData resources using GoodData Pipelines:
 
 ### Provision Child Workspaces
 ```python

docs/content/en/latest/pipelines/provisioning/_index.md

@@ -7,7 +7,6 @@ no_list: true
 
 Manage resources in GoodData.
 
-
 ## Supported Resources
 
 Resources you can provision using GoodData Pipelines:
@@ -34,3 +33,47 @@ Full load provisioning aims to fully synchronize the state of your GoodData inst
 ### Incremental Load
 
 During incremental provisioning, the algorithm will only interact with resources specified in the input. During the incremental load, the input data expects an extra parameter: `is_active`. Resources with `True` value will be updated. On the other hand, by setting it to `False`, you can mark resources for deletion. Any other resources already existing in GoodData will not be altered.
+
+
+## Usage
+
+Regardless of workflow type or provisioned resource, the typical usage can be broken down into following steps:
+
+1. Initialize the provisioner
+
+1. Validate your data using an input model
+
+1. Run the selected provisioning method (`.full_load()` or `.incremental_load()`) with your validated data
+
+
+Check the [resource pages](#supported-resources) for examples of workflow implementations.
+
+## Logs
+
+By default, the provisioners will not print out any information to the console. However, you can subscribe to the emitted logs using the `.subscribe()` method on the `logger` property of the provisioner instance. The logging service emits unformatted messages based on severity.
+
+```python
+# Import and set up your logger
+import logging
+
+# Import the provisioner
+from gooddata_pipelines import WorkspaceProvisioner
+
+host="http://localhost:3000", token="some_user_token"
+
+# In this example, we will use Python standard logging library.
+# However, you can subscribe any logger conforming to the LoggerLike protocol
+# defined in gooddata_pipelines.logger.logger
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# Initialize the provisioner
+provisioner = WorkspaceProvisioner.create(host=host, token=token)
+
+# Subscribe to the logging service
+provisioner.logger.subscribe(logger)
+
+# Continue with the provisioning
+...
+```

docs/content/en/latest/pipelines/provisioning/workspaces.md

@@ -3,3 +3,217 @@ title: "Workspaces"
 linkTitle: "Workspaces"
 weight: 1
 ---
+
+Workspace provisioning allows you to create, update or delete child workspaces.
+
+You can provision child workspaces using full or incremental load methods. Each of these methods requires a specific input type.
+
+
+## Usage
+
+Start by importing and initializing the WorkspaceProvisioner.
+
+```python
+
+from gooddata_pipelines import WorkspaceProvisioner
+
+host="http://localhost:3000", token="some_user_token"
+
+# Initialize the provisioner with GoodData credentials
+provisioner = WorkspaceProvisioner.create(host=host, token=token)
+```
+
+
+Then validate your data using an input model corresponding with the provisioned resource and selected workflow type, i.e., `WorkspaceFullLoad` if you intend to run the provisioning in full load mode, or `WorkspaceIncrementalLoad` if you want to provision incrementally.
+
+The models expect following fields:
+```python
+class WorkspaceFullLoad
+    parent_id: str # ID of parent workspace
+    workspace_id: str # ID of child workspace
+    workspace_name: str # Name of child workspace
+    workspace_data_filter_id: str | None = None # ID of applied workspace data filter
+    workspace_data_filter_values: list[str] | None = None # Filter values to apply
+
+class WorkspaceIncrementalLoad
+    parent_id: str
+    workspace_id: str
+    workspace_name: str
+    workspace_data_filter_id: str | None = None
+    workspace_data_filter_values: list[str] | None = None
+    is_active: bool # Set to True to keep the workspace, False to delete it
+
+```
+
+Use one of the models to validate your data:
+
+```python
+# Add the model to the imports
+from gooddata_pipelines import WorkspaceProvisioner, WorkspaceFullLoad
+
+host="http://localhost:3000", token="some_user_token"
+
+# Initialize the provisioner with GoodData credentials
+provisioner = WorkspaceProvisioner.create(host=host, token=token)
+
+# Load your data
+raw_data = [
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "workspace_id_1",
+        "workspace_name": "Workspace 1",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_1"],
+    },
+]
+
+# Validate the data
+validated_data = [WorkspaceFullLoad(
+    parent_id=item["parent_id"],
+    workspace_id=item["workspace_id"],
+    workspace_name=item["workspace_name"],
+    workspace_data_filter_id=item["workspace_data_filter_id"],
+    workspace_data_filter_values=item["workspace_data_filter_values"],
+) for item in raw_data]
+
+```
+
+Now with the provisioner initialized and your data validated, you can run the provisioner:
+
+```python
+# Import, initialize, validate...
+...
+
+# Run the provisiong method
+provisioner.full_load(validated_data)
+```
+
+
+## Workspace Data Filters
+
+If you want to apply Workspace Data Filters on a child workspace, it needs to be set up on the parent workspace before you run the provisioning.
+
+See [Set Up Data Filters in Workspaces](https://www.gooddata.com/docs/cloud/workspaces/workspace-data-filters/) to learn how workspace data filters work in GoodData.
+
+
+## Examples
+
+Here are full examples of a full load and incremental load workspace provisioning workflows:
+
+### Full Load
+
+```python
+import logging
+
+from gooddata_pipelines import WorkspaceProvisioner, WorkspaceFullLoad
+
+host="http://localhost:3000", token="some_user_token"
+
+# Initialize the provisioner
+provisioner = WorkspaceProvisioner.create(host=host, token=token)
+
+# Optional: set up logging and subscribe to logs emited by the provisioner
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+provisioner.logger.subscribe(logger)
+
+# Prepare your data
+raw_data: list[dict] = [
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "workspace_id_1",
+        "workspace_name": "Workspace 1",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_1"],
+    },
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "workspace_id_2",
+        "workspace_name": "Workspace 2",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_2"],
+    },
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "child_workspace_id_1",
+        "workspace_name": "Workspace 3",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_3"],
+    },
+]
+
+# Validate the data
+validated_data = [WorkspaceFullLoad(
+    parent_id=item["parent_id"],
+    workspace_id=item["workspace_id"],
+    workspace_name=item["workspace_name"],
+    workspace_data_filter_id=item["workspace_data_filter_id"],
+    workspace_data_filter_values=item["workspace_data_filter_values"],
+) for item in raw_data]
+
+# Run the provisioning with the validated data
+provisioner.full_load(validated_data)
+
+```
+
+### Incremental Load
+
+```python
+import logging
+
+from gooddata_pipelines import WorkspaceProvisioner, WorkspaceIncrementalLoad
+
+host="http://localhost:3000", token="some_user_token"
+
+# Initialize the provisioner
+provisioner = WorkspaceProvisioner.create(host=host, token=token)
+
+# Optional: set up logging and subscribe to logs emited by the provisioner
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+provisioner.logger.subscribe(logger)
+
+# Prepare your data
+raw_data: list[dict] = [
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "workspace_id_1",
+        "workspace_name": "Workspace 1",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_1"],
+        "is_active": True,
+    },
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "workspace_id_2",
+        "workspace_name": "Workspace 2",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_2"],
+        "is_active": True,
+    },
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "child_workspace_id_1",
+        "workspace_name": "Workspace 3",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["workspace_data_filter_value_3"],
+        "is_active": False # This will mark the workspace for deletion
+    },
+]
+
+# Validate the data
+validated_data = [WorkspaceIncrementalLoad(
+    parent_id=item["parent_id"],
+    workspace_id=item["workspace_id"],
+    workspace_name=item["workspace_name"],
+    workspace_data_filter_id=item["workspace_data_filter_id"],
+    workspace_data_filter_values=item["workspace_data_filter_values"],
+    is_active=item["is_active]
+) for item in raw_data]
+
+# Run the provisioning with the validated data
+provisioner.incremental_load(validated_data)
+
+```