Also see the Generated Maven plugin documentation ↗
cics-bundle-maven-plugin
This is a Maven plugin and related utilities that can be used to build CICS bundles, and deploy them into CICS TS.
This project contains:
cics-bundle-maven-plugin
, a Maven plugin that authors CICS bundles for deploying resources into CICS TS. It supports a subset of bundleparts, including Java assets. Read the generated plugin documentation for information about this plugin's goals.
Using the plugin you can:
cics-bundle-reactor-archetype
, a Maven archetype that provides a simple reactor build that contains a CICS bundle and a Dynamic Web Project (WAR). This archetype builds and packages the WAR and CICS bundle.
cics-bundle-deploy-reactor-archetype
, a Maven archetype that provides a simple reactor build that contains a CICS bundle and a Dynamic Web Project (WAR). This archetype packages the WAR into a CICS Bundle and installs it into CICS.
samples
, a collection of samples that demonstrate the different ways in which to use the plugin.
The cics-bundle-maven-plugin
supports building CICS bundles that contain the following bundleparts:
It can deploy CICS bundles containing any bundleparts.
To use the plugin to build CICS bundles, make sure that Maven is installed.
Make sure any required bundles or projects are installed into your local maven repository (.m2 cache) correctly using mvn install
if they are not available in an online repository.
The plugin builds CICS bundles for any in-service version of CICS Transaction Server for z/OS (version 5.3 and later at the time of writing).
However, if you are using the deploy
goal of the plugin to deploy bundles to CICS, you must enable the CICS bundle deployment API. The CICS bundle deployment API is supported by the CMCI JVM server that must be set up in a WUI region or a single CICS region. See the CICS TS doc for details. To use the deploy
goal, make sure that:
cics-bundle-maven-plugin
This way of building a CICS bundle is useful when the CICS bundle contains more than one Java bundlepart, or contains extra bundleparts like FILE or URIMAP. It uses a separate module for the CICS bundle.
The cics-bundle-maven-plugin
contributes a new packaging type called cics-bundle
. This is bound to the plugin's build
goal that will use the information in the pom.xml
and dependencies to create a CICS bundle, ready to be stored in an artifact repository or installed into CICS.
To create a CICS bundle in this way:
Create a new Maven module for the CICS bundle.
Register the plugin to the pom.xml
of the CICS bundle module:
<build>
<plugins>
<plugin>
<groupId>com.ibm.cics</groupId>
<artifactId>cics-bundle-maven-plugin</artifactId>
<version>1.0.7</version>
<extensions>true</extensions>
</plugin>
</plugins>
</build>
Note that the version should be the latest version of this plugin, which can be found at the top of this page.
Change the packaging type of the CICS bundle module to the new CICS bundle type:
<packaging>cics-bundle</packaging>
If at this point you build the CICS bundle module, it will create a valid CICS bundle! However, it doesn't do much, because it doesn't define any bundle parts.
In the CICS bundle module, define a dependency on another module for a Java project that can be included into CICS, such as an OSGi bundle, WAR, EAR, or EBA.
<dependencies>
<dependency>
<groupId>my.group.id</groupId>
<artifactId>my-web-project</artifactId>
<version>1.0.0</version>
<!-- Version ranges are also supported CICS phase in support with OSGi bundles i.e. -->
<!-- <version>[1.0.0,2.0.0)</version> -->
<type>war</type>
</dependency>
</dependencies>
The plugin requires very little configuration. However, an important property for Java bundleparts is the name of the JVM server that the application will be installed into. To define this, alter how you registered the plugin to add some configuration, with the <defaultjvmserver>
property:
<build>
<plugins>
<plugin>
<groupId>com.ibm.cics</groupId>
<artifactId>cics-bundle-maven-plugin</artifactId>
<version>1.0.7</version>
<extensions>true</extensions>
<configuration>
<defaultjvmserver>DFHWLP</defaultjvmserver>
</configuration>
</plugin>
</plugins>
</build>
Now if you build the CICS bundle (mvn clean verify
or mvn clean install
) it will pull in the dependency, add it into the CICS bundle, and define it in the CICS bundle's manifest. The CICS bundle is ready to be deployed to CICS or stored in an artifact repository (if you use mvn clean install
the CICS bundle is installed into your local .m2 repository at the end of the build).
The generated CICS bundle takes its bundle ID from the Maven module's artifactId
and its version from the Maven module's version
.
To include CICS bundleparts like FILE or URIMAP, put the bundlepart files in your bundle Maven module's bundle parts directory, which defaults to src/main/bundleParts
. Files in your Maven module's bundle parts directory will be included within the output CICS bundle, and supported types will have a <define>
element added to the CICS bundle's cics.xml
.
The location of the bundle parts directory can be configured by using the <bundlePartsDirectory>
property. The configured directory is relative to src/main/
.
cics-bundle-maven-plugin
This way of building a CICS bundle modifies an existing Java module to make it also build the CICS bundle. This makes it more lightweight, but it has limitations - the CICS bundle can only contain one Java bundlepart, and can't contain any extra bundleparts such as FILE or URIMAP.
To create a CICS bundle in this way:
Take an existing OSGi bundle, WAR, EAR or EBA module. In this case we'll use the bundle-war
goal for a WAR module, but there are matching bundle-osgi
, bundle-ear
and bundle-eba
goals for those types of module. These goals bind, by default, to the verify
phase.
Register the plugin to the pom.xml
of the CICS bundle module, and add the appropriate goal as an execution, including configuration for which JVM server the CICS bundle will be installed into:
<build>
<plugins>
<plugin>
<groupId>com.ibm.cics</groupId>
<artifactId>cics-bundle-maven-plugin</artifactId>
<version>1.0.7</version>
<executions>
<execution>
<goals>
<goal>bundle-war</goal>
</goals>
<configuration>
<jvmserver>DFHWLP</jvmserver>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
Now if you build the Java module with verify phase or later, i.e. mvn clean verify
to avoid installing the artifact locally or mvn clean install
to install it locally in your .m2 directory, it will build the module as usual but then also wrap it in a CICS bundle, and define it in the CICS bundle's manifest. The CICS bundle is added to the output of the module, by default using the cics-bundle
classifier, and is ready to be stored in an artifact repository or deployed to CICS.
cics-bundle-maven-plugin
Following the instructions from one of the two methods above, you will have built a CICS bundle. You can use the cics-bundle-maven-plugin
to install this into CICS by using the CICS bundle deployment API. This requires some setup in CICS as a prerequisite.
<bundle_deploy_root>/<bundle_id>_<bundle_version>
.The username defined in the pom.xml is the developer’s credentials which need to have access to the appropriate RACF profile_prefix.CMCI.DEPLOYER EJBROLE. Credentials, such as a username and password, should not be directly placed into the pom.xml file. Instead, variables for the credentials should be referenced in the pom.xml file.
In the pom.xml
, extend the plugin configuration to include the extra parameters below:
<build>
<plugins>
<plugin>
<groupId>com.ibm.cics</groupId>
<artifactId>cics-bundle-maven-plugin</artifactId>
<version>1.0.7</version>
<executions>
<execution>
<goals>
<goal>bundle-war</goal>
<goal>deploy</goal>
</goals>
<configuration>
<!-- if you are deploying a Java module that also builds the CICS bundle,
you must specify the artifact with the cics-bundle classifier to be deployed.
<classifier>cics-bundle</classifier>
-->
<defaultjvmserver>DFHWLP</defaultjvmserver>
<url>http://yourcicsurl.com:9080</url>
<username>${cics-user-id}</username>
<password>${cics-password}</password>
<bunddef>DEMOBUND</bunddef>
<csdgroup>BAR</csdgroup>
<cicsplex>CICSEX56</cicsplex>
<region>IYCWEMW2</region>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
Note: If you're deploying the bundle into a single CICS region environment (SMSS), omit the <cicsplex>
and <region>
fields.
Edit the values in the configuration section to match your CICS configuration.
url
- Set the transport, hostname, and port for your CMCIusername
& password
- These are your credentials for CICS. Use Maven's password encryption, or supply your credentials using environment variables or propertiesbunddef
- The name of the BUNDLE definition to be installedcsdgroup
- The name of the CSD group that contains the BUNDLE definitioncicsplex
- The name of the CICSplex that the target region belongs to. This value is ignored in a single CICS region environment (SMSS).region
- The name of the region that the bundle should be installed to. This value is ignored in a single CICS region environment (SMSS).Now if you run the Maven build it will create the CICS bundle as above, and install this in CICS. If you run into an unable to find valid certification path to requested target
error during deployment, see Troubleshooting for a fix.
Each time you make a change to the Java project and rerun the build it will redeploy the bundle and publish your changes.
Typically, you won't want this deployment to happen in every environment that the build is run. Placing this execution in a separate Maven profile that is only enabled in development environments is suggested.
Snapshot builds are published to the Sonatype OSS Maven snapshots repository which is not available in a default Maven install. To try a snapshot build, you will need to add the following plugin repository to your pom.xml
:
<project>
...
<pluginRepositories>
<!-- Configure Sonatype OSS Maven snapshots repository -->
<pluginRepository>
<id>sonatype-nexus-snapshots</id>
<name>Sonatype Nexus Snapshots</name>
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>false</enabled>
</releases>
</pluginRepository>
</pluginRepositories>
...
</project>
Use of this plugin will vary depending on what you're starting with and the structure of your project. We have included some samples to demonstrate the different methods.
Reactor sample
This sample is the best starting place if you don't already have a Java project you want to build and want to have a go at building and deploying straight away. This is a reactor project with one module including the source for a web page (including a JCICS call), which will be packaged into a WAR. It has a second module, which creates the bundle and installs this in CICS.
Further information can be found here.
WAR sample
This sample shows how you can add to the pom of an existing Java Maven project, to build it into a bundle and install it in CICS.
Further information can be found here.
Another way to get started with the plugin is to use one of the provided archetypes. Maven archetypes provide parameterized templates for how a module could, or should, be structured. There are two archetypes, one which builds and packages a WAR into a CICS Bundle, and another which then installs this bundle to CICS using the CICS bundle deployment API. Further details on how to use the archetypes can be found here.
Maven best practice is to version your code <version>-SNAPSHOT
during development (for instance 0.0.1-SNAPSHOT
or 1.0.0-SNAPSHOT
- for more information see the Maven doc about SNAPSHOT versions).
Developing your code using a SNAPSHOT version will ensure that every time you build your code the previous SNAPSHOT is overwritten in your local Maven repository.
When you are happy with the quality of your code and want to make a release version, reversion your plugin to remove the -SNAPSHOT
qualifier. The maven-release-plugin provides facilities to automatically remove qualifiers, automatically updating dependencies and promoting code in your source control.
If you do not want to use the maven-release-plugin, you can update the version numbers of your parent reactor project, which will also update child project version numbers. Run this command within your parent reactor project:
mvn versions:set -DnewVersion=0.0.1
Note that this versions:set
approach will not update dependencies (e.g. from your bundle project to your Java project) which you will need to update manually.
After releasing your code, update to your next development version number, for instance 0.0.2-SNAPSHOT
.
unable to find valid certification path to requested target
during deploymentWhy does it happen?
You may run into this error when deploying your CICS bundle.
sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
It indicates an issue with establishing a trusted connection over TLS/SSL to the remote server (CICS Bundle Deployment API). It may happen when you are using a self-signed certificate or a certificate that's issued by an internal certificate authority, or that the certificate is not added to the trusted certificate list of your JVM.
How to resolve it?
You have two ways of resolving this issue:
Recommended Obtain the server certificate(s) and add it/them to the trusted certificate list to your JVM:
For security consideration, you may still want the TLS/SSL checking to be enabled. In this case, follow the instructions in How do I import a certificate into the truststore to trust the server's certificate, supplying your server's information. More information about the command involved is listed below:
Disable TLS/SSL certificate checking:
Add <insecure>true</insecure>
to the <configuration/>
block for the deploy goal in the bundle's pom.xml
(See snippet in Step 2 in deploy a CICS bundle to a target CICS region).
Note: Trusting all certificates can pose a security issue for your environment.
internal server error
during deploymentYou might see this error in the Maven log when you deploy a CICS bundle:
com.ibm.cics.bundle.deploy.BundleDeployException: An internal server error occurred. Please contact your system administrator
Why does it happen?
It indicates errors on the CMCI JVM server side.
How to resolve it?
Contact your system administrator to check the messages.log
file of the CMCI JVM server. For more information about how to resolve CMCI JVM server errors, see Troubleshooting CMCI JVM server in CICS documentation.
Error creating directory
during deploymentYou might see this message in the Maven log when deploying a CICS bundle:
[ERROR] - Error creating directory '<directory>'.
Why does it happen?
The error occurs because the credential that deploys the bundle doesn't have access to the bundles directory.
How to resolve it?
Contact your system administrator to make sure the deploy_userid
configured for the CICS bundle deployment API has WRITE access to the bundles directory. The bundles directory is specified on the com.ibm.cics.jvmserver.cmci.bundles.dir
option in the JVM profile of the CMCI JVM server.
For instructions on how to specify the bundles directory and grant access to deploy_userid
, see Configuring the CMCI JVM server for the CICS bundle deployment API in CICS documentation.
Why does it happen?
When you are using a bundle-war, bundle-ear, or bundle-osgi goal, the deploy goal must be configured with a cics-bundle classifier specifically.
How to resolve it?
Use the
We welcome contributions! Find out how in our contribution guide.
The CICS bundle Maven plugin is supported as part of the CICS Transaction Server for z/OS license. Problems can be raised as IBM Support cases, and requests for enhancement can use the Ideas site, for product CICS Transaction Server for z/OS.
Equally, problems and enhancement requests can be raised here on GitHub, as new issues.
This project is licensed under the Eclipse Public License, Version 2.0.