Log in / create account
Openbravo.com
Issues
Forge
University
View source | Discuss this page | Page history | Printable version   

Release Management/Customizing the Setup Tool

Release Management/Internal

Index


Contents

Introduction

The Setup Tool is used in Openbravo ERP for doing the initial configuration in custom and development installations. It provides a comfortable user interface to configure the basic files required by Openbravo ERP to be built and to run properly. This includes information like database connection information or a directory for the ERP attachments.


Objective

The Setup Tool offers an easy way for end users to configure all the files required for Openbravo ERP to build and run properly. Currently the files are the following ones:

While all this files contain templates can be copied and configured by hand, it's hard to keep track of all the files that the development team requires users to configure. So the setup tool is always up to date with these changes and provides a simplified way of doing this.

Note that it supports both graphical and command line environments.

General process

The Setup Tool is a binary file that is generated from a XML file. This XML includes a definition of what fields we want to include in each window. And we use a program called BitRock InstallBuilder to build binaries from that XML file. Currently we generate binaries for AIX, FreeBSD (x86 and x86_64), HPUX, Linux (x86, x86_64, IA64 and PPC), OpenBSD, OSX, (open)Solaris (Intel, Sparc) and Windows.

High-level process


Infrastructure setup

The first step to get the environment ready is to install BitRock InstallBuilder. We do not use the latest version of the package, and it is no longer available in the official download website. So ask the Release Management Team to provide you this, if you think you should have it.

Once you have the tar file, uncompress it give it permissions to your everyday user: 

$ cd /opt && tar zxvf /tmp/installbuilder.tgz
$ ln -sf installbuilder-5.4.10 installbuilder
$ chown -R johndoe:johndoe /opt/installbuilder

Add it to the PATH of your everyday user (if you use bash, otherwise do the equivalent in your shell): 

$ echo "export PATH=$PATH:/opt/installbuilder/bin" > /home/johndoe/.bashrc
$ source $HOME/.bashrc

Then check out the setp tool sources, stored in a Subversion repository: 

$ cd $HOME/src/openbravo/erp
$ svn co https://dev.openbravo.com/svn/packaging/setup

XML structure

Now let's analyze the structure of the repository we've just checked out: 

$HOME/src/openbravo/erp/setup
 |
 |-- images/ -> Directory containing some png images used in the binary.
 |-- licenses/ -> Directory containing the license used in a window.
 |-- output/ -> Directory where the binaries are stored. Once committed the ant setup task takes the binaries from this URL.
 |-- setup-properties.xml -> XML file that feeds BitRock InstallBuilder to create the final binaries.

The setup-properties.xml file has the following general structure: 

 
 <project>
 
   <!-- 1. General information about the installer, like the name, the license, dimensions and images -->
   <installationType>update</installationType>
   <shortName>OpenbravoERPsetup</shortName>
   <fullName>Openbravo ERP</fullName>
   <!-- (..) -->
 
   <!-- 2. PreInstallation actions, such as getting the current values from the Openbravo.properties -->
   <preInstallationActionList>
   <!-- (...) -->
   </preInstallationActionList>
 
   <!-- 3. All the screens of the program, marked in the code with the ''paramenterList'' XML tag -->
   <parameterList>
   <!-- (...) -->
   </parameterList>
 
   <!-- 4. PostInstallation actions, such as setting the selected values into Openbravo.properties, log4j.lcf, etc -->
   <postInstallationActionList>
   <!-- (...) -->
   </postInstallationActionList>
 
 </project>

We'll take some lines of config/Openbravo.properties to see what the tool does with them: 

$ cat /some/erp/root/config/Openbravo.properties
(..)
bbdd.rdbms=POSTGRE
bbdd.driver=org.postgresql.Driver
bbdd.url=jdbc:postgresql://localhost:5432
bbdd.sid=openbravo
(..)

First, the tool takes the already selected values of those properties in the preInstallationActionList tag. That is, it detects that bbdd.rdbms is set to POSTGRE so it selects PostgreSQL in combo box when that window appears to the user.

Next, when that window appears (window defined with a parameterList tag) the user can choose between PostgreSQL and Oracle in that combo box.

The final choice is saved in the config/Openbravo.properties when the user confirms it with the final "OK" button in the tool. And this is implemented in the postInstallationActionList tag.


Common controls

In this section we'll see how to implement the different kind of most used controls, such as a text box, a combo box, etc.

Text box

Use the stringParameter tag for this. Example: 

 
<stringParameter>
  <name>contextname</name>
  <description>Context name</description>
  <allowEmptyValue>1</allowEmptyValue>
  <width>40</width>
</stringParameter>


Text box example

Directory selection box

Use the directoryParameter tag for this. Example: 

 
<directoryParameter>
  <name>attachpath</name>
  <description>Attachments directory</description>
  <allowEmptyValue>1</allowEmptyValue>
  <width>40</width>
</directoryParameter>


Directory box example after clicking on the directory icon

Combo box

Use the choiceParameter tag for this. Example: 

 
<choiceParameter>
  <name>dateformat</name>
  <title>Date format</title>
  <description>Date format</description>
  <default>DD_MM_YYYY</default>
  <optionList>
    <option>
      <text>DD MM YYYY</text>
      <value>DDMMYYYY</value>
    </option>
  <option>
    <text>MM DD YYYY</text>
    <value>MMDDYYYY</value>
  </option>
  <option>
    <text>YYYY MM DD</text>
    <value>YYYYMMDD</value>
  </option>
  </optionList>
</choiceParameter>


Combo box example, not expanded

Radio buttons

Use the choiceParameter tag with the radiobuttons value in the displayType tag for this. Example: 

 
<choiceParameter>
  <name>bbddrdbms</name>
  <description>Please select a database</description>
  <allowEmptyValue>1</allowEmptyValue>
  <ask>1</ask>
  <width>40</width>
  <optionList>
    <option text="Oracle" value="ORACLE"/>
    <option text="PostgreSQL" value="POSTGRE"/>
  </optionList>
  <displayType>radiobuttons</displayType>
</choiceParameter>


Radio buttons example

Common actions

Get/Set values of variables from Java properties files

Openbravo ERP uses the Java property format for both config/Openbravo.properties and config/log4j.lcf. So we mostly want to read the values of the properties and change them to other values.

To get the value of a property and store it in a variable, in this case we'll take the attach.path property and save its value in the attachpath variable (BitRock internal variable): 

 
<propertiesFileGet>
  <file>Openbravo.properties</file>
  <key>attach.path</key>
  <variable>attachpath</variable>
  <abortOnError>0</abortOnError>
</propertiesFileGet>

We mostly do this property retrievals in the preInstallationActionList tag.

Now imagine that the attachpath variable has been selected by the user using a directory box. To set its value back to the property file: 

 
<propertiesFileSet>
  <file>Openbravo.properties</file>
  <key>attach.path</key>
  <value>${attachpath}</value>
</propertiesFileSet>

Validations

In some situations it is very valuable to validate if the input given by the users makes sense in the given control. For example, if we have a text box that asks for the port number of the database server, it does not make sense for the user to enter non-numerical or empty values. For this purpose we can use validations.

As an example: 

 
<validationActionList>
  <throwError>
    <text>Please enter a valid port</text>
    <ruleEvaluationLogic>and</ruleEvaluationLogic>
    <ruleList>
      <regExMatch text="${ora_bbddport}" logic="does_not_match" pattern="^[0-9]*$"/>
      <compareText logic="does_not_equal" text="${ora_bbddport}" value=""/>
    </ruleList>
  </throwError>
</validationActionList>


Validation example


Build and publish binaries

To build a binary for a specific platform (example: linux): 

$ cd $HOME/src/openbravo/erp/setup
$ /opt/installbuilder/bin/builder build setup-properties.xml linux

We recommend adding the following script somewhere your PATH (e.g. $HOME/bin/bitrock-installer-rebuild.sh), which will make your life easier to create the binaries for all the platforms: 

 
#!/bin/sh
 
xmlfile=$1
 
if [ ! -f $xmlfile ]; then
  echo 'File does not exist.'
  exit 1
fi
 
shift
 
if [ $# -eq 0 ]; then
  archs='linux windows linux-x64 linux-ia64 osx solaris-sparc solaris-intel linux-ppc freebsd6 freebsd6-x64 openbsd3 hpux aix'
else
  archs=$*
fi
 
for i in $archs;
do
  /opt/installbuilder/bin/builder build $xmlfile $i
done

For testing purposes it is useful just to build one binary for your own system: 

$ bitrock-installer-rebuild.sh $HOME/src/openbravo/erp/setup/setup-properties.xml linux

So once you are happy with the results, to build all the installers: 

$ bitrock-installer-rebuild.sh $HOME/src/openbravo/erp/setup/setup-properties.xml

The results are stored in /opt/installbuilder/output/

For OSX it creates a directory, so we need to compress it: 

$ rm -f $HOME/src/openbravo/erp/setup/output/*
$ cp -r /opt/installbuilder/output/setup* $HOME/src/openbravo/erp/setup/output/
$ cd $HOME/src/openbravo/erp/setup/output/
$ tar zcvf setup-properties-osx.app.tar.gz setup-properties-osx.app
$ rm -rf setup-properties-osx.app

To publish the files, just commit the files to the Subversion repository: 

$ cd $HOME/src/openbravo/erp/setup/
$ svn ci -m "Update the setup binaries with x and y"

References

Retrieved from "http://wiki.openbravo.com/wiki/Release_Management/Customizing_the_Setup_Tool"

This page has been accessed 5,944 times. This page was last modified on 2 February 2010, at 07:32. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.