How to use triggers

Triggers are a very powerful feature that allows you, the developer, to trigger an action when a form is inserted or updated.

You can create as many triggers per form as you need for different "events". Events are defined as a match in the Triggers "Initial State Rule" and "Change State Rule". This is simply the value before and after a record is updated. So, if the "Priority" field goes from "hot" to "cold", that would be an example of a initial and change state.

It's worth noting that you can set your triggers to run On Insert and/or On Update. This means you can force a trigger to run when a NEW record is submitted. In this case, the initial state rule is not needed and is not used (there is no initial state for new submissions)

Once a trigger's Rules (Initial State and/or Change State) are matched, the  Trigger Actions and Trigger Action Rules are then executed. Unlike, autoresponders and notification's, Trigger Actions do not have a default profile and ALL of the rules run through to the end.  This enables you to trigger multiple events. It also means that any time you have more than one Trigger Action Profile, you MUST have a rule that triggers the Profile - or it will never run. When you only have one Trigger Action Profile, you do not needs rules, that profile will automatically run.

Often, you will want to create dummy rule. Something like "Where FirstName Does not Equal 'dsfsdfasdfasdfasd'" would be an example of a Dummy rule that you could use to make sure a Trigger Action Profile was run.

Another key concept is the use of hidden fields that are used as flags for the Trigger Action Rules and Profiles. This becomes even more important when you are using a Rescheduled Trigger Action. A rescheduled Trigger Action is simply a Trigger Action Profile that tells the Trigger to run again X number of days later. When the trigger is later invoked by the scheduler, the initial/change state rules are ignored and the engines skips directly to the trigger Action Profiles and Rules.

What this means is that ALL of the rules will be run again. So unless, you have set a flag in your data, the same Trigger Action Profiles would run again. Likely not what you wanted. What you need to do to avoid this is to pay very close attention to the order the rules execute in. Why do you need to pay such close attention to the order the rules execute in? Because you can use the rules in conjunction with hidden fields/flags to control how the processing is done.

Take this example.
1. Create a form with the following 3 fields:
Name
Phone
Comments

2. And these two hidden "control" fields:
Status (Open,Closed,Contacted)
TriggerControl (new,old)

Note: the first option shown above is the default option.

The first time this form is submitted, Status will equal "Open" and TriggerControl will equal "new". This is important to remember.  Now let's imagine, that our trigger is set to process "On Insert" and the change State Rule will be triggered if "Status=Open". This will engage the trigger for ALL new submissions because Status will always be Open..and TriggerControl will always be new.

In order to keep this example simple, lets say all we want to do is call a Trigger Action Profile that will Reschedule an event to run 10 Days later. The event that we want to run 10 days later would be to Send an Email if the Status was still Open. Are you with me so far?

Now, in order to do this we need actually 3 Trigger Action Profiles and 3 Trigger Action Rules. And the rules MUST be sorted in the correct order for this to work. Here are the rules and profiles you would need to accomplish this:

Rule 1 will trigger Profile "Reschedule" (Reschedule Profile)
----------------------------------------------------------------------
"Status=Open and TriggerControl=new"

*this rule will match the first time the form is submitted and call the reschedule Trigger Action Profile

Rule 2 will trigger Profile "Send Email" (Email Profile)
----------------------------------------------------------------------
"Status=Open and TriggerControl=old"

*You might ask, why does this rule come next? Well, because it will NOT match when the form is first submitted because the triggerControl value will be "new".
If it were to match then the email would be sent.


Rule 3 will trigger Profile "Update Trigger Control Flag" (Update Profile)
----------------------------------------------------------------------
"Status=Open and TriggerControl=new"

*This is an important Rule/Profile. It is an "Update" profile and it needs to be set to Update the TriggerControl field to equal "old".  The reason we have to do this is so that when this set of rules run's again (triggered 10 days later via the scheduled event), we do not want  the Reschedule Trigger Action to run again. By updating this flag (which is used specifically for this purpose) we can be sure that the next time these 3 rules are executed there will only be one match. And that match will be the 2nd Rule, the one that sends the email if the Status is still "open".

I hope you can see now why the order of rules is so important. If you moved the 3rd and final rule above Rule Number 2, then the TriggerControl field would be set to "old" and when the "Send Email"  Rule/Profile pair was run it would match! Which is not what we want.

In order to debug the triggers, we highly recommend that you add a field to your form and name it "TriggerDebug". Set the default value to TRUE. This will force the triggers to output some debugging information which can be very helpful when setting up triggers. You will be able to see which rules were matched and which profiles were triggered.