superset 0.1.6 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16bb352b533737ed4faed7d5b4360c850619d60b7997b12638019681a8b36bfd
-  data.tar.gz: e7dd50138ea34bd23969a61bf6f69f7eb98cc6174f67abdb05fdb9ba4eb60197
+  metadata.gz: 0f3edd28b29118fb3c7ebc2eb7a199a92939429683bbe0c19aecc87b09202d9e
+  data.tar.gz: f4eba7dd0dccd0093f8016e565df81861f0157560ab2f0320e7c4f29caec31c7
 SHA512:
-  metadata.gz: ed7199d606cb33b4f30e79d6816ccd2d00c63061c88d630b8e9b538e540cbf4ae3ea50bfccf3acb8ba7e6d92ba09e51871a58b0ea3a84cbfc37d16641923d737
-  data.tar.gz: 50e1ed97a6fb3b698136c313b0384755f42eecf6b171aa7a02021919e59fc9d2bed6991fb03129d8f37a47df6ca4d825b542fe8d36b1410d1bbd284570014e01
+  metadata.gz: c89e37964c7a4e3ae49c484cd4594f7471734184500874c04c217a58ea785eede26390fcee81b178da92d7f4f0a0f263f61d959f33ee235a7d633a609b3cdb77
+  data.tar.gz: 96a68b6e37885caa88dd6fc1b8b219f5fbe45f25347f9e3c66a52f1a8f167b5fa48d03dac849f4fa8b04426d450ba050af0cabe268b5961e77c306fdba98b969

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## Change Log
 
+## 0.2.4 - 2025-01-29
+* modifies the `Superset::Dashboard::Datasets::List.new(id).schemas` to optionally include filter datasets as well.
+* modifies the `Superset::Dashboard::Embedded::Get.new` to accept dashboard_id as named parameter
+* modifies the `Superset::Dashboard::List.new()` to accept an additional named parameter `include_filter_dataset_schemas` to decide whether filter datasets needs to be included when getting the schemas of the datasets
+* modifies the `Superset::Dashboard::List.new().retrieve_schemas` to call `Datasets::List.new(dashboard_id: id).schemas` with an additional parameter `include_filter_datasets` to fetch the filter dataset schemas as well.
+
+
+## 0.2.3 - 2024-11-15
+
+* modifies the `Superset::Dashboard::Datasets::List.new(id).dataset_details` and `Superset::Dashboard::Datasets::List.new(id).list` to optionally include filter datasets as well to duplicate those during the dashboard duplication process. It also add a new column "Filter only" in the result which shows if a dataset is used only on filters
+* This also adds an additional check in source dataset duplication that if any dataset already exists with the new name in the target schema we can use the existing dataset itself for the new dashboard also.
+* Exporting a Dashboard will also include the Zip file in the repo backup (destination_path) folder.
+* Exporting a Dashboard and copying the files to the backup folder will also clear out any previous backup files that no longer exist in the current zip export.
+* Adds a put endpoint for chart and datasets which is needed for the bulk update of set of charts/datasets
+
+## 0.2.2 - 2024-10-10
+
+* add ImportDashboardAcrossEnvironments class for transfering between superset environments
+
+## 0.2.1 - 2024-09-17
+
+* add Superset::Database::Export class for exporting database configurations
+* add Superset::Dashboard::Import class for importing a dashboards
+
+## 0.2.0 - 2024-08-19
+
+* Adding RLS filter clause to the 'api/v1/security/guest_token/' API params in guest_token.rb - https://github.com/rdytech/superset-client/pull/31
+* Any filter that needs to applied to the dataset's final where condition can be passed here. Ex: [{ "clause": "publisher = 'Nintendo'" }]. Refer this: https://github.com/apache/superset/tree/master/superset-embedded-sdk#creating-a-guest-token
+
+## 0.1.7 - 2024-08-27
+
+* adds filter title_equals to dashboard list class - https://github.com/rdytech/superset-client/pull/33
+
 ## 0.1.6 - 2024-07-10
 
 * added a class **WarmUpCache** to hit the 'api/v1/dataset/warm_up_cache' endpoint to warm up the cache of all the datasets for a particular dashaboard being passed to the class - https://github.com/rdytech/superset-client/pull/28

data/README.md

@@ -8,6 +8,12 @@ All ruby classes are namespaced under `Superset::`
 
 # Installation
 
+## Setup API Credentials
+
+Follow this to [setup your users API creds](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
+
+Short version is .. copy the `env.sample` to `.env` and add edit values where applicable.  Opening a console with `bin/console` will then auto load the `.env` file.
+
 ## Docker Setup
 
 Build, bundle and open a ruby console
@@ -18,188 +24,74 @@ docker-compose run --rm app bundle install
 docker-compose run --rm app bin/console
 ```
 
-Run specs
+## Setup Locally ( no docker ) 
+
+Requires Ruby >= 2.6.0 
+
+Bundle install and open a ruby console.
 
 ```
-docker-compose run --rm app rspec
-# or 
-docker-compose run --rm app bash      # then run 'bundle exec rspec' from the container.
+bundle install
+bin/console
 ```
 
-## Local setup or including in a Ruby/Rails app
+## Including in a Ruby app
 
 Add to your Gemfile `gem 'superset'`  
 And then execute: `bundle install`  
 Or install it yourself as `gem install superset`
 
-## Setup API Credentials
+## Run specs
 
-Follow this doc setup your users API creds [setting_up_personal_api_credentials](https://github.com/rdytech/superset-client/tree/develop/doc/setting_up_personal_api_credentials.md)
+```
+docker-compose run --rm app rspec
+# or 
+docker-compose run --rm app bash      # then run 'bundle exec rspec' from the container.
+```
 
-Short version is .. copy the `env.sample` to `.env` and add edit values where applicable.  Opening a console with `bin/console` will then auto load the `.env` file.
 
 ## Usage
 
-Experiment with the API calls directly by open a pry console using  `bin/console`
-
-
-
-
-### API calls
-
-Quickstart examples
+Experiment with the API calls directly by open a pry console using  `bin/console`.
 
 ```ruby
-Superset::Database::List.call
-Superset::Database::GetSchemas.new(1).list # get schemas for database 1
-
 Superset::Dashboard::List.call
-Superset::Dashboard::List.new(title_contains: 'Sales').list
-
-Superset::Dashboard::BulkDelete.new(dashboard_ids: [1,2,3]).perform        # Dashboards only ( leaves all charts, datasets in place)
-Superset::Dashboard::BulkDeleteCascade.new(dashboard_ids: [1,2,3]).perform # Dashboards and related charts and datasets.
-
-Superset::Sqllab::Execute.new(database_id: 1, schema: 'public', query: 'select count(*) from birth_names').perform
-
-Superset::Dashboard::Export.new(dashboard_id: 1, destination_path: '/tmp').perform
-
-Superset::RouteInfo.new(route: 'dashboard/_info').perform # Get info on an API endpoint .. handy for getting available filters
-Superset::RouteInfo.new(route: 'chart/_info').filters     # OR just get the filters for an endpoint
 
 superset_class_list # helper method to list all classes under Superset::
-
+sshelp              # aliased for superset_class_list
 ```
 
-### Duplicating Dashboards
-
-Primary motivation behind this library was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.  
-See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
-
-### API Examples with results
-
-Generally classes follow the convention/path of the Superset API strucuture as per the swagger docs.
+More examples [listed here](https://github.com/rdytech/superset-client/tree/develop/doc/usage.md)
 
-ref https://superset.apache.org/docs/api/
 
-Limited support for filters is available on some list pages, primarily through param `title_contains`.  
-Pagination is supported via `page_num` param.
+## Duplicating Dashboards
 
-Primary methods across majority of api calls are
-- response : the full API response
-- result : just the result attribute array
-- list : displays a formatted output to console, handy for quick investigation of objects
-- call : is a class method to list on Get and List requests
-
-```ruby
-# List all Databases
-Superset::Database::List.call
-# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/?q=(page:0,page_size:100), {}
-+----+------------------------------------+------------+------------------+
-|                        Superset::Database::List                         |
-+----+------------------------------------+------------+------------------+
-| Id | Database name                      | Backend    | Expose in sqllab |
-+----+------------------------------------+------------+------------------+
-| 1  | examples                           | postgresql | true             |
-+----+------------------------------------+------------+------------------+
-
-# List database schemas for Database 1
-Superset::Database::GetSchemas.new(1).list
-# DEBUG -- : Happi: GET https://your-superset-host/api/v1/database/1/schemas/, {}
-=> ["information_schema", "public"]
-
-# List dashboards
-Superset::Dashboard::List.call
-# PAGE_SIZE is set to 100, so get the second set of 100 dashboards with
-Superset::Dashboard::List.new(page_num: 1).list
-# OR filter by title
-Superset::Dashboard::List.new(title_contains: 'Sales').list
-# DEBUG -- : Happi: GET https://your-superset-host/api/v1/dashboard/?q=(filters:!((col:dashboard_title,opr:ct,value:'Sales')),page:0,page_size:100), {}
-
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-|                                              Superset::Dashboard::List                                              |
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-| Id  | Dashboard title              | Status    | Url                                                                |
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-| 6   | Video Game Sales             | published | https://your-superset-host/superset/dashboard/6/                   |
-| 8   | Sales Dashboard              | published | https://your-superset-host/superset/dashboard/8/                   |
-+-----+------------------------------+-----------+--------------------------------------------------------------------+
-
-
-Superset::Dashboard::Get.call(1)  # same as Superset::Dashboard::Get.new(1).list
-+----------------------------+
-|     World Banks Data      |
-+----------------------------+
-| Charts                     |
-+----------------------------+
-| % Rural                    |
-| Region Filter              |
-| Life Expectancy VS Rural % |
-| Box plot                   |
-| Most Populated Countries   |
-| Worlds Population          |
-| Worlds Pop Growth          |
-| Rural Breakdown            |
-| Treemap                    |
-| Growth Rate                |
-+----------------------------+
-
-
-```
-## Optional Credential setup for Embedded User
+One Primary motivation behind this gem was to use the Superset API to duplicate dashboards, charts, datasets across multiple database connections.
 
-Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
+Targeted use case was for superset embedded functionality implemented in a application resting on multi tenanted database setup.
 
-The Superset API users fall into 2 categories  
-- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.  
-  ref `Superset::Credential::ApiUser`  
-  which pulls credentials from  `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
-
-- a user for guest token api call to use when embedding dashboards in a host application.  
-  ref `Superset::Credential::EmbeddedUser`
-  which pulls credentials from  `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+See examples in [Duplicate Dashboards](https://github.com/rdytech/superset-client/tree/develop/doc/duplicate_dashboards.md)
 
+## Moving / Transferring Dashboards across Environments
 
-### Fetch a Guest Token for Embedded user
+With a few configuration changes to an import file, the process can be codified to transfer a dashboard between environments.
 
-Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in  
-`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+See example in [Transferring Dashboards across Environments](https://github.com/rdytech/superset-client/tree/develop/doc/migrating_dashboards_across_environments.md)
 
-```
-Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
-=> "eyJ0eXAiOi............VV4mrMfsvg"
-```
+## Contributing
 
-## Releasing a new version
+- Fork it
+- Create your feature branch (git checkout -b my-new-feature)
+- Commit your changes (git commit -am 'Add some feature')
+- Push to the branch (git push origin my-new-feature)
+- Create new Pull Request
 
-On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.  
-Build the new version and upload to gemfury.
 
-`gem build superset.gemspec`
 
 ### Publishing to RubyGems
 
 WIP .. direction is for this gem to be made public
 
-### ReadyTech private Gemfury repo
-
-ReadyTech hosts its own private gemfury remote repo.
-
-Get the latest develop into master
-
-    git checkout master
-    git pull
-    git fetch
-    git merge origin/develop
-
-Tag the version and push to github
-
-    git tag -a -m "Version 0.1.0" v0.1.0
-    git push origin master --tags
-
-Push to gemfury or upload the build manually in the gemfury site.
-
-    git push fury master
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/doc/duplicate_dashboards.md

@@ -206,9 +206,6 @@ Putting it simply, the current thinking is to delete all the replica dashboards
 
 ### Bringing the Duplicate Dashboard process into Superset core
 
-(WIP) The goal would be to have the DuplicateDashboard process as a part of the core superset codebase.
-
-To that end this Superset Improvement Proposal (SIP) .. is a starting point.
-
-{add SIP request here}
+An ideal direction would be to have the DuplicateDashboard process as a part of the core superset codebase.
 
+A Superset discussion thread has been started in  [Duplicating Dashboards into a new database or schema](https://github.com/apache/superset/discussions/29899)

data/doc/migrating_dashboards_across_environments.md

@@ -0,0 +1,173 @@
+# Transferring Dashboards across Environments
+
+In this document, we will discuss how to transfer dashboards across Superset hosting environments with the goal of heading towards an API call to automate the process.
+
+Current process is limited to dashboards with all datasets based on a single database connection.
+
+## Short Version
+
+Assuming you want to transfer a dashboard from Env1 to Env2.
+
+You will need the following:
+- a Env1 Dashboard Export Zip file
+- a Env2 Database config export yaml
+- a Env2 schema to point your datasets to
+
+Assuming your API env for ruby is setup for your target superset environment.
+( ie using API creds for Env2 for this example )
+
+```ruby
+
+new_import_zip = Superset::Services::ImportDashboardAcrossEnvironments.new(
+  dashboard_export_zip:      'path_to/dashboard_101_export_20241010.zip',
+  target_database_yaml_file: 'path_to/env2_db_config.yaml', 
+  target_database_schema:    'acme', 
+  ).perform
+
+# now import the adjusted zip to the target superset env
+Superset::Dashboard::Import.new(source_zip_file: new_import_file).perform
+
+```
+
+## Background
+
+A common practice is to set up infrastructure to deploy multiple Superset environments. For example, a simple setup might be:
+- Local development environment for testing version upgrades and feature exploration
+- Staging Superset environment for testing in a production-like environment
+- Production Superset environment that requires a higher level of stability and uptime
+
+For the above example, the Superset staging environment often holds connections to staging databases, and the Superset production environment will hold connections to the production databases.
+
+In the event where the database schema structure for the local development, staging, and production databases are exactly the same, dashboards can be replicated and transferred across Superset hosting environments.
+
+That process does require some manual updating of the exported YAML files before importing them into the target environment. Also required is some understanding of the underlying dashboard export structure and how the object UUIDs work and relate to each other, especially in the context of databases and datasets.
+
+## Dashboard Export/Import within the Same Environment
+
+This is a fairly straightforward process.
+
+There are multiple methods for exporting a dashboard:
+- Export from the dashboard list page in the GUI
+- Export via the Superset API
+- Export via the Superset CLI
+
+Each export method will result in a zip file that contains a set of YAML files as per this list below, which is an export of customized version of the test Sales dashboard from the default example dashboards.
+
+Test fixture is: https://github.com/rdytech/superset-client/blob/develop/spec/fixtures/dashboard_18_export_20240322.zip
+
+```
+└── dashboard_export_20240321T214117
+    ├── charts
+    │   ├── Boy_Name_Cloud_53920.yaml
+    │   ├── Names_Sorted_by_Num_in_California_53929.yaml
+    │   ├── Number_of_Girls_53930.yaml
+    │   ├── Pivot_Table_53931.yaml
+    │   └── Top_10_Girl_Name_Share_53921.yaml
+    ├── dashboards
+    │   └── Birth_Names_18.yaml
+    ├── databases
+    │   └── examples.yaml
+    ├── datasets
+    │   └── examples
+    │       └── birth_names.yaml
+    └── metadata.yaml
+```
+
+Each of the above YAML files holds UUID values for the primary object and any related objects.
+
+- Database YAMLs hold the database connection string as well as a UUID for the database
+- Dataset YAMLs have their own UUID as well as a reference to the database UUID
+- Chart YAMLs have their own UUID as well as a reference to their dataset UUID
+
+Example of the database YAML file:
+
+```
+cat databases/examples.yaml
+database_name: examples
+sqlalchemy_uri: postgresql+psycopg2://superset:XXXXXXXXXX@superset-host:5432/superset
+cache_timeout: null
+expose_in_sqllab: true
+allow_run_async: true
+allow_ctas: true
+allow_cvas: true
+allow_dml: true
+allow_file_upload: true
+extra:
+  metadata_params: {}
+  engine_params: {}
+  metadata_cache_timeout: {}
+  schemas_allowed_for_file_upload:
+  - examples
+  allows_virtual_table_explore: true
+uuid: a2dc77af-e654-49bb-b321-40f6b559a1ee
+version: 1.0.0
+```
+
+If we grep the database/examples.yaml we can see the UUID of the database.
+
+```
+grep -r uuid databases/
+  databases/examples.yaml:uuid: a2dc77af-e654-49bb-b321-40f6b559a1ee
+
+```
+
+Now if we look at the UUID values in the datasets, you will see both the dataset UUID and the reference to the database UUID.
+
+```
+grep -r uuid datasets
+datasets/examples/birth_names.yaml:uuid: 283f5023-0814-40f6-b12d-96f6a86b984f
+datasets/examples/birth_names.yaml:database_uuid: a2dc77af-e654-49bb-b321-40f6b559a1ee
+```
+
+If the above dashboard zip file `dashboard_18_export_20240322.zip` was imported as is to the same superset environment as it was exported from, this would mean all UUID's would already exist in superset and these objects would be found and updated with the imported zip data.
+
+If the above zip file was imported as is to a different target Superset environment, it would fail as there would be no matching database UUID entry in that target Superset environment.
+
+**Key Point:** When importing a dashboard to a different Superset environment than the original environment, the database configuration in the zip export must exist in the target Superset environment and all datasets must point to the database config.
+
+## Migrate a Dashboard to a Different Superset Environment
+
+With the above knowledge, we can now think about how to migrate dashboards between Superset environments.
+
+Each Superset object is given a UUID. Within the exported dashboard files, we are primarily concerned with:
+- Replacing the staging database configuration with the production configuration
+- Updating all staging datasets to point to the new production database UUID
+
+Given we have a request to 'transfer' a dashboard across to a different environment, say staging to production, how would we then proceed?
+
+With the condition that the database in staging and production are structurally exactly the same schema, from the above discussion on UUIDs, you can then see that if we want to import a staging dashboard export into the production environment, we will need to perform the following steps:
+
+1. Export the staging dashboard and unzip
+2. Note the staging database UUIDs in the `databases/` directory
+3. Get a copy of the production database YAML configuration file
+4. In the exported dashboard files, replace the staging database YAML with the production YAML
+5. In the dataset YAML files, replace all instances of the previously noted staging database UUID with the new production UUID
+6. Zip the files and import them to the production environment
+
+The process above assumes that whoever is migrating the dashboard has a copy of the target database YAML files so that in steps 3 and 4 we can then replace the staging database YAML with the production one.
+
+## Requirements
+
+The overall process requires the following:
+- The source dashboard zip file
+- The target Superset environment database YAML file
+- Ability to copy and manipulate the source dashboard zip file
+- The ability to import via API to the target Superset environment
+
+
+## Gotchas!
+
+Migrating a dashboard once to a new target environment, database, schema will result in:
+- Creating a new dashboard with the UUID from the import zip
+- Creating a new set of charts with their UUIDs from the import zip
+- Creating a new set of datasets with their UUIDs from the import zip
+
+Migrating the same dashboard a second time to the same target environment, database, but different schema will NOT create a new dashboard.
+
+It will attempt to update the same dashboard as the UUID for the dashboard has not changed. It will also NOT change any of the datasets to the new schema. This appears to be a limitation of the import process, which may lead to some confusing results.
+
+## References
+
+Some helpful references relating to cross-environment workflows:
+- [Managing Content Across Workspaces](https://docs.preset.io/docs/managing-content-across-workspaces)
+- [Superset Slack AI Explanation](https://apache-superset.slack.com/archives/C072KSLBTC1/p1722382347022689)

data/doc/publishing.md

@@ -0,0 +1,39 @@
+# Publishing
+
+The team at ReadyTech currently manages the gem and new version releases.
+
+As per demand / usage of the public gem, the team at ReadyTech will soon move to primarily hosting
+the gem on RubyGems.
+
+Until then, ReadyTech will continue to host a private Gemfury version as well as RubyGems.
+
+
+## ReadyTech private Gemfury repo
+
+### Releasing a new version
+
+On develop branch make sure to update `Superset::VERSION` and `CHANGELOG.md` with the new version number and changes.  
+
+Build the new version and upload to gemfury.
+
+`gem build superset.gemspec`
+
+### Publish to Gemfury
+
+ReadyTech hosts its own private gemfury remote repo.
+
+Get the latest develop into master
+
+    git checkout master
+    git pull
+    git fetch
+    git merge origin/develop
+
+Tag the version and push to github
+
+    git tag -a -m "Version 0.1.0" v0.1.0
+    git push origin master --tags
+
+Push to gemfury or upload the build manually in the gemfury site.
+
+    git push fury master

data/doc/setting_up_personal_api_credentials.md

@@ -26,17 +26,19 @@ Starting a ruby console with `bin/console` will auto load the env vars.
 
 If your Superset instance is setup to authenicate via SSO then your authenticating agent will most likely have provided a username for you in the form of a UUID value.
 
-This is easily retrieved on you User Profile page in Superset.
+This is easily retrieved on your user profile page in Superset.
 
-Optionally use jinja template macro in sql lab.
+Optionally use the jinja template macro in sql lab.
 
 ```
 select '{{ current_username() }}' as current_username;
 ```
 
+Then plug your username in to the .env file.
+
 ## Creating / Updating your password via Swagger interface
 
-A common setup is to use SSO to enable user access in Superset.  This would mean your authenticating agent is your SSO provider service ( ie Azure ) and most likely you do not have / need a password configured for your Superset user for GUI access.
+A common setup is to use SSO to enable user access in Superset.  This would mean your authenticating agent is your SSO provider service ( ie Azure etc ) and most likely you do not have / need a password configured for your Superset user for GUI access.
 
 If this is the case, you will need to add your own password via hitting the superset API using the swagger interface.
 
@@ -50,7 +52,7 @@ select '{{ current_user_id() }}' as current_user_id;
 ```
 - ask your superset admin to tell you what your personal superset user id is.
 
-Once you have your user id value, open the Swagger API page on you superset host.  
+Once you have your user id value, open the Swagger API page on your superset host.  
 `https://{your-superset-host}/swagger/v1`
 
 Scroll down to the 'Security Users' area and find the PUT request that will update your users record.
@@ -78,7 +80,7 @@ Given some local development requirements where you have to access multiple supe
 Just set the overall superset environment in `.env`
 
 ```
-# .env file holding one setting for the overall superset environment
+# .env file holding one setting for the superset environment your accessing
 SUPERSET_ENVIRONMENT='staging'
 ```
 
@@ -101,11 +103,22 @@ SUPERSET_API_USERNAME="production-user-here"
 SUPERSET_API_PASSWORD="set-password-here"
 ```
 
-The command `bin/console` will then load your env file depending on the value in ENV['SUPERSET_ENVIRONMENT'] from the primary `.env`.
+And again, for localhost if required to perform api call in you local dev environment.
+Create a new file called `.env-localhost` that holds your superset development host and credentials.
+
+```
+# specific settings for the superset localhost env
+SUPERSET_HOST="http://localhost:8080/"
+SUPERSET_API_USERNAME="dev-user-here"
+SUPERSET_API_PASSWORD="set-password-here"
+```
+
+
+The command `bin/console` will then load your env file depending on the value in ENV['SUPERSET_ENVIRONMENT'] from the primary `.env` file.
 
 When you need to switch envs, exit the console, edit the .env to your desired value, eg `production`, then open a console again.
 
-Bonus is the Pry prompt will now also include the `SUPERSET_ENVIRONMENT` value.
+The ruby prompt will now also include the `SUPERSET_ENVIRONMENT` value.
 
 ```
 bin/console
@@ -122,6 +135,29 @@ Happi: GET https://your-staging-superset-host.com/api/v1/dashboard/?q=(filters:!
 +----+------------------+-----------+------------------------------------------------------------------+
 ```
 
+## Optional Credential setup for Embedded User
+
+Primary usage is for api calls and/or for guest token retrieval when setting up applications to use the superset embedded dashboard workflow.
+
+The Superset API users fall into 2 categories  
+- a user for general api calls to endpoints for Dashboards, Datasets, Charts, Users, Roles etc.  
+  ref `Superset::Credential::ApiUser`  
+  which pulls credentials from  `ENV['SUPERSET_API_USERNAME']` and `ENV['SUPERSET_API_PASSWORD']`
+
+- a user for guest token api call to use when embedding dashboards in a host application.  
+  ref `Superset::Credential::EmbeddedUser`
+  which pulls credentials from  `ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+
+
+### Fetch a Guest Token for Embedded user
+
+Assuming you have setup your Dashboard in Superset to be embedded and that your creds are setup in  
+`ENV['SUPERSET_EMBEDDED_USERNAME']` and `ENV['SUPERSET_EMBEDDED_PASSWORD']`
+
+```
+Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
+=> "eyJ0eXAiOi............VV4mrMfsvg"
+```