name: cja-sdr-generator
description: Guide for using cja_auto_sdr to generate Solution Design Reference documents from Adobe CJA, compare Data Views, and track changes. Use when working with CJA documentation, audits, or migration validation.

CJA SDR Generator Skill

This skill provides guidance on using the cja_auto_sdr tool to automate Solution Design Reference (SDR) documentation from Adobe Customer Journey Analytics.

When to Use This Skill

Invoke this skill when:
- Generating SDR documentation from CJA Data Views
- Comparing Data Views between environments (Production vs Staging)
- Tracking changes to Data View configurations over time
- Setting up automated CJA audits in CI/CD pipelines
- Managing multiple Adobe organizations with profiles
- Troubleshooting cja_auto_sdr errors

Quick Start

Installation

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

# Install dependencies (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Windows alternative
python -m venv .venv
.venv\Scripts\activate
pip install -e .

Configuration

Create config.json with your Adobe Developer Console credentials:

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

Prerequisite: You need OAuth Server-to-Server credentials from Adobe Developer Console with both CJA API and Experience Platform API enabled. See the adobe-api-setup skill for detailed setup instructions.

Verify Setup

# Validate configuration
uv run cja_auto_sdr --validate-config

# List accessible Data Views
uv run cja_auto_sdr --list-dataviews

Two Main Modes

SDR Generation Commands

Basic Usage

# Generate SDR by Data View ID
cja_auto_sdr dv_12345

# Generate SDR by name (case-sensitive, exact match required)
cja_auto_sdr "Production Analytics"

# Generate and open file immediately
cja_auto_sdr dv_12345 --open

# Quick stats only (no full report)
cja_auto_sdr dv_12345 --stats

Output Formats

# Excel (default) - includes Data Quality sheet
cja_auto_sdr dv_12345 --format excel

# Other formats
cja_auto_sdr dv_12345 --format csv
cja_auto_sdr dv_12345 --format json
cja_auto_sdr dv_12345 --format html
cja_auto_sdr dv_12345 --format markdown

# Generate all formats at once
cja_auto_sdr dv_12345 --format all

# Output to stdout (for piping)
cja_auto_sdr dv_12345 --format json --output -

Batch Processing

# Process multiple Data Views in parallel
cja_auto_sdr dv_12345 dv_67890 dv_abcde

# Mix IDs and names
cja_auto_sdr dv_12345 "Production Analytics" "Staging"

# Continue processing if some fail
cja_auto_sdr dv_1 dv_2 dv_3 --continue-on-error

# Custom output directory
cja_auto_sdr dv_12345 --output-dir ./reports

Performance Options

# Skip data quality validation (20-30% faster)
cja_auto_sdr dv_12345 --skip-validation

# Enable caching for repeated runs (50-90% faster on cache hits)
cja_auto_sdr dv_12345 --enable-cache

# Adjust parallel workers (default: auto)
cja_auto_sdr dv_1 dv_2 dv_3 --workers 4

Diff Comparison Commands

Compare Two Data Views

# Compare by ID
cja_auto_sdr --diff dv_12345 dv_67890

# Compare by name
cja_auto_sdr --diff "Production" "Staging"

# Show only changes (hide unchanged components)
cja_auto_sdr --diff dv_12345 dv_67890 --changes-only

# Custom labels in output
cja_auto_sdr --diff dv_12345 dv_67890 --diff-labels "Before" "After"

Snapshot Management

# Save a snapshot for later comparison
cja_auto_sdr dv_12345 --snapshot ./snapshots/baseline.json

# Compare current state to a saved snapshot
cja_auto_sdr dv_12345 --diff-snapshot ./snapshots/baseline.json

# Compare against most recent snapshot (auto-finds it)
cja_auto_sdr dv_12345 --compare-with-prev

# Compare two snapshot files (no API calls needed)
cja_auto_sdr --compare-snapshots ./old.json ./new.json

# Auto-save snapshots during diff operations
cja_auto_sdr --diff dv_12345 dv_67890 --auto-snapshot

# Keep only last N snapshots per Data View
cja_auto_sdr --diff dv_12345 dv_67890 --auto-snapshot --keep-last 10

Diff Output Formats

# Console output (default for diff)
cja_auto_sdr --diff dv_12345 dv_67890

# Markdown (great for documentation)
cja_auto_sdr --diff dv_12345 dv_67890 --format markdown

# JSON (for integrations)
cja_auto_sdr --diff dv_12345 dv_67890 --format json

# Excel workbook
cja_auto_sdr --diff dv_12345 dv_67890 --format excel

# GitHub/GitLab PR comment format
cja_auto_sdr --diff dv_12345 dv_67890 --format-pr-comment

CI/CD Integration

Exit codes for pipeline automation:

# Fail pipeline if changes exceed 10%
cja_auto_sdr --diff dv_12345 dv_67890 --warn-threshold 10

# Use in CI script
cja_auto_sdr --diff dv_prod dv_staging --quiet-diff
case $? in
  0) echo "No differences" ;;
  2) echo "Review needed" ;;
  3) echo "Too many changes" && exit 1 ;;
esac

Multi-Organization Profile Management

Manage credentials for multiple Adobe organizations:

# Create a profile interactively
cja_auto_sdr --profile-add client-a

# List all profiles
cja_auto_sdr --profile-list

# Use a specific profile
cja_auto_sdr --profile client-a --list-dataviews
cja_auto_sdr -p client-b "Main Data View"

# Test profile connectivity
cja_auto_sdr --profile-test client-a

# Set default profile via environment
export CJA_PROFILE=client-a
cja_auto_sdr --list-dataviews  # Uses client-a automatically

Profiles are stored in ~/.cja/orgs/<profile-name>/config.json.

Common Troubleshooting

Configuration Errors

Authentication Errors

Data View Errors

Debug Mode

# Enable verbose logging
cja_auto_sdr dv_12345 --log-level DEBUG

# JSON logging for automated analysis
cja_auto_sdr dv_12345 --log-format json

# Dry run (validate without generating output)
cja_auto_sdr dv_12345 --dry-run

Log files are saved to logs/ directory.

Quick Reference

Discovery Commands

cja_auto_sdr --list-dataviews              # List all Data Views
cja_auto_sdr --list-dataviews --format json # JSON output for scripting
cja_auto_sdr --interactive                  # Interactive Data View selection
cja_auto_sdr dv_12345 --stats              # Quick component count
cja_auto_sdr --validate-config             # Test configuration

Common Options

Environment Variables

# Credentials (override config.json)
export ORG_ID="your_org_id@AdobeOrg"
export CLIENT_ID="your_client_id"
export SECRET="your_client_secret"
export SCOPES="your_scopes"

# Optional settings
export OUTPUT_DIR="./reports"
export LOG_LEVEL="INFO"
export CJA_PROFILE="default-profile"

Resources