docs(gooddata-pipelines): public documentation

Author: janmatzek

CONTRIBUTING.md

@@ -60,6 +60,8 @@ The project documentation is done in hugo. To contribute:
 
 2. Run `make new-docs`
 
+3. Open [http://localhost:1313/latest/](http://localhost:1313/latest/) in your browser to see the preview.
+
 The documentation is deployed using manually triggered GitHub workflows.
 
 One logical change is done in one commit.

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

@@ -0,0 +1,84 @@
+---
+title: "Pipelines Overview"
+linkTitle: "Pipelines Overview"
+weight: 14
+---
+
+GoodData Pipelines contains tools for automation of GoodData life cycle. Built over GoodData Python SDK, it allows you to conveniently manage user profiles, workspace permissions and more.
+
+For further information, refer to the PIPELINES section in the left navigation menu.
+
+## Installation
+
+
+Run the following command to install the ``gooddata-pipelines`` package on your system:
+
+```bash
+pip install gooddata-pipelines
+```
+
+### Requirements
+
+- Python 3.10 or newer
+- GoodData.CN or GoodData Cloud
+
+
+
+## Examples
+Here is an introductory example how to manage GoodData resources using GoodData Pipelines:
+
+### Provision Child Workspaces
+```python
+from gooddata_pipelines import WorkspaceFullLoad, WorkspaceProvisioner
+
+# GoodData.CN host in the form of uri eg. "http://localhost:3000"
+host = "http://localhost:3000"
+
+# GoodData.CN user token
+token = "some_user_token"
+
+# Initialize the provisioner
+provisioner = WorkspaceProvisioner.create(host=host, token=token)
+
+# Gather the definitions of the workspaces you want to create
+raw_data: list[dict] = [
+    {
+        "parent_id": "parent_workspace_id",
+        "workspace_id": "child_workspace_0",
+        "workspace_name": "Child Workspace 0",
+        "workspace_data_filter_id": "data_filter_id",
+        "workspace_data_filter_values": ["value_0"],
+    },
+]
+
+# Validate the data
+validated_data = [WorkspaceFullLoad(**item) for item in raw_data]
+
+# Run the provisioning
+provisioner.full_load(validated_data)
+
+```
+<!--
+### Workspace Backup
+```python
+from gooddata_pipelines import BackupManager, BackupRestoreConfig
+
+# GoodData.CN host in the form of uri eg. "http://localhost:3000"
+host = "http://localhost:3000"
+
+# GoodData.CN user token
+token = "some_user_token"
+
+# Define a list with IDs of workspaces you want to back up
+workspaces_to_back_up = ["workspace_id_1", "workspace_id_2"]
+
+# Configure backup options
+config = BackupRestoreConfig(storage_type="local")
+
+# Initialize the backup manager
+backup_manager = BackupManager.create(config, host, token)
+
+# Run the backup
+backup_manager.backup_workspaces(workspace_ids=workspaces_to_back_up)
+
+``` -->

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

@@ -0,0 +1,6 @@
+---
+title: "GOODDATA PIPELINES"
+linkTitle: "GOODDATA PIPELINES"
+weight: 60
+navigationLabel: true
+---

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

@@ -0,0 +1,79 @@
+---
+title: "Provisioning"
+linkTitle: "Provisioning"
+weight: 1
+no_list: true
+---
+
+Manage resources in GoodData.
+
+## Supported Resources
+
+Resources you can provision using GoodData Pipelines:
+
+- [Workspaces](workspaces)
+- [Users](users)
+- [User Groups](user_groups)
+- [Workspace Permissions](workspace-permissions)
+
+
+## Workflow Types
+
+There are two types of provisioning supported by GoodData Pipelines:
+
+- [Full load](#full-load)
+- [Incremental load](#incremental-load)
+
+The provisioning types employ different algorithms and expect different structure of input data. For details about the expected inputs, check out the documentation page of individual provisioned resource.
+
+### Full Load
+
+Full load provisioning aims to fully synchronize the state of your GoodData instance with the provided input. This workflow will create new resources and update existing ones based on the input. Any resources existing on GoodData Cloud not inluded in the input will be deleted.
+
+### 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/user_groups.md

@@ -0,0 +1,173 @@
+---
+title: "User Groups"
+linkTitle: "User Group"
+weight: 3
+---
+
+User group provisioning allows you to create, update or delete user groups.
+
+You can provision user groups using full or incremental load methods. Each of these methods requires a specific input type.
+
+## Usage
+
+Start by importing and initializing the UserGroupProvisioner.
+
+```python
+
+from gooddata_pipelines import UserGroupProvisioner
+
+host="http://localhost:3000"
+token="some_user_token"
+
+# Initialize the provisioner with GoodData credentials
+provisioner = UserGroupProvisioner.create(host=host, token=token)
+
+```
+
+
+Then validate your data using an input model corresponding with the provisioned resource and selected workflow type, i.e., `UserGroupFullLoad` if you intend to run the provisioning in full load mode, or `UserGroupIncrementalLoad` if you want to provision incrementally.
+
+The models expect following fields:
+- **user_group_id**: ID of the user group.
+- **user_group_name**: Name of the user group.
+- **parent_user_groups**: A list of parent user group IDs.
+- _**is_active**:_ Deletion flag. Present only in the IncrementalLoad models.
+
+> **Note on IDs**: Each ID can only contain allowed characters. See [Workspace Object Identification](https://www.gooddata.com/docs/cloud/create-workspaces/objects-identification/) to learn more about object identifiers.
+
+Use the appropriate model to validate your data:
+
+```python
+# Add the model to the imports
+from gooddata_pipelines import UserGroupFullLoad, UserGroupProvisioner
+
+host = "http://localhost:3000"
+token = "some_user_token"
+
+# Initialize the provisioner with GoodData credentials
+provisioner = UserGroupProvisioner.create(host=host, token=token)
+
+# Load your data
+raw_data = [
+    {
+        "user_group_id": "user_group_1",
+        "user_group_name": "User Group 1",
+        "parent_user_groups": [],
+    },
+]
+
+# Validate the data
+validated_data = [
+    UserGroupFullLoad(
+        user_group_id=item["user_group_id"],
+        user_group_name=item["user_group_name"],
+        parent_user_groups=item["parent_user_groups"],
+    )
+    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)
+
+```
+
+## Examples
+
+Here are full examples of a full load and incremental load user group provisioning workflows:
+
+### Full Load
+
+```python
+import logging
+
+from gooddata_pipelines import UserGroupFullLoad, UserGroupProvisioner
+
+host = "http://localhost:3000"
+token = "some_user_token"
+
+# Initialize the provisioner
+provisioner = UserGroupProvisioner.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 = [
+    {
+        "user_group_id": "user_group_1",
+        "user_group_name": "User Group 1",
+        "parent_user_groups": [],
+    },
+]
+
+# Validate the data
+validated_data = [
+    UserGroupFullLoad(
+        user_group_id=item["user_group_id"],
+        user_group_name=item["user_group_name"],
+        parent_user_groups=item["parent_user_groups"],
+    )
+    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 UserGroupIncrementalLoad, UserGroupProvisioner
+
+host = "http://localhost:3000"
+token = "some_user_token"
+
+# Initialize the provisioner
+provisioner = UserGroupProvisioner.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 = [
+    {
+        "user_group_id": "user_group_1",
+        "user_group_name": "User Group 1",
+        "parent_user_groups": [],
+        "is_active": True,
+    },
+]
+
+# Validate the data
+validated_data = [
+    UserGroupIncrementalLoad(
+        user_group_id=item["user_group_id"],
+        user_group_name=item["user_group_name"],
+        parent_user_groups=item["parent_user_groups"],
+        is_active=item["is_active"],
+    )
+    for item in raw_data
+]
+
+# Run the provisioning with the validated data
+provisioner.incremental_load(validated_data)
+
+```