Sales Engagement API

Sales Engagement API

Use this skill when programmatic Apex code needs to enroll records in Sales Engagement cadences, react to cadence lifecycle events, or log outcomes on cadence steps. The objective is reliable, bulkified enrollment that respects the platform's invocable action model and leverages Change Data Capture for event-driven reactions rather than unsupported triggers.

Before Starting

• Confirm the org has an active Sales Engagement (formerly High Velocity Sales) license and that the Sales Engagement feature is enabled in Setup.
• Identify the target object type — enrollment supports Lead, Contact, and Person Account. Standard Account and custom objects are not supported targets for assignTargetToSalesCadence as of Spring '25.
• Determine whether the cadence already exists in the Cadence Builder UI. The cadence structure (steps, branches, email templates, call scripts) is entirely read-only via API. Apex cannot create or modify cadence content — that belongs in the UI.
• Clarify if the requirement is enrollment only, step-completion logging, real-time reaction to cadence state changes, or all three.
• Understand volume expectations. Invocable actions called from Apex count against DML and governor limits. Bulk enrollment via the action supports a list of inputs, which is critical for batch contexts.

Core Concepts

The assignTargetToSalesCadence Invocable Action Is the Only Enrollment API

Salesforce does not expose a direct DML-based way to create enrollment records. Cadence enrollment is performed by calling the assignTargetToSalesCadence invocable action using Invocable.Action in Apex or by invoking it from Flow. Attempting to insert ActionCadenceTracker or related objects directly via DML will result in errors. This pattern is intentional: the platform enforces enrollment rules (duplicate prevention, license checks, step scheduling) inside the action rather than exposing them to raw DML.

The ActionCadence Object Family Is Read-Only via Apex DML

The ActionCadence, ActionCadenceStep, ActionCadenceStepVariant, and ActionCadenceTracker objects represent the cadence structure and enrollment state. They can be queried via SOQL, but DML mutations are restricted or unsupported except through the designated invocable actions. Do not attempt to insert or update these objects directly. The only mutation surface for enrollment is the invocable action; for step completion and call logging it is the designated completeActionCadenceStep action or task record updates.

Triggers Are Not Supported on ActionCadence Objects — Use CDC

Standard Apex triggers cannot be placed on ActionCadenceTracker, ActionCadenceStepTracker, or related objects. Reacting to cadence state changes requires Change Data Capture (CDC). Enable CDC on the ActionCadenceTracker object in Setup, then author an Async Apex Trigger on the ActionCadenceTrackerChangeEvent channel. This is the officially supported pattern for event-driven reactions to enrollment lifecycle changes.

Enrollment Respects Duplicate Guards at the Platform Level

The invocable action enforces that a target cannot be enrolled in the same cadence twice if an active enrollment already exists. The action returns output fields indicating success or failure. Production code must inspect these outputs per invocation. Swallowing action errors silently leaves the calling code unable to distinguish successful enrollments from duplicates or license errors.

Common Patterns

Bulk Cadence Enrollment Service

When to use: A batch process, trigger, or scheduled job needs to enroll many Leads or Contacts into a cadence at once.

How it works: Collect Invocable.Action.Input instances for each target, set the sObjectName, targetId, cadenceName, and userId parameters, then invoke the assignTargetToSalesCadence action as a bulk list. Inspect each Invocable.Action.Result for success and log or surface failures per record.

Why not the alternative: Calling the action one record at a time in a loop inflates Apex CPU time and may exceed governor limits on large sets. The list-based invocation is the bulk-safe pattern.

CDC-Based Async Trigger for Enrollment Lifecycle Events

When to use: Downstream processes need to react when a target is enrolled, a step is completed, or a cadence run ends.

How it works: Enable ActionCadenceTracker CDC in Setup. Implement an Async Apex Trigger on ActionCadenceTrackerChangeEvent. Inside the trigger, read EventBus.TriggerContext.currentResumeCheckpoint() and process the ChangeEventHeader to determine the change type (CREATE, UPDATE, DELETE). Enqueue a Queueable for heavier work.

Why not the alternative: A synchronous Apex trigger on ActionCadenceTracker is not supported. Polling SOQL for state changes is fragile and wastes queries.

Step Completion and Call Logging

When to use: A CTI integration or custom UI needs to record the outcome of a call step and advance the cadence.

How it works: Use the completeActionCadenceStep invocable action, passing the ActionCadenceStepTrackerId and outcome fields (call result, disposition). This advances the tracker to the next step. Alternatively, update the associated Task record's call result fields; the cadence engine reads those fields to determine step completion in call-step contexts.

Why not the alternative: Directly updating ActionCadenceStepTracker status fields via DML is not supported and will fail silently or throw errors.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Confirm prerequisites — verify that the Sales Engagement license is active, the target cadence exists in the UI, and the target object type is Lead, Contact, or Person Account.
2. Query existing enrollment state — SOQL ActionCadenceTracker for active enrollments on the target records to prevent duplicate action calls and interpret likely results.
3. Build the enrollment service — implement a service class that constructs Invocable.Action.Input lists, calls assignTargetToSalesCadence in bulk, and inspects Invocable.Action.Result per record to capture errors.
4. Handle CDC for lifecycle reactions — if downstream automation is needed, enable CDC on ActionCadenceTracker, scaffold an Async Apex Trigger on ActionCadenceTrackerChangeEvent, and move heavy work to Queueable.
5. Implement step completion logging — if call results must be logged programmatically, use the completeActionCadenceStep invocable action or update the Task record associated with the step.
6. Test in a scratch org or sandbox with Sales Engagement enabled — confirm invocable action outputs, governor limit consumption, and CDC event delivery under bulk load.
7. Run the skill checker and validate the full package before committing.

Review Checklist

• Enrollment is performed via assignTargetToSalesCadence invocable action, not DML on ActionCadence objects.
• Invocable action results are inspected per record and failures are surfaced or logged.
• A duplicate enrollment guard queries ActionCadenceTracker for active enrollments before calling the action.
• CDC is used for lifecycle reactions, not Apex triggers on ActionCadence objects.
• Step completion uses completeActionCadenceStep or Task field updates — not direct DML on ActionCadenceStepTracker.
• All action calls use list inputs to stay bulkification-safe.
• Tests use @isTest stubs or mock invocable action results since the action cannot fire in test contexts without the managed package.

Salesforce-Specific Gotchas

1. Invocable actions do not run in unit tests without the Sales Engagement package context — tests that call assignTargetToSalesCadence via Invocable.Action.invoke() will return empty results or throw in a standard scratch org without the SE license provisioned. Use a wrapper interface to allow mocking in test context.
2. ActionCadenceTracker CDC events can arrive out of order — Async Apex Triggers process events in the order they are delivered by the event bus, which may not match the business order of step completions. Designs that require strict ordering must use the ChangeEventHeader sequence or query the tracker state rather than relying on event order.
3. assignTargetToSalesCadence silently no-ops if the target is already in an active enrollment — the action returns a result with success = false and an error code rather than throwing an exception. Callers that only check for exceptions will not detect duplicate enrollment failures.
4. Cadence structure objects (ActionCadence, ActionCadenceStep) are accessible via SOQL but reflect the live state — they do not represent a versioned snapshot. A cadence modified in the UI mid-run changes the SOQL results.

Output Artifacts

Related Skills

• apex/change-data-capture-apex — use for deep CDC pattern design including resume checkpoints, chunking, and replay gaps when the CDC trigger is more complex than a thin enqueue.
• apex/invocable-methods — use when building or calling invocable actions for advanced input/output type design.
• apex/async-apex — use when the Queueable work spawned from the CDC trigger requires chaining, retry, or batch fallback patterns.
• apex/governor-limits — use when enrollment volume is high enough that invocable action call counts and DML governor consumption need modeling.