From 8a50fc3106dce51706a3a2fe2fec1e45492c1e24 Mon Sep 17 00:00:00 2001 From: Brian Mesick Date: Fri, 21 Jun 2024 16:07:11 -0400 Subject: [PATCH 1/2] docs: Update information on extending Superset assets --- docs/how-tos/superset_extra_assets.rst | 82 +++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 9 deletions(-) diff --git a/docs/how-tos/superset_extra_assets.rst b/docs/how-tos/superset_extra_assets.rst index dd335ce..743ff91 100644 --- a/docs/how-tos/superset_extra_assets.rst +++ b/docs/how-tos/superset_extra_assets.rst @@ -3,7 +3,7 @@ Superset extra assets ********************* -Developers the patch `superset-extra-assets` to add extra assets to Superset and those +Developers user the `superset-extra-assets` patch to add extra assets to Superset and those will be imported at initialization. An example a tutor inline plugin using the patch is the following: @@ -27,19 +27,83 @@ An example a tutor inline plugin using the patch is the following: table_name: "..." ... + The patch is expected to be a list of assets with an extra attribute called **_file_name**, which uniquely identifies the asset entry. Each asset is expected to be a valid yaml object with the attributes that Superset expects for each asset type. See -`assets.yaml `_ +`assets `_ for examples of asset yaml declarations. -Additionally to the default fields for each asset type, the following fields are supported: +In most cases, however, you will want to develop Superset dashboards, charts, datasets, and +sometimes even databases in the Superset UI and import them into a plugin that can be managed +in source control. As of Aspects 1.0.3 use the same command to import assets into a Tutor +plugin that we use to maintain Aspects itself. + +You can use the `Tutor Plugin Cookiecutter `_ +to create a skeleton plugin. Then you can create a patch file that will include all of your +Superset assets into Aspects when the plugin is enabled. + +The file name is the patch name ``/patches/superset-extra-assets``: + +.. code-block:: + + {% for file in "/superset-assets/"|walk_templates %} + --- + _file_name: {{ file.split('/')[-1] }} + {% include file %} + {% endfor %} + + +This recursively includes each file in the superset-assets directory of your extension's +tempates directory, when ``tutor config save is run``. For example +``/templates/superset-assets/*``. + +Now you can export your Superset dashboard, which it will download to your local computer +as a .zip file. As long as you are running Aspects 1.0.3 or newer you can use the following +command to unzip the file to your plugin directory: + + +.. code-block:: + + tutor aspects import_superset_zip /.zip --base_assets_path //templates//superset-assets/ + + +This command does several things to make import safer and easier, including checking for some +required security fields, safely naming files so that charts with duplicate names don't +overwrite each other, and checking that certain fields use Tutor settings instead of hard +coded values. It also adds a special ``_file_name`` key that tells Aspects what name to use +for the file when importing back to Superset. + +.. warning:: + + When importing a dashboard you will need to manually add a ``_roles`` key, which + sets the permissions for who can view the dashboard. In addition to the default roles + (student, instructor, operator, admin) you can also add custom roles . + + +An example roles key looks like this: + +.. code-block:: + + _roles: + - '{{ SUPERSET_ROLES_MAPPING.instructor }}' + + +.. warning:: + + When a Superset zip is exported it will contain any datasets and databases needed for + all of the charts in that dashboard. This may include the default xapi and MySQL + databases or Aspects datasets that you probably do not want to overwrite, and can + include their passwords! + + Use caution when importing datasets or databases your project and make sure that they + are only ones you have created yourself unless you truly intend to overwrite defaults. + -- Dashboard: **_roles** a list of roles names to be associated with a dashboard. +A simple example showing the final directory structure is available +`here `_. -Override Superset Default Assets -################################ +Once you have your files imported to the plugin, make sure it is installed and enabled +in your Tutor environment, then you should just be able to do ``tutor config save`` and +``tutor import-assets`` to update your Superset assets. -Aspects allows the site operator to override the default Superset assets by creating an Superset -extra asset as explained above using the same UUID as the default asset. The UUID of the default -assets can be found in the `assets.yaml` From 02c07b4b5a2cf0ad8de2075a0d004b823b282dc6 Mon Sep 17 00:00:00 2001 From: Brian Mesick Date: Mon, 24 Jun 2024 10:57:55 -0400 Subject: [PATCH 2/2] docs: Feedback updates --- docs/how-tos/superset_extra_assets.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-tos/superset_extra_assets.rst b/docs/how-tos/superset_extra_assets.rst index 743ff91..f2e828e 100644 --- a/docs/how-tos/superset_extra_assets.rst +++ b/docs/how-tos/superset_extra_assets.rst @@ -3,7 +3,7 @@ Superset extra assets ********************* -Developers user the `superset-extra-assets` patch to add extra assets to Superset and those +Developers can use the `superset-extra-assets` patch to add extra assets to Superset and those will be imported at initialization. An example a tutor inline plugin using the patch is the following: @@ -55,10 +55,10 @@ The file name is the patch name ``/patches/superset-extra-assets This recursively includes each file in the superset-assets directory of your extension's -tempates directory, when ``tutor config save is run``. For example +tempates directory, when ``tutor config save`` is run. For example ``/templates/superset-assets/*``. -Now you can export your Superset dashboard, which it will download to your local computer +Now you can export your Superset dashboard, which will download to your local computer as a .zip file. As long as you are running Aspects 1.0.3 or newer you can use the following command to unzip the file to your plugin directory: