A production-ready Python tool that automates the creation of Solution Design Reference (SDR) documents from your Adobe Customer Journey Analytics (CJA) implementation.

A Solution Design Reference is the essential documentation that bridges your business requirements and your analytics implementation. It catalogs every metric and dimension in your CJA Data View, serving as the single source of truth for what data you're collecting and how it's configured.

The Problem: Manually documenting CJA implementations is time-consuming, error-prone, and quickly becomes outdated. Teams waste hours exporting data, formatting spreadsheets, and cross-referencing configurations—only to repeat the process when things change.

The Solution: This tool connects directly to the CJA API, extracts your complete Data View configuration, validates data quality, and generates professionally formatted documentation in seconds. It also tracks changes between Data Views over time with built-in diff comparison and snapshot capabilities.

Origin: This project evolved from a Jupyter notebook proof-of-concept into a production-ready CLI. The notebook remains excellent for learning; this tool is for teams needing automation, change tracking, and enterprise-grade reliability.

1. Connects to your CJA instance via the Adobe API
2. Extracts all metrics, dimensions, and configuration from your Data View(s)
3. Validates data quality with 8+ automated checks (duplicates, missing fields, null values)
4. Generates formatted documentation with color-coded quality indicators

• Analytics Teams needing up-to-date implementation documentation
• Consultants managing multiple client implementations
• Data Governance teams requiring audit trails and quality tracking
• DevOps Engineers automating CJA audits in CI/CD pipelines

# Clone the repository
git clone https://github.com/brian-a-au/cja_auto_sdr.git
cd cja_auto_sdr

macOS/Linux:

# Install uv package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

Windows (PowerShell):

# Install uv package manager
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install project dependencies
uv sync

If uv doesn't work, use native Python instead (recommended for Windows):

python -m venv .venv
.venv\Scripts\activate
pip install -e .

Windows Users: If you encounter issues with uv run or NumPy import errors on Windows, we recommend using Python directly. See the Windows-Specific Issues section in the troubleshooting guide for detailed solutions.

Running commands: You have three equivalent options:

• uv run cja_auto_sdr ... — works immediately on macOS/Linux, may have issues on Windows
• cja_auto_sdr ... — after activating the venv: source .venv/bin/activate (Unix) or .venv\Scripts\activate (Windows)
• python cja_sdr_generator.py ... — run the script directly (most reliable on Windows)

This guide uses uv run. Windows users should substitute with python cja_sdr_generator.py. The Common Use Cases table omits the prefix for brevity.

Get your credentials from Adobe Developer Console (see QUICKSTART_GUIDE for detailed steps).

Option A: Configuration File (Quickest)

Create a config.json file with your Adobe credentials:

# Copy the example template
cp config.json.example config.json

# Or generate a template (creates config.sample.json)
uv run cja_auto_sdr --sample-config

# Edit config.json with your credentials

Note: The configuration file must be named config.json and placed in the project root directory.

{
  "org_id": "YOUR_ORG_ID@AdobeOrg",
  "client_id": "YOUR_CLIENT_ID",
  "secret": "YOUR_CLIENT_SECRET",
  "scopes": "your_scopes_from_developer_console"
}

Option B: Environment Variables (Recommended for CI/CD)

Use a .env file (copy from .env.example) or export directly:

ORG_ID=your_org_id@AdobeOrg
CLIENT_ID=your_client_id
SECRET=your_client_secret
SCOPES=your_scopes_from_developer_console

Note: Environment variables take precedence over config.json.

macOS/Linux:

# Verify configuration and list available data views
uv run cja_auto_sdr --validate-config
uv run cja_auto_sdr --list-dataviews

# Generate SDR for a data view (by ID)
uv run cja_auto_sdr dv_YOUR_DATA_VIEW_ID

# Or by name (quotes recommended for names with spaces)
uv run cja_auto_sdr "Production Analytics"

Windows (if uv run doesn't work):

# Activate virtual environment first
.venv\Scripts\activate

# Verify configuration and list available data views
python cja_sdr_generator.py --validate-config
python cja_sdr_generator.py --list-dataviews

# Generate SDR for a data view (by ID or name)
python cja_sdr_generator.py dv_YOUR_DATA_VIEW_ID
python cja_sdr_generator.py "Production Analytics"

Tip: You can specify Data Views by name in addition to ID. If multiple Data Views share the same name, all matching views will be processed.

• Generated Excel file: CJA_DataView_[Name]_[ID]_SDR.xlsx
• Logs: logs/ directory

Note: Commands below omit the uv run or python cja_sdr_generator.py prefix for brevity:

• macOS/Linux: Add uv run before each command (e.g., uv run cja_auto_sdr dv_12345)
• Windows: Use python cja_sdr_generator.py instead (e.g., python cja_sdr_generator.py dv_12345)

• Python 3.14+
• Adobe I/O integration with CJA API access
• Network connectivity to Adobe APIs

cja_auto_sdr/
├── cja_sdr_generator.py     # Main script (single-file application)
├── pyproject.toml           # Project configuration and dependencies
├── uv.lock                  # Dependency lock file for reproducible builds
├── README.md                # This file
├── CHANGELOG.md             # Version history and release notes
├── LICENSE                  # License file
├── config.json              # Your credentials (DO NOT COMMIT)
├── config.json.example      # Config file template
├── .env.example             # Environment variable template
├── docs/                    # Documentation (15 guides)
│   ├── QUICKSTART_GUIDE.md  # Getting started guide
│   ├── CONFIGURATION.md     # Profiles, config.json & env vars
│   ├── CLI_REFERENCE.md     # Command-line reference
│   ├── DIFF_COMPARISON.md   # Data view comparison guide
│   ├── GIT_INTEGRATION.md   # Git integration guide
│   ├── INSTALLATION.md      # Setup instructions
│   └── ...                  # Additional guides
├── tests/                   # Test suite (786 tests)
├── sample_outputs/          # Example output files
│   ├── excel/               # Sample Excel SDR
│   ├── csv/                 # Sample CSV output
│   ├── json/                # Sample JSON output
│   ├── html/                # Sample HTML output
│   ├── markdown/            # Sample Markdown output
│   ├── diff/                # Sample diff comparison outputs
│   └── git-snapshots/       # Sample Git integration snapshots
├── logs/                    # Generated log files
└── *.xlsx                   # Generated SDR files

See LICENSE for details.

• CJA API Documentation
• cjapy Library
• uv Package Manager
• Changelog