Sitecore Engagement Plans: A Note About Adding Visitors and Timeout Triggers

Tuesday, July 28, 2015 @ 03:38

By James Kiel

We recently developed a project in Sitecore 7.2 that involves visitors submitting a form and receiving a follow up email 1 week later.

Using the following engagement plan, the form would enroll a visitor into the "Form Submitted" state that contained a 7 day timeout trigger. Our plan was that after 7 days, Sitecore would evaluate the visitor to the "Follow Up Email Sent" state and send the email:

Plan one

 

Using Sitecore's VisitorManager in the form's backend code, we were able to successfully enroll the visitor:

    
        using Sitecore.Analytics.Automation;
        ...
        public void AddUserToEngagementPlan(string user, Item engagementPlanState)
        {
             VisitorManager.AddVisitor(user, engagementPlanState.ID);
         }
    

 

However, something unexpected happened. Sitecore would not honor the "Form Submitted" state's 7 day timeout trigger. Instead, the visitor immediately moved to the "Follow Up Email Sent" state and received the email message that was supposed to be sent 7 days later.

Why wasn't Sitecore honoring the timeout trigger?

Investigating deeper, we took a look at the database.

Sitecore's Analytics database contains an "AutomationStates" table that keeps a record for every visitor in every engagement plan state. By querying this table, we found our visitor in the engagement plan:

Database one

 

Two fields in the table caught our attention:

  • LastAccessedDateTime: Stores the time when Sitecore last evaluated the visitor
  • WakeupDateTime: Stores the time when Sitecore should next evaluate the visitor. Sitecore calculates this by adding the state's timeout trigger to the "LastAccessedDateTime" value

 

Now that the visitor was in the "Follow Up Email Sent" state, which contains no next steps and no timeout trigger, the "WakeupDateTime" had the max value of "2100-12-31 00:00:00.000". We understood this to mean "do not evaluate this visitor anymore."

We removed the visitor from the engagement plan and tried another form submission. Immediately after submitting and subsequently re-enrolling the visitor, we queried the database again:

Database two

 

Sitecore successfully enrolled the visitor to the "Form Submitted" state. However, the visitor’s “WakeupDateTime” incorrectly contained the same value as “LastAccessedDateTime.” The expected behavior was to have it be 1 week in the future.

It turns out VisitorManager.AddVisitor will enroll a visitor, but it will not apply a state’s timeout trigger to the visitor's next wake up time. This causes the visitor to evaluate on the next update cycle regardless of timeout triggers.

As a workaround, we modified the engagement plan to include a pending state:

Plan two

 

Now when visitors submit the form, they get added to a state that does not contain a timeout trigger. Sitecore immediately evaluates the visitors to the "Follow Up Email Pending" state, and in doing so properly calculates their wake up time of 7 days later:

Database three