Managing Resources With Code

Code management lifecycle

Managing resources with code in Hashboard follows this lifecycle:

1. You create a build that bundles together proposed changes to your resources
2. Hashboard validates that your changes will not break anything in your project.
3. You and/or the relevant reviewers preview the changes in your build to ensure they are having the intended impact.
4. Your build is applied to your project, which deploys your changes to your users.

Below is more detail on each of these steps of the process.

Creating a build

Create a Hashboard build by defining one or more Hashboard yml configuration files in your filesystem and passing them into the hb build command.

Hashboard builds automatically propagate any changes necessary to keep your project consistent. This includes:

• Updating downstream resources. If a column is changed, it will be updated in all dependent items (regardless of whether the dependent items are part of your build) - so changes like name updates will be correctly reflected everywhere.
• Cleaning up defunct resources. If any Models, Attributes, or Measures are deleted, all dependent items that relied on that Model or Column will also be deleted.

The CLI will provide you with a link to view the details of your build after it is created. You can also see a list of all your previous builds on the Builds (opens in a new tab) page.

Build validation

After your configuration files are added to a build, Hashboard checks for issues like:

• Missing or broken dependencies
• Mismatches between database columns and model definitions
• SQL errors

Any issues that are found are surfaced as warnings or errors. A build with errors cannot be applied.

Previewing a build

Builds can be previewed from the build details page, by clicking "Preview" in the top corner or next to any of the resources in the build.

When in a build preview, you are viewing what your project would look like if you were to apply that build. This includes any downstream impacts on resources that are not in your build. For instance, if your build renames an Attribute in a Model, that new name will appear in your build preview when viewing any Saved Exploration or Dashboard that uses data from that model.

Build previews are non-destructive and shareable via their URL. They do not expire, although they may become invalid as the other resources in your project change over time.

Applying a build

When you are ready to apply the changes in a build to your project, you can do so by clicking the Apply button on the build's details page, or by running

$ hb build apply

in your CLI. By default, this will apply the most recent build you created in your bash session. You can also provide a build ID to the build apply command if desired.

Hashboard configuration files

Hashboard supports configuration files written in YAML or JSON. A Hashboard Build will attempt to include every .yml or .json file containing an hbVersion key.

Full documentation of all configuration files can be found for each resource type:

• Data Models
• Saved Explorations
• Dashboards
• Color Palettes
• Homepage Launchpad

Migrating existing resources to code

If you have existing content built in the UI and want to move it into code, you can specify the grn property on the resource. This will cause the config to update an existing resource with that GRN, instead of creating a new resource.

This can also be used to avoid recreating resources when renaming or refactoring the file structure of your project.

Code managed resources

To protect specific resources to only be editable with the Hashboard deployments, add the preventUpdatesFromUI flag set as true to any config. This prevents users from unintentionally updating critical resources from the Hashboard web application and gives your team greater control over valuable long lived resources that are core to your business needs.

Builds vs. Project drafts

Builds and Project Drafts serve similar purposes -- they both can be used to stage, test, and apply changes. Here is how they differ:

Managing build state

Builds can be in any of the following states:

• Queued: Our servers have received the files you would like to build, the build is waiting to be processed.
• Building: Our servers are converting your files into Hashboard resources, you should see results shortly.
• Staged: All resources have been built and can be previewed. If there are no errors you can apply all changes directly to your project.
• Staging Only: All resources have been built and can be previewed. However these changes cannot be applied.
• Applied: Changes were applied to the project.
• Archived: This build is being retained for record-keeping purposes but cannot be modified or applied to the project.

By default builds that are created will finish in the "Staged" state. In order to create a "Staging Only" build you can run hb build --staging-only or click the dropdown next to the 'Apply' button in the Build UI and mark the build as 'Staging Only'. The dropdown also contains an option to archive the selected build. To apply a build that has successfully been staged you can either click "Apply" in the Build UI or run hb build apply via the command line.