Space & Session Guide

Space is Webfuse’s metaphor for your specific web proxy confgurations. A Space comprises certain access configurations, installed Apps, and installed Extensions. Alltogether, it renders virtual web Sessions that apply the web augmentations and load infrastructural enhancements.

1. Create a Space

When you open Webfuse Studio, you will be presented with a bunch of Space tiles to create a specific type of Space from. Choose Solo Space, which is a virtual resemblence of an ordinary web browser. Choose a Name and a Slug to later identify the Space and access it on the web.

2. Start a Session

To see the Space in action, start a Session from the Space page in Studio. Sessions can be started in various ways: Studio, but also via REST API, or Widget API to build seamless user experiences. Space access can be configured in Studio through the Space Settings page. Space related web augmentation can be configured within a Session, using the Session Editor. The Session Editor shows only to Admins of the Space.

3. Install an App & Extension

There are two ways to achieve web augmentations with Webfuse: via App, or via Extension. Apps bring functionality that goes beyond page scope – touching the fundamental infrastructure. Extensions are modeled after browser extensions and allow fully customized augmentations loaded for every user that joins a Session by opening the related Space URL.

Open the Session Editor in the top bar and select Apps. In the App tab, you can browse available Apps. Choose one and install it. Now, open the Extensions tab and upload an Extension. If you do not yet have developed an Extension, skip this step or reuse an existing one, such as the Assistant Agent Extension Example.

4. Configure Session Appearance

Within the Session, you will immediately see the effects of installed Apps and Extensions. For a seamless experience, you can configure a Session’s behavior further through the Session Settings. Open it from the top bar. Go to Interface -> Hide Session UI and enable the toggle. Save the changes and close the Settings modal.

5. Export Space

You can export and import Spaces using the REST API. This is useful for cloning Spaces, migrating Spaces between companies or for backup purposes. Space export contains all the data needed to recreate the Space, including name, type of the Space, access control settings, settings, etc.

Currently we support the following data to be exported/imported:

Space Name
Space Type
Space Visibility
Space Identification
Space Access Control
Space Host Rights
Space Settings
Space Apps (installed)
Space Extensions (installed)
Space Landing Page (if applicable)

To export a Space, you need to use the GET /spaces/{space_id}/export endpoint. This will return a base64 encoded JSON object that you can use to import the Space.

You can use either the company token or the Space token to export the Space.

Storage apps and references to them in the applications are not exported. Instead, you can use the overrides field to specify the storage app to use for the Space while importing. The format is the same as the one used in the GET /Spaces/{Space_id}/storages/ endpoint.

Exporting Extensions

To export extensions, you need to modify the extensions field in the resulting JSON object.

Each extension is represented as a JSON object with the following fields:

manifest: The manifest of the extension.
branch: The branch of the GitHub repository that contains the extension.

The manifest field is the same as the one used in the GET /Spaces/{Space_id}/extensions/ endpoint.

To specify the repository URL, you need to modify the homepage_url field in the manifest object.

Exporting custom landing page

To export the custom landing page, you need to modify the custom_landing_page field in the resulting JSON object.

Custom landing page is represented as a JSON object with the following fields:

repo_url: The URL of the GitHub repository that contains the custom landing page.
branch: The branch of the GitHub repository that contains the custom landing page.

If you don’t specify the branch field, it will default to main.

6. Import Space

To import a Space, you need to use the POST /Spaces/import endpoint. This will import the Space and all related objects. The name of the Space will be the same as the original Space, but the slug will be a random string. You can change the slug any time in the Space settings.

Default Storage

To define a default storage for the Space, you need to use the overrides.default_storage field in the request body. The format is the same as the one used in the GET /Spaces/{Space_id}/storages/ endpoint.

Example

Here is an example of how to export and import a Space using Python.

import requests

BASE_URL = "https://webfuse.com/api/Spaces"
HEADERS = {
    "Authorization": "Token ck_<YOUR_COMPANY_TOKEN>",
    "Content-Type": "application/json",
}


def export_Space(Space_id):
    url = f"{BASE_URL}/{Space_id}/export"
    response = requests.get(url, headers=HEADERS)
    response.raise_for_status()
    return response.json()


def import_Space(Space_data):
    url = f"{BASE_URL}/import/"
    response = requests.post(url, headers=HEADERS, json=Space_data)
    response.raise_for_status()
    return response.json()


def add_admin(Space_id, user_id):
    url = f"{BASE_URL}/{Space_id}/members/"
    response = requests.post(
        url,
        headers=HEADERS,
        json={"member": user_id, "Space": Space_id, "role": "admin"},
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    # Export Space with id 31
    Space_id = 31
    Space_data = export_Space(Space_id)
    print("Exported Space", Space_data)  # `{"Space_data": "...", "overrides": {}}`

    # Check the resulting file and fill in the missing fields if needed
    Space_data["Space_data"]["extensions"] = [
        {
            "manifest": {
                "homepage_url": "https://github.com/owner/extension",
            },
            "branch": "main",
        }
    ]

    Space_data["Space_data"]["custom_landing_page"] = {
        "repo_url": "https://github.com/owner/landing-page",
        "branch": "main",
    }

    # Now import Space using the hash generated above and add a default storage
    Space_data["overrides"] = {
        "default_storage": {
            "provider": "s3",
            "name": "a valid s3 storage",
            "config": {
                "endpoint_url": "https://s3.amazonaws.com",
                "bucket_name": "test",
                "region_name": "us-east-1",
                "access_key": "test",
                "secret_key": "test",
            },
        }
    }
    imported_Space = import_Space(Space_data)
    print(imported_Space)  # {"id": 123, "name": "..."}

    # Add admin, since new Space has no admins by default
    admin_id = 1
    add_admin(imported_Space["id"], admin_id)