Managing Sisense Plugin States via the REST API Overview Manually enabling and disabling Sisense plugins through the admin interface can become time consuming, particularly when keeping multiple Sisense server instances in a consistent state, switching active plugin lists quickly for testing, restoring a previous known working plugin list after an upgrade or support session, or iterating on a plugin during development where having only one plugin active significantly reduces build time for any plugin changes to become active. This article describes a Python command line (CLI) tool that manages Sisense plugin states via the Sisense REST API, using a simple configuration file as the config. The tool supports enabling and disabling plugins, isolating (enabling only one and disabling all others) a single plugin for faster development builds, saving and restoring named snapshots of plugin state, and previewing changes before applying them. This tool does not install or uninstall plugins, and does not update plugins or upgrade/downgrade or modify the code within the plugins. The script, configuration file, and dependencies are included in this article. Sisense instances often have many plugins active, with the enabled list changing over time. Common scenarios include: Plugins being left enabled or disabled after support sessions or testing, or enabling or disabling all plugins The need to quickly reach a server plugin state with no plugins enabled, to isolate whether a plugin is causing a potential issue Maintaining a consistent plugin list across multiple Sisense environments or after upgrades Needing to roll back to a previous plugins active state after a change is potentially creating issues (This tool does not rollback plugin versions, only active plugin lists) Performing these operations manually through the Sisense UI admin panel is practical for occasional changes, but becomes inefficient when the changes are frequent, when many plugins are involved, or when the same configuration needs to be applied reliably and repeatably. Description The plugin manager script reads an enable_plugins list from a configuration file and syncs the Sisense instance to match via the REST API. The script: Enables plugins listed in enable_plugins in the configuration file Optionally disables plugins listed in disable_plugins Leaves all other plugins in their current state by default Saves a timestamped snapshot of the current plugin state before applying any changes, providing an automatic rollback point Supports restoring any saved snapshot to return to a previous state A strict mode is also available, which disables any currently enabled plugin that is not listed in enable_plugins , making the instance exactly match the configuration file. The script also supports previewing what would change without making any API calls, and can save named snapshots for later reference or comparison. Plugin name matching Plugin names in the configuration file accept either the short form ( SwitchDimension ) or the full form ( plugin-SwitchDimension ). Matching is case-insensitive. This applies both to the configuration file and to command line arguments. Prerequisites Python 3.7 or later Network access to the Sisense instance (The tool runs remotely and does not need to be installed directly on the server, or SSH access) A Sisense API token, which can be generated from Admin > REST API > v1.0 > GET /authentication/tokens/api Setup Install the required Python packages: pip install requests pyyaml Create a config.yaml and fill in the Sisense instance URL and API token: sisense:
url: https://your-sisense-instance.com
token: YOUR_API_TOKEN_HERE
Add the plugins to enable to the enable_plugins list. See the Configuration reference section for all available settings. The script is then ready to run. Configuration reference sisense:
url: https://your-sisense-instance.com
token: YOUR_API_TOKEN_HERE # Admin → REST API → v1.0 → GET /authentication/tokens/api
bulk: true # set false to update plugins one at a time instead of a single batch request
# Plugins to enable.
# Accepts short names (SwitchDimension) or full names (plugin-SwitchDimension).
# Matching is case-insensitive.
#
# Default behavior: enable listed plugins; leave every other plugin unchanged.
# With --strict: also disable any currently-enabled plugin NOT in this list,
# making the instance exactly match this config.
enable_plugins:
- examplePlugin
# Plugins to explicitly disable (optional).
# Only needed in the default sync (no --strict), where unlisted plugins are
# left alone. Listing a plugin here ensures it stays off and documents the
# intentional exclusion.
# disable_plugins:
# - anotherExamplePlugin
enable_plugins : the list of plugins to enable. By default, plugins not on this list are left in their current state. With --strict , any currently enabled plugin not on this list will be disabled. disable_plugins : optional. Plugins to explicitly disable in the default sync without --strict . This is useful for documenting intentional exclusions when strict mode is not being used. bulk : controls whether plugin state changes are sent as a single batch API request or one at a time. Set to false for individual requests, which is slower but can be useful for diagnosing issues with specific plugins. Usage Run the script with no arguments to enable plugins in enable_plugins , disable plugins in disable_plugins , and leave everything else unchanged: python plugin_manager.py
Before making any changes, the script saves a timestamped snapshot of the current plugin state. To restore the most recent snapshot: python plugin_manager.py --restore-snapshot
To preview what would change without making any API calls: python plugin_manager.py --dry-run
Common Use Cases Maintaining a known good plugin baseline Organizations that need to ensure consistent plugin configuration across upgrades, support sessions, or environment changes can maintain an enable_plugins list in the configuration file. Running the script applies the defined configuration to the instance. To also disable any currently enabled plugin not in the list: python plugin_manager.py --strict
Testing on a stock Sisense instance Plugin interference is a common source of issues that are hard to reproduce. To quickly disable all plugins and test against a clean instance, clear enable_plugins in the configuration file and run with --strict . The current state is saved automatically before any changes are made, and can be restored when testing is complete: # with enable_plugins cleared in config.yaml
python plugin_manager.py --strict
# restore when done
python plugin_manager.py --restore-snapshot
Developing and testing a single plugin When many plugins are installed, Sisense rebuilds all of them whenever any plugin changes. Using --enable-one disables all currently enabled plugins and enables only the specified plugin, which can significantly reduce rebuild time on instances with many plugins: python plugin_manager.py --enable-one MyPlugin
Snapshots The script saves snapshots as YAML files to a snapshots/ folder alongside the script. Snapshots capture the full enabled and disabled plugin state at a point in time. Snapshots are saved automatically before any run that changes state. Named snapshots can also be saved and restored explicitly: # save the current state with a specific name
python plugin_manager.py --save-snapshot before-upgrade
# list all saved snapshots
python plugin_manager.py --list-snapshots
# restore a specific snapshot
python plugin_manager.py --restore-snapshot before-upgrade
Including --log-version when saving a snapshot records the version of each plugin at that point in time, which can be useful for tracking plugin versions across upgrades. Full option reference usage: plugin_manager.py [-h] [--config FILE] [--dry-run] [--no-bulk]
[--skip-snapshot] [--log-version] [--strict]
[--enable-only | --disable-only]
[--enable-one PLUGIN | --save-snapshot [NAME] |
--list-snapshots | --restore-snapshot [NAME]]
Manage Sisense plugin states via the REST API.
options:
-h, --help show this help message and exit
--config FILE Path to config.yaml (default: config.yaml next to this
script)
--dry-run Preview what would change; make no API calls and save
no snapshot
--no-bulk Send one API call per plugin instead of a single batch
PATCH. Slower but easier to diagnose partial failures.
Overrides sisense.bulk in config.
--skip-snapshot Do not automatically save a snapshot before this run
--log-version Record each plugin's version field (from the API
response) in any snapshot saved during this run
(manual --save-snapshot or auto saved snapshot)
--strict Also disable every currently enabled plugin that is
not listed in enable_plugins. Without this flag, only
plugins in disable_plugins are disabled; everything
else is left alone. Always active for --restore-
snapshot.
--enable-only Run only the enable step; skip all disables
--disable-only Run only the disable step; skip all enables
--enable-one PLUGIN Enable exactly one plugin by name and disable all
currently enabled others. Accepts the short or full
plugin name.
--save-snapshot [NAME]
Save the current plugin state as a named snapshot.
Omit NAME for an auto generated timestamp filename.
Combine with --log-version to also record versions for
each plugin.
--list-snapshots List all saved snapshots with creation date and
enabled plugin count
--restore-snapshot [NAME]
Restore plugin state to exactly match a saved
snapshot. Omit NAME to use the most recently created
snapshot. Always strict (disables plugins not in
snapshot) unless --enable-only.
Plugin names accept the short form (SwitchDimension) or the full
form (plugin-SwitchDimension) in both CLI args and config.yaml.
Default behavior: enable plugins in enable_plugins, disable plugins
in disable_plugins, leave everything else unchanged.
Use --strict to also disable any enabled plugin not in enable_plugins.
A snapshot is saved automatically before each run that
modifies state. Use --skip-snapshot to suppress this.
Use Case Managing plugins via the REST API and a configuration file offers several advantages over manual administration: Applies plugin active list consistently and repeatably without manual steps Provides automatic rollback through snapshots saved before each change Supports quickly switching between plugin states for testing or development Reduces the time required to restore a known working plugin list after an issue is resolved Gives server administrators a record of plugin state changes over time (done via the tool and saved via snapshots) Summary With this tool in place, administrators and developers can manage Sisense plugin states quickly and reliably from the command line. The configuration file serves as a single source of truth for the intended plugin set, and the snapshot system ensures that any change can be reversed. Whether maintaining a consistent production environment, isolating issues related to plugins, or iterating on plugin development, the tool provides a practical and repeatable approach to plugin state management. The code is not compressed or obfuscated and can be modified as needed or used as a reference for similar tools. Full Python Code: """
Sisense Plugin Manager: manage Sisense plugin states via the REST API.
Overview
Manages Sisense plugin states via the REST API. Treats plugin configuration
as code: define which plugins should be enabled in config.yaml, run the script,
and the instance matches, quickly, from anywhere with network access.
Before applying any changes, the current plugin state is automatically captured
in a timestamped snapshot. If a change needs to be reverted, a single
--restore-snapshot command rolls the instance back to exactly how it was.
By default only the plugins explicitly listed in config.yaml are enabled or disabled,
everything else is left as is. Use --strict to also disable any enabled plugin
not in the list, making the instance enabled plugin list exactly match the config.
Common use cases
Maintain a known good plugin baseline
Keep enable_plugins in config.yaml up to date. Run the script after
upgrades, support sessions, or any time the instance may have drifted
from the expected state.
Test against a stock (no plugins) Sisense instance
Eliminate plugins as a potential cause of a bug or issue. Clear
enable_plugins in config.yaml, run --strict to disable everything, test,
then restore when done, the snapshot is saved automatically before changes:
# (clear enable_plugins in config.yaml)
python plugin_manager.py --strict
# ... reproduce the issue on a vanilla instance ...
python plugin_manager.py --restore-snapshot # restores most recent
Develop and iterate on a single plugin quickly
With many plugins installed Sisense rebuilds all of them on each change.
--enable-one isolates a single plugin and disables the rest, cutting
rebuild time to a fraction on instances with many plugins:
python plugin_manager.py --enable-one MyPlugin
Roll back any change instantly
Every run saves a timestamped snapshot of the state it found before
making changes. Use --list-snapshots to find an earlier state and
--restore-snapshot to return to it.
Usage
# Enable listed plugins, disable listed disable_plugins, leave rest unchanged
python plugin_manager.py
# Strict: also disables any enabled plugin not in enable_plugins
python plugin_manager.py --strict
# Preview what would change (no API calls, no auto snapshot)
python plugin_manager.py --dry-run
python plugin_manager.py --strict --dry-run
# Run only one half of the sync
python plugin_manager.py --enable-only # enable listed; skip all disables
python plugin_manager.py --disable-only # disable listed; skip all enables
# Enable exactly one plugin and disable every other currently enabled plugin
python plugin_manager.py --enable-one SwitchDimension
# Snapshots
python plugin_manager.py --save-snapshot [NAME] # name is optional
python plugin_manager.py --save-snapshot [NAME] --log-version # also record per-plugin versions
python plugin_manager.py --list-snapshots
python plugin_manager.py --restore-snapshot [NAME] # omit NAME → most recent
# Other flags (combinable with any of the above)
--no-bulk one API call per plugin instead of a single batch request
--skip-snapshot do not save an auto-snapshot before this run
--log-version record each plugin's version in any snapshot saved this run
--config FILE use a config file other than the default config.yaml
Plugin names
All plugin names accept either the short form (SwitchDimension) or the full
form (plugin-SwitchDimension), both in CLI arguments and in config.yaml.
Matching is case insensitive.
API token
Admin → REST API → v1.0 → GET /authentication/tokens/api
Setup
pip install requests pyyaml # Python 3.7+ required
cp config.yaml.example config.yaml
# Edit config.yaml: set sisense.url, sisense.token, and enable_plugins list
"""
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Optional
import requests
import yaml
# Constants
SCRIPT_DIR = Path(__file__).parent
DEFAULT_CONFIG_PATH = SCRIPT_DIR / "config.yaml"
SNAPSHOTS_DIR = SCRIPT_DIR / "snapshots"
PLUGIN_PAGE_SIZE = 20 # plugins returned per page by GET /api/v1/plugins
# Config helpers
def load_config(config_path: Path) -> dict:
"""Load and return the YAML config file, printing an error and exiting if missing."""
if not config_path.exists():
print(f"Config file not found: {config_path}")
print("Copy config.yaml.example to config.yaml and fill in your instance URL and API token.")
sys.exit(1)
with config_path.open() as file_handle:
return yaml.safe_load(file_handle)
def make_auth_headers(api_token: str) -> dict:
"""Return the Authorization + Content-Type headers required by the Sisense REST API."""
return {
"Authorization": f"Bearer {api_token}",
"Content-Type": "application/json",
}
# Plugin name normalization
def normalize_plugin_name(raw_name: str) -> str:
"""
Return a canonical form: lowercase with any leading 'plugin-' prefix stripped.
Both 'plugin-SwitchDimension' and 'SwitchDimension' normalize to 'switchdimension',
so callers do not need to be consistent about the prefix.
"""
lowered = raw_name.lower()
return lowered[len("plugin-"):] if lowered.startswith("plugin-") else lowered
def build_name_lookup(plugin_names: list) -> set:
"""
Build a set that matches a plugin regardless of whether the caller used the
'plugin-' prefix. Each name contributes two entries: the bare normalized
form and the 'plugin-<normalized>' form.
Use with plugin_matches_lookup() to test whether an API plugin object is
covered by a configured list.
"""
lookup: set = set()
for name in plugin_names:
normalized = normalize_plugin_name(name)
lookup.add(normalized)
lookup.add("plugin-" + normalized)
return lookup
def plugin_matches_lookup(plugin: dict, name_lookup: set) -> bool:
"""
Return True if either the plugin's folderName or its API name appears in
name_lookup (case insensitive, prefix agnostic).
"""
plugin_identifiers = {plugin["folderName"].lower(), plugin["name"].lower()}
return bool(plugin_identifiers & name_lookup)
# Plugin list API
def fetch_all_plugins(base_url: str, auth_headers: dict) -> list:
"""
Retrieve the full plugin list from the Sisense instance via paginated GET requests.
Prints progress to stdout and exits on HTTP error.
"""
print("Fetching plugin list...")
try:
all_plugins = _paginate_plugins(base_url, auth_headers)
except requests.HTTPError as http_error:
print(f"Failed to fetch plugins: {http_error}")
sys.exit(1)
print(f" {len(all_plugins)} plugins total\n")
return all_plugins
def _paginate_plugins(base_url: str, auth_headers: dict) -> list:
"""Internal: collect every page from GET /api/v1/plugins."""
endpoint = f"{base_url}/api/v1/plugins"
all_plugins: list = []
offset = 0
while True:
response = requests.get(
endpoint,
headers=auth_headers,
params={"limit": PLUGIN_PAGE_SIZE, "skip": offset},
timeout=30,
)
response.raise_for_status()
payload = response.json()
page = payload.get("plugins", [])
all_plugins.extend(page)
offset += len(page)
total_count = payload.get("count", 0)
print(f" Fetched {offset} / {total_count} plugins...")
if offset >= total_count or not page:
break
return all_plugins
# Plugin versions
def extract_plugin_versions(plugins: list) -> dict:
"""
Extract the version field from each plugin object in an API response.
Returns a dict mapping folderName → version string for every plugin that
carries a version field. Plugins with no version field are
omitted so the caller can treat an absent key as 'version unknown'.
"""
versions: dict = {}
for plugin in plugins:
version_value = plugin.get("version") or plugin.get("pluginVersion")
if version_value:
versions[plugin["folderName"]] = str(version_value)
return versions
# Applying changes
def _patch_plugins(base_url: str, auth_headers: dict, updates: list) -> None:
"""Send a PATCH /api/v1/plugins request. Raises requests.HTTPError on failure."""
response = requests.patch(
f"{base_url}/api/v1/plugins",
headers=auth_headers,
json=updates,
timeout=60,
)
response.raise_for_status()
def apply_plugin_updates(
base_url: str,
auth_headers: dict,
updates: list,
use_bulk: bool,
) -> tuple:
"""
Apply a list of enable/disable changes and print the outcome per plugin.
use_bulk=True → single PATCH with all updates at once (faster, one round-trip).
use_bulk=False → one PATCH per plugin (slower, easier to diagnose partial failures).
Returns (success_count, error_count).
"""
if use_bulk:
print(f"Sending bulk request ({len(updates)} plugin(s))...")
try:
_patch_plugins(base_url, auth_headers, updates)
except requests.HTTPError as http_error:
print(f" [ERROR] Bulk request failed: {http_error}")
sys.exit(1)
for update in updates:
status_label = "ENABLED" if update["isEnabled"] else "DISABLED"
print(f" [{status_label}] {update['folderName']}")
return len(updates), 0
success_count = error_count = 0
for update in updates:
folder_name = update["folderName"]
status_label = "ENABLED" if update["isEnabled"] else "DISABLED"
try:
_patch_plugins(base_url, auth_headers, [update])
print(f" [{status_label}] {folder_name}")
success_count += 1
except requests.HTTPError as http_error:
print(f" [ERROR] {folder_name}: {http_error}")
error_count += 1
return success_count, error_count
# Snapshot I/O
def save_snapshot(
snapshot_name: str,
enabled_folders: list,
*,
disabled_folders: Optional[list] = None,
plugin_versions: Optional[dict] = None,
) -> Path:
"""
Write a snapshot YAML file to snapshots/<snapshot_name>.yaml.
Fields written (in this order):
enable_plugins: sorted list of currently enabled folderNames
disabled_plugins: sorted list of currently-disabled folderNames (when provided)
plugin_versions: {folderName: version} for each plugin (when provided)
created: ISO-8601 UTC timestamp
Key ordering is preserved (sort_keys=False) so the file reads naturally.
"""
SNAPSHOTS_DIR.mkdir(exist_ok=True)
# created goes last so the plugin lists appear first in the file
snapshot_data: dict = {"enable_plugins": sorted(enabled_folders)}
if disabled_folders is not None:
snapshot_data["disabled_plugins"] = sorted(disabled_folders)
if plugin_versions:
snapshot_data["plugin_versions"] = plugin_versions
snapshot_data["created"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
snapshot_path = SNAPSHOTS_DIR / f"{snapshot_name}.yaml"
with snapshot_path.open("w") as file_handle:
yaml.dump(snapshot_data, file_handle, sort_keys=False, default_flow_style=False, allow_unicode=True)
return snapshot_path
def _snapshot_enable_list(snapshot: dict) -> list:
"""
Return the enabled plugin list from a snapshot, handling both the current
'enable_plugins' key and the legacy 'plugins' key used by older snapshots.
"""
return snapshot.get("enable_plugins") or snapshot.get("plugins", [])
def load_snapshot(snapshot_name: str) -> dict:
"""Load a snapshot by stem name, exiting with an error if the file is missing."""
snapshot_path = SNAPSHOTS_DIR / f"{snapshot_name}.yaml"
if not snapshot_path.exists():
print(f"Snapshot not found: {snapshot_path}")
sys.exit(1)
with snapshot_path.open() as file_handle:
return yaml.safe_load(file_handle)
def list_snapshot_files() -> list:
"""Return all snapshot YAML files in the snapshots directory, sorted by filename."""
if not SNAPSHOTS_DIR.exists():
return []
return sorted(SNAPSHOTS_DIR.glob("*.yaml"))
def latest_snapshot_name() -> str:
"""
Return the stem of the snapshot with the most recent 'created' timestamp.
Exits if no snapshots exist.
"""
snapshot_files = list_snapshot_files()
if not snapshot_files:
print("No snapshots found.")
sys.exit(1)
def created_timestamp(path: Path) -> str:
with path.open() as file_handle:
return yaml.safe_load(file_handle).get("created", "")
return max(snapshot_files, key=created_timestamp).stem
def auto_save_snapshot(plugins: list, include_version: bool) -> None:
"""
Save a snapshot from an already fetched plugin list, before applying changes.
Accepts the plugin list fetched at the start of the run so no second API
call is needed. Called before any changes are applied, giving every
run that changes state a rollback point. Failures are caught and reported as
a warning so a snapshot error never blocks the intended change.
"""
snapshot_name = datetime.now().strftime("auto_%Y%m%d_%H%M%S")
print(f"\nSaving snapshot '{snapshot_name}' before applying changes...")
try:
enabled_folders = [p["folderName"] for p in plugins if p.get("isEnabled")]
disabled_folders = [p["folderName"] for p in plugins if not p.get("isEnabled")]
plugin_versions = extract_plugin_versions(plugins) if include_version else None
snapshot_path = save_snapshot(
snapshot_name,
enabled_folders,
disabled_folders=disabled_folders or None,
plugin_versions=plugin_versions,
)
print(f" Saved to {snapshot_path} ({len(enabled_folders)} enabled / {len(disabled_folders)} disabled)")
except Exception as exc:
print(f" Warning: auto snapshot failed: {exc}")
# Sync computation
def compute_plugin_updates(
all_plugins: list,
enable_names: list,
disable_names: list,
*,
strict: bool,
enable_only: bool,
disable_only: bool,
) -> tuple:
"""
Determine which plugins need their state changed.
Default behavior (strict=False):
- Enable: plugins in enable_names that are currently disabled.
- Disable: plugins in disable_names that are currently enabled.
- Leave alone: everything else (not mentioned in either list).
With strict=True:
- Enable: same as default.
- Disable: plugins in disable_names, PLUS any currently enabled plugin
that does not appear in enable_names. This makes the instance
exactly match enable_names.
Direction overrides (applied after the above):
enable_only=True → clears to_disable entirely.
disable_only=True → clears to_enable entirely.
Returns:
to_enable: sorted folderNames to enable
to_disable: sorted folderNames to disable
unmatched_names: entries from enable_names that matched no instance plugin
"""
enable_lookup = build_name_lookup(enable_names)
disable_lookup = build_name_lookup(disable_names)
# Plugins from the instance that match the enable list
matched_enable_plugins = [p for p in all_plugins if plugin_matches_lookup(p, enable_lookup)]
enable_folder_set = {plugin["folderName"] for plugin in matched_enable_plugins}
# Plugins that should be enabled but currently are not
to_enable: list = [] if disable_only else sorted(
plugin["folderName"]
for plugin in matched_enable_plugins
if not plugin.get("isEnabled")
)
# Plugins that should be disabled but currently are enabled
if enable_only:
to_disable: list = []
elif strict:
# Strict: disable every enabled plugin not in the enable list
to_disable = sorted(
plugin["folderName"]
for plugin in all_plugins
if plugin.get("isEnabled") and plugin["folderName"] not in enable_folder_set
)
else:
# Soft: only disable what is explicitly listed in disable_plugins
to_disable = sorted(
plugin["folderName"]
for plugin in all_plugins
if plugin.get("isEnabled") and plugin_matches_lookup(plugin, disable_lookup)
)
# Entries from enable_names that found no matching plugin in the instance
matched_normalized_names = (
{normalize_plugin_name(plugin["folderName"]) for plugin in matched_enable_plugins} |
{normalize_plugin_name(plugin["name"]) for plugin in matched_enable_plugins}
)
unmatched_names = sorted(
name for name in enable_names
if normalize_plugin_name(name) not in matched_normalized_names
)
return to_enable, to_disable, unmatched_names
def _build_update_payload(to_enable: list, to_disable: list) -> list:
"""Combine enable and disable lists into the PATCH payload format."""
return (
[{"folderName": folder_name, "isEnabled": True} for folder_name in to_enable] +
[{"folderName": folder_name, "isEnabled": False} for folder_name in to_disable]
)
def _execute_sync(
base_url: str,
auth_headers: dict,
to_enable: list,
to_disable: list,
use_bulk: bool,
) -> int:
"""
Build the PATCH payload from to_enable / to_disable and apply it.
Prints 'Nothing to change.' if both lists are empty.
Returns the error count (0 on full success).
"""
updates = _build_update_payload(to_enable, to_disable)
if not updates:
print("Nothing to change.")
return 0
_, error_count = apply_plugin_updates(base_url, auth_headers, updates, use_bulk)
return error_count
# Output helpers
def _print_update_plan(
to_enable: list,
to_disable: list,
already_correct_count: int,
untouched_count: int = 0,
) -> None:
"""Print a summary of pending changes before they are applied."""
print(f" To enable: {len(to_enable)}")
print(f" To disable: {len(to_disable)}")
if already_correct_count > 0:
print(f" Already set: {already_correct_count}")
if untouched_count > 0:
print(f" Untouched: {untouched_count} (not listed in config; left as-is)")
print()
def _print_dry_run_preview(to_enable: list, to_disable: list) -> None:
"""Print the would-be changes when --dry-run is active."""
if not to_enable and not to_disable:
print("Nothing to change.")
if to_enable:
print("Would enable:")
for folder_name in to_enable:
print(f" + {folder_name}")
if to_disable:
print("Would disable:")
for folder_name in to_disable:
print(f" - {folder_name}")
print("\n[DRY RUN] No changes made.")
def _report_unmatched_names(unmatched_names: list) -> None:
"""Warn about configured plugin names that matched nothing in the instance."""
if unmatched_names:
print(f"\nNot found in instance ({len(unmatched_names)}):")
for name in unmatched_names:
print(f" - {name}")
# Commands
def cmd_sync_to_config(
base_url: str,
auth_headers: dict,
enable_names: list,
disable_names: list,
*,
dry_run: bool,
use_bulk: bool,
strict: bool,
enable_only: bool,
disable_only: bool,
skip_snapshot: bool,
include_version: bool,
) -> None:
"""
Default command: sync the instance to match config.yaml.
Enables plugins in enable_plugins; in strict mode, also disables any
currently enabled plugin not in enable_plugins. Without strict, only
plugins explicitly in disable_plugins are disabled.
"""
all_plugins = fetch_all_plugins(base_url, auth_headers)
to_enable, to_disable, unmatched_names = compute_plugin_updates(
all_plugins, enable_names, disable_names,
strict=strict, enable_only=enable_only, disable_only=disable_only,
)
enable_lookup = build_name_lookup(enable_names)
disable_lookup = build_name_lookup(disable_names)
matched_plugins = [p for p in all_plugins if plugin_matches_lookup(p, enable_lookup)]
already_correctly_enabled = sum(1 for p in matched_plugins if p.get("isEnabled"))
# Untouched: plugins in neither list, only relevant without --strict, where
# we deliberately leave them alone
untouched_count = 0 if strict or enable_only else sum(
1 for p in all_plugins
if not plugin_matches_lookup(p, enable_lookup)
and not plugin_matches_lookup(p, disable_lookup)
)
# Table of plugins matched by the enable list
if matched_plugins:
print(f"Matched {len(matched_plugins)} plugin(s) from enable_plugins:\n")
print(f" {'Folder name':<45} {'API name':<35} {'Enabled'}")
print(f" {'-'*45} {'-'*35} {'-'*7}")
for plugin in sorted(matched_plugins, key=lambda p: p["folderName"]):
print(f" {plugin['folderName']:<45} {plugin['name']:<35} {plugin['isEnabled']}")
print()
_print_update_plan(to_enable, to_disable, already_correctly_enabled, untouched_count)
if dry_run:
_print_dry_run_preview(to_enable, to_disable)
_report_unmatched_names(unmatched_names)
return
if not skip_snapshot and (to_enable or to_disable):
auto_save_snapshot(all_plugins, include_version)
error_count = _execute_sync(base_url, auth_headers, to_enable, to_disable, use_bulk)
print(f"\nDone. Enabled: {len(to_enable)} Disabled: {len(to_disable)} Errors: {error_count}")
_report_unmatched_names(unmatched_names)
def cmd_enable_single_plugin(
base_url: str,
auth_headers: dict,
plugin_name: str,
*,
dry_run: bool,
use_bulk: bool,
skip_snapshot: bool,
include_version: bool,
) -> None:
"""
Enable exactly one plugin and disable every other currently enabled plugin.
The target plugin is identified by name (short or full form, case insensitive).
This command does not consult enable_plugins or disable_plugins in config.
"""
target_name_lookup = build_name_lookup([plugin_name])
all_plugins = fetch_all_plugins(base_url, auth_headers)
target_plugin = next(
(plugin for plugin in all_plugins if plugin_matches_lookup(plugin, target_name_lookup)),
None,
)
if target_plugin is None:
print(f"Plugin not found: {plugin_name!r}")
print("Tip: check spelling against the Sisense admin panel, or run --save-snapshot to capture current names.")
sys.exit(1)
target_folder = target_plugin["folderName"]
target_currently_on = target_plugin.get("isEnabled", False)
to_enable = [] if target_currently_on else [target_folder]
to_disable = sorted(
plugin["folderName"]
for plugin in all_plugins
if plugin.get("isEnabled") and plugin["folderName"] != target_folder
)
print(f"Target plugin: {target_folder}")
print(f" Currently: {'enabled' if target_currently_on else 'disabled'}\n")
_print_update_plan(
to_enable, to_disable,
already_correct_count=1 if target_currently_on else 0,
)
if dry_run:
_print_dry_run_preview(to_enable, to_disable)
return
if not skip_snapshot and (to_enable or to_disable):
auto_save_snapshot(all_plugins, include_version)
error_count = _execute_sync(base_url, auth_headers, to_enable, to_disable, use_bulk)
print(f"\nDone. Enabled: {len(to_enable)} Disabled: {len(to_disable)} Errors: {error_count}")
def cmd_save_named_snapshot(
base_url: str,
auth_headers: dict,
snapshot_name: str,
include_version: bool,
) -> None:
"""Save the current plugin state as a named snapshot file."""
all_plugins = fetch_all_plugins(base_url, auth_headers)
enabled_folders = [plugin["folderName"] for plugin in all_plugins if plugin.get("isEnabled")]
disabled_folders = [plugin["folderName"] for plugin in all_plugins if not plugin.get("isEnabled")]
plugin_versions = extract_plugin_versions(all_plugins) if include_version else None
snapshot_path = save_snapshot(
snapshot_name,
enabled_folders,
disabled_folders=disabled_folders or None,
plugin_versions=plugin_versions,
)
print(f"\nSnapshot '{snapshot_name}' saved to {snapshot_path}")
print(f" {len(enabled_folders)} enabled / {len(disabled_folders)} disabled plugin(s) captured.")
if plugin_versions is not None:
print(f" Versions recorded for {len(plugin_versions)} plugin(s).")
def cmd_list_snapshots() -> None:
"""Print a formatted table of all saved snapshots."""
snapshot_files = list_snapshot_files()
if not snapshot_files:
print("No snapshots found.")
return
print(f"Snapshots ({len(snapshot_files)}):\n")
print(f" {'Name':<32} {'Created':<22} {'Enabled':<9} {'Versions'}")
print(f" {'-'*32} {'-'*22} {'-'*9} {'-'*8}")
for snapshot_path in snapshot_files:
with snapshot_path.open() as file_handle:
snapshot_data = yaml.safe_load(file_handle)
enabled_count = len(_snapshot_enable_list(snapshot_data))
versions_logged = "yes" if snapshot_data.get("plugin_versions") else "no"
print(
f" {snapshot_path.stem:<32} "
f"{snapshot_data.get('created', 'unknown'):<22} "
f"{enabled_count:<9} "
f"{versions_logged}"
)
def cmd_restore_from_snapshot(
base_url: str,
auth_headers: dict,
snapshot_name: str,
*,
dry_run: bool,
use_bulk: bool,
enable_only: bool,
disable_only: bool,
skip_snapshot: bool,
include_version: bool,
) -> None:
"""
Restore plugin state to exactly match a saved snapshot.
Restore is always strict: plugins in the snapshot are enabled and all other
currently enabled plugins are disabled, matching the state at snapshot time.
Use --enable-only to skip the disable step (only enable what the snapshot lists).
"""
snapshot = load_snapshot(snapshot_name)
snapshot_enable_list = _snapshot_enable_list(snapshot)
print(f"Snapshot '{snapshot_name}' ({snapshot.get('created', 'unknown')})")
if snapshot.get("disabled_plugins"):
print(f" {len(snapshot_enable_list)} enabled / {len(snapshot['disabled_plugins'])} disabled at snapshot time")
else:
print(f" {len(snapshot_enable_list)} plugin(s) enabled in snapshot")
if snapshot.get("plugin_versions"):
print(f" Plugin versions recorded: {len(snapshot['plugin_versions'])}")
print()
all_plugins = fetch_all_plugins(base_url, auth_headers)
# Restore is inherently strict: disable anything not in the snapshot
# unless the caller asked only to enable (enable_only=True).
to_enable, to_disable, unmatched_names = compute_plugin_updates(
all_plugins,
enable_names=snapshot_enable_list,
disable_names=[],
strict=not enable_only,
enable_only=enable_only,
disable_only=disable_only,
)
already_correct_count = max(
0, len(snapshot_enable_list) - len(to_enable) - len(unmatched_names)
)
_print_update_plan(to_enable, to_disable, already_correct_count)
if dry_run:
_print_dry_run_preview(to_enable, to_disable)
_report_unmatched_names(unmatched_names)
return
if not skip_snapshot and (to_enable or to_disable):
auto_save_snapshot(all_plugins, include_version)
error_count = _execute_sync(base_url, auth_headers, to_enable, to_disable, use_bulk)
print(f"\nDone. Enabled: {len(to_enable)} Disabled: {len(to_disable)} Errors: {error_count}")
_report_unmatched_names(unmatched_names)
# Main
def main() -> None:
import argparse
parser = argparse.ArgumentParser(
prog="plugin_manager.py",
description="Manage Sisense plugin states via the REST API.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=(
"Plugin names accept the short form (SwitchDimension) or the full\n"
"form (plugin-SwitchDimension) in both CLI args and config.yaml.\n"
"\n"
"Default behavior: enable plugins in enable_plugins, disable plugins\n"
"in disable_plugins, leave everything else unchanged.\n"
"Use --strict to also disable any enabled plugin not in enable_plugins.\n"
"\n"
"A snapshot is saved automatically before each run that\n"
"modifies state. Use --skip-snapshot to suppress this."
),
)
# Universal flags
parser.add_argument(
"--config", default=str(DEFAULT_CONFIG_PATH), metavar="FILE",
help="Path to config.yaml (default: config.yaml next to this script)",
)
parser.add_argument(
"--dry-run", action="store_true",
help="Preview what would change; make no API calls and save no snapshot",
)
parser.add_argument(
"--no-bulk", action="store_true",
help=(
"Send one API call per plugin instead of a single batch PATCH. "
"Slower but easier to diagnose partial failures. "
"Overrides sisense.bulk in config."
),
)
parser.add_argument(
"--skip-snapshot", action="store_true",
help="Do not automatically save a snapshot before this run",
)
parser.add_argument(
"--log-version", action="store_true",
help=(
"Record each plugin's version field (from the API response) in any "
"snapshot saved during this run (manual --save-snapshot or auto saved snapshot)"
),
)
parser.add_argument(
"--strict", action="store_true",
help=(
"Also disable every currently enabled plugin that is not listed in "
"enable_plugins. Without this flag, only plugins in disable_plugins are "
"disabled; everything else is left alone. "
"Always active for --restore-snapshot."
),
)
# Direction flags (mutually exclusive)
direction_group = parser.add_mutually_exclusive_group()
direction_group.add_argument(
"--enable-only", action="store_true",
help="Run only the enable step; skip all disables",
)
direction_group.add_argument(
"--disable-only", action="store_true",
help="Run only the disable step; skip all enables",
)
# Mode (mutually exclusive)
mode_group = parser.add_mutually_exclusive_group()
mode_group.add_argument(
"--enable-one", metavar="PLUGIN",
help=(
"Enable exactly one plugin by name and disable all currently enabled "
"others. Accepts the short or full plugin name."
),
)
mode_group.add_argument(
"--save-snapshot", metavar="NAME", nargs="?", const="__auto__",
help=(
"Save the current plugin state as a named snapshot. "
"Omit NAME for an auto generated timestamp filename. "
"Combine with --log-version to also record versions for each plugin."
),
)
mode_group.add_argument(
"--list-snapshots", action="store_true",
help="List all saved snapshots with creation date and enabled plugin count",
)
mode_group.add_argument(
"--restore-snapshot", metavar="NAME", nargs="?", const="__latest__",
help=(
"Restore plugin state to exactly match a saved snapshot. "
"Omit NAME to use the most recently created snapshot. "
"Always strict (disables plugins not in snapshot) unless --enable-only."
),
)
args = parser.parse_args()
# --list-snapshots reads local files only; no config or API connection needed
if args.list_snapshots:
cmd_list_snapshots()
return
# Load config and connect
config = load_config(Path(args.config))
sisense_config = config.get("sisense", {})
base_url = sisense_config.get("url", "").rstrip("/")
api_token = sisense_config.get("token", "")
if not base_url or not api_token:
print("config.yaml must include sisense.url and sisense.token.")
sys.exit(1)
auth_headers = make_auth_headers(api_token)
use_bulk = sisense_config.get("bulk", True) and not args.no_bulk
# Support both 'enable_plugins' (current key) and 'plugins' (legacy key)
enable_names = config.get("enable_plugins") or config.get("plugins", [])
disable_names = config.get("disable_plugins", [])
# Dispatch
if args.enable_one:
cmd_enable_single_plugin(
base_url, auth_headers, args.enable_one,
dry_run=args.dry_run,
use_bulk=use_bulk,
skip_snapshot=args.skip_snapshot,
include_version=args.log_version,
)
elif args.save_snapshot is not None:
snapshot_name = (
datetime.now().strftime("snapshot_%Y%m%d_%H%M%S")
if args.save_snapshot == "__auto__"
else args.save_snapshot
)
cmd_save_named_snapshot(
base_url, auth_headers, snapshot_name, args.log_version,
)
elif args.restore_snapshot is not None:
snapshot_name = (
latest_snapshot_name()
if args.restore_snapshot == "__latest__"
else args.restore_snapshot
)
cmd_restore_from_snapshot(
base_url, auth_headers, snapshot_name,
dry_run=args.dry_run,
use_bulk=use_bulk,
enable_only=args.enable_only,
disable_only=args.disable_only,
skip_snapshot=args.skip_snapshot,
include_version=args.log_version,
)
else:
# Default: sync instance state to config
if not enable_names and not disable_names:
print("config.yaml must include at least one entry in 'enable_plugins'.")
sys.exit(1)
cmd_sync_to_config(
base_url, auth_headers, enable_names, disable_names,
dry_run=args.dry_run,
use_bulk=use_bulk,
strict=args.strict,
enable_only=args.enable_only,
disable_only=args.disable_only,
skip_snapshot=args.skip_snapshot,
include_version=args.log_version,
)
if __name__ == "__main__":
main()
