Unica Plan Integration Services basics

You use Unica Plan Integration Services to create custom procedures. You can use these procedures to trigger external events when certain events occur within Unica Plan. You can use these procedures to run Unica Plan functions from external systems or programs.

The API interface interacts with Unica Plan at the programmatic level, in the same way the GUI interfaces with Unica Plan at a user level. Using the API, you construct procedures. Using these procedures, you communicate between Unica Plan and external systems. The Unica Plan Webservice is the container object for the procedures, API, and triggers.

The architecture of the Unica Plan Integration Services is shown here.


Integration Services communicating with each other, and with external systems

The following are key components of the Integration Services.

  • Unica Plan Procedure Manager: extends the business logic by interacting with Unica Plan through the API.
  • Unica Plan Trigger Manager: associates a condition (for example, the state change of a marketing object) with an action (a procedure to run when the condition for the trigger is met).

Methods

You use the components of Unica Plan Integration Services to develop custom procedures, as shown in the following diagram.


Programmer uses the Unica Plan Installer, Java IDE, and Application Server

After you install the developer's kit, you follow these basic steps:

  1. Code the custom procedure.
  2. Update the plug-in definition in the XML definition file.
  3. Build the plug-in:
    1. Compile the necessary classes.
    2. If you are using a third-party library that is not in the Unica Plan archive, bundle the library inside the plan.war file and redeploy.
  4. Restart Unica Plan. Changes to the procedure classes are applied when you restart the application server.
    Note: If you change the plan.war file, you must undeploy and redeploy Unica Plan with the new plan.war file. Undeploy and redeploy Unica Plan if you use a third-party library that is not in the Unica Plan archive and you edit the plan.war file.

Basic Example to communicate between Unica Plan and the API

The following basic example describes establishing communication between the API and Unica Plan. It does not do any useful work; it performs a round trip between Unica Plan and the Integration Services.

This example uses portions of the example procedures included with the Unica Plan Integration Services developer's kit. Specifically, you can find the code that is referenced here in the following files.

  • PlanClientFacade.java
  • PlanWSNOOPTestCase.java

The noop method is a webservice call to Unica Plan. It is defined in the PlanClientFacade class, and passes null values in an array.

public ProcedureResponse noop(String jobId) 
  throws RemoteException, ServiceException {
  NameValueArrays parameters =
    new NameValueArrays(null, null, null, null, null, null, null, null); 
  return _serviceBinding.executeProcedure("uapNOOPProcedure", jobId, parameters);
}

The procedure testExecuteProcedure calls the noop method from PlanClientFacade to establish a round trip with the Unica Plan application.

public void testExecuteProcedure() throws Exception {
  // Time out after a minute
  int timeout = 60000;
  PlanClientFacade clientFacade = new PlanClientFacade(urlWebService, timeout);
  System.out.println("noop w/no parameters");
  long startTime = new Date().getTime();
  ProcedureResponse response = clientFacade.noop("junit-jobid");
  long duration = new Date().getTime() - startTime;

  // zero or positive status => success
  System.out.println("Status: " + response.getStatus());
  System.out.println("Duration: " + duration + " ms");
  assertTrue(response.getStatus() >= 0);
  System.out.println("Done.");
}

For details of NameValueArrays, ProcedureResponse, and other listed methods and data types, refer to the Unica Plan Integration Module and the JavaDocs.