How Cadence Builder Operations Affect Record Data
To get data about cadences, you must understand what happens in the background when someone builds and updates cadences in Cadence Builder.
As you update the cadence steps using the builder, it isn’t always clear how the data tables change and how that change affects targets on these steps. This section describes the behaviors and rules of builder operations, such as adding, deleting, and modifying steps and activating, deactivating, and deleting cadences.
For more information about object fields, see Object Relationships.
When a cadence is in a draft state, you can’t save steps that aren’t connected to the graph. The new step must be inserted into the graph or appended to the end of a branch or path. Fortunately, Cadence Builder prevents adding floating steps.
When you insert a step into the graph, the ParentStepName
fields of the preceding and following steps are updated so that the steps follow the proper sequence. Steps without a ParentStepName
value aren’t allowed.
Cadence Builder inserts new steps and updates steps to maintain your intended step order in the same transaction. The system actions for adding and deleting steps are different. Deleting a step is a more complex process.
It's simple to add steps at the end of a path. A ActionCadenceStep record is created with the ParentStepName
being the previous last step. No steps are modified.
Deleting a step doesn’t necessarily delete the step from the database. The behaviors of deleting a step before and after activating the cadence are different.
If you delete a step before activating the cadence, when the ActionCadence record is in a Draft
state, the step changes to the Orphaned
state and the ParentStepName
field is nulled. An Orphaned
step is effectively deleted from the cadence, but the ActionCadenceStep record is deleted from the database when the cadence is activated.
When you delete a step in Cadence Builder, the system removes it from the UI, but you can still see it in the database as an Orphaned
step. The step is deleted from the database asynchronously when the cadence is activated. After a step is orphaned, you can’t undo the action.
If you delete a step from a graph after the cadence is activated, the step state is changes to Retired
and the ParentStepName
field is nulled. The step is removed from the UI but kept in the database. After a cadence is active, targets can still be on this step and historical ActionCadenceStepTracker records can be associated with this step, so the system keeps retired steps in the database.
Any active target that’s on a deleted step is removed from the cadence after it completes the step. No option exists for changing the GoToStepName
field through Cadence Builder. In this case, the CompletionReason
in the ActionCadenceTracker record is AutomaticallyExitedDeletedStep
.
Similar to deleting a step before activation, the ParentStepName
field isn’t updated until you save the changes to the cadence. After a step is retired, you can’t undo the action.
You can modify the attributes of a step, such as changing the template on an email step, or you can replace the step by changing the step type. Replacing the step works differently from deleting and adding a step.
If you replace a step in an active cadence, the system determines the next step for the targets on the replaced step differently, depending on whether you simply replace the step or replace it and add a new step immediately after it.
To replace a step in Cadence Builder, change the step’s Type
. Don't delete the step and add a new step. This example replaces a Follow Up Call step with a custom step on an active cadence.
Here, a new ActionCadenceStep record is created for the custom step and the record for the Follow Up Call step updates in these ways.
- The state changes to
Retired
. Active targets can be on this step and step trackers can be associated with this step, so the step isn't deleted from the database. - The
ParentStepName
is nulled. - The
GoToStepName
field is populated with what would’ve been the next step if the step hadn’t been replaced.
If an active target is on the Follow Up Call step when the step is retired, the target finishes the step and goes to the Send Discount Email step.
Let’s take the same example where you change the Follow Up Call step to a custom step using Cadence Builder and add a New Call step after that custom step. In this case, the GoToStepName
of the retired step populates with the next step in the sequence, the New Call step. Active targets on the retired Follow Up Call step complete this step and then go to the New Call step.
When you activate a cadence using the Activate button in , the builder validates the graph structure. All required field values are also checked.
For example, the validation rules check that the graph doesn’t have two consecutive wait steps. This situation doesn’t cause an error in the draft state but fails when you attempt to activate the cadence.
Another validation rule checks that all wait steps have a valid WaitTimeInSeconds
value.
This list isn’t complete. Check the error messages or validation errors.
To stop or pause a cadence, set it to inactive. For example, you can have a Q2 cadence that is used every year in Q2 only. When Q2 ends, you want to set that cadence to inactive until next year. After you set a cadence to inactive, active targets are allowed to finish the cadence, but you can’t add new targets.
Deleting a cadence is a significant decision. You can’t delete an action cadence with any active targets (ActionCadenceTrackers). You must remove or complete all active targets on the action cadence before you can delete it. When you click the Delete button on a cadence record, the system deletes the action cadence and all its historical related records from the database.
- ActionCadence
- ActionCadenceRule
- ActionCadenceRuleCondition
- ActionCadenceStep
- ActionCadenceStepTracker
- ActionCadenceStepVariant
- ActionCadenceTracker
At first, the state of the cadence changes to Deleting
. Related records are deleted asynchronously because the number of records can be large. The state remains Deleting
until all related records are deleted. Next, the ActionCadence record is also deleted. You can no longer perform any queries on the action cadence.