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

Mode	Purpose	Default Output
SDR Generation	Document Data View components (metrics, dimensions)	Excel workbook
Diff Comparison	Compare two Data Views or track changes over time	Console output

---

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:

Code	Meaning
0	Success (no changes found)
1	Error occurred
2	Changes detected
3	Changes exceeded threshold

# 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

Error	Solution
Configuration file not found	Run cja_auto_sdr --sample-config to generate template
Missing required field: 'org_id'	Add all required fields to config.json
Configuration file is not valid JSON	Check for missing commas, use double quotes

Authentication Errors

Error	Solution
CJA INITIALIZATION FAILED	Verify credentials match Adobe Developer Console
HTTP 401 Unauthorized	Check Client Secret is current (not regenerated)
HTTP 403 Forbidden	Ensure both CJA API and AEP API are added to project

Data View Errors

Error	Solution
Data view not found	Run --list-dataviews to see accessible views
Name not found (case-sensitive)	Copy exact name from --list-dataviews including case
No data views found	Check product profile permissions in Admin Console

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

Option	Purpose
--profile NAME, -p	Use named profile
--output-dir PATH	Save output to directory
--format FORMAT	Output format (excel, csv, json, html, markdown, all)
--open	Open generated file immediately
--skip-validation	Skip data quality checks (faster)
--continue-on-error	Don't stop batch on failures
--log-level DEBUG	Verbose logging
--dry-run	Validate without generating output

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

Resource	URL
GitHub Repository	https://github.com/brian-a-au/cja_auto_sdr
CJA API Documentation	https://developer.adobe.com/cja-apis/docs/
Adobe Developer Console	https://developer.adobe.com/console/
cjapy Library	https://github.com/pitchmuc/cjapy