Ant tasks for installation of MobileFirst runtime environments

Ant tasks for installation of MobileFirst runtime environments

Reference information for the <configureapplicationserver>, <updateapplicationserver>, and <unconfigureapplicationserver> Ant tasks.

Task effects

<configureapplicationserver>

Configure an application server to run a MobileFirst project WAR file as a web application....

Declare the MobileFirst web application in the specified context root, by default /worklight.

Deploy the project WAR file on the application server.

Declare data sources and - on WAS full profile - JDBC providers for runtime and reports.

Deploy the MobileFirst Server runtime file worklight-jee-library.jar and the database drivers in the application server.

Set JNDI environment entries. These entries override the values contained in worklight.properties inside the WAR file.

On WebSphere Application Server, configure a web container custom property.

<updateapplicationserver>

Update an already-configured MobileFirst web application on an application server...

Update the project WAR file. The file must have the same base name as the project WAR file that was previously deployed.
Update the MobileFirst Server runtime worklight-jee-library.jar library file.

The task does not change the application server configuration, that is, the web application configuration, data sources, and JNDI environment entries.

<unconfigureapplicationserver>

Undo the effects of an earlier <configureapplicationserver> run...

Remove the configuration of the MobileFirst web application with the specified context root. The task also removes the settings that have been added manually to that application.
Remove the project WAR file from the application server.
Remove the data sources and - on WAS full profile - the JDBC providers for runtime and reports.
Remove the MobileFirst Server runtime worklight-jee-library.jar library file and the database drivers from the application server.

Remove the associated JNDI environment entries.

Attributes

Attribute Description Required Default
contextroot Common prefix in URLs to the application (context root) No /worklight
id Distinguishes different deployments No Empty
environmentId Distinguishes different MobileFirst environments No Empty
wasStartingWeight Start order for WAS. Lower values start first. No 2
shortcutsDir Directory where to place shortcuts No None

contextroot and id

Distinguish different MobileFirst projects. By default, when a project is created in v6.0.0 of this product and higher, its context root is the name of the project. The default value of /worklight was chosen to facilitate compatibility with IBM Worklight V5.x applications.
In WAS Liberty profiles and in Tomcat environments, the contextroot parameter is sufficient for this purpose. In WAS full profile environments, the id attribute is used instead.

environmentId

Use the environmentId attribute to distinguish several environments, consisting each of MobileFirst Server administration and MobileFirst runtime web applications, that must operate independently. We must set this attribute to the same value for the runtime application as the one that was set in the <installworklightadmin> invocation, for the administration services application.

wasStartingWeight

Use the wasStartingWeight attribute to specify a value used in WebSphere Application Server as a weight to ensure that a start order is respected. As a result of the start order value, the administrative services web application is deployed and started before any other MobileFirst runtime projects. If MobileFirst projects are deployed or started before the web application, the JMX communication is not established and we cannot manage the project..

shortcutsDir

The shortcutsDir attribute for the <unconfigureApplicationServer> Ant task specifies where to expect the shortcuts to the operations console if it was installed by a version of the <configureApplicationServer> Ant task older than 6.2.0. If we set this attribute, the Ant task might remove the following files from that directory: worklight-console.url, worklight-console.sh, and worklight-console.html.

The <configureapplicationserver>, <updateapplicationserver>, and <unconfigureapplicationserver> tasks support the following elements:

Element Description Count
project Project 1
property Properties 0..∞
applicationserver Application server 1
reports Reports 0..1
database Databases 2

The <project> element specifies details about the project to deploy to the application server. It has the following attributes:

Attribute Description Required Default
warfile Project WAR file Yes None
libraryfile File name of worklight-jee-library.jar No In the same directory as worklight-ant-deployer.jar
migrate Whether to automigrate the WAR file to the current MobileFirst Server version No True
migratedWarBackupFile Where to store a backup of the migrated WAR file No None

To create the warfile attribute, run the <war-builder> Ant task. See Build a project WAR file with Ant.
By default, the WAR file is automatically migrated to the current MobileFirst Server version. In this case, we can request a backup of the migrated WAR file on disk before it is deployed in the application server. To do so, specify a value for the migratedWarBackupFile attribute. If we set the migrate attribute to false, the WAR file is not migrated and, if the MobileFirst version that produced the WAR file is not suitable for the MobileFirst Server version, the deployment fails.
The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:

Attribute Description Required Default value
name Name of the property Yes None
value Value for the property Yes None

For general information about MobileFirst properties, or for a list of properties we can set, see Application server-side configuration parameters.
The <applicationserver> element describes the application server to which the MobileFirst application is deployed. It is a container for one of the following elements:

Element Description Count
websphereapplicationserver or was Parameters for WAS 0..1
tomcat Parameters for Apache Tomcat 0..1

The <websphereapplicationserver> element (or <was> in its short form) denotes a WebSphere Application Server instance, version 7.0 or newer. WAS full profile (Base, and Network Deployment) are supported, as is Liberty profile (Core). Liberty profile Network Deployment is not yet supported. The <websphereapplicationserver> element has the following attributes:

Attribute Description Required Default
installdir WebSphere Application Server installation directory. Yes None
profile WebSphere Application Server profile, or Liberty Yes None
user WebSphere Application Server administrator name Yes, except for Liberty None
password WebSphere Application Server administrator password No Queried interactively

It supports the following elements for single-server deployment:

Element Description Count
server A single server 0..1

The <server> element, used in this context, has the following attributes:

Attribute Description Required Default
name Server name Yes None

It supports the following elements for Network Deployment:

Element Description Count
cell The entire cell 0..1
cluster All servers of a cluster 0..1
node All servers in a node, clusters excluded 0..1
server A single server 0..1

The<cell> element has no attributes.
The <cluster> element has the following attributes:

Attribute Description Required Default
name Cluster name Yes None

The MyNode element has the following attributes:

Attribute Description Required Default
name Node name Yes None

The <server> element, used in a Network Deployment context, has the following attributes:

Attribute Description Required Default
nodeName Node name Yes None
serverName Server name Yes None

The <tomcat> element denotes an Apache Tomcat server. It has the following attributes:

Attribute Description Required Default
installdir Tomcat installation directory. For a Tomcat installation that is split between a CATALINA_HOME directory and a CATALINA_BASE directory, specify the value of the CATALINA_BASE environment variable. Yes None

The <reports> element specifies what set of BIRT *.rptdesign report files to instantiate for access to the database of reports.
The <reports> element has the following attribute:

Attribute Description Required Default
todir Destination directory Yes None

The <reports> element supports the following element:

Element Description Count
fileset Set of files to copy and process 0..∞

A <reports> element without any inner <fileset> element instantiates all the report templates provided in the WorklightServer/report-templates/ directory in the MobileFirst Server distribution.
The <database> element specifies what information is necessary to access a particular database. Two databases must be declared: <database kind="Worklight"> and <database kind="WorklightReports">. The <database> element is specified like the <configuredatabase> Ant task, except that it does not have the <dba> and <client> elements. It might, however, have <property> elements. The<database> element has the following attributes:

Attribute Description Required Default
kind The kind of database: Worklight or WorklightReports Yes None

The<database> element supports the following elements:

Element Description Count
derby Parameters for Derby 0..1
db2 Parameters for DB2 0..1
mysql Parameters for MySQL 0..1
oracle Parameters for Oracle 0..1
driverclasspath JDBC driver class path 0..1

To specify an Apache Derby database

The <derby> element has the following attributes:

Attribute Description Required Default
database Database name No WRKLGHT or WLREPORT, depending on the kind
datadir Directory containing the databases Yes None
schema Schema name No WORKLIGHT

The <derby> element supports the following element:

Element Description Count
property Data source property or JDBC connection property 0..s∞

For more information about the available properties, see the documentation for Class EmbeddedDataSource40. See also the documentation for Class EmbeddedConnectionPoolDataSource40.
For more information about the available properties for a Liberty server, see the documentation for properties.derby.embedded at Liberty profile: Configuration elements in the server.xml file.
When the worklight-ant-deployer.jar file is used within the installation directory of MPF, a<driverclasspath> element is not necessary.

To specify a DB2 database

The <db2> element has the following attributes:

Attribute Description Required Default
database Database name No WRKLGHT or WLREPORT, depending on the kind
server Host name of the database server Yes None
port Port on the database server No 50000
user User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations. Yes None
password Password for accessing databases No Queried interactively
schema Schema name No Depends on the user

For more information about DB2 user accounts, see DB2 security model overview.
The <db2> element supports the following element:

Element Description Count
property Data source property or JDBC connection property 0..∞

For more information about the available properties, see Properties for the IBM Data Server Driver for JDBC and SQLJ.
For more information about the available properties for a Liberty server, see the properties.db2.jcc section at Liberty profile: Configuration elements in the server.xml file.
The <driverclasspath> element must contain JAR files for the DB2 JDBC driver and the associated license. We can download DB2 JDBC drivers from DB2 JDBC Driver Versions.

To specify a MySQL database

The <mysql> element has the following attributes:

Attribute Description Required Default
database Database name No WRKLGHT or WLREPORT, depending on kind
server Host name of the database server Yes None
port Port on the database server No 3306
user User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations. Yes None
password Password for accessing databases No Queried interactively

Instead of database, server, and port, we can also specify a URL. In this case, use the following attributes:

Attribute Description Required Default
url URL for connection to the database Yes None
user User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations. Yes None
password Password for accessing databases No Queried interactively

For more information about MySQL user accounts, see MySQL User Account Management.
The <mysql> element supports the following element:

Element Description Count
property Data source property or JDBC connection property 0..∞

For more information about the available properties, see the documentation at Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J.
For more information about the available properties for a Liberty server, see the properties section at Liberty profile: Configuration elements in the server.xml file.
The <driverclasspath> element must contain a MySQL Connector/J JAR file. We can download it from Download Connector/J.

To specify an Oracle database

The <oracle> element has the following attributes:

Attribute Description Required Default
database Database name No ORCL
server Host name of the database server Yes None
port Port on the database server No 1521
user User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations.
See the note under this table.
Yes None
password Password for accessing databases No Queried interactively

For the user attribute, use preferably a user name in uppercase letters. Oracle user names are generally in uppercase letters. Unlike other database tools, the configureapplicationserver Ant task does not convert lowercase letters to uppercase letters in the user name. If the configureapplicationserver Ant task fails to connect to the database, try to enter the value for the user attribute in uppercase letters.
Instead of database, server, and port, we can also specify a URL. In this case, use the following attributes:

Attribute Description Required Default
url URL for connection to the database Yes None
user User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations.
See the note under this table.
Yes None
password Password for accessing databases No Queried interactively

For the user attribute, use preferably a user name in uppercase letters. Oracle user names are generally in uppercase letters. Unlike other database tools, the configureapplicationserver Ant task does not convert lowercase letters to uppercase letters in the user name. If the configureapplicationserver Ant task fails to connect to the database, try to enter the value for the user attribute in uppercase letters.
For more information about Oracle user accounts, see Overview of Authentication Methods.
For more information about Oracle database connection URLs, see the Database URLs and Database Specifiers section at Data Sources and URLs.
It supports the following elements:

Element Description Count
property Data source property or JDBC connection property 0..∞

For more information about the available properties, see the Data Sources and URLs section at Data Sources and URLs.
For more information about the available properties for a Liberty server, see the properties.oracle section at Liberty profile: Configuration elements in the server.xml file.
The <driverclasspath> element must contain an Oracle JDBC driver JAR file. We can download Oracle JDBC drivers from JDBC, SQLJ, Oracle JPublisher and Universal Connection Pool (UCP).
The <property> element, which can be used inside <derby>, <db2>, <mysql>, or <oracle> elements, has the following attributes:

Attribute Description Required Default
name Name of the property Yes None
type Java type of the property values, usually java.lang.String/Integer/Boolean No java.lang.String
value Value for the property Yes None

Parent topic: Reference

Attribute	Description	Required	Default
contextroot	Common prefix in URLs to the application (context root)	No	/worklight
id	Distinguishes different deployments	No	Empty
environmentId	Distinguishes different MobileFirst environments	No	Empty
wasStartingWeight	Start order for WAS. Lower values start first.	No	2
shortcutsDir	Directory where to place shortcuts	No	None

Element	Description	Count
project	Project	1
property	Properties	0..∞
applicationserver	Application server	1
reports	Reports	0..1
database	Databases	2

Attribute	Description	Required	Default
warfile	Project WAR file	Yes	None
libraryfile	File name of worklight-jee-library.jar	No	In the same directory as worklight-ant-deployer.jar
migrate	Whether to automigrate the WAR file to the current MobileFirst Server version	No	True
migratedWarBackupFile	Where to store a backup of the migrated WAR file	No	None

Attribute	Description	Required	Default value
name	Name of the property	Yes	None
value	Value for the property	Yes	None

Element	Description	Count
websphereapplicationserver or was	Parameters for WAS	0..1
tomcat	Parameters for Apache Tomcat	0..1

Attribute	Description	Required	Default
installdir	WebSphere Application Server installation directory.	Yes	None
profile	WebSphere Application Server profile, or Liberty	Yes	None
user	WebSphere Application Server administrator name	Yes, except for Liberty	None
password	WebSphere Application Server administrator password	No	Queried interactively

Element	Description	Count
cell	The entire cell	0..1
cluster	All servers of a cluster	0..1
node	All servers in a node, clusters excluded	0..1
server	A single server	0..1

Element	Description	Count
derby	Parameters for Derby	0..1
db2	Parameters for DB2	0..1
mysql	Parameters for MySQL	0..1
oracle	Parameters for Oracle	0..1
driverclasspath	JDBC driver class path	0..1

Attribute	Description	Required	Default
database	Database name	No	WRKLGHT or WLREPORT, depending on the kind
datadir	Directory containing the databases	Yes	None
schema	Schema name	No	WORKLIGHT

Attribute	Description	Required	Default
database	Database name	No	WRKLGHT or WLREPORT, depending on kind
server	Host name of the database server	Yes	None
port	Port on the database server	No	3306
user	User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations.	Yes	None
password	Password for accessing databases	No	Queried interactively

Attribute	Description	Required	Default
url	URL for connection to the database	Yes	None
user	User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations.	Yes	None
password	Password for accessing databases	No	Queried interactively

Attribute	Description	Required	Default
database	Database name	No	ORCL
server	Host name of the database server	Yes	None
port	Port on the database server	No	1521
user	User name for accessing databases. This user does not need extended privileges on the databases. If we implement restrictions on the database, we can set a user with the restricted privileges listed in Restrict database user permissions for runtime operations. See the note under this table.	Yes	None
password	Password for accessing databases	No	Queried interactively