Working with Forms in Kentico Marketing Automation – Part 2

In Part 1 of this series, I showed you how you could easily create a form and implement a simple Marketing Automation process to execute when a user submits their information. While this is great and uses all out-of-the-box features, I wanted to show more advanced functionality you can implement to make the process even better. Specifically, I will show how you can leverage a custom macro and some reserved resource names within your process to execute specific steps of your process conditionally, based on the form data submitted.

You can read Part 1 of the series here.

Note: While it is possible to create this functionality using a global event handler on the form submission, I want to demonstrate how EMS can provide the same capabilities.

Understanding  the ActivtyItemID and ActivityDetailItemID Values

Every Marketing Automation process gets passed a number of values when it is initiated, depending on the type of activity that triggered the process. Many of these are used for internal purposes, allowing Kentico to keep track of the process and log it accordingly. These values are often denoted with a reserved resource name, which will identify the value throughout the system.

For the Form Submission activity, there are two reserved resource names that are particularly useful: ActivityItemID and ActivityDetailItemID. These two values contain the submitting form ID and the newly inserted form record ID. By leveraging these two values, I can access the underlying form data to perform my validation.

Creating a Custom Macro

The first step of the process is to create a custom macro namespace and method for my logic. This method can be used to validate the value of the field for the specified form record.

You can learn more about adding custom macro namespaces and methods here.

For my method, I wanted to accept specific values to get the data I needed. The return value will be a True/False flag, indicating if the form record field matches the specified value.

[MacroMethod(typeof(bool), "Returns whether the form field matches the expected value.", 1)]
[MacroMethodParam(0, "ActivityID", typeof(int), "Form ID")]
[MacroMethodParam(1, "ActivityDetailID", typeof(int), "Form record ID")]
[MacroMethodParam(2, "ColumnName", typeof(string), "Form column")]
[MacroMethodParam(3, "ColumnValue", typeof(string), "Expected column value")]

Activity ID
Specifies the form to retrieve

ActivityDetailID
Specifies the form record to retrieve

ColumnName
Specifies the column to validate

ColumnValue
Specifies the expected column value

The macro will require each of these values to be passed in order to validate the form field value. With those four values, I retrieved the form and the form record, and I validated the specified field with the expected value.

Adding a Multi-Choice Step

Once the macro method was created, I was ready to add my conditional logic to the Marketing Automation process.  In my process, I added a Multi-Choice step, which allowed me to evaluate the submitted form values.

For each condition, I evaluated the SubmissionStatus field, determining if it had been Approved, Rejected, or other.  In each condition of the step, I used the custom macro method to validate the value, passing the ActivityItemID and ActivityItemDetailID values. The idea is that each status will lead to a different step of the process, allowing it to be conditional on the form data. The Approved and Rejected statuses will send an email. The Else condition will then enter a Wait step for one day and try the process again.

Here is the macro condition code for Approved form submissions, for clarity:

(CustomMacroNamespace.CheckFormFieldValue(AutomationState.StateCustomData["TriggerDataActivityItemId"], AutomationState.StateCustomData["TriggerDataActivityItemDetailId"],"SubmissionStatus", "Approved") == true)

Note how the ActivityItemID and ActivityDetailItemID values can be accessed using the AutomationState.StateCustomData collection. This is where the values are stored when the process is initiated.

Configuring Personalized Emails

With the conditional logic in place, I added a Send an email step for Approved and Rejected submissions. Once the email steps execute, the process will be finished.

For the Approved submissions, I configured the Send approved email step to send the appropriate email. Note that I used the Contact.ContactEmail value to set the recipient dynamically to the user that submitted the form.

I then repeated the process for the Rejected submissions.

Testing

With the custom functionality in place, I was ready to test the process. I submitted a new form within the site.

I confirmed the activity initiated the process by viewing the Contacts tab within the process. Because the form submission had not been Approved or Rejected, the process immediately went to the Wait 1 Day step.

I then updated the form to Approved in the Forms module.

After the Wait 1 Day step had been completed, the process attempted to evaluate the SubmissionStatus field, using the Multi-Choice step. Because the submission was Approved, the Send approval email step executed and created the email.

Once the Send approved email step completed, the process was Finished.

I then submitted another phrase, this time setting the status to Rejected.

I confirmed the Send rejected email step process executed and the process completed.

Moving Forward

In this blog series, I demonstrated how you could leverage reserved resource names within your Marketing Automation processes to build out dynamic steps and functionality. By using a custom macro, you can format and store your code in a reusable format that can be used throughout your site. By using EMS and custom macros within your Kentico sites, you can automate many aspects of the system and simplify your business processes. Good luck!