Oracle BPM 10.3 Ant Libraries - Reference Documentation

Apache Ant is a platform-independent (Java-based) build tool. It is useful for automating repetitive tasks and is well suited for implementing standardized build and deployment processes.

Ant's XML syntax is extensible. Oracle BPM extends Ant to automate BPM-specific tasks.

For general documentation about Apache Ant refer to its official website and online manual.

Running Oracle BPM Ant scripts

The Oracle BPM Ant tasks require Ant 1.6.5 or newer. They rely on the namespace and antlib features introduced in Ant version 1.6.

Oracle BPM Ant .jar libraries

To use Oracle BPM Ant Libraries you must pass the -lib option to Ant specifying the full path to the Oracle BPM lib/ and ext/ directories. Example:

 On Unix:
 ant -lib /OraBPMEnterpriseHome/lib:/OraBPMEnterpriseHome/ext

 On Windows:
 ant -lib c:\OraBPMEnterpriseHome\lib;c:\OraBPMEnterpriseHome\ext

To avoid using the -lib argument every time, you can specify it once using the ANT_ARGS environment variable: 

 On Unix:
 ANT_ARGS="-lib /OraBPMEnterpriseHome/lib:/OraBPMEnterpriseHome/ext"
 export ANT_ARGS

 On Windows:
 set ANT_ARGS=-lib c:\OraBPMEnterpriseHome\lib;c:\OraBPMEnterpriseHome\ext

Writing Oracle BPM Ant scripts

Namespace declaration

Your Ant scripts must include the Oracle BPM antlib in their project definition: 

<project name="OracleBPMExample"
         xmlns:fuego="antlib:fuego.tools.ant.enterprise"
         xmlns:fuego.j2ee="antlib:fuego.tools.ant.j2ee">
 ...
</project>

The previous example defines the fuego namespace for accessing the standard Oracle BPM library of tasks and fuego.j2ee for those tasks specific to the J2EE edition of Oracle BPM.

Every reference to a task provided by Oracle BPM will be prefixed by either "fuego:" (general tasks) or "fuego.j2ee:" (J2EE-specific tasks). The following ant script snippet uses the publish and buildear tasks: 

<project name="OracleBPMExample" xmlns:fuego="antlib:fuego.tools.ant.enterprise">
 ...
  <target name="publish">
    ...
    <!-- Publish a process -->
    <fuego:publish fpr="myproject.fpr">
      ...
    </fuego:publish>

    <fuego.j2ee:buildear ...
      ...

    </fuego.j2ee:buildear>
  </target>
 ...
</project>

Setting fuego.basedir

Your build script must define the fuego.basedir property. The value of this property must be the full path to your Oracle BPM Enterprise installation directory. Example: 

<project name="OracleBPMExample" xmlns:fuego="antlib:fuego.tools.ant.enterprise">

  <property name="fuego.basedir"
           value="/OraBPMEnterpriseHome"/>
 ...
</project>

Example 1: Publish a BPM Project

The following example represents a small but complete Ant script that uses Oracle BPM tasks.

The example script publishes and deploys an Oracle BPM project using the following tasks and types:

Fuego:publish is the task that allows for publishing and deploying processes. As for any other task that needs access to a BPM directory, you must enclose it within a fuego:session task.

A fuego:passport defines the authentication information needed to access a particular BPM directory. The fuego:session task accepts a passport reference to establish a session to the directory. 

<!-- This script publishes and deploys a BPM Project. -->
<project name="OracleBPMExample" xmlns:fuego="antlib:fuego.tools.ant.enterprise">

  <!-- Include properties -->
  <property file="build.properties"/>

  <!-- Define an Oracle BPM Directory passport -->
  <fuego:passport id="fuego.passport"
         directoryid="default"
            preset="engine" />

  <target name="publish" description="Publish and deploy processes">

  <!-- Open a session to the Oracle BPM directory -->
    <fuego:session
          passportref="fuego.passport"
              verbose="true"
          haltonerror="true" >

      <!-- Publish processes -->
      <fuego:publish fpr="${fuego.project}"
                  deploy="true"
                  engine="${fuego.engine}">

        <fuego:rolemap abstract="Employee" real="Role1"/>
        <fuego:rolemap abstract="Idea Evaluator" real="Role1"/>
      </fuego:publish>
    </fuego:session>

  </target>

</project>

The example includes properties from another file: build.properties. Keeping the values that are likely to change in a separate properties file is a good practice to follow, since it allows for easy parameterization of the script.

This is a build.properties file suitable for the above example: 

# Oracle BPM Enterprise installation directory
fuego.basedir=/OraBPMEnterpriseHome

# Name of Oracle BPM Engine to deploy to
fuego.engine=Standalone

# Project to deploy
fuego.project=/tmp/ExpenseManagement

Note: The publishing process can take-up a large amount of memory. If you get an OutOfMemoryException you need to increase the JVM's memory heap that the ant task uses. You can do this using the external variable ANT_OPTS. The following command shows you how to set the value of the ANT_OPTS external variable: export ANT_OPTS=-Xmx1024m

Example 2: Configure a BPM environment

Oracle BPM includes a complete example Ant script. Locate the example at <ORABPM_HOME>/samples/interop/AntTasks.

This example script automates the following tasks:

It also shows a simple scheme to handle the configuration of multiple environments.

For details on how to run the example refer to the included README.txt.

© 2008 Oracle Corporation