PranavNagrecha/AwesomeSalesforceSkills / skills/admin/change-data-capture-admin
change-data-capture-admin
VerifiedUse when enabling, configuring, or monitoring Change Data Capture (CDC) entity selection, channel enrichment, and delivery usage limits from an admin perspective. Covers the PlatformEventChannel and PlatformEventChannelMember metadata, the standard ChangeEvents channel, custom __chn data channels, enrichedFields, filterExpression, destructive deselection, and PlatformEventUsageMetric / EventBusSubscriber monitoring. Trigger keywords: change data capture, CDC, entity selection, change event, platform event channel, channel member, enrichment, event delivery allocation. NOT for writing an Apex change-event trigger — use apex/change-data-capture-apex. NOT for subscribing an external system over Pub/Sub or CometD — use integration/change-data-capture-integration.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.6 KB |
| references/examples.md | markdown | 7.6 KB |
| references/gotchas.md | markdown | 15.1 KB |
| references/llm-anti-patterns.md | markdown | 6.3 KB |
| references/metadata-examples.md | markdown | 14.9 KB |
| references/well-architected.md | markdown | 6.3 KB |
| scripts/check_change_data_capture_admin.pyexecutable | script | 12.4 KB |
| templates/change-data-capture-admin-template.md | markdown | 3.3 KB |
scripts/check_change_data_capture_admin.py
View on GitHub#!/usr/bin/env python3
"""Checker script for the Change Data Capture Admin skill.
Inspects PlatformEventChannel / PlatformEventChannelMember metadata in SFDX
source format (or a retrieved unzip) for the configuration mistakes documented
in references/gotchas.md and references/metadata-examples.md.
Uses stdlib only - no pip dependencies.
Checks
1. ERROR selectedEntity on a `data` channel that is not a change event
(must end in `ChangeEvent`).
2. ERROR the same enriched field listed twice on one channel member.
3. WARN a member whose eventChannel is a custom `__chn` channel that has
no PlatformEventChannel file in the tree.
4. WARN a channel file that looks Data Cloud-managed.
5. INFO filterExpression / enrichedFields used below the API version that
introduced them (56.0 / 51.0), read from package.xml or
sfdx-project.json.
6. INFO a `data` channel with no member files pointing at it.
Usage:
python3 check_change_data_capture_admin.py [--manifest-dir path/to/metadata]
Exit codes:
0 - no ERROR or WARN findings (INFO findings may still be printed)
1 - at least one ERROR or WARN finding, or the directory does not exist
"""
from __future__ import annotations
import argparse
import json
import sys
import xml.etree.ElementTree as ET
from pathlib import Path
SF_NS = "http://soap.sforce.com/2006/04/metadata"
# Metadata API Developer Guide, PlatformEventChannelMember:
# enrichedFields "Available in API version 51.0 and later";
# filterExpression "Available in API version 56.0 and later".
ENRICHED_FIELDS_MIN_API = 51.0
FILTER_EXPRESSION_MIN_API = 56.0
ERROR = "ERROR"
WARN = "WARN"
INFO = "INFO"
class Finding:
def __init__(self, severity: str, path: Path, message: str) -> None:
self.severity = severity
self.path = path
self.message = message
def render(self) -> str:
return f"{self.severity}: {self.path.name}: {self.message}"
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Check Change Data Capture channel metadata for known configuration mistakes.",
)
parser.add_argument(
"--manifest-dir",
default=".",
help="Root of the Salesforce project or retrieved metadata (default: current directory).",
)
return parser.parse_args()
def _tag(local: str) -> str:
return f"{{{SF_NS}}}{local}"
def _find(parent: ET.Element, name: str) -> ET.Element | None:
"""Direct child lookup that works with or without the metadata namespace.
`parent.find(a) or parent.find(b)` must never be used here: an Element with
no children is falsy, so a found leaf such as <eventChannel> would be
discarded and every namespaced file would look empty (fail-open).
"""
element = parent.find(_tag(name))
if element is not None:
return element
return parent.find(name)
def _findall(parent: ET.Element, name: str) -> list[ET.Element]:
found = parent.findall(_tag(name))
if found:
return found
return parent.findall(name)
def _text(parent: ET.Element, name: str) -> str:
element = _find(parent, name)
if element is None or element.text is None:
return ""
return element.text.strip()
def _files(root: Path, suffix: str) -> list[Path]:
"""All files for one metadata suffix, in DX (-meta.xml) or retrieved form."""
results = list(root.rglob(f"*.{suffix}-meta.xml"))
results.extend(p for p in root.rglob(f"*.{suffix}") if p.is_file())
return sorted(set(results))
def _component_name(path: Path, suffix: str) -> str:
"""`SalesEvents__chn.platformEventChannel-meta.xml` -> `SalesEvents__chn`."""
name = path.name
for tail in (f".{suffix}-meta.xml", f".{suffix}"):
if name.endswith(tail):
return name[: -len(tail)]
return path.stem
def detect_api_version(root: Path) -> tuple[float | None, str]:
"""Highest API version declared by the project, and where it came from."""
versions: list[tuple[float, str]] = []
for manifest in root.rglob("package.xml"):
try:
tree = ET.parse(manifest)
except (ET.ParseError, OSError):
continue
raw = _text(tree.getroot(), "version")
if raw:
try:
versions.append((float(raw), manifest.name))
except ValueError:
continue
for project in root.rglob("sfdx-project.json"):
try:
data = json.loads(project.read_text(encoding="utf-8"))
except (OSError, ValueError):
continue
raw = data.get("sourceApiVersion")
if raw:
try:
versions.append((float(raw), project.name))
except (TypeError, ValueError):
continue
if not versions:
return None, ""
best = max(versions, key=lambda item: item[0])
return best[0], best[1]
def read_channels(root: Path) -> tuple[dict[str, str], list[Finding]]:
"""Map custom channel name -> channelType, plus findings about the files."""
channels: dict[str, str] = {}
findings: list[Finding] = []
for path in _files(root, "platformEventChannel"):
try:
element = ET.parse(path).getroot()
except (ET.ParseError, OSError) as exc:
findings.append(Finding(ERROR, path, f"could not be parsed as XML ({exc})."))
continue
name = _component_name(path, "platformEventChannel")
channels[name] = _text(element, "channelType")
if "datacloud" in name.lower() or "data_cloud" in name.lower():
findings.append(
Finding(
WARN,
path,
f"channel '{name}' looks Data Cloud-managed. Deploying members for a "
"feature-managed channel can disrupt that feature's ingestion silently; "
"manage it in that feature's own admin UI (references/gotchas.md, Gotcha 1).",
)
)
return channels, findings
def check_member(path: Path, channels: dict[str, str], api_version: float | None,
api_source: str) -> tuple[list[Finding], str]:
"""Check one PlatformEventChannelMember file. Returns findings and its channel."""
findings: list[Finding] = []
try:
element = ET.parse(path).getroot()
except (ET.ParseError, OSError) as exc:
return [Finding(ERROR, path, f"could not be parsed as XML ({exc}).")], ""
channel = _text(element, "eventChannel")
entity = _text(element, "selectedEntity")
if not channel:
findings.append(
Finding(ERROR, path, "<eventChannel> is missing; it is a required field on "
"PlatformEventChannelMember.")
)
if not entity:
findings.append(
Finding(ERROR, path, "<selectedEntity> is missing; it is a required field on "
"PlatformEventChannelMember.")
)
# Standard channel is named ChangeEvents and has no PlatformEventChannel file:
# "In API version 47.0 and later, you can't deploy or retrieve the ChangeEvents
# standard channel." Custom channel names end in __chn.
is_standard_channel = channel == "ChangeEvents"
channel_type = "data" if is_standard_channel else channels.get(channel, "")
if channel and not is_standard_channel and channel not in channels:
findings.append(
Finding(
WARN,
path,
f"references channel '{channel}', which has no "
f"platformEventChannels/{channel}.platformEventChannel-meta.xml in this tree. "
"Deploy the channel in the same package as its members, or check for a "
"double underscore that should have been collapsed in the file name "
"(references/gotchas.md, Gotcha 5).",
)
)
# A data channel carries change events only.
if entity and channel_type == "data" and not entity.endswith("ChangeEvent"):
findings.append(
Finding(
ERROR,
path,
f"selectedEntity '{entity}' on data channel '{channel}' is not a change "
"event. On channelType=data the value is the change event name, such as "
"AccountChangeEvent or MyObject__ChangeEvent. A custom platform event "
"(MyEvent__e) belongs on a channelType=event channel.",
)
)
enriched = [
(_text(field, "name") or "").strip()
for field in _findall(element, "enrichedFields")
]
seen: set[str] = set()
duplicates: list[str] = []
for name in enriched:
if not name:
continue
if name in seen and name not in duplicates:
duplicates.append(name)
seen.add(name)
for name in duplicates:
findings.append(
Finding(
ERROR,
path,
f"enriched field '{name}' is listed more than once. Each field is enriched "
"once per channel member; remove the duplicate <enrichedFields> block.",
)
)
filter_element = _find(element, "filterExpression")
if api_version is not None:
where = f" (API {api_version:g} from {api_source})" if api_source else ""
if filter_element is not None and api_version < FILTER_EXPRESSION_MIN_API:
findings.append(
Finding(
INFO,
path,
f"uses <filterExpression> but the project targets API {api_version:g}"
f"{where}. filterExpression is 'Available in API version 56.0 and later' "
"(Metadata API Developer Guide, PlatformEventChannelMember).",
)
)
if enriched and api_version < ENRICHED_FIELDS_MIN_API:
findings.append(
Finding(
INFO,
path,
f"uses <enrichedFields> but the project targets API {api_version:g}"
f"{where}. enrichedFields is 'Available in API version 51.0 and later' "
"(Metadata API Developer Guide, PlatformEventChannelMember).",
)
)
return findings, channel
def check_change_data_capture_admin(manifest_dir: Path) -> list[Finding]:
if not manifest_dir.exists():
return [Finding(ERROR, manifest_dir, "manifest directory not found.")]
channels, findings = read_channels(manifest_dir)
api_version, api_source = detect_api_version(manifest_dir)
member_files = _files(manifest_dir, "platformEventChannelMember")
if not channels and not member_files:
print(f"INFO: no PlatformEventChannel or PlatformEventChannelMember metadata "
f"found under {manifest_dir}.")
return findings
referenced: dict[str, int] = {}
for path in member_files:
member_findings, channel = check_member(path, channels, api_version, api_source)
findings.extend(member_findings)
if channel:
referenced[channel] = referenced.get(channel, 0) + 1
for name, channel_type in sorted(channels.items()):
if channel_type == "data" and referenced.get(name, 0) == 0:
findings.append(
Finding(
INFO,
manifest_dir / "platformEventChannels" / f"{name}.platformEventChannel-meta.xml",
f"data channel '{name}' has no PlatformEventChannelMember files in this "
"tree, so it publishes nothing. Add a member per selected entity, or drop "
"the channel from the package.",
)
)
return findings
def main() -> int:
args = parse_args()
findings = check_change_data_capture_admin(Path(args.manifest_dir))
order = {ERROR: 0, WARN: 1, INFO: 2}
for finding in sorted(findings, key=lambda f: (order[f.severity], str(f.path))):
print(finding.render())
blocking = [f for f in findings if f.severity in (ERROR, WARN)]
if not blocking:
if not findings:
print("No CDC channel configuration issues found.")
return 0
print(
f"{len(blocking)} blocking finding(s): "
f"{sum(1 for f in blocking if f.severity == ERROR)} ERROR, "
f"{sum(1 for f in blocking if f.severity == WARN)} WARN.",
file=sys.stderr,
)
return 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |