User Triggers

In the (upcoming) 4.2 release of iHRIS, you can now trigger messages to users. As an administrator, you can link a trigger to a user and they will be notified when the trigger is called depending on the trigger configuration.

For any triggers that you want to send that are based on hooks, you can simply define that hook in your custom module and call the trigger.

Enable the Module

You will need to enable the UserTriggers module. You can do this from the Configure System page under Configure Modules. It will be under iHRIS Common. You can also add the requirement to your site configuration as follows:

<source lang="xml"> <requirement name="UserTriggers">

 <atLeast version="4.2" />
 <lessThan version="4.3" />

</requirement> </source>

Advanced users can also enable the modules from a terminal by running the following command from your pages directory:

<source lang="bash"> php index.php --update=1 --enable=UserTriggers </source>

You will need to restart memcached and your server after doing this from the command line to refresh the APC.

<source lang="bash"> sudo service memcached restart sudo service apache2 restart </source>

Defining a Trigger

The first step is to define your new trigger. Once defined, you can link the trigger with a user so they will be notified when the trigger is called.

Translatable Messages

Messages you want to be translatable can be configured under /modules/UserTriggers/triggers. This allows you to just pass the required message key to the trigger method and it will pull out a translated messaged depending on the settings of the user that causes the trigger. You can also define some other default messages here, for example default_email_subject is used for the email handler. You can define these messages in your module with the following. (Note: The default email subject also appends the display name of the trigger to the subject.)

<source lang="xml">

   <configurationGroup name="messages" path="/modules/UserTriggers/messages" locale="en_US">
     <configuration name="default_email_subject">
       <value>Automated email for: </value>
     </configuration>
   </configurationGroup>

</source>

Configuration a Trigger

Triggers are defined in magic data under /modules/UserTriggers/triggers. There are currently three types of handlers available: alert, email, hook. Arguments can be customized depending on the handler in the configuration or when the trigger is called. Each trigger can enable any of these handlers that are desired so some triggers may only sent alerts, some only email and some may send both. See #Hook Handler for a more advanced way to notify your users.

The structure of a trigger configuration is as follows:

• $trigger: [array] This is what you will use to call the trigger when desired.
  • display: [string] This is the value of the display name of the trigger. It should be set with a locale so it can be translated.
  • handler: [array] The enabled handlers for this trigger.
    • alert: [true|false] This is a boolean if you want to enable the alert handler for this trigger.
    • email: [true|false] This is a boolean if you want to enable the email handler for this trigger.
    • hook: [true|false] This is a boolean if you want to enable the hook handler for this trigger.
  • message: [array] The default messages for this trigger.
    • prefix: [string] Any text you want prepended to the triggered message.
    • suffix: [string] Any text you want appended to the triggered message.
    • link: [url] A default URL to be sent with the message. It may be overridden by the trigger call.
    • link_text: [string] The text to go along with the link. It may be overridden by the trigger call.
  • args: [array] Any arguments to pass along to the handlers.
    • alert: [array] Any custom alert arguments.
      • alert_type: [notice|problem] Set the alert type for this trigger. The default is notice.
    • email: [array] Any custom email arguments.
      • subject: [string] You can override the default email subject for this handler.
    • hook: [array] Any custom hook arguments.
      • hooks: [array] The list of hooks to be called.
        • 0: [string] The hook to be called.

An example trigger may be defined in your module as follows:

<source lang="xml"> <configurationGroup name="my_trigger" path="/modules/UserTriggers/triggers/my_trigger">

 <configuration name="display" locale="en_US">
   <value>My Trigger</value>
 </configuration>
 <configurationGroup name="handler">
   <configuration name="alert" type="boolean">
     <value>true</value>
   </configuration>
   <configuration name="email" type="boolean">
     <value>true</value>
   </configuration>
 </configurationGroup>
 <configurationGroup name="message">
   <configuration name="prefix" locale="en_US">
     <value>This is my trigger: </value>
   </configuration>
   <configuration name="link">
     <value>http://demo.ihris.org/iHRIS/Manage/</value>
   </configuration>
   <configuration name="link_text" locale="en_US">
     <value>iHRIS Manage Demo</value>
   </configuration>
 </configurationGroup>
 <configurationGroup name="args">
   <configurationGroup name="email">
     <configuration name="subject" locale="en_US">
       <value>My Custom Subject</value>
     </configuration>
   </congurationGroup>
   <configurationGroup name="alert">
     <configuration name="alert_type">
       <value>problem</value>
     </configuration>
   </configurationGroup>
 </configurationGroup>

</configurationGroup> </source>

Advanced Customization

Trigger Handlers

There are currently three types of handlers available: alert, email, hook. The hook option is there so you can more easily customize what happens with the trigger, but you can also add additional handlers under /modules/UserTriggers/handlers. You can also add more function calls to an existing handler so both would be called when the trigger uses the given handler.

The default handlers are defined in the module as:

<source lang="xml">

   <configurationGroup name="handlers">
     <configuration name="email" type="delimited">
       <value>UserTriggers:triggerEmail</value>
     </configuration>
     <configuration name="hook" type="delimited">
       <value>UserTriggers:triggerHook</value>
     </configuration>
   </configurationGroup>

</source>

Additionally, the User Alerts module adds the following handler: <source lang="xml">

   <configuration name="Triggers" path="/modules/UserTriggers/handlers/alert" type="delimited">
     <value>UserAlerts:triggerAlert</value>
   </configuration>

</source>

What these mean is that when the email handler is enabled for a trigger, then the method triggerEmail will be called on the UserTriggers module class. So if you defined a new module that could handle SMS, you could add an SMS handler and set up your own trigger method.

All the trigger handler methods must be defined to accept the following arguments:

<source lang="php">

   /**
    * Handler method for triggers
    * @param string $username The username to be notified
    * @param string $trigger The trigger being called
    * @param string $message The message to send
    * @param string $link The optional link to include
    * @param string $link_text The link text for the link
    * @param array $args Any option arguments for this trigger handler
    * @return boolean
    */
   public function triggerMethod( $username, $trigger, $message, $link=false, $link_text=, $args=array() ) {
   }

</source>

Hook Handler

If you want to have a custom trigger without having to create a new handler, you can use the hook handler and then define a custom hook for your notification. You first define the hooks to be called in the trigger arguments or it can be overridden by the trigger call if desired. The hook will be passed the same arguments as the triggerMethod above.