From 0be6bae08b69bbc4f4805618186cb1bb69e9a761 Mon Sep 17 00:00:00 2001 From: Chandresh Patel Date: Thu, 30 Apr 2026 10:58:32 -0700 Subject: [PATCH] fix: address PR #180 review feedback and validation errors - Wrap description values in double quotes in both SKILL.md files - Trim developing-datacloud-code-extension SKILL.md from 755 to 319 lines - Move README.md and quick-reference.md to references/ directory - Remove "Claude Code" references and hardcoded local paths - Use relative script paths (scripts/get_dlo_schema.py) - Move getting-datacloud-schema docs/README.md to references/ --- .../README.md | 409 --------------- .../SKILL.md | 495 +----------------- .../references/README.md | 193 +++++++ .../{ => references}/quick-reference.md | 130 ++--- skills/getting-datacloud-schema/SKILL.md | 2 +- .../getting-datacloud-schema/docs/README.md | 265 ---------- .../references/README.md | 191 +++++++ 7 files changed, 450 insertions(+), 1235 deletions(-) delete mode 100644 skills/developing-datacloud-code-extension/README.md create mode 100644 skills/developing-datacloud-code-extension/references/README.md rename skills/developing-datacloud-code-extension/{ => references}/quick-reference.md (58%) delete mode 100644 skills/getting-datacloud-schema/docs/README.md create mode 100644 skills/getting-datacloud-schema/references/README.md diff --git a/skills/developing-datacloud-code-extension/README.md b/skills/developing-datacloud-code-extension/README.md deleted file mode 100644 index 421659a..0000000 --- a/skills/developing-datacloud-code-extension/README.md +++ /dev/null @@ -1,409 +0,0 @@ -# developing-datacloud-code-extension Skill - -## Overview - -A Claude Code skill that provides complete workflow for developing, testing, and deploying custom Python code extensions to Salesforce Data Cloud using the SF CLI plugin. - -## Installation - -The skill is now installed at: -``` -/home/codebuilder/dx-project/.a4drules/skills/developing-datacloud-code-extension/ -``` - -## What It Does - -This skill helps you create Data Cloud Code Extensions through a complete workflow: - -1. **Init** - Create new code extension project with scaffolding -2. **Develop** - Write Python transformation logic -3. **Scan** - Auto-detect permissions and generate config -4. **Run** - Test locally against Data Cloud org -5. **Deploy** - Package and deploy to Data Cloud - -## Usage - -### In Claude Code Conversations - -Simply ask Claude naturally: - -**Initialize a project:** -``` -"Create a new Data Cloud code extension project called employee-transform" -"Initialize a code extension to transform employee data" -``` - -**Test locally:** -``` -"Run the code extension in my-transform directory against afvibe org" -"Test the entrypoint.py file locally" -``` - -**Scan for permissions:** -``` -"Scan the entrypoint.py to generate config" -"Update permissions in config.json" -``` - -**Deploy:** -``` -"Deploy Employee_Upper code extension to afvibe" -"Deploy this transform with package-version 1.0.0" -``` - -### Direct Command Usage - -```bash -# Initialize project -sf data-code-extension init --code-type script - -# Scan for permissions -sf data-code-extension scan ./payload/entrypoint.py - -# Test locally -sf data-code-extension run ./payload/entrypoint.py --target-org - -# Deploy -sf data-code-extension deploy --target-org --name --package-version --description --package-dir -``` - -## Prerequisites - -1. **SF CLI with Plugin** - ```bash - sf plugins install @salesforce/plugin-data-codeextension - ``` - -2. **Python 3.11** - ```bash - python --version # Must be 3.11.x - ``` - -3. **Data Cloud Custom Code SDK** - ```bash - pip install salesforce-data-customcode - ``` - -4. **Docker** (for deploy only) - - Docker Desktop or equivalent - -5. **Authenticated Org** - ```bash - sf org login web --alias - ``` - -## Quick Start - -### Complete End-to-End Example - -```bash -# 1. Create project -mkdir employee-transform && cd employee-transform -sf data-code-extension init . --code-type script - -# 2. Edit payload/entrypoint.py with your transformation - -# 3. Scan for permissions -sf data-code-extension scan ./payload/entrypoint.py - -# 4. Test locally -sf data-code-extension run ./payload/entrypoint.py --target-org afvibe - -# 5. Deploy -sf data-code-extension deploy \ - --target-org afvibe \ - --name Employee_Upper \ - --version 1.0.0 \ - --description "Uppercase employee positions" -``` - -## Command Reference - -### Init -```bash -sf data-code-extension init --code-type -``` -Creates project structure with entrypoint.py, config.json, requirements.txt. - -### Scan -```bash -sf data-code-extension scan [--config ] [--dry-run] [--no-requirements] -``` -Detects read/write permissions and Python dependencies. - -### Run -```bash -sf data-code-extension run --target-org [--config-file ] -``` -Executes transformation locally using real Data Cloud data. - -### Deploy -```bash -sf data-code-extension deploy \ - --target-org \ - --name \ - [--version ] \ - [--description ] \ - [--cpu-size ] \ - [--path ] -``` -Packages and deploys to Data Cloud. - -## Example Transformation - -**Read from DLO, transform, write to DLO:** - -```python -from datacustomcode import Client - -client = Client() - -# Read employee data from DLO -employees = client.read_dlo('Employee__dll') - -# Transform - uppercase position field -employees['position_upper'] = employees['position'].str.upper() - -# Select output columns -output = employees[['id', 'name', 'position_upper']] - -# Write to output DLO -client.write_to_dlo('Employee_Upper__dll', output, 'overwrite') - -print(f"Processed {len(output)} employee records") -``` - -## Project Structure - -After `init`, you'll have: - -``` -my-transform/ -├── payload/ -│ ├── entrypoint.py # Your transformation code -│ ├── config.json # Permissions and configuration -│ └── requirements.txt # Python dependencies -└── README.md -``` - -## Common Operations - -### Read/Write DLOs -```python -# Read -df = client.read_dlo('Employee__dll') - -# Write (modes: 'overwrite', 'append') -client.write_to_dlo('Employee_Upper__dll', df, 'overwrite') -``` - -### Read/Write DMOs -```python -# Read -df = client.read_dmo('EmployeeDMO') - -# Write (modes: 'upsert', 'insert') -client.write_to_dmo('EmployeeDMO', df, 'upsert') -``` - -### Data Transformations -```python -import pandas as pd - -# Filter -active_employees = df[df['status'] == 'Active'] - -# Add computed column -df['full_name'] = df['first_name'] + ' ' + df['last_name'] - -# Aggregate -summary = df.groupby('department').agg({'salary': 'mean'}) - -# Join -merged = employees.merge(departments, on='dept_id') -``` - -## Troubleshooting - -### Plugin Not Found -```bash -sf plugins install @salesforce/plugin-data-codeextension -``` - -### Python SDK Missing -```bash -pip install salesforce-data-customcode -datacustomcode version # Verify -``` - -### Wrong Python Version -```bash -# Use pyenv to manage versions -pyenv install 3.11.0 -pyenv local 3.11.0 -python --version # Verify 3.11.x -``` - -### Docker Not Running -- Start Docker Desktop -- Or: `sudo systemctl start docker` (Linux) - -### Org Not Connected -```bash -sf org login web --alias -sf org list # Verify -``` - -### Config.json Missing -```bash -sf data-code-extension scan ./payload/entrypoint.py -``` - -### DLO Not Found -- Use DLO Schema skill to list DLOs -- Verify DLO name ends with `__dll` -- Check read permissions in config.json - -## CPU Size Selection - -Choose based on data volume: - -| CPU Size | Use Case | Data Volume | -|----------|----------|-------------| -| CPU_L | Small datasets | < 1M records | -| CPU_XL | Medium datasets | 1M-5M records | -| CPU_2XL | Large datasets (default) | 5M-10M records | -| CPU_4XL | Very large datasets | > 10M records | - -## Integration with Other Skills - -### With DLO Schema Skill -``` -1. "Show me all DLOs in afvibe" -2. "Get schema for Employee__dll" -3. "Create a code extension to read Employee__dll and transform it" -``` - -### With Datakit Workflow -``` -1. Create DLO via code extension -2. Map DLO to DMO using datakit workflow -3. Create segments from DMO -``` - -## Example Use Cases - -### 1. Data Enrichment -Read employee data, lookup additional info, write enriched data back. - -### 2. Data Cleansing -Read raw data, standardize formats, remove duplicates, write clean data. - -### 3. Aggregation -Read transaction data, calculate summaries, write aggregated metrics. - -### 4. Multi-Source Join -Read from multiple DLOs, join on keys, write unified view. - -### 5. Data Validation -Read data, check quality rules, write valid records and flag errors. - -## Best Practices - -### Development -1. Always scan after code changes -2. Test locally before deploying -3. Use semantic versioning -4. Add descriptive deployment names - -### Code Quality -1. Add print statements for logging -2. Handle errors with try/except -3. Validate input data types -4. Document transformation logic - -### Performance -1. Choose appropriate CPU size -2. Filter data early in pipeline -3. Select only needed columns -4. Process in batches for large datasets - -### Security -1. Never hardcode credentials -2. Use SF CLI authentication only -3. Validate all input data -4. Limit write permissions in config - -## Files Created - -``` -developing-datacloud-code-extension/ -├── SKILL.md # Complete skill documentation -├── README.md # This file -└── quick-reference.md # Command cheat sheet -``` - -## Resources - -- **SF CLI Plugin**: https://github.com/salesforcecli/plugin-data-code-extension -- **Python SDK**: https://github.com/forcedotcom/datacloud-customcode-python-sdk -- **Data Cloud Docs**: https://help.salesforce.com/s/articleView?id=sf.c360_a_intro.htm -- **SDK on PyPI**: https://pypi.org/project/salesforce-data-customcode/ - -## Command Flow - -``` -┌─────────────────────────────────────────────────────┐ -│ 1. INIT │ -│ sf data-code-extension init my-project │ -│ Creates: entrypoint.py, config.json, requirements │ -└─────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ 2. DEVELOP │ -│ Edit payload/entrypoint.py │ -│ Write transformation logic │ -└─────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ 3. SCAN │ -│ sf data-code-extension scan --entrypoint ./payload/entrypoint.py│ -│ Updates: config.json, requirements.txt │ -└─────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ 4. RUN (Local Test) │ -│ sf data-code-extension run --entrypoint │ -│ ./payload/entrypoint.py --target-org afvibe │ -└─────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ 5. DEPLOY │ -│ sf data-code-extension deploy --target-org afvibe │ -│ --name Employee_Upper --package-version 1.0.0 │ -| --description "Upper case Employee position column"│ -│ --package-dir ./payload │ -└─────────────────────────────────────────────────────┘ -``` - -## Version History - -- **v1.0** (2026-03-26) - Initial release - - Complete init/scan/run/deploy workflow - - Comprehensive error handling - - Integration with DLO Schema skill - - Full documentation - -## Support - -For issues or questions: -- SF CLI Plugin: https://github.com/salesforcecli/plugin-data-code-extension/issues -- Python SDK: https://github.com/forcedotcom/datacloud-customcode-python-sdk/issues - -## The Skill is Ready! 🚀 - -Try it now: -``` -"Create a code extension to uppercase employee positions" -"Deploy my transform to Data Cloud" -``` diff --git a/skills/developing-datacloud-code-extension/SKILL.md b/skills/developing-datacloud-code-extension/SKILL.md index 1ea15e1..f69aa4f 100644 --- a/skills/developing-datacloud-code-extension/SKILL.md +++ b/skills/developing-datacloud-code-extension/SKILL.md @@ -1,6 +1,6 @@ --- name: developing-datacloud-code-extension -description: Develop and deploy Data Cloud Code Extensions using SF CLI plugin. Use this skill when creating custom Python transformations for Data Cloud, deploying code extensions, or testing data transformations. Supports init, run, scan, and deploy operations. +description: "Develop and deploy Data Cloud Code Extensions using SF CLI plugin. Use this skill when creating custom Python transformations for Data Cloud, deploying code extensions, or testing data transformations. Supports init, run, scan, and deploy operations." --- # developing-datacloud-code-extension Skill @@ -76,19 +76,10 @@ sf data-code-extension function init --package-dir **Required Option:** - `--package-dir, -p` - Directory path where the package will be created -**Examples:** -```bash -# Create script project in new directory -sf data-code-extension script init --package-dir ./my-transform - -# Create function project in current directory -sf data-code-extension function init --package-dir . -``` - **What it creates:** ``` -my-transform/ # ← Project root -├── payload/ # ← CRITICAL: This is what --package-dir must point to for deploy +my-transform/ # Project root +├── payload/ # CRITICAL: This is what --package-dir must point to for deploy │ ├── entrypoint.py # Main transformation code │ ├── requirements.txt # Python dependencies │ └── config.json # Code extension configuration @@ -99,17 +90,6 @@ my-transform/ # ← Project root **IMPORTANT:** Understanding the directory structure is critical for successful deployment. -After running `init`, your structure looks like: - -``` -my-transform/ # ← Project root (run commands from here) -├── payload/ # ← THIS directory contains deployable code -│ ├── entrypoint.py -│ ├── config.json -│ └── requirements.txt -└── README.md -``` - **Commands and their directory requirements:** | Command | Run From | Path/File Argument | @@ -147,16 +127,11 @@ from datacustomcode import FunctionClient def transform(event, context): client = FunctionClient(context) - - # Process incoming record input_data = event['data'] - - # Transform output = { 'name': input_data['name'].upper(), 'status': 'processed' } - return output ``` @@ -172,12 +147,6 @@ Scan the entrypoint file to detect required permissions and generate config.json **Command:** ```bash -sf data-code-extension script scan --entrypoint -``` - -**Example:** -```bash -# Scan and update config.json sf data-code-extension script scan --entrypoint ./payload/entrypoint.py ``` @@ -187,26 +156,10 @@ sf data-code-extension script scan --entrypoint ./payload/entrypoint.py - Python package dependencies - Updates `config.json` and `requirements.txt` -**Example config.json:** -```json -{ - "version": "1.0", - "permissions": { - "read": ["Employee__dll"], - "write": ["Employee_Upper__dll"] - }, - "resources": { - "cpu_size": "CPU_2XL" - } -} -``` - ### Phase 4: Validate DLO Schema (Pre-Test Check) **CRITICAL: Before running tests locally, validate that all DLOs used in your code exist and have the expected fields.** -This prevents runtime errors and ensures your transformation will work with the actual Data Cloud schema. - #### Step 4a: Extract DLOs from config.json After scanning, review the generated `config.json` to identify all DLOs: @@ -215,16 +168,6 @@ After scanning, review the generated `config.json` to identify all DLOs: cat payload/config.json ``` -Look for DLOs in the `permissions` section: -```json -{ - "permissions": { - "read": ["Employee__dll", "Department__dll"], - "write": ["Employee_Upper__dll"] - } -} -``` - #### Step 4b: Validate Each DLO Schema **Use the `getting-datacloud-schema` skill to verify DLOs exist and check field names.** @@ -232,28 +175,11 @@ Look for DLOs in the `permissions` section: For each DLO referenced in your code: 1. **Verify DLO exists:** - ``` - Ask Claude: "Use getting-datacloud-schema skill to check if Employee__dll exists in afvibe" - ``` - - Or manually: ```bash - python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee__dll + python3 scripts/get_dlo_schema.py ``` -2. **Verify field names match:** - - Compare fields used in your `entrypoint.py` against the DLO schema: - - **In your code:** - ```python - df['position_upper'] = df['position'].str.upper() - ``` - - **Verify in schema:** - - Check that `position` field exists in Employee__dll - - Check data type is Text - - Verify you have read permissions +2. **Verify field names match** — compare fields used in your `entrypoint.py` against the DLO schema. 3. **Check all DLOs:** - Validate all DLOs in `read` permissions @@ -271,33 +197,6 @@ Before proceeding to run, ensure: - [ ] Primary key fields are correctly identified - [ ] Write target DLOs are created and accessible -**Common Issues to Check:** - -| Issue | Check | Fix | -|-------|-------|-----| -| DLO doesn't exist | Use getting-datacloud-schema skill | Create DLO first or update code | -| Field name typo | Compare code vs. schema | Fix field name in entrypoint.py | -| Wrong data type | Check schema data type | Update transformation logic | -| Missing permissions | Check config.json | Re-run scan | - -**Example Validation Workflow:** - -```bash -# 1. Check what DLOs are used -cat payload/config.json - -# 2. Validate source DLO exists and get schema -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee__dll - -# 3. Verify field 'position' exists in schema output -# Look for: name: position__c (or position) - -# 4. Check target DLO exists -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee_Upper__dll - -# 5. If all checks pass, proceed to run -``` - ### Phase 5: Test Locally After validating DLO schemas, run the code extension locally against your Data Cloud org. @@ -311,27 +210,6 @@ sf data-code-extension script run --entrypoint --target-org --name --pa - `--function-invoke-opt` - Function invoke options (for function type) - `--network` - Docker network (default: default) -**Example from project root:** -```bash -# Basic deployment (MUST include --package-dir ./payload) -sf data-code-extension script deploy \ - --target-org afvibe \ - --name Employee_Upper \ - --package-version 1.0.0 \ - --description "Uppercase employee positions" \ - --package-dir ./payload - -# Full deployment with all options -sf data-code-extension script deploy \ - --target-org afvibe \ - --name Employee_Upper \ - --package-version 1.0.0 \ - --description "Uppercase employee positions" \ - --cpu-size CPU_4XL \ - --package-dir ./payload -``` - -**Example with full path (if not in project root):** -```bash -sf data-code-extension script deploy \ - --target-org afvibe \ - --name Employee_Upper \ - --package-version 1.0.0 \ - --description "Uppercase employee positions" \ - --package-dir /full/path/to/my-transform/payload -``` - -**What it does:** -- Packages code with dependencies using Docker -- Uploads to Data Cloud -- Creates deployment record -- Makes code available for execution in UI - **After deployment:** - Navigate to Data Cloud in Salesforce UI - Go to Data Transforms section @@ -404,332 +246,51 @@ sf data-code-extension script deploy \ - Click "Run Now" to execute - Schedule for recurring execution -## Complete Workflow Example - -Here's a complete end-to-end example for creating an Employee uppercase transformation: - -```bash -# 1. Create project directory (or use existing directory) -mkdir employee-transform && cd employee-transform - -# 2. Initialize script project -sf data-code-extension script init --package-dir . - -# 3. Edit payload/entrypoint.py (see code below) - -# 4. Scan for permissions -sf data-code-extension script scan --entrypoint ./payload/entrypoint.py - -# 5. Validate DLO schemas (CRITICAL: check before testing) -# Check config.json for DLOs used -cat payload/config.json -# Validate Employee__dll exists and has 'position' field -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee__dll -# Validate Employee_Upper__dll exists (target DLO) -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee_Upper__dll - -# 6. Test locally (after DLO validation passes) -sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe - -# 7. Deploy to Data Cloud (CRITICAL: include --package-dir ./payload) -sf data-code-extension script deploy \ - --target-org afvibe \ - --name Employee_Upper \ - --package-version 1.0.0 \ - --description "Uppercase employee positions" \ - --package-dir ./payload -``` - -**entrypoint.py code:** -```python -from datacustomcode import Client - -client = Client() - -# Read employee data -employees = client.read_dlo('Employee__dll') - -# Transform - uppercase position field -employees['position_upper'] = employees['position'].str.upper() - -# Select relevant columns -output = employees[['id', 'name', 'position_upper']] - -# Write to output DLO -client.write_to_dlo('Employee_Upper__dll', output, 'overwrite') - -print(f"Processed {len(output)} employee records") -``` - ## Error Handling ### Common Issues and Solutions -**1. SF CLI Plugin Not Found** -``` -Error: command data-code-extension not found -``` -Solution: -```bash -sf plugins install @salesforce/plugin-data-codeextension -``` - -**2. Python SDK Not Installed** -``` -Error: datacustomcode CLI not found -``` -Solution: -```bash -pip install salesforce-data-customcode -datacustomcode version # Verify -``` - -**3. Wrong Python Version** -``` -Error: Python version mismatch -``` -Solution: -```bash -python --version # Should show 3.11.x -# Use pyenv to manage Python versions -pyenv install 3.11.0 -pyenv local 3.11.0 -``` - -**4. Docker Not Running** -``` -Error: Cannot connect to Docker daemon -``` -Solution: -- Start Docker Desktop -- Or start Docker service: `sudo systemctl start docker` - -**5. Org Not Authenticated** -``` -Error: No org found for alias 'afvibe' -``` -Solution: -```bash -sf org login web --alias afvibe -sf org list # Verify -``` - -**6. Config.json Missing** -``` -Error: config.json not found -``` -Solution: -```bash -sf data-code-extension scan ./payload/entrypoint.py -``` - -**7. DLO Not Found During Run** -``` -Error: DLO 'Employee__dll' not found -``` -Solution: -- Verify DLO exists in org (use DLO Schema skill) -- Check spelling and suffix (__dll) -- Ensure proper read permissions in config.json - -**8. Permission Denied During Write** -``` -Error: Permission denied writing to 'Employee_Upper__dll' -``` -Solution: -- Run scan to update permissions: `sf data-code-extension script scan ./payload/entrypoint.py` -- Verify target DLO exists and is writable -- Check Data Cloud permissions in org - -**9. Deploy Fails - Wrong Directory Path** -``` -Error: Cannot find entrypoint.py or config.json -Error: No such file or directory: './entrypoint.py' -Error: Deploy failed - invalid path -``` -Solution: -**CRITICAL:** Ensure `--package-dir` argument points to the `payload` directory, not the project root. - -```bash -# WRONG - Missing --package-dir argument -sf data-code-extension script deploy -o afvibe -n MyTransform - -# WRONG - Pointing to project root instead of payload -sf data-code-extension script deploy -o afvibe -n MyTransform --package-dir . - -# CORRECT - From project root, point to payload directory, includes package-version -sf data-code-extension script deploy -o afvibe -n MyTransform --package-dir ./payload --package-version 1.0.0 --description "Uppercase employee positions" - -# CORRECT - With full path -sf data-code-extension script deploy -o afvibe -n MyTransform --package-version 1.0.0 --package-dir /full/path/to/project/payload --description "Uppercase employee positions" -``` - -Check your current directory: -```bash -pwd # Should be in project root -ls # Should see 'payload' directory -ls payload/ # Should see entrypoint.py, config.json, requirements.txt -``` +| Error | Solution | +|-------|----------| +| `command data-code-extension not found` | `sf plugins install @salesforce/plugin-data-codeextension` | +| `datacustomcode CLI not found` | `pip install salesforce-data-customcode` | +| `Python version mismatch` | Use pyenv: `pyenv install 3.11.0 && pyenv local 3.11.0` | +| `Cannot connect to Docker daemon` | Start Docker Desktop | +| `No org found for alias` | `sf org login web --alias ` | +| `config.json not found` | `sf data-code-extension script scan --entrypoint ./payload/entrypoint.py` | +| `DLO not found` | Verify DLO exists (use getting-datacloud-schema skill), check spelling and `__dll` suffix | +| `Permission denied writing` | Re-run scan, verify target DLO exists and is writable | +| `Deploy fails - wrong directory` | Ensure `--package-dir` points to `payload/` directory, not project root | ## Best Practices ### Development -1. **Always scan before testing**: Run scan after code changes -2. **Test locally first**: Use `run` command before deploying -3. **Use version control**: Git commit after each successful test -4. **Version your deployments**: Use semantic versioning (1.0.0, 1.1.0, etc.) -5. **Deploy from project root with --package-dir ./payload**: ALWAYS specify the payload directory explicitly in deploy commands - -### Code Organization -1. **Keep entrypoint.py focused**: Main transformation logic only -2. **Extract helpers**: Create separate modules for reusable functions -3. **Add logging**: Use print statements for debugging -4. **Handle errors**: Add try/except blocks for data operations +1. Always scan before testing — run scan after code changes +2. Test locally first — use `run` command before deploying +3. Use version control — git commit after each successful test +4. Version your deployments — use semantic versioning (1.0.0, 1.1.0, etc.) +5. Deploy from project root with `--package-dir ./payload` ### Performance -1. **Choose appropriate CPU size**: - - CPU_L: Small datasets (< 1M records) - - CPU_2XL: Medium datasets (1M-10M records) - - CPU_4XL: Large datasets (> 10M records) -2. **Filter early**: Read only needed columns/rows -3. **Batch operations**: Process data in chunks for large datasets +- **CPU_L**: Small datasets (< 1M records) +- **CPU_2XL**: Medium datasets (1M-10M records) +- **CPU_4XL**: Large datasets (> 10M records) ### Security -1. **No hardcoded credentials**: Use SF CLI authentication only -2. **Validate input data**: Check for nulls and data types -3. **Limit write permissions**: Only grant necessary DLO/DMO access +1. No hardcoded credentials — use SF CLI authentication only +2. Validate input data — check for nulls and data types +3. Limit write permissions — only grant necessary DLO/DMO access ## Integration with Other Skills -**Use with DLO Schema Skill (CRITICAL for validation):** +**Use with getting-datacloud-schema skill (CRITICAL for validation):** The `getting-datacloud-schema` skill is **required** for validating DLOs before testing code extensions. -**Workflow Integration:** -``` -1. List all DLOs: "Show me all DLOs in afvibe" - → Verify target DLOs exist in org - -2. Get DLO schema: "What's the schema for Employee__dll?" - → Validate field names used in code - -3. Check field types: Review schema output for data types - → Ensure transformation logic is compatible - -4. Validate before test: Use schema validation BEFORE running locally - → Prevents runtime errors from missing fields/DLOs - -5. Create code extension: "Create a code extension to read Employee__dll" - → Design transformation based on actual schema -``` - -**Example Integrated Workflow:** -```bash -# Step 1: Check what DLOs exist -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe - -# Step 2: Get schema for source DLO -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee__dll - -# Step 3: Design code extension based on schema -# (Write entrypoint.py using fields from schema) - -# Step 4: Scan for permissions -sf data-code-extension script scan --entrypoint ./payload/entrypoint.py - -# Step 5: Validate all DLOs referenced in config.json -cat payload/config.json -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee__dll -python3 ~/.a4drules/skills/getting-datacloud-schema/scripts/get_dlo_schema.py afvibe Employee_Upper__dll - -# Step 6: Test locally (after validation passes) -sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe - -# Step 7: Deploy -sf data-code-extension script deploy --target-org afvibe --name Employee_Upper --package-dir ./payload --package-version 1.0.0 --description "Uppercase employee positions" -``` - **Use with Datakit Workflow:** -``` 1. Create DLO via code extension 2. Map DLO to DMO using datakit workflow 3. Use DMO in segments and activations -``` - -## Output Interpretation - -### Scan Output -``` -Scanning ./payload/entrypoint.py... -Found permissions: - Read: Employee__dll - Write: Employee_Upper__dll -Found dependencies: - pandas==2.0.0 - numpy==1.24.0 -Updated: payload/config.json -Updated: payload/requirements.txt -``` - -### Run Output -``` -Reading from Employee__dll... -Records read: 12 -Transforming data... -Writing to Employee_Upper__dll... -Records written: 12 -Execution completed in 2.3s -``` - -### Deploy Output -``` -Building Docker image... -Packaging dependencies... -Uploading to Data Cloud... -Deployment 'Employee_Upper' created successfully -ID: 2dgXXXXXXXXXXXXXXX -Version: 1.0.0 -Status: ACTIVE -``` - -## Advanced Usage - -### Custom Dependencies -Add to `requirements.txt`: -```txt -pandas==2.0.0 -numpy==1.24.0 -scikit-learn==1.3.0 -``` - -### Multiple DLO Operations -```python -# Read from multiple DLOs -employees = client.read_dlo('Employee__dll') -departments = client.read_dlo('Department__dll') - -# Join data -merged = employees.merge(departments, on='dept_id') - -# Write to multiple outputs -client.write_to_dlo('Employee_Enriched__dll', merged, 'overwrite') -client.write_to_dmo('EmployeeDMO', merged, 'upsert') -``` - -### Conditional Logic -```python -# Read data -df = client.read_dlo('Employee__dll') - -# Apply transformations based on conditions -df['grade'] = df['position'].apply(lambda x: - 'Senior' if 'Director' in x or 'VP' in x else 'Junior' -) - -# Filter and write -senior_employees = df[df['grade'] == 'Senior'] -client.write_to_dlo('Senior_Employees__dll', senior_employees, 'overwrite') -``` ## Command Reference diff --git a/skills/developing-datacloud-code-extension/references/README.md b/skills/developing-datacloud-code-extension/references/README.md new file mode 100644 index 0000000..6b148d3 --- /dev/null +++ b/skills/developing-datacloud-code-extension/references/README.md @@ -0,0 +1,193 @@ +# developing-datacloud-code-extension Skill + +## Overview + +A skill that provides a complete workflow for developing, testing, and deploying custom Python code extensions to Salesforce Data Cloud using the SF CLI plugin. + +## What It Does + +This skill helps you create Data Cloud Code Extensions through a complete workflow: + +1. **Init** - Create new code extension project with scaffolding +2. **Develop** - Write Python transformation logic +3. **Scan** - Auto-detect permissions and generate config +4. **Run** - Test locally against Data Cloud org +5. **Deploy** - Package and deploy to Data Cloud + +## Usage + +**Initialize a project:** +``` +"Create a new Data Cloud code extension project called employee-transform" +"Initialize a code extension to transform employee data" +``` + +**Test locally:** +``` +"Run the code extension in my-transform directory against afvibe org" +"Test the entrypoint.py file locally" +``` + +**Scan for permissions:** +``` +"Scan the entrypoint.py to generate config" +"Update permissions in config.json" +``` + +**Deploy:** +``` +"Deploy Employee_Upper code extension to afvibe" +"Deploy this transform with package-version 1.0.0" +``` + +### Direct Command Usage + +```bash +# Initialize project +sf data-code-extension script init --package-dir + +# Scan for permissions +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py + +# Test locally +sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org + +# Deploy +sf data-code-extension script deploy --target-org --name --package-version --description --package-dir ./payload +``` + +## Prerequisites + +1. **SF CLI with Plugin** + ```bash + sf plugins install @salesforce/plugin-data-codeextension + ``` + +2. **Python 3.11** + ```bash + python --version # Must be 3.11.x + ``` + +3. **Data Cloud Custom Code SDK** + ```bash + pip install salesforce-data-customcode + ``` + +4. **Docker** (for deploy only) + - Docker Desktop or equivalent + +5. **Authenticated Org** + ```bash + sf org login web --alias + ``` + +## Quick Start + +### Complete End-to-End Example + +```bash +# 1. Create project +mkdir employee-transform && cd employee-transform +sf data-code-extension script init --package-dir . + +# 2. Edit payload/entrypoint.py with your transformation + +# 3. Scan for permissions +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py + +# 4. Test locally +sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe + +# 5. Deploy (MUST include --package-dir ./payload) +sf data-code-extension script deploy \ + --target-org afvibe \ + --name Employee_Upper \ + --package-version 1.0.0 \ + --description "Uppercase employee positions" \ + --package-dir ./payload +``` + +## Example Transformation + +**Read from DLO, transform, write to DLO:** + +```python +from datacustomcode import Client + +client = Client() + +# Read employee data from DLO +employees = client.read_dlo('Employee__dll') + +# Transform - uppercase position field +employees['position_upper'] = employees['position'].str.upper() + +# Select output columns +output = employees[['id', 'name', 'position_upper']] + +# Write to output DLO +client.write_to_dlo('Employee_Upper__dll', output, 'overwrite') + +print(f"Processed {len(output)} employee records") +``` + +## Project Structure + +After `init`, you'll have: + +``` +my-transform/ +├── payload/ +│ ├── entrypoint.py # Your transformation code +│ ├── config.json # Permissions and configuration +│ └── requirements.txt # Python dependencies +└── README.md +``` + +## Common Operations + +### Read/Write DLOs +```python +# Read +df = client.read_dlo('Employee__dll') + +# Write (modes: 'overwrite', 'append') +client.write_to_dlo('Employee_Upper__dll', df, 'overwrite') +``` + +### Read/Write DMOs +```python +# Read +df = client.read_dmo('EmployeeDMO') + +# Write (modes: 'upsert', 'insert') +client.write_to_dmo('EmployeeDMO', df, 'upsert') +``` + +## Troubleshooting + +| Error | Quick Fix | +|-------|-----------| +| Plugin not found | `sf plugins install @salesforce/plugin-data-codeextension` | +| Python SDK missing | `pip install salesforce-data-customcode` | +| Wrong Python version | Use pyenv to install 3.11.0 | +| Org not connected | `sf org login web --alias ` | +| Config missing | Run scan command | +| DLO not found | Check DLO name, use getting-datacloud-schema skill | +| Docker error | Start Docker Desktop | + +## CPU Size Selection + +| CPU Size | Use Case | Data Volume | +|----------|----------|-------------| +| CPU_L | Small datasets | < 1M records | +| CPU_XL | Medium datasets | 1M-5M records | +| CPU_2XL | Large datasets (default) | 5M-10M records | +| CPU_4XL | Very large datasets | > 10M records | + +## Resources + +- **SF CLI Plugin**: https://github.com/salesforcecli/plugin-data-code-extension +- **Python SDK**: https://github.com/forcedotcom/datacloud-customcode-python-sdk +- **Data Cloud Docs**: https://help.salesforce.com/s/articleView?id=sf.c360_a_intro.htm +- **SDK on PyPI**: https://pypi.org/project/salesforce-data-customcode/ diff --git a/skills/developing-datacloud-code-extension/quick-reference.md b/skills/developing-datacloud-code-extension/references/quick-reference.md similarity index 58% rename from skills/developing-datacloud-code-extension/quick-reference.md rename to skills/developing-datacloud-code-extension/references/quick-reference.md index c41a222..5b542d9 100644 --- a/skills/developing-datacloud-code-extension/quick-reference.md +++ b/skills/developing-datacloud-code-extension/references/quick-reference.md @@ -5,78 +5,70 @@ ### Initialize Project ```bash # Create script project -sf data-code-extension init --code-type script +sf data-code-extension script init --package-dir # Create function project -sf data-code-extension init --code-type function +sf data-code-extension function init --package-dir # Examples -sf data-code-extension init . --code-type script -sf data-code-extension init my-transform --code-type script +sf data-code-extension script init --package-dir . +sf data-code-extension script init --package-dir my-transform ``` ### Scan for Permissions ```bash # Basic scan -sf data-code-extension scan ./payload/entrypoint.py +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py # Preview without saving -sf data-code-extension scan ./payload/entrypoint.py --dry-run +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py --dry-run # Custom config location -sf data-code-extension scan ./payload/entrypoint.py --config ./custom-config.json +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py --config ./custom-config.json # Skip requirements.txt -sf data-code-extension scan ./payload/entrypoint.py --no-requirements +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py --no-requirements ``` ### Run Locally ```bash # Basic run -sf data-code-extension run ./payload/entrypoint.py --target-org +sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org # With custom config -sf data-code-extension run ./payload/entrypoint.py -o -c custom-config.json +sf data-code-extension script run --entrypoint ./payload/entrypoint.py -o -c custom-config.json # Examples -sf data-code-extension run ./payload/entrypoint.py --target-org afvibe -sf data-code-extension run ./payload/entrypoint.py -o afvibe +sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe +sf data-code-extension script run --entrypoint ./payload/entrypoint.py -o afvibe ``` ### Deploy ```bash -# Minimal deployment (MUST include --path ./payload) -sf data-code-extension deploy \ +# Minimal deployment (MUST include --package-dir ./payload) +sf data-code-extension script deploy \ --target-org \ --name \ --package-version \ --description "" \ - --path ./payload + --package-dir ./payload # Full options -sf data-code-extension deploy \ +sf data-code-extension script deploy \ --target-org \ --name \ --package-version \ --description "" \ --cpu-size \ - --path ./payload + --package-dir ./payload -# Examples (CRITICAL: Always include --path ./payload) -sf data-code-extension deploy \ +# Examples (CRITICAL: Always include --package-dir ./payload) +sf data-code-extension script deploy \ --target-org afvibe \ --name Employee_Upper \ --package-version 1.0.0 \ --description "Uppercase employee positions" \ - --path ./payload - -sf data-code-extension deploy \ - -o afvibe \ - -n Employee_Upper \ - --package-version 1.0.0 \ - --description "Uppercase employee positions" \ - --cpu-size CPU_4XL \ - --path ./payload + --package-dir ./payload ``` ## Common Workflows @@ -87,43 +79,42 @@ sf data-code-extension deploy \ mkdir my-transform && cd my-transform # 2. Initialize -sf data-code-extension init . --code-type script +sf data-code-extension script init --package-dir . -# 3. Edit entrypoint.py -# (Add your transformation code) +# 3. Edit payload/entrypoint.py with your transformation # 4. Scan -sf data-code-extension scan ./payload/entrypoint.py +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py # 5. Test -sf data-code-extension run ./payload/entrypoint.py --target-org afvibe +sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe -# 6. Deploy (MUST include --path ./payload) -sf data-code-extension deploy \ +# 6. Deploy (MUST include --package-dir ./payload) +sf data-code-extension script deploy \ --target-org afvibe \ --name MyTransform \ --package-version 1.0.0 \ - --description "Uppercase employee positions" \ - --path ./payload + --description "My transformation" \ + --package-dir ./payload ``` ### Update Existing Code Extension ```bash -# 1. Edit entrypoint.py +# 1. Edit payload/entrypoint.py # 2. Re-scan -sf data-code-extension scan ./payload/entrypoint.py +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py # 3. Test -sf data-code-extension run ./payload/entrypoint.py -o afvibe +sf data-code-extension script run --entrypoint ./payload/entrypoint.py -o afvibe -# 4. Deploy with new version (include --path ./payload) -sf data-code-extension deploy \ +# 4. Deploy with new version (include --package-dir ./payload) +sf data-code-extension script deploy \ -o afvibe \ -n MyTransform \ --package-version 1.1.0 \ - --description "Uppercase employee positions" \ - --path ./payload + --description "Updated transformation" \ + --package-dir ./payload ``` ## Python Code Patterns @@ -188,10 +179,6 @@ df['grade'] = df['position'].apply( ## Option Reference -### --code-type -- `script` - Batch transformation (default) -- `function` - Real-time function - ### --cpu-size - `CPU_L` - Small datasets (< 1M records) - `CPU_XL` - Medium datasets (1M-5M) @@ -220,7 +207,7 @@ python --version sf org login web --alias # Config missing -sf data-code-extension scan ./payload/entrypoint.py +sf data-code-extension script scan --entrypoint ./payload/entrypoint.py # Docker not running (for deploy) # Start Docker Desktop @@ -261,7 +248,7 @@ my-project/ | Wrong Python version | Use pyenv to install 3.11.0 | | Org not connected | `sf org login web --alias ` | | Config missing | Run scan command | -| DLO not found | Check DLO name, use DLO Schema skill | +| DLO not found | Check DLO name, use getting-datacloud-schema skill | | Docker error | Start Docker Desktop | ## Deployment Checklist @@ -275,49 +262,6 @@ my-project/ - [ ] Docker running - [ ] Org authenticated -## Next Steps After Deploy - -1. Go to Data Cloud in Salesforce UI -2. Navigate to Code Extensions -3. Find your deployment -4. Click "Run Now" to test -5. Schedule for recurring execution -6. Monitor execution logs - -## Quick Examples - -### Example 1: Simple Transform -```python -from datacustomcode import Client -client = Client() - -df = client.read_dlo('Employee__dll') -df['upper_pos'] = df['position'].str.upper() -client.write_to_dlo('Employee_Upper__dll', df, 'overwrite') -``` - -### Example 2: Filter and Write -```python -from datacustomcode import Client -client = Client() - -df = client.read_dlo('Employee__dll') -managers = df[df['position'].str.contains('Manager')] -client.write_to_dlo('Managers__dll', managers, 'overwrite') -``` - -### Example 3: Join Two DLOs -```python -from datacustomcode import Client -client = Client() - -employees = client.read_dlo('Employee__dll') -departments = client.read_dlo('Department__dll') - -merged = employees.merge(departments, left_on='dept_id', right_on='id') -client.write_to_dlo('Employee_With_Dept__dll', merged, 'overwrite') -``` - ## Resources - Plugin: https://github.com/salesforcecli/plugin-data-code-extension diff --git a/skills/getting-datacloud-schema/SKILL.md b/skills/getting-datacloud-schema/SKILL.md index 735d342..3bd2ed5 100644 --- a/skills/getting-datacloud-schema/SKILL.md +++ b/skills/getting-datacloud-schema/SKILL.md @@ -1,6 +1,6 @@ --- name: getting-datacloud-schema -description: Retrieve Data Lake Object (DLO) and Data Model Object (DMO) schema information from Salesforce Data Cloud using REST APIs. Use this skill when you need to inspect DLO or DMO field definitions, data types, or metadata. Takes org alias and optional DLO/DMO name as parameters. +description: "Retrieve Data Lake Object (DLO) and Data Model Object (DMO) schema information from Salesforce Data Cloud using REST APIs. Use this skill when you need to inspect DLO or DMO field definitions, data types, or metadata. Takes org alias and optional DLO/DMO name as parameters." --- # getting-datacloud-schema Skill diff --git a/skills/getting-datacloud-schema/docs/README.md b/skills/getting-datacloud-schema/docs/README.md deleted file mode 100644 index fb549fc..0000000 --- a/skills/getting-datacloud-schema/docs/README.md +++ /dev/null @@ -1,265 +0,0 @@ -# getting-datacloud-schema Skill - -## Overview - -A Claude Code skill that retrieves Data Lake Object (DLO) and Data Model Object (DMO) schema information from Salesforce Data Cloud using REST APIs. - -## Installation - -The skill is now installed at: -``` -/home/codebuilder/dx-project/.a4drules/skills/getting-datacloud-schema/ -``` - -## Usage - -### Using the Skill in Claude Code - -Simply ask Claude to get DLO or DMO information: - -**List all DLOs:** -``` -"Show me all DLOs in afvibe org" -"List Data Lake Objects in myorg" -``` - -**Get specific DLO schema:** -``` -"Get the schema for Employee__dll in afvibe" -"What fields does the Employee__dll DLO have in myorg?" -``` - -**List all DMOs:** -``` -"Show me all DMOs in afvibe org" -"List Data Model Objects in myorg" -``` - -**Get specific DMO schema:** -``` -"Get the schema for Individual__dlm in afvibe" -"What fields does the Individual__dlm DMO have in myorg?" -``` - -### Direct Script Usage - -You can also run the scripts directly: - -```bash -# List all DLOs -python3 ./scripts/get_dlo_schema.py - -# Get specific DLO schema -python3 ./scripts/get_dlo_schema.py - -# List all DMOs -python3 ./scripts/get_dmo_schema.py - -# Get specific DMO schema -python3 ./scripts/get_dmo_schema.py -``` - -**Examples:** -```bash -# List all DLOs in afvibe org -python3 ./scripts/get_dlo_schema.py afvibe - -# Get Employee__dll schema from afvibe -python3 ./scripts/get_dlo_schema.py afvibe Employee__dll - -# List all DMOs in afvibe org -python3 ./scripts/get_dmo_schema.py afvibe - -# Get Individual__dlm schema from afvibe -python3 ./scripts/get_dmo_schema.py afvibe Individual__dlm -``` - -## Prerequisites - -1. **SF CLI Installed** - ```bash - sf --version - ``` - -2. **Authenticated to Target Org** - ```bash - sf org login web --alias - ``` - -3. **Python 3 and Dependencies** - ```bash - pip install requests pyyaml - ``` - -4. **Data Cloud Enabled** - - Org must have Data Cloud provisioned - - User must have Data Cloud permissions - -## What It Does - -### List All DLOs -- Calls: `GET /services/data/v64.0/ssot/data-lake-objects` -- Returns: All DLOs with name, label, category, ID, record count -- Shows paginated results - -### Get DLO Schema -- Calls: `GET /services/data/v64.0/ssot/data-lake-objects/{dlo_name}` -- Returns: Detailed field schema including: - - Field names and labels - - Data types (Text, Number, DateTime, etc.) - - Primary key indicators - - Nullable status - - Field metadata - -### List All DMOs -- Calls: `GET /services/data/v64.0/ssot/data-model-objects` -- Returns: All DMOs with name, label, category, ID -- Shows paginated results - -### Get DMO Schema -- Calls: `GET /services/data/v64.0/ssot/data-model-objects/{dmo_name}` -- Returns: Detailed field schema including: - - Field names and labels - - Data types (Text, Number, DateTime, etc.) - - Primary key indicators - - Nullable status - - Field metadata - -## API Endpoints - -| Endpoint | Method | Purpose | -|----------|--------|---------| -| `/services/data/v64.0/ssot/data-lake-objects` | GET | List all DLOs | -| `/services/data/v64.0/ssot/data-lake-objects/{name}` | GET | Get DLO schema | -| `/services/data/v64.0/ssot/data-model-objects` | GET | List all DMOs | -| `/services/data/v64.0/ssot/data-model-objects/{name}` | GET | Get DMO schema | - -## Output Format - -### DLO List -``` -Found 5 DLOs in org 'afvibe': - -1. DataCustomCodeLogs__dll - Label: DataCustomCodeLogs - Category: Engagement - Records: 233 - -2. Employee__dll - Label: Employee - Category: Profile - Records: 12 -``` - -### DLO Schema -``` -DLO: Employee__dll -Label: Employee -Category: Profile -Status: ACTIVE -Records: 12 - -Fields (9 total): - • id__c (Text) - Primary Key - • name__c (Text) - • position__c (Text) - • manager_id__c (Number) - • DataSource__c (Text) - • InternalOrganization__c (Text) - [...] -``` - -### DMO List -``` -Found 10 DMOs in org 'afvibe': - -1. Individual__dlm - Label: Individual - Category: Profile - -2. ContactPointEmail__dlm - Label: Contact Point Email - Category: Profile -``` - -### DMO Schema -``` -DMO: Individual__dlm -Label: Individual -Category: Profile - -Fields (8 total): - • Id__c (Text) - Primary Key - • FirstName__c (Text) - • LastName__c (Text) - • BirthDate__c (DateTime) - [...] -``` - -## Files - -``` -getting-datacloud-schema/ -├── SKILL.md # Skill definition and instructions -├── docs/ -│ └── README.md # This file -└── scripts/ - ├── get_dlo_schema.py # Python script for DLO REST APIs - └── get_dmo_schema.py # Python script for DMO REST APIs -``` - -## Troubleshooting - -**Issue: "Org not connected"** -```bash -sf org login web --alias -sf org list # Verify -``` - -**Issue: "Module not found: requests"** -```bash -pip install requests pyyaml -``` - -**Issue: "DLO not found"** -- Verify DLO name ends with `__dll` suffix -- List all DLOs first to confirm exact name - -**Issue: "DMO not found"** -- Verify DMO name ends with `__dlm` suffix -- List all DMOs first to confirm exact name - -**Issue: "Permission denied"** -- Verify user has Data Cloud permissions -- Check org has Data Cloud enabled - -## Related Skills - -- `aisuite_datakit_workflow` - For DMO mapping operations -- `aisuite_datakit_validation` - For validating datakit configs - -## Next Steps After Getting Schema - -1. **Query DLO Data** - ```sql - SELECT * FROM Employee__dll LIMIT 10 - ``` - -2. **Create Segments** - - Use fields to build audience segments - -3. **Set Up Data Streams** - - Create ingestion pipelines - -4. **Create DMO Mappings** - - Map DLO fields to Data Model Objects - -5. **Build Calculated Insights** - - Aggregate data from DLO fields - -## Version - -- **Version**: 1.0 -- **Created**: 2026-03-26 -- **API Version**: v64.0 -- **Python**: 3.9+ diff --git a/skills/getting-datacloud-schema/references/README.md b/skills/getting-datacloud-schema/references/README.md new file mode 100644 index 0000000..54102a8 --- /dev/null +++ b/skills/getting-datacloud-schema/references/README.md @@ -0,0 +1,191 @@ +# getting-datacloud-schema Skill + +## Overview + +A skill that retrieves Data Lake Object (DLO) and Data Model Object (DMO) schema information from Salesforce Data Cloud using REST APIs. + +## Usage + +**List all DLOs:** +``` +"Show me all DLOs in afvibe org" +"List Data Lake Objects in myorg" +``` + +**Get specific DLO schema:** +``` +"Get the schema for Employee__dll in afvibe" +"What fields does the Employee__dll DLO have in myorg?" +``` + +**List all DMOs:** +``` +"Show me all DMOs in afvibe org" +"List Data Model Objects in myorg" +``` + +**Get specific DMO schema:** +``` +"Get the schema for Individual__dlm in afvibe" +"What fields does the Individual__dlm DMO have in myorg?" +``` + +### Direct Script Usage + +You can also run the scripts directly: + +```bash +# List all DLOs +python3 scripts/get_dlo_schema.py + +# Get specific DLO schema +python3 scripts/get_dlo_schema.py + +# List all DMOs +python3 scripts/get_dmo_schema.py + +# Get specific DMO schema +python3 scripts/get_dmo_schema.py +``` + +**Examples:** +```bash +# List all DLOs in afvibe org +python3 scripts/get_dlo_schema.py afvibe + +# Get Employee__dll schema from afvibe +python3 scripts/get_dlo_schema.py afvibe Employee__dll + +# List all DMOs in afvibe org +python3 scripts/get_dmo_schema.py afvibe + +# Get Individual__dlm schema from afvibe +python3 scripts/get_dmo_schema.py afvibe Individual__dlm +``` + +## Prerequisites + +1. **SF CLI Installed** + ```bash + sf --version + ``` + +2. **Authenticated to Target Org** + ```bash + sf org login web --alias + ``` + +3. **Python 3 and Dependencies** + ```bash + pip install requests pyyaml + ``` + +4. **Data Cloud Enabled** + - Org must have Data Cloud provisioned + - User must have Data Cloud permissions + +## What It Does + +### List All DLOs +- Calls: `GET /services/data/v64.0/ssot/data-lake-objects` +- Returns: All DLOs with name, label, category, ID, record count +- Shows paginated results + +### Get DLO Schema +- Calls: `GET /services/data/v64.0/ssot/data-lake-objects/{dlo_name}` +- Returns: Detailed field schema including field names, data types, primary key indicators, nullable status + +### List All DMOs +- Calls: `GET /services/data/v64.0/ssot/data-model-objects` +- Returns: All DMOs with name, label, category, ID +- Shows paginated results + +### Get DMO Schema +- Calls: `GET /services/data/v64.0/ssot/data-model-objects/{dmo_name}` +- Returns: Detailed field schema including field names, data types, primary key indicators, nullable status + +## API Endpoints + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/services/data/v64.0/ssot/data-lake-objects` | GET | List all DLOs | +| `/services/data/v64.0/ssot/data-lake-objects/{name}` | GET | Get DLO schema | +| `/services/data/v64.0/ssot/data-model-objects` | GET | List all DMOs | +| `/services/data/v64.0/ssot/data-model-objects/{name}` | GET | Get DMO schema | + +## Output Format + +### DLO List +``` +Found 5 DLOs in org 'afvibe': + +1. DataCustomCodeLogs__dll + Label: DataCustomCodeLogs + Category: Engagement + Records: 233 + +2. Employee__dll + Label: Employee + Category: Profile + Records: 12 +``` + +### DLO Schema +``` +DLO: Employee__dll +Label: Employee +Category: Profile +Status: ACTIVE +Records: 12 + +Fields (9 total): + - id__c (Text) - Primary Key + - name__c (Text) + - position__c (Text) + - manager_id__c (Number) + - DataSource__c (Text) + [...] +``` + +### DMO List +``` +Found 10 DMOs in org 'afvibe': + +1. Individual__dlm + Label: Individual + Category: Profile + +2. ContactPointEmail__dlm + Label: Contact Point Email + Category: Profile +``` + +### DMO Schema +``` +DMO: Individual__dlm +Label: Individual +Category: Profile + +Fields (8 total): + - Id__c (Text) - Primary Key + - FirstName__c (Text) + - LastName__c (Text) + - BirthDate__c (DateTime) + [...] +``` + +## Troubleshooting + +| Issue | Fix | +|-------|-----| +| Org not connected | `sf org login web --alias ` | +| Module not found: requests | `pip install requests pyyaml` | +| DLO not found | Verify name ends with `__dll`, list all DLOs first | +| DMO not found | Verify name ends with `__dlm`, list all DMOs first | +| Permission denied | Verify user has Data Cloud permissions | + +## Related Skills + +- **datakit workflow**: For DMO mapping operations +- **datakit validation**: For validating datakit configurations +- Use this skill before creating DMO mappings to understand source DLO structure