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

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

Configuration file not found

cja_auto_sdr --sample-config

Missing required field: 'org_id'

Configuration file is not valid JSON

Authentication Errors

CJA INITIALIZATION FAILED

HTTP 401 Unauthorized

HTTP 403 Forbidden

Data View Errors

Data view not found

--list-dataviews

Name not found (case-sensitive)

--list-dataviews

No data views found

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/

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

--profile NAME

-p

--output-dir PATH

--format FORMAT

--open

--skip-validation

--continue-on-error

--log-level DEBUG

--dry-run

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