Skip to main content

Mavenization of OpenESB Projects for Continuous Integration

1. 1. Document Objective​

This document describes the recommended process for mavenizing an existing OpenESB project, with the objective of:

  • Standardizing project structure

  • Enabling reproducible builds

  • Facilitating Continuous Integration (CI) in tools such as Jenkins, GitLab CI, or Bitbucket Pipelines

  • Eliminating dependencies on the NetBeans environment for artifact generation

2. General Approach​

The mavenization strategy is based on:

  • Using Maven as the build system

  • Adopting standard archetypes compatible with OpenESB

  • Progressively migrating existing projects to a Maven structure

  • Enabling automatic packaging of:

    • BPEL Service Units (SU)

    • WSDL/XSD catalogs

    • Composite Applications (CA)

This approach completely decouples the build process from the IDE and enables real Continuous Integration.

3. Available Maven Archetypes​

Currently, there are 4 official archetypes available, covering the different roles of modules within an OpenESB solution.

3.1 soa-bpel-module-archetype​

<![CDATA[<groupId>com.vico.openesb.studio</groupId>
<artifactId>soa-bpel-module-archetype</artifactId>
<version>2.0</version>]]>

Self-contained BPEL processes that do not depend on other modules for contract definitions. Most existing projects fall into this category.

Typical Use Cases​

  • Legacy processes with local or remotely referenced WSDL/XSD

  • BPEL modules that do not share contracts with other modules

  • Initial migrations from existing NetBeans projects

  • Simple cases where fast and direct mavenization is desired

Features​

  • Includes WSDL and XSD within the module itself

  • Fully autonomous build

  • Suitable as a first mavenization step

3.2 soa-bpel-module-catalog-archetype​

<![CDATA[<groupId>com.vico.openesb.studio</groupId>
<artifactId>soa-bpel-module-catalog-archetype</artifactId>
<version>2.0</version>]]>

Provider BPEL modules responsible for defining and publishing reusable contracts.

Typical Use Cases​

  • Core services

  • Shared public WSDLs

  • Platform entry points

Features​

  • Manages a WSDL/XSD catalog

  • Allows controlled contract versioning

  • Other modules can depend on this catalog

  • Avoids schema duplication

  • Enables a single update point for schemas

3.3 soa-bpel-module-catalog-consumer-archetype​

<![CDATA[<groupId>com.vico.openesb.studio</groupId>
<artifactId>soa-bpel-module-catalog-consumer-archetype</artifactId>
<version>2.0</version>]]>

Consumer BPEL modules that use contracts defined in one or more catalogs.

Typical Use Cases​

  • BPEL processes that consume services and use a catalog module to obtain schemas and WSDLs

  • Integrations with corporate services

  • Orchestrators that do not publish their own contracts

Features​

  • Does not define public WSDLs

  • Consumes catalogs using the maven-dependency-plugin

  • Eliminates local copies of WSDL/XSD (they are generated temporarily during the build)

3.4 soa-composite-application-archetype​

<![CDATA[<groupId>com.vico.openesb.studio</groupId>
<artifactId>soa-composite-application-archetype</artifactId>
<version>2.0</version>]]>

Composite Application (CA) responsible for grouping and assembling the actual modules.

Typical Use Cases​

  • Final deployment artifact

  • Explicit dependency definition

  • Deployment automation

Features​

  • Declares dependencies on BPEL and other Service Units

  • It is the only artifact deployed into OpenESB

  • Enables deterministic builds without NetBeans

4. Strategy and Steps for Mavenizing OpenESB Projects​

The mavenization of an OpenESB project should be approached as a structured and repeatable process, consisting of a series of well-defined technical steps depending on the architecture of your projects.

This approach guarantees reproducible builds and enables Continuous Integration.

4.1 Environment Preconfiguration (Mandatory)​

Before mavenizing any BPEL or Composite Application, it is essential to correctly configure the developer's local environment.

4.1.1 Maven Configuration​

Configure the Maven settings.xml file to allow access to the private repository containing archetypes and dependencies:

<![CDATA[https://nexus.vico.org/repository/openesb-premium-releases/]]>

Example configuration:

<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="https://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="https://maven.apache.org/SETTINGS/1.2.0
                              https://maven.apache.org/xsd/settings-1.2.0.xsd">

  <servers>
    <server>
      <id>openESB-Premium-releases</id>
      <username>xunta</username>
      <password>********</password>
    </server>
  </servers>

  <profiles>
    <profile>
      <id>nexus</id>
      <repositories>
        <repository>
          <id>openESB-Premium-releases</id>
          <url>https://nexus.vico.org/repository/openesb-premium-releases/</url>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
          </releases>
        </repository>
      </repositories>

      <pluginRepositories>
        <pluginRepository>
          <id>openESB-Premium-releases</id>
          <url>https://nexus.vico.org/repository/openesb-premium-releases/</url>
        </pluginRepository>
        <pluginRepository>
          <id>central</id>
          <url>https://repo.maven.apache.org/maven2/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>nexus</activeProfile>
  </activeProfiles>
</settings>
]]>

This configuration is required to:

  • Resolve OpenESB archetypes

  • Download proprietary plugins and dependencies

4.1.2 GitLab Configuration​

Correctly configure:

  • Access tokens

  • SSH keys (Not allowed in Xunta environments)

  • Git user configuration

Reference:Git and Maven Installation

This step is essential for:

  • Repository cloning

  • CI pipeline execution

  • Artifact publishing

4.2 Initial Decision: Identifying the Module Type​

Before generating any Maven project, the type of each existing module must be determined.

It must be identified whether the BPEL module is:

  • A catalog provider (WSDL, XSD, etc.)

  • A consumer (business BPEL that uses a catalog)

  • Self-contained (in our case, most modules are of this type)

It must also be determined whether the module is part of a Composite Application.

This decision directly defines which archetype should be used and avoids future rework.

4.3 Generating the Maven Structure​

Using the corresponding archetype, a new project is generated, which will serve as the base structure for the migration.

This initial project includes:

  • A pom.xml with the standard configuration

  • The required OpenESB directory structure

  • The plugins required for the build

At this stage, the project does not yet contain the functional code.

Its purpose is to provide a valid Maven structure onto which the artifacts from the original project will later be migrated.

4.3.1 Mavenization of a BPEL​

Step 1: Generate the Maven Project According to the BPEL Type​

  • catalog → soa-bpel-module-catalog-archetype

  • consumer → soa-bpel-module-catalog-consumer-archetype

  • self-contained → soa-bpel-module-archetypeDuring the process, the following information will be requested (in the case of mavenizing an existing project, these values will be copied from the project being migrated):

<![CDATA[mvn archetype:generate \
  -DarchetypeGroupId=com.vico.openesb.studio \
  -DarchetypeArtifactId=soa-bpel-module-archetype \
  -DarchetypeVersion=2.0 \
  -DarchetypeRepository=https://nexus.vico.org/repository/openesb-premium-releases/
]]>

During the process, the following information will be requested (in the case of mavenizing an existing project, these values will be copied from the project being migrated):

  • groupId

  • artifactId

  • version

Step 2: Adjust the pom.xml​

  • Add the corporate parent POM (if one exists, depending on your project distribution)

  • Remove the module version if it is managed from the parent

  • Verify inherited properties and plugins

📌 Important Note for Catalog Consumer BPEL Modules

If the BPEL is a consumer, the catalog name being used must be declared through the following property:

<![CDATA[<bpel.catalog.name>catalog-name</bpel.catalog.name>
]]>

This property can be defined:

  • In the parent POM, if it exists and is shared across multiple modules

  • Or directly in the BPEL pom.xml, if it is a specific case

Correctly defining this property is necessary to:

  • Properly resolve WSDL and XSD files during build time

  • Avoid implicit dependencies on the development environment

  • Guarantee reproducible builds in Continuous Integration

Step 3: Artifact Migration​

From the original NetBeans project:

  • Copy the contents of the src directory

  • Replace the src directory of the Maven-generated project

⚠️ It is essential to respect the structure defined by the archetype.

Step 4: Build and Validation​

<![CDATA[mvn clean install
]]>

Verify that:

  • The module compiles correctly

  • The expected OpenESB artifact is generated

Step 5: OpenESB Studio Compatibility​

  • Open the Maven project in the IDE

  • Regenerate the project if necessary (clean and build)

4.3.2 Mavenization of a Composite Application (CA)​

Step 1: Generate the Maven Project​

<![CDATA[mvn archetype:generate \
  -DarchetypeGroupId=com.vico.openesb.studio \
  -DarchetypeArtifactId=soa-composite-application-archetype \
  -DarchetypeVersion=2.0 \
  -DarchetypeRepository=https://nexus.vico.org/repository/openesb-premium-releases/
]]>

Step 2: Adjust the pom.xml​

From the original project, the following values can be reused:

  • groupId

  • artifactId

  • version

Recommended actions:

  • Add a clear description (if this is not done, the build will fail)

  • Add the parent POM

  • Remove the version if it is managed from the parent

Step 3: Artifact Migration​

  • Copy the contents of the src directory from the original CA

  • Replace the src directory of the generated Maven project

Step 4: Configure dragdropautomation.properties​

Edit the following file:

<![CDATA[/src/conf/dragdropautomation.properties
]]>

Add:

  • CA identification information

  • List of BPEL modules used

Be careful: the paths must be relative in order to ensure correct generation in Jenkins and on other developers' machines.

This file is key for assembly automation.

Step 5: Execute the Generation Scripts​

Depending on the operating system:

  • script.bat (Windows)

  • mac_script.sh (macOS)

  • linux_script.sh (Linux)

Step 6: Build and Validation​

<![CDATA[mvn clean install
]]>

Verify that:

  • The CA is generated correctly

  • It includes all the expected modules

5. Benefits for Continuous Integration

Once the project has been mavenized:

  • It can run on any CI agent

  • NetBeans is no longer required

This enables:

  • Automated builds

  • Nexus publishing

  • Controlled versioning

  • Automated deployment in OpenESB

6. Recommended Best Practices

  • One Maven module = one Service Unit or one CA

  • Centralize versions in a parent POM or multimodule POM