@@ -93,10 +93,11 @@ Sharing Charts and Dashboards
9393To share your charts with others in the community, use Superset's "Export" button to
9494save a zip file of your charts and related datasets.
9595
96- .. note ::
96+ .. warning ::
9797 The exported datasets will contain hard-coded references to your particular
98- databases, including your database hostname, port, and username, but it
99- will not contain passwords.
98+ databases, including your database hostname, port, and username, in some cases
99+ it may also contain database passwords. It is vital that you review the
100+ database and dataset files before sharing them.
100101
101102To import charts or dashboards shared by someone in the community:
102103
@@ -109,29 +110,50 @@ To import charts or dashboards shared by someone in the community:
109110Contributing Charts and Dashboards to Aspects
110111^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
111112
112- The Superset assets provided by Aspects can be found in the templated `assets.yaml `_ file.
113- For the most part, these files what Superset exports, but with some crucial differences
113+ The Superset assets provided by Aspects can be found in the templated
114+ `tutoraspects/templates/openedx-assets/assets ` directory. For the most part,
115+ these files are what Superset exports, but with some crucial differences
114116which make these assets usable across all Tutor deployments.
115117
116118To contribute assets to Aspects:
117119
120+ #. Fork this repository and have a locally running Tutor set up with this plugin
121+ installed.
118122#. Export the assets you want to contribute as described in `Sharing Charts and Dashboards `
119- #. Expand the ``.zip `` file.
120- #. Update any database connection strings to use Tutor configuration template variables
121- instead of hard-coded strings, e.g. replace ``clickhouse `` with ``{{CLICKHOUSE_HOST}} ``.
122- Passwords can be left as ``{{CLICKHOUSE_PASSWORD}} ``, though be aware that if you are adding new
123+ #. Run the command:
124+ `tutor aspects import_superset_zip ~/Downloads/your_file.zip `
125+ #. This command will copy the files from your zip to the assets directory and
126+ attempt to warn you if there are hard coded connection settings where it expects
127+ template variables. These are usually in database and dataset assets, and those are
128+ often assets that already exist. The warnings look like:
129+
130+ `WARN: fact_enrollments.yaml has schema set to reporting instead of a setting. `
131+ #. Check the diff of files and update any database connection strings or table names
132+ to use Tutor configuration template variables instead of hard-coded strings, e.g.
133+ replace ``clickhouse `` with ``{{CLICKHOUSE_HOST}} ``. Passwords can be left as
134+ ``{{CLICKHOUSE_PASSWORD}} ``, though be aware that if you are adding new
123135 databases, you'll need to update ``SUPERSET_DB_PASSWORDS `` in the init scripts.
124136 Here is the default connection string for reference::
125137
126- ``clickhousedb+connect://{{CLICKHOUSE_REPORT_URL}}``
127- #. Remove any ``metadata.yaml `` files from the export. We generate these as needed during import.
128- #. Merge your exported files into the directories and files in the `assets.yaml `_.
129- #. Submit a PR with screenshots of your new chart or dashboards, along with an explanation
130- of what data question they answer.
138+ ``clickhousedb+connect://{{CLICKHOUSE_REPORT_URL}} ``
139+ #. You will likely also run into issues where our SQL templates have been expanded into
140+ their actual SQL. If you haven't changed the SQL of these queries (stored in
141+ `tutoraspects/templates/openedx-assets/queries ` you can just revert that change back
142+ to their `include ` values such as:
143+ `sql: "{% include 'openedx-assets/queries/fact_enrollments_by_day.sql' %}" `
144+ #. The script will also warn about missing `_roles ` in dashboards. Superset does not export
145+ these, so you will need to manually add this key with the roles that are necessary to
146+ view the dashboard. See the existing dashboards for how this is done.
147+ #. Run the command `tutor aspects check_superset_assets ` to confirm there are no
148+ duplicate assets, which can happen when you rename an asset, and will cause import
149+ to fail. The command will automatically delete the older file if it finds a duplicate.
150+ #. Check that everything imports correctly by running `tutor local do init -l aspects `
151+ and confirming there are no errors.
152+ #. Double check that your database password did not get exported before committing!
153+ #. Commit and submit a PR with screenshots of your new chart or dashboards, along with an
154+ explanation of what data question they answer.
131155
132156
133- .. _assets.yaml : tutoraspects/templates/aspects/apps/superset/pythonpath/assets.yaml
134-
135157Virtual datasets in Superset
136158^^^^^^^^^^^^^^^^^^^^^^^^^^^^
137159
0 commit comments