SAS Visual Analytics: Building a Governance and History Framework for Report Version Control

[#1]

SAS Visual Analytics reports are often treated as living assets. Business users continuously refine calculations, add or remove objects, adjust prompts, change visualizations, and update layouts. While these changes improve reports over time, they also create a governance challenge:

• What changed between two versions of a report?
• When was a visualization modified?
• Can we recover a previous version?
• How do we support audit and compliance requirements?

The report_history project provides a practical solution. It extracts the complete JSON definition of Visual Analytics reports and captures PNG images of every report section, creating artifacts that can be stored and tracked in Git.

By combining report extraction with Git version control, organizations can create a complete history of report evolution and establish a lightweight governance framework for their SAS Visual Analytics environment.

What is report_history?

The report_history project is a Python utility that connects to SAS Viya, extracts report definitions, and generates images of report sections. For each configured report, the tool:

• Downloads report definitions as JSON.
• Creates PNG images of all report sections.
• Processes reports concurrently.
• Produces a structured output folder.

The resulting output contains both:

• A machine-readable representation of the report.
• Visual snapshots that provide an immediate view of the report's appearance.

This combination makes the repository particularly useful for governance, auditing, documentation, and change tracking.

Why Extract Report Definitions?

The JSON representation of a Visual Analytics report contains the report's metadata, layout definitions, visual objects, data mappings, calculations, filters, and other configuration elements.

• Layout definitions
• Objects and visualizations
• Data mappings
• Calculated items
• Prompts and filters
• Formatting and configuration

Unlike screenshots, JSON files can be compared automatically using version control systems.

For example, a Git comparison can show:

• Added/removed filters
• Added/removed objects
• Calculated item changes
• Prompt definition modifications
• Section layout redesigns

This level of detail is essential for governance teams and report administrators.

Why Capture Images?

Although JSON is essential for technical comparisons, it is not always easy for business stakeholders to review.

The generated PNG images complement the JSON definition by providing a visual representation of each report section.

These images make it easy to:

• Quickly review report changes.
• Validate report rendering.
• Include report snapshots in governance reports.
• Provide visual evidence during audits.
• Compare report versions without opening SAS Visual Analytics.

When combined with Git, image differences become an additional layer of change visibility.

Repository Configuration

The project is configured using a .env file containing:

• SAS Viya connection information.
• User credentials.
• OAuth client credentials.
• Server certificate location.
• Output directory.
• List of reports to extract.

Here is a sample .env file.

VIYA_BASE_URL=https://viya.company.com

VIYA_USERNAME=myuser
VIYA_PASSWORD=mypassword

VIYA_CLIENT_ID=myclient
VIYA_CLIENT_SECRET=mysecret

VIYA_SERVER_CERTIFICATE=/path/to/certificate.pem

REPORT_HISTORY_OUTPUT_LOCATION=/reports/output

REPORT_HISTORY_REPORTS_LIST=/reports/reports.json

The reports to process are defined in a JSON file referenced by the REPORT_HISTORY_REPORTS_LIST parameter.

Each entry contains:

[
  {
    "report_url": "https://viya.company.com/links/resources/report?uri=/reports/reports/12345",
    "label": "Executive Dashboard"
  }
]

The report URL can be obtained directly from Visual Analytics using the Copy Link action. Using the SAS Visual Analytics REST APIs, you can also create a list of reports based on your needs.

The utility extracts the report identifier from the URL and uses it to retrieve the report definition and generate images.

Running the Extraction

Once configured, the extraction process can be executed with:

uv run --env-file .env report-history

The utility authenticates with SAS Viya, removes any existing output directory for the report, downloads the report definition, and generates PNG images for all report sections. The resulting structure resembles:

output/
└── report-id/
    ├── report-id.json
    └── images/
        ├── Retail Insights.png
        ├── Sales.png
        └── Forecast.png

The resulting json will look like this with browser formatting applied:

The resulting PNG image of a report section will look like this:

Governance Workflow

The real value emerges when these extracted assets are committed to a Git repository.

Instead of treating reports as objects hidden inside the SAS Viya platform, organizations can manage report definitions similarly to source code.

A typical workflow looks like this:

1. SAS Visual Analytics reports are identified and configured.
2. The report_history utility extracts report definitions and images.
3. JSON and PNG artefacts are generated.
4. The generated content is committed to a Git repository.
5. Git provides a complete historical record of report changes.
6. Governance teams can review, audit, certify and recover previous versions.

Each extraction becomes a snapshot of the reporting environment. A scheduled execution can:

1. Extract all governed reports.
2. Commit updated files.
3. Push changes to Git.

The Git repository then becomes the historical archive for reporting assets.

Benefits of Using Git

Complete Audit Trail

Every commit records:

• Who made the change.
• When the change occurred.
• Which report was affected.
• Which files changed.

This provides a valuable audit trail without requiring specialized governance software.

Version Recovery

Suppose a report is modified incorrectly. With Git, previous versions remain available. Administrators can review historical report definitions and identify when an issue was introduced. Because the report definition is stored as JSON, recovering earlier configurations becomes straightforward.

Change Reviews

Teams can review report modifications through pull requests.

Before accepting a report update, reviewers can inspect:

• Changes in report definitions.
• Visual differences in generated images.
• Impacted report sections.

This introduces software engineering practices into analytics governance.

Compliance and Regulatory Support

Many organizations operate in regulated environments where reporting changes must be documented.

Examples include:

• Financial reporting.
• Pharmaceutical reporting.
• Manufacturing quality systems.
• Environmental monitoring.

A Git repository containing JSON definitions and report images provides a historical record demonstrating how reports evolved over time.

Disaster Recovery

If a report is accidentally deleted or corrupted, the extracted JSON serves as a backup representation of the report at multiple points in time.

While the repository is not intended to replace SAS backup strategies, it provides an additional layer of protection.  

Governance Scenarios

 

Report Certification

Governance teams can certify specific report versions by tagging Git commits.

Example:

git tag certified-q3-finance

This creates a permanent reference for a certified report state.

Release Tracking

Teams can associate report versions with business releases:

Release 2026.1

├── Sales Dashboard

├── Executive Summary

└── Forecast Analysis

Each release corresponds to a set of Git commits.

Historical Analysis

By reviewing Git history, administrators can answer questions such as:

• How many times was a report modified?
• Which sections change most frequently?
• When was a KPI introduced?
• Which release altered a particular visual?

Best Practices

To maximize governance value:

Best practice	Recommendations & Examples
Store One Repository per Environment	Maintain separate repositories for: Development Test Production This makes environment comparisons easier.
Schedule Regular Extractions	Automate execution daily or weekly to capture report evolution continuously.
Use Meaningful Commit Messages	Examples: Updated Executive Dashboard KPIs Added Forecast Section Modified Customer Profitability Filters
Protect Main Branches	Require pull requests and reviews for governance-controlled reports.
Tag Major Releases	Create Git tags for official report publications or certification milestones.

Conclusion

The report_history project transforms SAS Visual Analytics reports from platform-managed assets into version-controlled artefacts. By extracting report definitions as JSON and generating visual snapshots of report sections, it creates a foundation for governance, auditing, change tracking, and documentation.

When integrated with Git, the solution provides capabilities typically associated with modern software development:

• Version history
• Change tracking
• Auditing
• Review workflows
• Recovery of previous versions
• Release management

For organisations seeking a lightweight yet powerful approach to Visual Analytics governance, combining report_history with Git offers a practical way to maintain visibility into how reports evolve over time while creating a durable historical record of analytic content.

The code related to this article is available here.

Find more articles from SAS Global Enablement and Learning here.