Each time a new version of a Data Standard is published in Apricot, a new dataset is automatically generated for use in Impact Hub. This article explains how dataset versioning works and how to replace a dataset in an existing Builder report to keep your reports current.
Important things to know
Every published Data Standard version creates a new, uniquely named dataset in Impact Hub. Existing datasets are not overwritten.
Replacing a dataset updates all visuals, filters, and field references in that report, but it clears the undo/redo history for the analysis.
If the replacement dataset is missing fields used by the report, you'll be prompted to map or ignore those fields before the replacement completes.
Dataset replacement only affects the report you're editing. Other reports using the original dataset are not impacted.
What triggers a new dataset version
A new dataset is created each time a Data Standard version is published in Apricot. Draft versions do not generate datasets. The new dataset appears alongside existing dataset versions for the same Data Standard.
How datasets are named
Datasets include the Data Standard name, a version number, and a dataset ID suffix. For example:
Student Goals_v1_APR_DS424 — version 1
Student Goals_v2_APR_DS447 — version 2
Note: Naming conventions may vary by organization. If you're unsure which datset corresponds to a published version, check with your Apricot administrator.
Create a new report with a specific dataset version
From Builder, select Create report.
Enter your Report name.
Search for and select the dataset version you want to use.
Select Save.
Replace a dataset in an existing report
Use this process when a new Data Standard version has been published and you want to update an existing report without rebuilding it.
Before you begin
Confirm the new dataset exists in Impact Hub. If it doesn't appear in the dataset list, the Data Standard version may not yet be fully published in Apricot.
Step 1: Open dataset management
Open the report in Builder, then locate the Data panel. From the dataset dropdown, select Manage datasets.
Step 2: Initiate the replacement
In the Datasets in this analysis dialog, find the dataset you want to replace. Select the three-dot (⋮) icon next to its status and choose Replace.
Step 3: Select the replacement dataset
In the Select replacement dataset dialog, search for and select the new dataset version. After selecting the appropriate version, choose Select to continue.
Step 4: Confirm the replacement
Review the original and replacement dataset names to ensure you are selecting the correct version. When ready, select Replace to confirm. This action clears the undo and redo history for the analysis.
If all fields used in the report exist in the new dataset version, the replacement completes automatically.
Step 5: Review and resolve missing fields
If the new dataset version is missing fields used in the report, Impact Hub displays a Mismatch in replacement dataset dialog before completing the replacement.
Select Update field mapping to review the list of fields used in the report. Impact Hub will attempt to automatically match fields where possible. Matched fields are indicated, while unmatched fields require manual action.
For each unmatched field, you can either map it to an equivalent field in the new dataset or choose to ignore it if no equivalent field exists.
Note: Ignoring a field may cause errors in visuals that depend on that field.
After resolving all unmatched fields, select Confirm to complete the replacement.
If any fields were ignored and are still referenced in visuals, those visuals will display the following message: Fields for this visual no longer in analysis. In that case, reassign the appropriate field from the new dataset or remove the affected visual.
Troubleshooting checklist
Pre-checks
Has the new Data Standard version been fully published in Apricot? Datasets are generated only after a version is published, not while in draft.
Do you know which fields are used in a report? Review visuals, filters, and calculated fields before replacing so you're ready to map or ignore renamed/removed fields.
Post-change verification
Does the Data panel show the new dataset name in the dataset dropdown?
Did the "Dataset replaced" banner appear? If not, try the process again.
Are any visuals showing "Fields for this visual no longer in analysis"? Assign a valid field from the new dataset or remove the visual.
Are there any Missing field indicators in a field well? Assign a valid field or remove the field well entry.
Did you re-publish the report as a dashboard? Select Publish to make the updated report visible to viewers.
Do other reports reference the original dataset? Replacement is report-specific, so update other affected reports individually.