Introduction to the IBM IIB version 9 Maven Build Lifecycle

The IIB9 Maven Plug-In is a significantly rework of the IIB-Maven-Plug-In originally developed by the Swiss SBB. Its code is derived from the original project Snapshot dated to October 2015 and found at https://github.com/SchweizerischeBundesbahnen/iib-maven-plugin. The rework includes the best pieces of the original work as well as new pieces that make the IIB9 build experience more closely match what developers and architects expect of a maven build life-cycle. The IIB9 Maven Plugin has been updated to support IBM's IIB Version 10 and to provide much better Linux support. The Version 10 documentation can be found at http://vadosity.com/maven/

The reworked source code for this IIB-Maven-Plugin is available on GitHub at https://github.com/bretthshelley/Maven-IIB9-Plug-In. Questions may be sent directly to brett.shelley@vadosity.com.

IIB9 Maven Plug-In Overview

This document offers many details and tips to use the Maven IIB9 Plug-In. It needs to since the IIB BAR lifecycle differs significantly from a normal maven artifact like a jar file. However, once your project is setup correctly, one should only need to run the command mvn clean deploy - or better yet, just check in your code and let a CI server like Jenkins do it for you. So, the extensive information below is presented for your setup assistance with the ultimate objective of keeping it simple. The Quick-Start section of this document goes through the full setup process. The MavenIIB9PlugIn.pptx powerpoint presentation provides an illustrated explanation of the plug-in's capabilities.

The plug-in performs the following:

  • Mavenizes an IIB9 workspace by generating pom.xml files for each project as well as a parent pom with library modules
  • Deploys versioned IIB9 libraries to a maven repository (Optional)
  • Downloads a project's Dependent IIB9 libraries from a repository into an IIB9 workspace (Optional)
  • Downloads a project's Dependent Jars from a repository into an IIB9 application project
  • Builds a broker archive (BAR) with compiled message flows:
  • Compiles java-based unit and integration tests
  • Validates property files containing BAR overrides
  • Performs BAR overrides on any number of properties files
  • Deploys BAR files to any number of defined environments
  • Executes Integration Tests on Deployed BARs
  • Uploads versioned BAR files to a configured Maven Distribution Repository

IIB9 Maven Plug-In Build Lifecycle Basics

The IIB9 Maven Plug-In is based around the central concept of a build lifecycle. What this means is that the process for building and distributing a particular artifact (library project or broker archive -BAR) is clearly defined.

For the person building a project, this means that it is only necessary to learn a small set of commands to build an IIB9 Maven project, and the POM will ensure they get the results they desired.

This plugin has several build lifecycles: The main iib-bar lifecycle automates IIB9 BAR file creation and deployment to a Broker Node.The iib-bar lifecycle will perform most day-to-day operations. The iib-zip lifecycle zips up versioned common IIB9 library projects and deploys them to a Maven repository for use in IIB9 application projects.

The iib-bar Build Lifecycle

The iib-bar lifecycle comprises of the following phases:

  • clean - performs the standard cleanup and removal of a project's target directory
  • initialize - performs any additional file cleanup
  • generate-resources - copies jar dependencies into project and downloads any common library dependencies into workspace
  • process-resources - validates that each project in a workspace has correct format (project name = directory name)
  • compile - creates a broker archive using mqsicreatebar command (recommended) or using package bar.
  • test-compile - compiles unit and integration tests in the src/test/java directory.
  • process-classes - applies bar overrides using properties files found in resources folders and validates classloader approach
  • pre-integration-test - deploys a bar file to a configured broker and execution server
  • integration-test - executes integration tests against the just-deployed bar on the configured broker
  • verify - evaluates integration test results and stops build in event of failure(s)
  • deploy - done in an integration or release environment, copies the final bar to the remote repository for sharing with other developers and projects.

These lifecycle phases are executed sequentially to complete the iib-bar lifecycle. Given the lifecycle phases above, this means that when the iib-bar lifecycle is used, Maven will initialize the project, download dependencies, create a default bar file, apply bar overrides on any and all properties files in the src/main/resources against the default bar file, deploy overridden bar file(s) to defined environments, run integration tests, then deploy the bar file(s) to a maven snapshot or release respository.

To do all this, you only need to call the last build phase to be executed, in this case, deploy:

mvn deploy

That is because if you call a build phase in this plug-in, it will execute not only that build phase, but also every build phase prior to the called build phase. Just like any other Maven plug-in. Thus, doing

mvn compile

will execute every life cycle phase before it (initialize, generate-resources, process-resources), before executing compile.

There are more commands that can be executed with this eMI IIB9 Maven plugin, which will be discussed in the following sections.

The iib-zip Build Lifecycle

The iib-zip lifecycle makes common libraries available to developers in a read-only fashion. This enables common libraries to be "immutable" and not exposed to accidental developer alterations. This iib-zip lifecycle should only be periodically executed when versions of common libraries become available. The iib-zip lifecycle is comprised of the following phases:

  • package - zips up the contents of an IIB9 library project into a versioned zip file
  • install - installs the versioned, zipped-up IIB9 library project into your local maven repository
  • deploy - copies the zipped-up IIB9 file to the remote repository for sharing with other developers and projects.

Given the lifecycle phases above, this means that when the iib-zip lifecycle is used, Maven will zip up the IIB9 library project, install a local version and deploy a versioned zip file to a maven snapshot or release respository. It's a pretty neat idea - storing common source code projects in a Maven repository.

To do all this, you only need to call the last build phase to be executed, in this case, deploy:

mvn deploy

 

Using the IIB9 Maven Plug-In

Mavenize Your Workspace

This plug-in can "mavenize" an entire IIB9 workspace in a few seconds.  IIB9 projects get 'mavenized' by adding a pom.xml file in each project's root directory. And the pom.xml files contain maven dependency references that mirror IIB9 project dependencies.  Also, mavenizing an IIB9 application project includes adding directories such as "src\main\resources" and "src\test\resources".  These directories facilititate bar overrides and bar deployments with property files and broker files respectively. The mavenize goal in the IIB9 Maven plug-in enables these pom.xml files to be automatically generated with a working configuration.

The simplest way to mavenize a workspace is to run maven at the root of your workspace with the command:

mvn -Doverwrite=true -DgroupId=<enter.your.group.id> -Dversion=1.0-SNAPSHOT  -Dmaven.multiModuleProjectDirectory=%M2_HOME% -Ddistribution.repository=http://www.vadosity.com:8081/nexus/content/repositories/snapshots/ -Dworkspace=<enter\path\to\your\iib9\workspace> ch.sbb.maven.plugins:iib-maven-plugin:9.0-SNAPSHOT:mavenize
The mavenize goal has the following configuration parameters:

  • overwrite - true or false value indicating whether existing pom.xml files should be overwritten, defaults to true
  • groupId - the groupId of the maven artifacts, defaults to org.yourorg.yourteam
  • distribution.repository - the url to the repository where the artifacts (bar files, zip files) get deployed, defaults to http://www.vadosity.com:8081/nexus/content/repositories/snapshots/
  • workspace - the location of the IIB9 workspace, defaults to present working directory

 

Workspace Pom.xml with modules

Once a workspace has been mavenized, then a pom.xml file will be present at the root of the workspace. This workspace pom.xml contains modules that facilitate the automatic deployment of versioned library projects to the configured maven distribution repository. This workspace pom file enables all of the common libraries to be versioned and uploaded to a maven repository for common use across projects - and the upload process should take less than 30 seconds. It is also important to note that this feature does not necessarily need to be used. If developers want to check out common libraries from source control into a workspace, then this activity may be skipped. The workspace pom.xml file might have the following content:
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.vadosity.esbteam</groupId>
    <artifactId>common-libraries-parent-pom</artifactId>
    <packaging>pom</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>Simple Parent Project</name>

    <modules>
		<module>EMICommon</module>
		<module>EMICommonJava</module>
		<module>HL7v251DFDLLibrary</module>
		<module>VIECommonLibrary</module>
		<module>VIEExceptionJava</module>
    </modules>

	<distributionManagement>
		<repository>
			<id>distribution.repository</id>
			<name>distribution.repository</name>
			<url>http://www.vadosity.com:8081/nexus/content/repositories/snapshots/</url>
		</repository>
	</distributionManagement>
</project>

Example Library Pom.xml

And each IIB9 application library would have a pom.xml file similar to the following:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.vadosity.esbteam</groupId>
	<artifactId>EMICommon</artifactId>
	<version>1.0-SNAPSHOT</version>
	<packaging>iib-zip</packaging>
	<build>
		<plugins>
			<plugin>
				<groupId>ch.sbb.maven.plugins</groupId>
				<artifactId>iib-maven-plugin</artifactId>
				<version>9.0-SNAPSHOT</version>
				<extensions>true</extensions>
				<configuration>
				</configuration>
			</plugin>
		</plugins>		
	</build>

	<dependencies>
		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>EMICommonJava</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>
	</dependencies>

	<distributionManagement>
		<repository>
			<id>distribution.repository</id>
			<name>distribution.repository</name>
			<url>http://www.vadosity.com:8081/nexus/content/repositories/snapshots/</url>
		</repository>
	</distributionManagement>
</project>

Running the Workspace Pom

Running the 'mvn deploy' command in the workspace root directory is all that needs to be done to publish read-only versions of common libraries across projects.
mvn deploy

In order to deploy the common libraries to a maven distribution repository, the repository id would also need an entry in the user's .m2/settings.xml file. For example, the following entry in the settings.xml file would be needed to authenticate with the defined distribution server.
	<server>
	  <id>distribution.repository</id> 
	  <username>admin</username>
	  <password>admin123</password>
    </server>
 

Building Your IIB9 Application Project

Mavenizing a workspace also injects a working pom.xml file into each IIB9 application project. This application project uses the iib-bar lifecycle. The pom.xml file also contains several configuration parameters to control the build process. The 'mavenize' goal's objective is to provide a working configuration, but the expectation is that developers and build engineers will change the IIB9 application's pom.xml file configuration to meet team needs. As an example, after mavenizing a workspace, an IIB9 application project's pom.xml file may appear as follows:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.vadosity.esbteam</groupId>
	<artifactId>C4_HDRVistaInterface</artifactId>
	<version>1.0-RELEASE</version>
	<packaging>iib-bar</packaging>

	<profiles>
		<profile>
			<id>localdev</id>
			<activation>
      			<activeByDefault>true</activeByDefault>
    		</activation>
			<properties>
				<workspace>C:\Users\Brett\IBM\IntegrationToolkit90\4.2\maven-demo-2</workspace>
				<initialDeletes>**/*.jar</initialDeletes>
				<unpackIibDependenciesIntoWorkspace>true</unpackIibDependenciesIntoWorkspace>
				<pathToMqsiProfileScript>C:\Program Files\IBM\MQSI\9.0.0.2\bin\mqsiprofile.cmd</pathToMqsiProfileScript>
				<failOnInvalidProperties>true</failOnInvalidProperties>
				<useClassloaders>false</useClassloaders>
				<failOnInvalidClassloader>true</failOnInvalidClassloader>
				<createOrPackageBar>package</createOrPackageBar>
				<completeDeployment>true</completeDeployment>
				<timeoutSecs>600</timeoutSecs>
			</properties>		
		</profile>	
	</profiles>
	
	
	<build>
		<plugins>
			<plugin>
				<groupId>ch.sbb.maven.plugins</groupId>
				<artifactId>iib-maven-plugin</artifactId>
				<version>9.0-SNAPSHOT</version>
				<extensions>true</extensions>
				<configuration>
					<workspace>${workspace}</workspace>
					<initialDeletes>${initialDeletes}</initialDeletes>
					<unpackIibDependenciesIntoWorkspace>${unpackIibDependenciesIntoWorkspace}</unpackIibDependenciesIntoWorkspace>
					<pathToMqsiProfileScript>${pathToMqsiProfileScript}</pathToMqsiProfileScript>
					<failOnInvalidProperties>${failOnInvalidProperties}</failOnInvalidProperties>
					<useClassloaders>${useClassloaders}</useClassloaders>
					<failOnInvalidClassloader>${failOnInvalidClassloader}</failOnInvalidClassloader>
					<createOrPackageBar>${createOrPackageBar}</createOrPackageBar>
					<!-- mqsideploy -n b1.broker -e default -a mybar.bar -m -w 600 -->					
					<completeDeployment>${completeDeployment}</completeDeployment>
					<timeoutSecs>${timeoutSecs}</timeoutSecs>
					<!-- if timeouts occur on broker, then try command:  mqsichangebroker IB9NODE -g 300 -k 300 -->
					<!-- to enable/disable decision services:  mqsimode IB9Node -x DecisionServices  -->
				</configuration>
			</plugin>
		</plugins>

		<pluginManagement>
			<plugins>
				<!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
				<plugin>
					<groupId>org.eclipse.m2e</groupId>
					<artifactId>lifecycle-mapping</artifactId>
					<version>1.0.0</version>
					<configuration>
						<lifecycleMappingMetadata>
							<pluginExecutions>
								<pluginExecution>
									<pluginExecutionFilter>
										<groupId>
											ch.sbb.maven.plugins
										</groupId>
										<artifactId>
											iib-maven-plugin
										</artifactId>
										<versionRange>
											[9.0-SNAPSHOT,)
										</versionRange>
										<goals>
											<goal>
												initialize-bar-build-workspace
											</goal>
										</goals>
									</pluginExecutionFilter>
									<action>
										<ignore></ignore>
									</action>
								</pluginExecution>
							</pluginExecutions>
						</lifecycleMappingMetadata>
					</configuration>
				</plugin>
			</plugins>
		</pluginManagement>
	</build>

	<dependencies>
		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>HL7v251DFDLLibrary</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>


		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>VIECommonLibrary</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>


		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>EMICommon</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>

		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>4.11</version>
			<scope>test</scope>
		</dependency> 
	</dependencies>
		
		<!-- NOTE:  The Integration Test FailSafe plugin looks for Test classes that follow the **/*IT.java, **/*ITCase.java, or **/IT*.java pattern -->

	<distributionManagement>
		<repository>
			<id>distribution.repository</id>
			<name>distribution.repository</name>
			<url>http://www.vadosity.com:8081/nexus/content/repositories/releases/</url>
		</repository>
	</distributionManagement>
</project>


IIB9 Application Configuration Parameters

The pom.xml file's configuration parameters are key to executing the iib-bar lifecycle of the eMI IIB9 Maven plugin. These parameters control the behavior of the iib-bar lifecycle.
  • workspace - the location of the IIB9 workspace directory
  • initialDeletes - files to delete/clean from a project ; the filenames can be absolute or follow the ant file patterns
  • unpackIibDependenciesIntoWorkspace - indicates whether library projects should be downloaded and unpacked into the workspace; For example, if set to true, then the example HDR pom.xml file will download and unzip the HDRJava, EmiCommon, and HL7v251DFDLLibrary into the workspace as part of the build process.
  • copyDependentJarsLocation - location where dependent jars are downloaded to; defaults to project's base directory
  • createOrPackageBar - value of 'create' launches mqsicreatebar whereas 'package' packages bar with uncompiled resources
  • pathToMqsiProfileScript - the path to the local mqsiprofile script
  • failOnInvalidProperties - indicates whether the build should fail if invalid bar override properties are found in a property file which is not a default property for an non-overridden bar file; During the "process-classes" phase, if a file, like xyz.properties, is found in the src/main/resources directory or the src/test/resources, then the file is used to generate an overridden bar file named xyz.bar.
  • useClassloaders - indicates whether class loaders are used; defaults to "false"
  • failOnInvalidClassloader - indicates whether build fails if useClassLoader entry differs in overridden property(ies) file(s)
  • brokerFileName> - the broker file that containing the connection information to use to deploy a bar file to it
  • barFileName - the bar file to deploy to the designated broker.
  • completeDeployment - indicates whether the bar file deployment should be a full/complete deployment or a partial deployment
  • timeoutSecs - the timeout in seconds to wait on a bar file deployment
  • integrationServerName - the name of the integration server to deploy a bar file to
  • mqsiPrefixCommands - comma-separated list of commands that will be issued to the underlying operating system before launching the mqsi* command
  • mqsiCreateBarReplacementCommand - an advanced parameter that allows you to replace the generated mqsiCreateBar command arguments with your 'tweaked' arguments
  • mqsiCreateBarCompileOnlyReplacementCommand - an advanced parameter that allows you to replace the generated mqsiCreateBar -compileOnly command arguments with your 'tweaked' arguments
  • mqsiDeployReplacementCommand - an advanced parameter that allows you to replace the generated mqsideploy command arguments with your 'tweaked' arguments

Running the IIB-BAR Lifecycle

 

Again, to run thru the full iib-bar lifecycle, one need only execute maven in the IIB9 project's base directory.

mvn deploy

Since the iib-bar plug-in's lifecycle is not identical to a typical maven lifecycle (jar, ear, war), it is helpful to step through the iib-bar lifecycle's phases to see what happens. For example:

  • To delete jar files or other defined files in a project's workspace, run:
    mvn initialize
  • To see jar files copied into a project's base directory and library projects get copied into a workspace, run:
    mvn generate-resources
  • To validate the projects in an IIB9 workspace, run:
    mvn process-resources
  • To execute the mqsicreatebar command that generates a bar with compiled message flows for an IIB9 application project, run:
    mvn compile
  • To compile integration tests to execute during the integration-test phase, run:
    mvn test-compile
  • To create overridden bar files for each properties file in a projects' src/main/resources and src/test/resources directory, run:
    mvn process-classses
  • To deploy an overridden bar to a broker node and execution server, run:
    mvn pre-integration-test
  • To execute integration tests against a just deployed BAR on a broker node, run:
    mvn integration-test
  • To deploy a bar file to a maven distribution repository, run:
    mvn deploy

Additional Notes:

Solving the IIB9 pom.xml problem

When working with the IIB9 Integration Toolkit's User Interface, the 'CreateBar' command will fail because a pom.xml file is in the project's base directory. The IDE will generate an error message indicating something to the effect that pom.xml has already been added to the bar file. To fix this problem, simply rename the pom.xml file to pom.xml.txt file or any file name that does not end with the '.xml' extension. Then, running maven can be accomplished using the command:
mvn -f pom.xml.txt deploy
.

'skip' and 'skipTo' Feature

Executing the entire iib-bar lifecycle can be time consuming. To save developer/tester time, one can define skip and skipTo arguments when running the iib-bar lifecycle with maven. For example, if one wants to skip directly to integration tests after performing a full-deploy, one can execute:
mvn -f pom.xml.txt -DskipTo=integration-test verify
Likewise, the skip JVM argument may also be used in a similar fashion with the caveat that one can define multiple 'skip' steps. The following script would have the same effect as the above skipTo command:
mvn -f pom.xml.txt -Dskip=initialize,generate-resources,process-resources,compile,process-classes,pre-integration-test verify
Please note that the skipTo and skip feature are just for developer and tester convenience. The goal of these non-standardized features is to save development and testing time - and not to replace the value of executing the entire iib-bar lifecycle.

mqsiPrefixCommands configuration parameter

This plugin's compile and pre-integration-test goals execute mqsi commands such as mqsiprofile, mqsicreatebar, and mqsideploy. These commands require that the IBM IIB MQSI software and related executables are installed on the system where maven is executed. And the commands are executed using the java Runtime.getRuntime().exec(String[] args) approach. That is, the commands are executed by sending an array of commands directly to the underlying operating system. In the case of Windows, these OS specific commands are already defined. However, with other operating systems, the 'mqsiPrefixCommands' commands need to be defined using a comma-separated list of commands. An example set of mqsiPrefix commands might appear like:
<mqsiPrefixCommands>cmd,/c,"C:\Program Files\IBM\MQSI\9.0.0.2\bin\mqsiprofile.cmd",&,cmd,/c</mqsiPrefixCommands>

The key is to get the plug-in to execute the desired mqsicommand with the mqsiprofile environment correctly setup.

Quick Start

1. Install Maven (Do this once)

Download and Install Maven. For installation instructions, go to https://maven.apache.org/install.html. If you just installed maven, then execute Step 3 of this quick start. The step will fail, but this step will create the directory structure needed to execute step 2. Then, you can successfully execute step 3 again.

2. Update Maven Settings (Do this once)

In order for maven to upload artifacts to a maven distribution repository such as nexus, it needs to have the repository, admin name and admin password defined in the maven settings.xml file. On Windows operating systems, this file is normally located at C:\Users\<YourUserName>\.m2\settings.xml. The Maven settings.xml file can contain user-level maven settings for many projects - so it should not be "lightly" overwritten. However, if you have just installed maven, then you can safely overwrite your settings.xml file with this linked settings.xml file. If you have an existing maven settings.xml file in your user directory, then use this example to add entries to correctly point at the team's maven repository (nexus). The maven settings in this example settings.xml file point to www.vadosity.com's nexus server - feel free to use it for testing purposes.

3. Download this Plug-In (Do this once)

Open up a command prompt and navigate to a directory such as c:\temp. Execute the following command to get a copy of this plugin:
mvn org.apache.maven.plugins:maven-dependency-plugin:2.8:get -DrepoUrl=http://www.vadosity.com:8081/nexus/ -Dartifact=ch.sbb.maven.plugins:iib-maven-plugin:9.0-SNAPSHOT -Ddest=iib-maven-plugin-9.0-SNAPSHOT.jar

4. Install the IBM ConfigManagerProxy.jar in your local repository (Do this once)

In the same command prompt window, install a copy of the IBM ConfigManagerProxy.jar in your local repository with the command:
mvn install:install-file -DgroupId=com.ibm.etools.mft.config -DartifactId=ConfigManagerProxy -Dversion=9.0.300.v20150305-1357 -Dpackaging=jar -Dfile="C:\Program Files\IBM\MQSI\9.0.0.2\classes\ConfigManagerProxy.jar"
* Note: The maven-plugin uses an IBM java archive to perform IIB9 bar packaging operations. It is assumed that the platform running maven will also have IBM IIB9 components installed on the system - so one need only locate the path to the ConfigManagerProxy.jar.

5. Install this Plug-In in your local repository (Do this once)

In the same command prompt window, install the copy of this plugin in your local repository with the command:
mvn install:install-file -Dfile=iib-maven-plugin-9.0-SNAPSHOT.jar -DgroupId=ch.sbb.maven.plugins -DartifactId=iib-maven-plugin -Dversion=9.0-SNAPSHOT -Dpackaging=jar

6. Generate this help file (Optional)

For a local copy of these instructions, run the plugin's 'morehelp' goal. This html file's contents, its associated images, and related files will be saved in the directory where the following command is run:
mvn ch.sbb.maven.plugins:iib-maven-plugin:9.0-SNAPSHOT:morehelp
.

7. Mavenize an IIB9 workspace (Do this just per IIB9 workspace)

With a command window, navigate to the root of an IIB9 workspace. Ideally the workspace will contain both IIB9 application and IIB9 library projects. Before executing the following commands, a developer should verify that only the projects of interest in the workspace. Otherwise, extraneous projects will be zipped up and deployed on a maven distribution repository such as nexus. To Mavenize a workspace, modify and execute this example command:
mvn -Doverwrite=true -DgroupId=com.vadosity.esbteam -Dversion=1.0-SNAPSHOT  -Dmaven.multiModuleProjectDirectory=%M2_HOME% -Ddistribution.repository=http://www.vadosity.com:8081/nexus/content/repositories/snapshots/ ch.sbb.maven.plugins:iib-maven-plugin:9.0-SNAPSHOT:mavenize
Verify that your workspace has been 'mavenized' by searching for pom.xml files in your workspace. A search for pom.xml files in your IIB9 workspace should produce results similar to 'Figure 1' below.
Figure 1

8. Upload Common Libraries to a Maven Distribution Repository (Do this once per Common Library Version IF involved in developing common libraries)

With a command prompt situated at the root of the IIB9 workspace, execute:
mvn deploy
Verify that the build successfully completed. Navigate to the distribution repository and check the appropriate repository for your IIB9 library artifacts. For example, navigate to http://www.vadosity.com:8081/nexus/#view-repositories;snapshots~browsestorage to view uploaded IIB9 library projects as seen in Figure 2.
Figure 2

9. Delete Common Library Projects (Optionally Do this once)

Step 8 uploaded IIB9 libraries and other dependent project to a maven distribution repository. To fully understand how the plugin works, delete the IIB9 dependendent libraries and projects in your workspace (if present). For example, delete all IIB9 projects in an IIB9 workspace except the HDR project. After deletion, your workspace should appear as seen in Figure 3.
Figure 3

10. Verify that Pom.xml include common libraries (Do this just per IIB9 workspace)


 
With a command prompt navigate from the iib9 project workspace directory into the IIB9 bar application project you are working on. For example, navigate to the HDR project.
cd HDR
When your project includes common libraries, then common libraries need to be added as dependencies in your project pom.xml file. The mavenize project step may have already added common library dependencies. If it has not, then your common libraries must be added. The common libraries are added as normal maven dependencies are - and absolutely must have the 'compile' scope defined. For example, your bar application's pom.xml dependencies section would appear similar to the following:
	<dependencies>
		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>HL7v251DFDLLibrary</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>VIECommonLibrary</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>com.vadosity.esbteam</groupId>
			<artifactId>EMICommon</artifactId>
			<version>1.0-SNAPSHOT</version>
			<type>zip</type>
			<scope>compile</scope>
		</dependency>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>4.11</version>
			<scope>test</scope>
		</dependency> 
	</dependencies>
If your project's pom.xml file does not include any entries for common libraries, then you can look up your common libraries in your maven distribution repository. The distribution repository will provide the dependency entries for any given common library available. Add dependencies for common libraries in your pom.xml just as any other normal dependencies are added. Also note that the junit dependency is necessary to execute integration tests in later steps. Save your pom.xml file when complete.

11. Run Generate Resources (Perform this and the following steps for each Project Build cycle)

Execute the following maven command:
mvn generate-resources
Open up Windows Explorer or a similar program to view the IIB9 workspace. Note that the directory contains not only your project, but also the dependent projects. For example, Figure 4 shows the HDR project as well as its dependent library projects. Note that Maven has downloaded the dependent source libraries into the workspace. The dependent library projects need not be checked out directly from source control. Thus, the downloaded IIB9 libraries are safe from accidental alteration. Also note that this dependent project download functionality can be turned off by setting the plug-in's 'unpackIibDependenciesIntoWorkspace' configuration parameter to false. You decide.
<unpackIibDependenciesIntoWorkspace>false</unpackIibDependenciesIntoWorkspace>

Figure 4

12. Run Compile

To create a bar file, run the command:
mvn compile
Verify that a bar file has been successfully generated by checking the "target" directory in your IIB9 application project's workspace. For example, Figure 5 shows the generated bar file in the HDR project's target directory.
Figure 5

13. Run Test Compile

To compile unit and integration tests, run the command:
mvn test-compile
Verify that test classes have been compiled by viewing the "target/test-classes" directory in your IIB9 application project's workspace.

14. Run Process Classes

To generate a default.properties file containing all possible bar override values and to override the bar file, run the command:
mvn process-classes
This step creates a default.properties file in your projects's target directory. It also creates a defined-default.properties file in the same directory. The default.properties file lists all possible properties that can be overridden in a bar. The defined-default.properties file only lists those that have been set during the development process. It is recommended to use defined-default.properties as a foundation for creating overridden properties files for deployment environments.
 
The plug-in then searches your project's src/main/resources directories for environments defined by naming convention. A single environment's files consist of a properties file, an optional broker file and a deploy-config file. For example, the files INT1.broker, INT1.deploy-config, INT1.properties define the 'INT1' environment. The broker file contains the WHERE information defining the 'INT1' broker node's location. To create a broker file, see IBM Documentation. The deploy-config defines the mqsideploy configuration values. The deploy-config file is also in properties file format and contains the config parameters specified in mqsideploy documentation. For example, the deploy-config file will define the integration server name to mqsideploy the bar file to for this environment. Finally, the properties file for an environment defines the bar override values for the named environment.
 
Thus, the plug-in perform bar overrides for as many environments as are specified in the src/main/resources directory. Figure 6 shows the overridden bar files in the C5_HDR_VistaInterface project's target/iib-overrides directory. This Figure shows environments 'INT1' and 'INT2' and the resulting overridden bar files. Note that an environment classifier is added to each overridden bar file name.
Figure 6

15. Run Pre-Integration-Test

Running the pre-integration-test maven command deploy overridden bar file to each defined environment. Before executing this command, it makes sense to verify your IIB9 Maven plug-in's configuration. For example, the following configuration is used to deploy a bar file to a local developer's environment.
<completeDeployment>true</completeDeployment>
<timeoutSecs>600</timeoutSecs>
During deployments, timeout failures are common. To configure a Broker Node and execution server for extended timeouts, see: http://www-01.ibm.com/support/knowledgecenter/SSKM8N_8.0.0/com.ibm.etools.mft.doc/ae18065_.htm.
Once ready, run the mqsideploy with the following command:
mvn pre-integration-test

To skip directly to the mqsideploy step in the pre-integration-test phase without having to run through the full iib-bar lifecycle:
mvn -DskipTo=pre-integration-test pre-integration-test

* If a decision services error occurs at mqsi deployment, then the following command enables and disables Decision services.
mqsimode <YourNode> -x DecisionServices
For example:
mqsimode IB9NODE -x DecisionServices

16. Run Integration-Test

Run Integration Tests with the standard maven plugin with the command:
mvn integration-test

17. Run Deploy

The Maven deploy command is not the same as the mqsideploy command executed in the iib-bar lifecycle's pre-integration-test step. The maven deploy just deploys the non-overridden bar to the Maven Distribution Repository. To execute the full iib-bar lifecycle:
mvn deploy

To skip mqsideploy that occurrs in the pre-integration-test goal, execute:
mvn -DskipTo=integration-test deploy

Verify the 'maven deploy' success by finding the iib-bar artifact in the maven distribution repository. For example, Figure 7 shows a deployed IIB9 bar file in a Releases repository.
Figure 7