How to create a Java Based Process

From InfiniteERP Wiki
Jump to: navigation, search
Bulbgraph.png   GUI for processes explained in this document is generated using 2.50 infrastructure and are kept for backwards compatibility. If you are working with 3.0MP20 or greater, consider implementing a Standard Process Definition instead.

How to create a Java Based Process

Java processes are one of the mechanisms Openbravo provides to implement business logic. A java process can be a background process or can have a user interface which allows entering parameters. In this howto we will discuss a java process supported with a user interface with parameters.

This document discusses the Openbravo infrastructure for Java processes. For a generic description of java processes see this wiki page: Processes.

Example Module

This howto is supported by an example module which shows example of the code shown and discussed in this howto.

The code of the example module can be downloaded from this mercurial repository: https://code.openbravo.com/erp/mods/org.openbravo.client.application.examples/

The example module is available through the Central Repository (See 'Client Application Examples'), for more information see the Examples Client Application project page.

For your specific development you should create a new module. Please follow the How to create and package a module section to create a new module.

Bulbgraph.png   The example module also contains implementations of other howtos.

Development Steps

The steps to create a java process supported by a user interface are:

  1. create a java class implementing the business logic
  2. enter a new record in 'Report and Process', defining the pattern, the java class (step 1) and the parameters
  3. add the new process to the menu

Java class declaration

First at all, take a look at the Java package in which the java class is defined, it must be included in the java package the module defines. The Java class implementing the process must implement the org.openbravo.scheduling.Process interface, this is done usually extending the class org.openbravo.service.db.DalBaseProcess that provides common code to use DAL in Processes. Extending this class there only needed to overwrite one method:

<source lang="java">

public void doExecute(ProcessBundle bundle) throws Exception;

</source>

This method receives a ProcessBundle, this bundle contains all the parameters for the process. When the process finishes it must add a result to this bundle, this result is an OBError instance that will be shown in the pop-up. For further explanations on messages read the Messages documentation.

Let's explain it using a little example (this class and its parameters are used in the process definition further down in this howto):

<source lang="java">public class ExampleJavaProcess extends DalBaseProcess {

 public void doExecute(ProcessBundle bundle) throws Exception {
   try {
     // retrieve the parameters from the bundle
     final String bPartnerId = (String) bundle.getParams().get("cBpartnerId");
     final String organizationId = (String) bundle.getParams().get("adOrgId");
     final String tabId = (String) bundle.getParams().get("tabId"); 
     final String myString = (String) bundle.getParams().get("mystring");
     // implement your process here
     // Show a result
     final StringBuilder sb = new StringBuilder();
     sb.append("Read information:
"); if (bPartnerId != null) { final BusinessPartner bPartner = OBDal.getInstance().get(BusinessPartner.class, bPartnerId); sb.append("Business Partner: " + bPartner.getIdentifier() + "
"); } if (organizationId != null) { final Organization organization = OBDal.getInstance().get(Organization.class, organizationId); sb.append("Organization: " + organization.getIdentifier() + "
"); } sb.append("MyString: " + myString + "
");
     // OBError is also used for successful results
     final OBError msg = new OBError();
     msg.setType("Success");
     msg.setTitle("Read parameters!");
     msg.setMessage(sb.toString());
     bundle.setResult(msg);
   } catch (final Exception e) {
     e.printStackTrace(System.err);
     final OBError msg = new OBError();
     msg.setType("Error");
     msg.setMessage(e.getMessage());
     msg.setTitle("Error occurred");
     bundle.setResult(msg);
   }
 }

}</source>

In this example a parameter named cBpartnerId is expected. It is read by the following line:

<source lang="java">

 final String bPartnerId = (String) bundle.getParams().get("cBpartnerId");

</source>

The name of the parameter to use in the get method depends on the db column name entered in the parameters of the process (see below).

Once the process is finished a new OBError is created to handle the message and it is added as result to the bundle.

<source lang="java">

 bundle.setResult(msg);

</source>

Defining the user interface

The java class above shows how to implement the backend business logic. This section explains how to define a user interface which makes it possible to enter parameters.

To define process records one should normally be a System Admin.

The first step is to create a process record, go to Application Dictionary > Report and Process (or easier use quick launch and goto the Report and Process window directly). Create a new process record like shown in the example below.


Obexapp CreateProcessRecord.png


The main thing here is to select UI Pattern: Standard. Further below it is explained what UI Pattern Manual means.

Then create a child record in Process Class and enter the fully qualified class name of the java class you created below.

Important: check the default flag! If this is not done then a compile error will occur in the next build step.

Now the parameters of the process need to be defined. Or more exactly their type and visualization. This is done through the Parameter child tab of the process. The example has three parameters: business partner, organization and a string. The screenshots below visualize their settings:


Obexapp CreateProcessParam1.png


Obexapp CreateProcessParam2.png


Some notes:

  • the db column name does not have to be a real database column, the value of this field is used to generate the parameter name used in the source code. It is adviced to use simple names without underscores (that's the simplest).
  • the application element defines the label in the user interface
  • the 2 reference fields denote the type of the field

Add the process form to the menu

To make the process window available to the user it has to be added to a menu. This is done like this:


Obexapp CreateProcessMenu.png


Build Step

After creating the process user interface, stop the application and type in the following command in a console (within the development project): <source lang="bash">ant compile -Dtab=XXX </source>

This will generate the process window.

If you have eclipse running, refresh the development project.

Then start the application and login with the client administrator (normally the system administrator will not have access).

The result

Goto quick launch and enter the name of the new process or find it in the correct location in the menu.


Obexapp CreateProcessResult1.png


Enter some values and press ok. The result:


Obexapp CreateProcessResult2.png

Variant: Running the process from a button in another window

A process can also be run from another window (from a button). A button in an Openbravo window needs a (dummy) database column. To accomplish this do the following:

  • add a column to the table shown in the window
  • give the column the button reference and select the process
  • create a window, tab and field for the column


Obexapp CreateProcessColumn.png


This will show a button on the right in the window.


Obexapp CreateProcessColumnDisplay.png


When a process is run from another window then the ProcessBundle will contain extra default parameters which can be useful:

  • recordID: the id of the selected record
  • tabId: the id of the tab from which the process was called

Variant: Manual UI Pattern

The difference between Standard and Manual UI Pattern is that no pop-up is automatically generated for Manual UI pattern processes, in this case the pop-up must be manually generated by the class implementing the process.

As shown above, java classes for standard processes implement the Manual processes are implemented by a Java class implementing the org.openbravo.scheduling.Process interface. For manual processes the java class needs to extend org.openbravo.base.secureApp.HttpSecureAppServlet, this is a standard servlet that generates the pop-up.