IBM WebSphere Application Server Plugin Reference

The IBM WebSphere Application Server (WAS) plugin adds capability for managing deployments and resources on an existing WebSphere application server.

This document provides information that is specific to this version of the WAS plugin. For general information about the plugin, refer to Introduction to the XL Deploy WebSphere Application Server plugin.

Requirements

• XL Deploy 5.1.0 or later
• IBM WebSphere Application Server Standard and Network Deployment 7.0, 8.0, or 8.5 (Unix and Microsoft Windows)

Using the deployables and deployeds

The following table shows the possible containers a deployable can be targeted to and the deployed that will be created as a result.

Deployable vs. containers table

Deployed actions table

The following table shows the actions taken when creating, modifying, or destroying a deployed.

Migrating from WAS plugin extensions

From version 4.5.0, the functionality of the WAS plugin extensions has been incorporated in the official WAS plugin. Version 4.5.0 of was-plugin-extensions exists for backwards compatibility only. Please port all your CIs to the WAS plugin, since this will be the only supported WAS plugin from now on.

The majority of the CIs can be ported by substituting the wasx prefix for was.

The following table shows the exceptions to this pattern:

Migrated type-modifications

Type-modifications previously present in the extensions plugin will be automatically upgraded to new state according to the following transition table:

Possible breaking changes / different behavior

Overwrite behavior

Take notice that existing values of complex properties (i.e. JVM args, Environment vars etc.) will by default be overwritten by values specified in XL Deploy CIs. If the existing values on WebSphere are to be preserved, please remember to include them in XL Deploy CIs prior to deployment.

If a CI property is not explicitly set, XL Deploy will use its default value. If a default value is not defined, an empty value will be sent to the WebSphere Application Server.

On CIs extending was.ConfigurationResource this behaviour can be overridden by setting the values of properties overwriteExistingValues and overwriteExistingCustomProperties to false.

When overwriteExistingValues is set to false, only the provided properties will be set; properties not specified in the deployed CI will be left as-is. Please note here that properties with default values still take effect and will be considered as set on the deployed CI!

Property overwriteExistingCustomProperties changes the MODIFY behaviour of complex properties (i.e. JVM args, Environment vars etc.) once user has defined at least one entry on the complex property. When set to false, existing entries present on the server will be left as is and new entries will be appended to the existing custom properties. If server already has an entry (property) of the same name, its value will be updated.

Managed server control task

was.ManagedServer doesn't have property "template". Instead, this control tasks accepts parameter of type was.ManagedServer_create. One can invoke control tasks from cli using following snippet:

newServerId='Infrastructure/localhost/vagrantCell01/vagrantNode01/test3'
newServer = factory.configurationItem(newServerId, 'was.ManagedServer', {'serverType': 'APPLICATION_SERVER', 'tags' : ['scope_jvm'] });
repository.create(newServer)
control = deployit.prepareControlTask(newServer, "create")
control.parameters.values['template'] = 'default'
taskId = deployit.createControlTask(control)
deployit.startTaskAndWait(taskId)

Container Restart Strategy property implementation at container level

When the containerRestartStrategy property is set to STOP_START or RESTART on was.Module, this value will take precedence over the value that is set on the WebSphere application servers and clusters.

If the containerRestartStrategy property is set to NONE on was.Module and is set to STOP_START or RESTART in was.ManagedServer, was.UnmanagedServer, or was.Cluster (that is, on the container level), then the value that is set on the container level will be applied to the respective containers.

Character encoding

If non-ASCII characters appear garbled on the WebSphere Application Server (WAS) Admin Console, verify that the default shell on the host with the deployment manager is correctly configured for UTF-8 character encoding; that is, a locales package is installed, the UTF-8 locale is generated, and the LC_ALL, LANG, and LANGUAGE environmental variables are configured with the correct value (en_US.UTF-8).

Release notes

WAS plugin 5.1.5

Bug fixes

• [DEPL-10244] - For Websphere Edition Applications, undeploy step is generated even if only dictionary value is modified
• [DEPL-10242] - Sychronization steps are not generated when deploying to a Websphere Dynamic Cluster

WAS plugin 5.1.4

Improvements

• [DEPL-10039] - Support creation of datasource without specifying Jaas Alias Name or Username/Password

WAS plugin 5.1.3

Bug fixes

• [DEPL-7528] - was.KeystoreSpec location property cannot be used in the Maven plugin
• [DEPL-8898] - Special characters are corrupted when deploying to WebSphere
• [DEPL-9945] - was.CustomPropertiesSpec cannot be deployed to was.UnmanagedServer or was.ManagedServer

WAS plugin 5.1.2

Bug fixes

• [DEPL-9227] - Fixed issue that resets the transport type when deploying a WMQ topic connection factory with CCDT URL

WAS plugin 5.1.1

Improvements

• [DEPL-8861] - Make contextRoot an optional property on was.EmbeddedWebModuleSpec

Bug fixes

• [DEPL-8614] - Fixed issue that prevented generation of stop and start steps when defining a modify script on was.Module
• [DEPL-8427] - Fixed issue that prevented the WAS version from being detected when WAS was installed using a language other than English
• [DEPL-8345] - Fixed issue where discovery did not find a folder called "config" on WAS 7 ND
• [DEPL-6864] - Fixed an issue that prevented a was.ManagedServer from being restarted unless the containerRestartStrategy was set

WAS plugin 5.0.3

Improvements

• [DEPL-10039] - Support creation of datasource without specifying Jaas Alias Name or Username/Password

Bug fixes

• [DEPL-7528] - was.KeystoreSpec location property cannot be used in the Maven plugin

WAS plugin 5.0.2

Improvements

• [DEPL-8861] - Make contextRoot an optional property on was.EmbeddedWebModuleSpec

Bug fixes

• [DEPL-8614] - Fixed issue that prevented generation of stop and start steps when defining a modify script on was.Module
• [DEPL-8427] - Fixed issue that prevented the WAS version from being detected when WAS was installed using a language other than English
• [DEPL-8345] - Fixed issue where discovery did not find a folder called "config" on WAS 7 ND
• [DEPL-7043] - Fixed an incorrect error message when an incomplete datasource was deployed to WAS
• [DEPL-6864] - Fixed an issue that prevented a was.ManagedServer from being restarted unless the containerRestartStrategy was set

WAS plugin 5.0.1

Bug fixes

• [DEPL-6957] - Fixed issue where was.ResourceEnvironmentProviderSpec wouldn't allow referenceables with non-alphanumeric characters
• [DEPL-7222] - Fixed issue where user was unable to specify an empty JAAS mapping alias
• [DEPL-7752] - Fixed issue where AdminTask.rolloutEdition doesn't accept nested brackets in WebSphere 8.5.5.x
• [DEPL-8127] - Fixed issue where an incorrect ripple start procedure would be executed in some circumstances
• [DEPL-8358] - Fixed issue where deployment of was.WmqActivationSpecification fails when the CCDT URL property is defined

WAS plugin 5.0.0

Compatible with XL Deploy 5.0.

As of version 5.0.0, the plugin no longer supports WebSphere Application Server 6.1.

Bug fixes

• [DEPL-8137] Cannot map users and groups to the same role in a was.Ear CI

Changes

• [DEPL-8106] Remove default values from WAS ConfigResource CIs

WAS plugin 4.5.4

Improvements

• [DEPL-8861] - Make contextRoot an optional property on was.EmbeddedWebModuleSpec

Bug fixes

• [DEPL-8427] - Fixed issue that prevented the WAS version from being detected when WAS was installed using a language other than English
• [DEPL-8345] - Fixed issue where discovery did not find a folder called "config" on WAS 7 ND
• [DEPL-7043] - Fixed an incorrect error message when an incomplete datasource was deployed to WAS
• [DEPL-6864] - Fixed an issue that prevented a was.ManagedServer from being restarted unless the containerRestartStrategy was set

WAS plugin 4.5.3

Improvements

• [DEPL-8041] - Allow specifying overwrite behavior for complex configuration CIs

Bug fixes

• [DEPL-7007] - Setting empty string for not set property in WebSphere Queue Connection Factory causes problem at runtime

WAS plugin 4.5.2

Bug fixes

• [DEPL-7292] - Support deployment of was.J2CResourceAdapter to a cell scope
• [DEPL-7394] - WAS - global webserver plugin not updated for managed web server on update

WAS plugin 4.5.1

Bug fixes

• [DEPL-6697] - NodeAgent host property should default to the host of the deployment manager.

WAS plugin 4.5.0

New features

• [DEPL-3284] - Add support for J2CActivation
• [DEPL-4166] - Add support for WmqActivationSpecification
• [DEPL-5661] - Extend discovery to all deployeds of was-plugin
• [DEPL-5802] - Add support for configuring server-specific application settings
• [DEPL-5803] - Add support for configuring session management
• [DEPL-5804] - Add support for configuring Performance Monitoring Infrastructure (PMI)
• [DEPL-5805] - Add support for configuring ports
• [DEPL-5806] - Add support for configuring web container
• [DEPL-5807] - Add support for configuring JVM and process management
• [DEPL-5809] - Add support for configuring EJB container
• [DEPL-5810] - Add support for configuring transaction service
• [DEPL-5812] - Implement DeploymentManager control tasks (start/stop/restart deployment manager and node agents)
• [DEPL-5813] - Add support for UnmanagedWebServer and plugin-cfg generation
• [DEPL-5815] - Implement ManagedServer control tasks (start/stop/restart/create/destroy)
• [DEPL-5816] - Add support for FileSynchronizationService
• [DEPL-5817] - Add support for setting CustomProperties on arbitrary containers
• [DEPL-5826] - Implement Cluster control tasks (start/stop/create)
• [DEPL-5828] - Add support for CoreGroup
• [DEPL-5830] - Add support for EjbNameSpaceBinding
• [DEPL-5831] - Add support for IndirectNameSpaceBinding
• [DEPL-5834] - Add support for ORBService
• [DEPL-5835] - Add support for URLProvider
• [DEPL-5836] - Add support for URLResource
• [DEPL-5837] - Add support for TimerManager
• [DEPL-5838] - Add support for Scheduler
• [DEPL-5839] - Migrate changes to Datasource type
• [DEPL-5850] - Add support for J2CResourceAdapter
• [DEPL-5854] - Add support for J2CAdminObject
• [DEPL-5868] - Add support for configuring core group service
• [DEPL-5894] - Add support for configuring logging and tracing
• [DEPL-5937] - Filter CI, SET_OF_CI and LIST_OF_CI properties by cell (requires XL Deploy 4.0.1+)
• [DEPL-6081] - Support specification of properties on modules inside was.Ear
• [DEPL-6104] - Add support for SIBusMember
• [DEPL-6112] - Add support for SIBWMQServer

Improvements

• [DEPL-3821] - Add "hostname" to was.DeploymentManager connection options
• [DEPL-4292] - Document that a "port" value of 0 for a WAS cell will suppress the -port argument
• [DEPL-5029] - Extend was.WmqQueueConnectionFactory
• [DEPL-5162] - Add virtualHostName property (STRING) to was.Module
• [DEPL-5230] - Add webserverNames property (SET_OF_STRING) to was.Module
• [DEPL-5483] - Extend was.Module type
• [DEPL-5485] - Extend was.WmqTopicConnectionFactory
• [DEPL-5820] - WebSphere MQ JMS provider not being detected during discovery

Bug fixes

• [DEPL-5401] - ListenerPort does not support deploying to Cluster anymore
• [DEPL-5442] - WAS discovery fails if a proxy server cluster is present
• [DEPL-5519] - ListenerPort fails when deployed to a was.Cluster
• [DEPL-5818] - J2CConnectionFactory discovered as SibQueueConnectionFactory
• [DEPL-5819] - ResourceEnvironmentEntry and ResourceEnvironmentProvider detected at wrong scope during discovery
• [DEPL-5822] - ServletCacheInstance detected at wrong scope during discovery
• [DEPL-5823] - WorkManager detected at wrong scope during discovery
• [DEPL-5825] - Creation of ThreadPool fails if it's not on the server scope
• [DEPL-5909] - MailSession created on first MailProvider found

Possible breaking changes / different behavior

This plugin version requires XL Deploy 4.0.1+

Take notice that existing values of complex properties (i.e. JVM args, Environment vars etc.) will by default be overwritten by values specified in XL Deploy CIs. If the existing values on WebSphere are to be preserved, please remember to include them in XL Deploy CIs prior to deployment.

If a CI property is not explicitly set, XL Deploy will use its default value. If a default value is not defined, an empty value will be sent to the WebSphere Application Server.

Type changes

Application resources

The was.Ear, was.War and was.EjbJar CIs have been extended with additional properties to support configuration of class loading, JSP compilation/reloading, security mappings and other.

In order to support configuration of properties on a specific module contained by a was.Ear artifact, new embedded types have been introduced into the hierarchy: was.EmbeddedWebModule and was.EmbeddedEjbModule.

To ensure backwards compatibility with previous versions, all properties (i.e. webServers, virtualHost, sharedLibraries, webClassLoaderMode) are still available on the was.Ear type. When used, those properties will be propagated to all modules inside an Enterprise Application Archive. To override the top-level EAR settings, specify an embedded module CI and set the module specific properties.

Properties configurable on the module level are:

For usage scenario, please see the following deployment package:

<udm.DeploymentPackage version="1.0" application="myapp">
  <deployables>
    <was.Ear name="myapp-ear" file="myapp-ear/myapp-1.0.5.ear">
      <virtualHostName>default_host</virtualHostName>
      <preCompileJsps>true</preCompileJsps>
      <jdkSourceLevel>16</jdkSourceLevel>
      <webModules>
        <was.EmbeddedWebModuleSpec name="myapp-ear/myappWeb.war">
          <contextRoot>/myappWeb</contextRoot>
          <startingWeight>10</startingWeight>
          <classloaderMode>PARENT_LAST</classloaderMode>
          <virtualHostName>proxy_host</virtualHostName>
          <webServerNames>
            <value>webserver-dmz01-zone</value>
          </webServerNames>
          <preCompileJsps>true</preCompileJsps>
          <jdkSourceLevel>15</jdkSourceLevel>
          <sessionManagers>
            <was.SessionManagerSpec name="myapp-ear/myappWeb.war/SessionManager">
              <TuningParams_invalidationTimeout>60</TuningParams_invalidationTimeout>
            </was.SessionManagerSpec>
          </sessionManagers>
          <ejbRefs>
            <was.EjbRefSpec name="myapp-ear/myappWeb.war/ejbConverter">
              <resourceRefName>ejb/Converter</resourceRefName>
              <resourceType>com.xebia.myapp.ejb.Converter</resourceType>
              <resourceJndiName>ejb/ConverterBean</resourceJndiName>
            </was.EjbRefSpec>
          </ejbRefs>
          <resourceRefs>
            <was.ResourceRefSpec name="myapp-ear/myappWeb.war/jdbcmyappdb">
              <resourceRefName>jdbc/myapp_db</resourceRefName>
              <resourceType>javax.sql.DataSource</resourceType>
              <resourceJndiName>jdbc/myapp_db_xa</resourceJndiName>
            </was.ResourceRefSpec>
          </resourceRefs>
        </was.EmbeddedWebModuleSpec>
      </webModules>
      <ejbModules>
        <was.EmbeddedEjbModuleSpec name="myapp-ear/myappEJB.jar">
          <startingWeight>20</startingWeight>
        </was.EmbeddedEjbModuleSpec>
      </ejbModules>
    </was.Ear>
  </deployables>
</udm.DeploymentPackage>

Name of the embedded module should correspond to the WAR or EJB module file name. If this is not possible, additional uri and displayName properties can be set. E.g.:

<was.EmbeddedEjbModuleSpec name="myapp-ear/myapp-ejb">
  <startingWeight>20</startingWeight>
  <uri>myappEJB.jar,META-INF/ejb-jar.xml</uri>
  <moduleDisplayName>myappEJB</moduleDisplayName>
</was.EmbeddedEjbModuleSpec>

JMS resources

New intermediate virtual types have been introduced into the WMQ ConnectionFactory, Destination and Generic ConnectionFactory CI hierarchy and now corresponds the following:

was.JmsResource | <- was.JmsConnectionFactory | <- was.WmqConnectionFactory | <- was.WmqQueueConnectionFactory
                |                             |                             | <- was.WmqTopicConnectionFactory
                |                             |
                |                             | <- was.GenericJmsConnectionFactory | <- was.GenericJmsQueueConnectionFactory
                |                                                                  | <- was.GenericJmsTopicConnectionFactory
                |
                | <- was.WmqDestination | <- was.WmqQueue
                                        | <- was.WmqTopic

Enum class changes

Script changes

WAS plugin 4.0.0

New features

Improvements

• [DEPL-5484] - Extend was.WmqQueue type

Bug fixes

• [DEPL-5445] - was.MailSession, was.MailProvider are destroyed in the wrong order

WAS plugin 3.9.0

New features

• [DEPL-3275] - Add support for generic JMS CIs
• [DEPL-3276] - Additional JDBC providers and data sources
• [DEPL-3277] - Add support for CustomService
• [DEPL-3278] - Add support for ThreadPool
• [DEPL-3279] - Add support for ListenerPort
• [DEPL-3280] - Add support for ServerPort
• [DEPL-3281] - Add support for WorkManager
• [DEPL-3282] - Add support for ResourceEnvironmentEntry
• [DEPL-3283] - Add support for ServletCacheInstance
• [DEPL-3287] - Add support for StringNamespaceBinding
• [DEPL-3288] - Add support for Variable
• [DEPL-4248] - Add support for deploying to dynamic clusters
• [DEPL-4249] - Add support for creating / modifying / setting mode of dynamic cluster via control tasks
• [DEPL-4250] - Add support for discovering dynamic clusters
• [DEPL-4251] - Add support for service policies
• [DEPL-4252] - Add support for deployment of health policies
• [DEPL-4254] - Add support for deploying editioned applications
• [DEPL-4255] - Add support to create / modify dynamic clusters of ODRs via control tasks
• [DEPL-4257] - Add support for discovery of dynamic clusters of ODRs
• [DEPL-4316] - Add support for Resource Environment Providers
• [DEPL-4879] - Add support for MailSession and MailProvider
• [DEPL-5028] - Add support for SiBus
• [DEPL-5032] - Add support for Keystore, CopiedKeystoreFile and SSLConfig

Improvements

• [DEPL-3285] - Improve support for JaasAliases, push changes to runtime automatically
• [DEPL-4165] - Improvements to was.WmqQueue
• [DEPL-4167] - Improvements to was.WmqQueueConnectionFactory
• [DEPL-4666] - Add ability to control WAS container and deployeds
• [DEPL-5031] - Add sharedLibraryNames property (LIST_OF_STRING) to was.Module
• [DEPL-5142] - Make JDBC provider and datasource scripts idempotent

Bug fixes

• [DEPL-2757] - Topology discovery fails when there are multiple servers defined
• [DEPL-3695] - Discovery says "Inspecting cell ..." twice
• [DEPL-3735] - Connection test fails when deploying an Oracle datasource
• [DEPL-4281] - Incorrect default for WAS cell port in description
• [DEPL-4350] - Start application step fails - hangs in an infinite loop
• [DEPL-4409] - Make stop, start script on was.Module not required
• [DEPL-4609] - Only WAR's should be mapped to web servers, not EJB's
• [DEPL-4910] - JAAS alias script will fail if multiple Security objects exist
• [DEPL-5006] - Discovery fixes for data sources, JDBC Providers, MQ Queue connection factory, MQ Queue
• [DEPL-5221] - Duplicate shared library check is too broad

Possible breaking changes / different behavior

The various data source, JDBC provider and JAAS alias scripts were made idempotent. This means they will be more robust against objects already being created. Objects found will be made to look according to what is specified in XL Deploy. If you have local changes to the scripts for these types you will have to verify if your changes are still necessary or work.

A JAAS alias will now be propagated to runtime in an additional step. No server restart needed. This behaviour also applies to data sources were a username and password is specified (and a JAAS alias is created under the hood). As a result the test connection functionality will now work with a newly deployed JAAS alias.

A JAAS alias generated by was.JaasAlias or was.DataSources will now always target Global Security. Previously it would fail if multiple Security objects existed.

Compared to the wasx.ListenerPort type the was.ListenerPort does not support deploying to a Cluster.

Known issues

• The DB2 JDBC Provider and data source types do not work on iSeries DB2

WAS plugin 3.8.3

Re-release of version 3.8.2 to account for some build infrastructure changes. Functionally identical to version 3.8.2.

WAS plugin 3.8.2

Improvements

• [DEPL-3771] - Support existing WAS plugin functionality on WAS 8.5
• [DEPL-4285] - Documentation improvements

Bug fixes

• [DEPL-2563] - The startup order of deployed applications is set to -1 if no value is specified
• [DEPL-2737] - Cannot deploy to a WAS cell that has two servers with the same name on different nodes
• [DEPL-3047] - Can create two shared libraries with the same name in the same scope
• [DEPL-3059] - Can create two JDBC providers with the same name in the same scope
• [DEPL-3426] - Success (return code) of starting app on WAS cluster depends only on the last server
• [DEPL-3882] - Create datasource script does not obtain the global security object correctly

WAS plugin-3.8.1

Improvement

• Improved usability of discovery

WAS plugin-3.8.0

Improvements

• In-depth discovery of WebSphere topologies