Application triggers

OTF allows developers to setup points of actions within your applications. For example, it could be when an object is saved or deleted. The point is that at some point in time, a notification may be sent when that action happens. These are called application triggers. Think of them as messengers that yell "something happened here," but they are not concerned with what that action triggers down the chain (like sending a text or email), only announcing that some event took place.

By themselves, application triggers don't do anything. However, there is an interface in the administrative part of OTF which allows application admins to setup actions that occur when those triggers are fired. OTF provides actions to send email immediately, queue an email to be sent, or send a text message.

Developing a Trigger

Lets say your app manages a conference, and you want to create an email that is sent every time someone signs up to come to your conference. Typically, you would just create a mail() call and send a message. However, if the content of that message needs to change, you will have to do a code push. Using an application trigger is the easiest way to accomplish this in a future-proof way.

First, we want to replace our outdated mail() call with a trigger. Triggers are dispatched by the Ot_Trigger_Dispatcher object.

$td = new Ot_Trigger_Dispatcher();

Now we want to define what kind of variables may be useful for the trigger. Perhaps we want to include the conference that the user signed up for, their name, and email address. To do that, we assign variables to the trigger dispatcher.

// assign it to the object directly
$td->conferenceName = 'My Conference Name';

// or set an entire array of options
$td->setVariables(array(
    'name' => $name,
    'emailAddress' => $emailAddress,
));

Now we have all the options we want exposed, we dispatch the trigger:

$td->dispatch('My_Trigger_Name');

You can call your trigger anything you want. In this case, I called it 'My_Trigger_Name', but you can be more descriptive if you want. The important thing is that each trigger name should be unique.

Now that we have setup our code to dispatch our trigger, we need to tell the application that our trigger exists. We do this via the EventRegister. You will need to register your triggers in the bootstrap of your application.

public function _initTriggers()
{
    $myTrigger = new Ot_Trigger_Event('My_Trigger_Name', 'My Trigger', 'fired when a person RSVPs for a conference');

Now, we need to tell the register what options we setup in the code. In our case, it is the conference name, users name, and their email address.

$myTrigger->addOption('conferenceName', 'Name of the conference')
           ->addOption('name', 'Name of the user.')
           ->addOption('emailAddress', 'Email address of the user.');

Now, we need to actually register the event:

$register = new Ot_Trigger_EventRegister();
$register->registerTriggerEvents(array($myTrigger));

Now we have done everything we need to do to register an application trigger. The next step is adding an action to happen when the trigger has been dispatched.

Adding an Action

To add an action to the trigger, login to your app and to to App Config -> Application Triggers. There, you should see the trigger you created. Click on it, and you can add multiple actions to be executed when the trigger is dispatched.

By default, OTF comes with 2 actions.

Email Immediately - Uses the Zend_Mail object to send email immediately

Send Via Email Queue - Uses the built-in Email Queue to send email.

When you add an action, you will see all the variables that you registered for the trigger. You can use these variables in any part of the trigger action form and it will be replaced with what is passed to the dispatcher. So you may replace to "To:" part of the email with emailAddress and the "To:" part of the message will now the email address for the user who just signed up for our conference.

Writing your own actions

Any kind of action can be written to take advantage of the trigger system. Perhaps one to post to Twitter, or send a push notification. To do this, you can create your own trigger action type and register them.

Each trigger action type should extend Ot_Trigger_ActionType_Abstract.

They need to be registered in the bootstrap file so that the application knows about them:

public function _initTriggerActionTypes()
{
    $plugins = array();

    $plugins[] = new Ot_Trigger_ActionType_EmailQueue('Ot_Trigger_ActionType_EmailQueue', 'Send email via Queue', 'Sends email using the built-in queue manager');

    $tpr = new Ot_Trigger_ActionTypeRegister();
    $tpr->registerTriggerActionTypes($plugins);
}