troubleshooting

Diagnose Revenue Cloud build, deployment, data load, and usage rating failures.

33|12|Updated Sep 24, 2024
One-click install
npx skills add https://github.com/bgaldino/rlm-base-dev --skill troubleshooting-bgaldino
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: troubleshooting
Source: https://github.com/bgaldino/rlm-base-dev/tree/main/.cursor/skills/troubleshooting
Command: npx skills add https://github.com/bgaldino/rlm-base-dev --skill troubleshooting-bgaldino

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Revenue Cloud Foundations builds involve 34 orchestrated steps across CCI flows, SFDMU data loads, metadata deploys, and usage rating pipelines, and failures surface as cryptic errors with no obvious cause. This Skill maps each failure to its root cause and fix, so you stop guessing and start resolving. ## Core Features & Use Cases - Step-Based Diagnosis: Identify which of the 34 prepare_rlm_org flow steps failed and jump directly to the relevant error catalog covering permissions, decision tables, expression sets, rating, billing, DocGen, PRM, and constraints. - Silent Failure Detection: Diagnose issues that report no error, such as rated usage reading zero, SOQL semi-joins on polymorphic fields matching nothing, and async batch failures hidden in BatchJobPartFailedRecord. - Live-Org Evidence Capture: Query RevenueTransactionErrorLog, AsyncOperationTracker, and order calculation state before a data reset destroys the evidence, with a dedicated reference for large-deal reprice/preprocess/activation flows. - Use Case: A CCI flow fails at step 18 with a PUR activation error about overlapping effective periods. The Skill tells you duplicate Draft PURs exist, and gives the exact delete-rates-then-rating reload sequence to recover. ## Quick Start Ask the agent to diagnose why your CCI flow step failed or why rated usage reads zero, and have it follow the troubleshooting skill's quick diagnosis table.

Frequently Asked Questions about troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose a failed CCI flow step in a Revenue Cloud build?

Run `cci task run validate_setup` first to check the local toolchain, then identify the failing step number from CCI output. The prepare_rlm_org flow has 34 steps; match the step range to the relevant error category such as SFDMU loading, metadata deploy, or rating.

Why does rated usage read zero with no error in Salesforce?

Zero rated usage is an ordering problem, not a data problem. Usage recorded after period orchestration stays Pending forever, the first orchestration pass closes past periods empty, and usage booked into the current period never rates. Record usage into a past period before orchestrating, then run orchestration several times.

Why does my SFDMU data load create duplicates on re-run?

Duplicates on re-run mean the CSV is missing or has a mismatched `$$` composite key column. Verify the CSV header matches the externalId fields exactly, such as `$$Field1$Field2` for `externalId: "Field1;Field2"`, and run the dataset validation script.

Can I use the same org alias for CCI and Salesforce CLI?

No, CCI and SF CLI maintain separate org registries with different alias formats. CCI uses short aliases like `beta` while SF CLI uses project-prefixed aliases like `rlm-base__beta`. The username always works with either tool.

Why does a SOQL semi-join on BindingObjectId return no rows?

BindingObjectId is a polymorphic field that can point at Account, Asset, Contract, or custom objects, and semi-joins against polymorphic lookups silently match nothing while reporting success. Materialize the ids into a Set<Id> and bind that variable instead.

How do I find why an async rating or entitlement batch failed?

Batch failures do not surface in flow results, so query the forensic objects directly. Query BatchJobPartFailedRecord for per-record failures using ErrorDescription and Record fields, and check TransactionUsageEntitlement.EntitlementProcessingStatus for entitlements stuck at PENDING.