Miscellaneous Ramblings on Hacking

September 27, 2011

Getting Started: Unica Marketing Operations’ Custom Triggers

Filed under: Uncategorized — Zack Bethem @ 2:52 pm

You have the SDK. You have the JavaDocs. There are samples, but how does it all glue together? This post is all about writing your first UMO custom trigger. These triggers help to automate tasks or enforce business rules within UMO.

What you Need?

A few needed items:

  • Unica Marketing Operations (UMO) environment
  • Eclipse IDE for EE
  • Associated JARs: affinium_plan.jar, log4j.jar

The JARs are best grabbed from the UMO environment.

Start Eclipse & Code

Startup Eclipse and create a new Application Client Project. This project template option is available under the Java EE folder.

Capture2

Set the JDK to the same level as the web application server that UMO is deployed on. I selected 5.0 for JDK 1.5.

Here I define my AutoReviewerAssignment class. All triggers are required to implement the IProcedure interface.

   1:  

   2: public class AutoReviewerAssignment implements IProcedure {

   3:  

   4:     // The Name and Description of this Procedure.

   5:     private static final String name           = "AutoReviewerAssignment";

   6:     private static final String desc           = "Provides automatic assignment of reviewers based on project member assignment";

   7:     private static final PluginVersion pv        = new PluginVersion(1, 0, 0); 

   8:       

   9:     // Constants

  10:     private static final String DEBUG          = "debug";

  11:     private static final int    STATUS_SUCCESS = 0;

  12:     private static final int    STATUS_FAILED  = -1;

  13:     

Unica products use Log4J for all system logging. There are a couple of products in the Unica suite that don’t, but it’s a safe bet that log4j is being used. For UMO, it is. I’m getting the logger and setting it to a static variable. This way I can add my own class’ log entries to the main log file.

   1: //added - latch on to the log4j logger

   2:     private static final Logger _LOG = Logger.getLogger(AutoReviewerAssignment.class);

   3:     

The interface defines some standard methods, the first of importance is the initialize() method. This is your time to grab some site specific parameters. In some cases, I’ve grabbed from a standard Java .properties file. But Unica also provides the ability to define these parameters in the actual procedure definition file  where the procedure is declared (more on this later).

   1: public void initialize(Map initParams) throws PluginInitializationException {

   2:         // TODO Auto-generated method stub

   3:         _LOG.info("Initializing class trigger procedure..");

   4:         

   5:         //only expecting one init parameter

   6:         if(initParams.containsKey(DEBUG))

   7:         {

   8:             try{

   9:                 isDebug = ((Boolean) initParams.get(DEBUG)).booleanValue();

  10:                 _LOG.debug("Debug mode is enabled: " + String.valueOf(isDebug));

  11:             } catch(Exception e)

  12:             {

  13:                 _LOG.fatal("Exception in initialization. "+ e.getMessage());

  14:                 throw new ProcedureInitializationException("Problem using init parameter: DEBUG");

  15:             }

  16:         }

  17:     }

Finally, there’s the execute method. This is where the action happens and is unique to your own implementation goals.

Configuration Deployment

Once compiled, it’s time to migrate the compiled class file for your procedure. Here’s the steps:

  • Review the [PLAN_HOME]\conf\plan_config.xml to ascertain the environment’s configuration. We’re looking for the following UAPInitParams: integrationProcedureDefinitionPath and integrationProcedureClasspathURL
  • integrationProcedureDefinitionPath points to a procedure_plugins.xml file. This file defines the class, including the initialization parameters. Here’s an example:
   1: <procedure>

   2:     <key>POCtest</key>

   3:     <class-name>com.amberleaf.procedure.POCtest</class-name>

   4:     <init-parameters>

   5:     <init-parameter>

   6:       <param-name>debug</param-name>

   7:       <param-type>java.lang.Boolean</param-type>

   8:             <param-value>true</param-value>

   9:     </init-parameter>

  10:     </init-parameters>

  11: </procedure>

  • integrationProcedureClasspathURL points to the directory where the resulting class file should be placed
  • Finally, bounce the web application server so that the new class can be cached

Now that the environment is setup, it’s time to define the actual trigger. This defines when the trigger should actually fire within Unica Marketing Operations. To do this, we go to: Settings > Marketing Operations Settings > Trigger Bindings.

  • Click ‘Add New Trigger Binding’
  • Define the trigger with the appropriate attributes:

Capture

For example, my trigger would be limited to the ‘Project’ marketing object. The trigger would be limited to the context of ‘People’. Put another way, the trigger would be limited to the ‘People’ tab under the ‘Project’ object. I then further limit the trigger to only execute on the ‘Updated’ event. In summary, the trigger will fire when the ‘People’ tab of a ‘Project’ is ‘Updated’.

And there you have it. You’ve created your first trigger. A special note here. Since we latched on to the log4j logger of Unica’s, we will see our logging entries in the Unica Marketing Operation’s system log. Just be sure to set your log4j logging level appropriately.

Blog at WordPress.com.