Adobe Customer Journey Analytics SDR Generator

A production-ready Python CLI that automates the creation of Solution Design Reference (SDR) documentation from your Adobe Customer Journey Analytics (CJA) implementation. Read-only against CJA.

Counterpart to aa_auto_sdr; shares UX conventions, does not share code.

Companion projects: sdr-visualizer turns generated JSON snapshots into self-contained visual catalogs, while sdr-grader provides deterministic, rule-based quality grading.

What It Is

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.

How It Works

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 core automated checks (duplicates, required fields, null values, missing descriptions, empty datasets, invalid IDs)
4. Generates formatted documentation with color-coded quality indicators

Key Features

Who It's For

• 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

Quick Start

Install from PyPI (recommended)

The tool is published on PyPI, so most users can install it without cloning. uv is recommended:

uv tool install cja-auto-sdr          # isolated install; puts `cja-auto-sdr` on your PATH
# or run once without installing:
uvx cja-auto-sdr --list-dataviews
# or with plain pip:
pip install cja-auto-sdr

Optional features ship as extras:

uv tool install "cja-auto-sdr[full]"   # clustering + env + shell completion + notion

Verify with cja-auto-sdr --version, then skip ahead to Configure Credentials.

To set up a development checkout from source instead, follow the numbered steps below.

1. Clone the Repository

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

2. Install Dependencies

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 two 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)

This guide uses uv run. Windows users should activate the venv first (pip install -e . makes the command available). The Common Use Cases table omits the prefix for brevity.

3. Configure Credentials

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

⚠ Important: Your Adobe Developer Console project must have both the CJA API and the AEP (Experience Platform) API added. The AEP API associates your service account with an Experience Platform product profile, which is required for CJA API authentication. See the Quickstart Guide for setup instructions.

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: By default, the tool reads ./config.json from your current working directory. Use --config-file /path/to/config.json to load a file from a different location or filename.

{
  "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.

4. Verify Setup & Run

Interactive Mode (Recommended for First-Time Users):

# Launch interactive mode - walks through all options step by step
uv run cja_auto_sdr --interactive

Interactive mode guides you through data view selection, output format, and inventory options.

macOS/Linux (Direct Commands):

# 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
cja_auto_sdr --validate-config
cja_auto_sdr --list-dataviews

# Generate SDR for a data view (by ID or name)
cja_auto_sdr dv_YOUR_DATA_VIEW_ID
cja_auto_sdr "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.

5. Review Output

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

Common Use Cases

Note: Commands below omit the uv run prefix for brevity:

• macOS/Linux: Add uv run before each command (e.g., uv run cja_auto_sdr dv_12345)
• Windows: Activate the venv first (.venv\Scripts\activate), then run commands directly

Documentation

Requirements

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

Project Structure

High-level overview of the current repository layout (representative, not exhaustive):

cja_auto_sdr/
├── .github/
│   └── workflows/             # CI, lint, version-sync, and release checks
├── src/
│   └── cja_auto_sdr/          # Main package (src-layout)
│       ├── __init__.py        # Package init with version
│       ├── __main__.py        # Installed CLI entry point (`cja_auto_sdr`, `cja-auto-sdr`)
│       ├── generator.py       # Main SDR generation flow and legacy full CLI path
│       ├── api/               # API communication layer
│       │   ├── cache.py       # Validation result caching
│       │   ├── client.py      # CJA client initialization
│       │   ├── fetch.py       # Parallel API data fetching
│       │   ├── quality.py     # Data quality validation
│       │   ├── quality_policy.py # Quality gates and policy helpers
│       │   ├── resilience.py  # Retry, circuit breaker
│       │   ├── tuning.py      # API worker auto-tuning
│       │   └── validation.py  # Config & input validation
│       ├── cli/               # CLI parsing and interactive mode
│       │   ├── commands/      # Subcommand handlers
│       │   ├── execution.py   # Execution-context resolution
│       │   ├── interactive.py # Interactive data view selection
│       │   ├── main.py        # CLI entry orchestration
│       │   ├── mode_scoped_options.py # Option validation by command mode
│       │   ├── option_resolution.py # Shared option normalization
│       │   ├── parser.py      # Argument parser definitions
│       │   └── standalone_policy.py # Standalone command policy rules
│       ├── core/              # Shared core utilities
│       │   ├── colors.py      # ANSI color helpers
│       │   ├── config.py      # Configuration dataclasses
│       │   ├── config_validation.py # Config validation helpers
│       │   ├── constants.py   # Global constants
│       │   ├── credentials.py # Credential loading
│       │   ├── discovery_*.py # Discovery normalization/payload helpers
│       │   ├── error_policies.py # Error-handling policy helpers
│       │   ├── exceptions.py  # Custom exception hierarchy
│       │   ├── exit_codes.py  # Stable exit-code definitions
│       │   ├── json_io.py     # JSON read/write helpers
│       │   ├── lazy.py        # Lazy-loading helpers
│       │   ├── logging.py     # Log setup and formatting
│       │   ├── perf.py        # Lightweight performance helpers
│       │   ├── profiles.py    # Multi-org profile management
│       │   └── version.py     # Single-source version string
│       ├── data/              # Shared data package hooks
│       ├── diff/              # Data view comparison
│       │   ├── cli.py         # Diff CLI dispatch helpers
│       │   ├── commands.py    # Diff command orchestration
│       │   ├── comparator.py  # Diff logic and change detection
│       │   ├── git.py         # Git snapshot integration
│       │   ├── models.py      # Snapshot and diff data models
│       │   ├── snapshot.py    # Snapshot save/load/prune
│       │   └── writers.py     # Diff output formatters
│       ├── git/               # Git package compatibility surface
│       ├── inventory/         # Component inventory modules
│       │   ├── calculated_metrics.py
│       │   ├── derived_fields.py
│       │   ├── segments.py
│       │   ├── summary.py     # Inventory summary stats
│       │   └── utils.py       # Shared inventory helpers
│       ├── org/               # Org-wide analysis
│       │   ├── analyzer.py    # OrgComponentAnalyzer
│       │   ├── cache.py       # Report caching
│       │   ├── identifiers.py # Org/data-view identifier helpers
│       │   ├── models.py      # Data classes for org analysis
│       │   ├── snapshot_utils.py # Org snapshot helpers
│       │   ├── trending.py    # Historical trend analysis
│       │   └── writers/       # Org-report writers
│       ├── output/            # Output generation
│       │   ├── diff/          # Diff output implementations
│       │   ├── excel.py       # Excel formatting
│       │   ├── inventory/     # Inventory summary output helpers
│       │   ├── protocols.py   # OutputWriter protocol
│       │   ├── registry.py    # Format registry
│       │   ├── run_summary.py # Run summary output helpers
│       │   ├── sdr/           # SDR output assembly
│       │   └── writers/       # CSV, HTML, JSON, Markdown writers
│       └── pipeline/          # Processing pipeline
│           ├── batch.py       # Batch processor
│           ├── dry_run.py     # Dry-run mode
│           ├── models.py      # Pipeline data models
│           ├── single.py      # Single data view processing
│           └── workers.py     # Worker coordination
├── docs/                      # Documentation (20+ guides)
│   ├── QUICKSTART_GUIDE.md    # Getting started guide
│   ├── CONFIGURATION.md       # Profiles, config.json & env vars
│   ├── CLI_REFERENCE.md       # Command-line reference
│   ├── INVENTORY_OVERVIEW.md  # Unified inventory guide
│   ├── DIFF_COMPARISON.md     # Data view comparison guide
│   ├── GIT_INTEGRATION.md     # Git integration guide
│   ├── ORG_WIDE_ANALYSIS.md   # Org-wide report guide
│   └── ...                    # Additional guides
├── examples/                  # Automation and GitHub Actions examples
├── scripts/                   # Utility scripts
├── tests/                     # Test suite (8,612+ tests)
│   ├── category_rules.py      # File-based test-category rules
│   ├── conftest.py            # Pytest fixtures and auto-marking
│   ├── README.md              # Test inventory and execution guide
│   └── test_*.py              # 114 collected test modules
├── 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
├── snapshots/                 # Saved Data View snapshots
├── sdr-snapshots/             # Additional SDR snapshot artifacts
├── 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.example        # Config file template
├── .env.example               # Environment variable template
└── *.xlsx                     # Generated SDR files

Additional Resources

• CJA API Documentation
• cjapy Library
• uv Package Manager
• Counterpart project: aa_auto_sdr — Adobe Analytics equivalent