Ant tasks for installation of MobileFirst runtime environments
Reference information for the <configureapplicationserver>, <updateapplicationserver>, and <unconfigureapplicationserver> Ant tasks.
Task effects
- <configureapplicationserver>
- The <configureapplicationserver> Ant task configures an application server to run a MobileFirst project WAR file as a web application. This task has the following effects.
- It declares the MobileFirst web application in the specified context root, by default /worklight.
- It deploys the project WAR file on the application server.
- It declares data sources and on WebSphere® Application Server full profile JDBC providers for runtime and reports.
- It deploys the MobileFirst Server runtime file worklight-jee-library.jar and the database drivers in the application server.
- It sets MobileFirst configuration properties through JNDI environment entries. These JNDI environment entries override the MobileFirst project default values that are contained in the worklight.properties file inside the WAR file.
- On WebSphere Application Server, it configures a web container custom property.
- <updateapplicationserver>
- The <updateapplicationserver> Ant task updates on an application server a MobileFirst web application that is already configured. This task has the following effects.
- It updates the project WAR file. The file must have the same base name as the project WAR file that was previously deployed.
- It updates the MobileFirst Server runtime worklight-jee-library.jar library file.
- It updates the application server configuration related to BIRT reports, which is a deprecated feature, or, if such reports are no longer used, it sets the value of the JNDI environment entry reports.exportRawData to "false".
Note: On WebSphere Application Server Liberty profile, the task does not change the features, which leaves a potential non-minimal list of features in the server.xml file for the installed application. - <unconfigureapplicationserver>
- The <unconfigureapplicationserver> Ant task
undoes the effects of an earlier <configureapplicationserver> run.
This task has the following effects.
- It removes 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.
- It removes the project WAR file from the application server.
- It removes the data sources and on WebSphere Application Server full profile the JDBC providers for runtime and reports.
- It removes the MobileFirst Server runtime worklight-jee-library.jar library file and the database drivers from the application server.
- It removes the associated JNDI environment entries.
Attributes and elements
The <configureapplicationserver>, <updateapplicationserver>, and <unconfigureapplicationserver> tasks have the following 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 WebSphere Application Server. Lower values start first. | No | 2 |
| shortcutsDir | Directory where to place shortcuts | No | None |
| useWorklightReports | Specifies whether you install the reports database or not. The possible values are true, false, or auto. | No | Auto |
- contextroot and id
The contextroot and id attributes 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 WebSphere Application Server Liberty profiles and in Tomcat environments, the contextroot parameter is sufficient for this purpose. In WebSphere Application Server 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. You 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 that is 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 MobileFirst Administration 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 you cannot manage your MobileFirst projects.
- shortcutsDir
- The shortcutsDir attribute for the <unconfigureApplicationServer> Ant task specifies where to expect the shortcuts to the MobileFirst Operations Console if it was installed by a version of the <configureApplicationServer> Ant task older than V6.2.0. If you set this attribute, the Ant task might remove the following files from that directory: worklight-console.url, worklight-console.sh, and worklight-console.html.
- useWorklightReports
- If this parameter is set to false, the reports data source is not installed. If set to true, the reports data source is installed. If set to auto, the reports data source is installed only if the task contains a database element of kind WorklightReports. This attribute has no effect on the <updateapplicationserver> task when you upgrade, and the status of the reports remains untouched.
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 | 1..2 |
| analytics | Analytics | 0..1 |
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 Building a project WAR file with Ant.
By default, the WAR file is automatically migrated to the current MobileFirst Server version. In this case, you 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 you 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 that you can set, see Configuration of MobileFirst applications on the server.
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 WebSphere Application Server | 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 later. WebSphere Application Server 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 |
| libertyEncoding | Algorithm to encode data source passwords for WebSphere Application Server Liberty.
The possible values are none, xor,
and aes. Note: aes is not supported
for WebSphere Application Server Liberty V8.5.0.x.
For the other versions, it is supported only with the default key.
On WebSphere Application Server Liberty 8.5.5.x, if the aes encoding is requested, the clear password is passed as argument to the sercurityUtility program, which is called through an external process. You can see the password with a ps command, or in the /proc file system on UNIX operating systems. |
No | xor |
| libertyAESKey | Do not set this property because the aes custom key is not supported. | No |
It supports the following elements for single-server deployment:
| Element | Description | Count |
|---|---|---|
| server | A single server | 0..1 |
The <server> element, which is 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 <node> element has the following attributes:
| Attribute | Description | Required | Default |
|---|---|---|---|
| name | Node name | Yes | None |
The <server> element, which is 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 that are 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 |
| validate | To validate whether the database is accessible or not. The possible values are true or false. | No | true |
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 |
| cloudant | Parameters for Cloudant® | 0..1 |
| driverclasspath | JDBC driver class path Note: This element is
not relevant to Cloudant
|
0..1 |
| Attribute | Description | Required | Default |
|---|---|---|---|
| install | Whether to connect the MobileFirst runtime to MobileFirst Operational Analytics | No | true |
| analyticsURL | MobileFirst Operational Analytics Services URL | Yes | None |
| consoleURL | MobileFirst Operational Analytics Console URL | Yes | None |
| username | The user name | Yes | None |
| password | The password | Yes | None |
| validate | To validate whether the MobileFirst Operational Analytics Console is accessible or not. | No | true |
| forwardLogs | Whether to send server logs to MobileFirst Operational Analytics | No | true |
| tenant | The tenant for indexing data that is collected from a MobileFirst runtime. | No | None |
- install
-
Use the install attribute to indicate that this MobileFirst runtime must be connected and send events to MobileFirst Operational Analytics. Valid values are true or false.
- analyticsURL
-
Use the analyticsURL attribute to specify the URL that is exposed by MobileFirst Operational Analytics, which receives incoming analytics data.
For example: http://<hostname>:<port>/analytics-service/data
Note: Optionally, you might append a tenant to this URL. For more information, see Multi-tenancy. - consoleURL
-
Use the consoleURL attribute to the URL that is exposed by MobileFirst Operational Analytics, which links to the MobileFirst Operational Analytics console.
For example: http://<hostname>:<port>/analytics/console
Note: Optionally, you might append a tenant to this URL. For more information, see Multi-tenancy. - username
-
Use the username attribute to specify the user name that is used if the data entry point for the MobileFirst Operational Analytics is protected with basic authentication.
- password
-
Use the password attribute to specify the password that is used if the data entry point for the MobileFirst Operational Analytics is protected with basic authentication.
- validate
-
Use the validate attribute to validate whether the MobileFirst Operational Analytics Console is accessible or not, and to check the user name authentication with a password. The possible values are true, or false
- forwardLogs
-
When the forwardLogs attribute is set to true, server logs that are recorded on the MobileFirst Server are captured and forwarded to the MobileFirst Operational Analytics.
- tenant
-
For more information about this attribute, see Multi-tenancy.
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 that contains 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 IBM MobileFirst™ Platform Foundation, 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 you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Restricting database user permissions for IBM MobileFirst Platform Server 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. You 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 you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Restricting database user permissions for IBM MobileFirst Platform Server runtime operations. | Yes | None |
| password | Password for accessing databases | No | Queried interactively |
Instead of database, server, and port, you 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 you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Restricting database user permissions for IBM MobileFirst Platform Server 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. You 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, or Oracle service name Note: You
must always use a service name to connect to a PDB database.
|
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 you implement
restrictions on the database, you can set a user with the restricted
privileges that are listed in Restricting database user permissions for IBM MobileFirst Platform Server runtime
operations. See the note under this table. |
Yes | None |
| password | Password for accessing databases | No | Queried interactively |
Instead of database, server, and port, you 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 you implement
restrictions on the database, you can set a user with the restricted
privileges that are listed in Restricting database user permissions for IBM MobileFirst Platform Server runtime
operations. See the note under this table. |
Yes | None |
| password | Password for accessing databases | No | Queried interactively |
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. You 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 |
To specify a Cloudant database
The <cloudant> element has the following attributes:
| Attribute | Description | Required | Default |
|---|---|---|---|
| url | The URL of the Cloudant account | No | https://user.cloudant.com |
| user | The user name of the Cloudant account | Yes | None |
| password | The password of the Cloudant account | No | Queried interactively |
| dbNamePrefix | The prefix that is added to the database name
of the MobileFirst runtime. For example, if the value department is assigned to this attribute, and the context root of your MobileFirst runtime is /mfp, the database name would be department_mfp_runtime_db. Important: This prefix must start with a lowercase letter, and
can contain only lowercase characters (a-z), digits (0-9), and any
of the following characters: _, $, -.
|
No | Empty string |
| connectTimeout | The timeout to establish a connection, in milliseconds. A value of zero means an infinite timeout. | No | Undocumented default value |
| socketTimeout | The timeout to wait for a response, in milliseconds. A value of zero means an infinite timeout. | No | Undocumented default value |
| maxConnections | The maximum number of connections to the database. | No | Undocumented default value |
| proxyHost | The host name to connect through the proxy | No | Undocumented default value |
| proxyPort | The proxy port | No | Undocumented default value |