Ant tasks for installation of MobileFirst Operational Analytics

The <installanalytics>, <updateanalytics>, and <uninstallanalytics> Ant tasks are provided for the installation of MobileFirst Operational Analytics.

About these Ant tasks

The purpose of these Ant Tasks is to configure the MobileFirst Operational Analytics console and the MobileFirst Operational Analytics service with the appropriate storage for the data on an application server.

The task installs MobileFirst Operational Analytics nodes that act as a master and data. For more information, see Setting up a production cluster.

Task effects

<installanalytics>
The <installanalytics> Ant task configures an application server to run IBM MobileFirst™ Platform Operational Analytics. This task has the following effects:
  • It deploys the MobileFirst Operational Analytics Service and the MobileFirst Operational Analytics Console WAR files on the application server.
  • It declares the MobileFirst Operational Analytics Service web application in the specified context root /analytics-service.
  • It declares the MobileFirst Operational Analytics Console web application in the specified context root /analytics.
  • It sets MobileFirst Operational Analytics Console and MobileFirst Operational Analytics Services configuration properties through JNDI environment entries.
  • On WebSphere® Application Server Liberty profile, it configures the web container.
  • Optionally, it creates users to use the MobileFirst Operational Analytics Console.
<updateanalytics>

The <updateanalytics> Ant task updates the already configured MobileFirst Operational Analytics Service and MobileFirst Operational Analytics Console web applications WAR files on an application server. These files must have the same base names as the project WAR files that were previously deployed.

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

<uninstallanalytics>
The <uninstallanalytics> Ant task undoes the effects of an earlier <installanalytics> run. This task has the following effects:
  • It removes the configuration of both the MobileFirst Operational Analytics Service and the MobileFirst Operational Analytics Console web applications with their respective context roots.
  • It removes the MobileFirst Operational Analytics Service and the MobileFirst Operational Analytics Console WAR files from the application server.
  • It removes the associated JNDI environment entries.

Attributes and elements

The <installanalytics>, <updateanalytics>, and <uninstallanalytics> tasks have the following attributes:

Table 1. Attributes for the <installanalytics>, <updateanalytics>, and <uninstallanalytics> Ant tasks
Attribute Description Required Default
serviceWar The WAR file for the MobileFirst Operational Analytics Service No The analytics-service.war file is in the directory Analytics.
serviceWar

Use the serviceWar attribute to specify a different directory for the MobileFirst Operational Analytics Services WAR file. You can specify the name of this WAR file with an absolute path or a relative path.

The <installanalytics>, <updateanalytics>, and <uninstallanalytics> tasks support the following elements:

Table 2. Inner elements for the <installanalytics>, <updateanalytics>, and <uninstallanalytics> Ant tasks
Attribute Description Required Default
console MobileFirst Operational Analytics Yes 1
user The user to be mapped to a security role. No 0..
storage The type of storage. Yes 1
applicationserver The application server. Yes 1
property Properties. No 0..

To specify a MobileFirst Operational Analytics Console

The <console> element collects information to customize the installation of the MobileFirst Operational Analytics Console. This element has the following attributes:

Table 3. Attributes of the <console> element
Attribute Description Required Default
warfile The console WAR file No The analytics-ui.war file is in the Analytics directory.
shortcutsdir The directory where you place the shortcuts. No None
warFile

Use the warFile attribute to specify a different directory for the MobileFirst Operational Analytics Console WAR file. You can specify the name of this WAR file with an absolute path or a relative path.

shortcutsDir
The shortcutsDir attribute specifies where to place shortcuts to the MobileFirst Operational Analytics Console. If you set this attribute, you can add the following files to that directory:
  • analytics-console.url: This file is a Windows shortcut. It opens the MobileFirst Operational Analytics Console in a browser.
  • analytics-console.sh: This file is a UNIX shell script. It opens the MobileFirst Operational Analytics Console in a browser.
Note: These shortcuts do not include the ElasticSearch tenant parameter.
The <console> element supports the following nested element:
Table 4. Inner element of the <console> element
Element Description Count
property Properties 0..
With this element, you can define your own JNDI properties.
The <property> element has the following attributes:
Table 5. Attributes of the <property> element
Attribute Description Required Default
name The name of the property. Yes None
value The value of the property. Yes None

To specify a user and a security role

The <user> element collects the parameters about a user to include in a certain security role for an application.

Table 6. Attributes of the <user> element
Attribute Description Required Default
role A valid security role for the application. Yes None
name The user name. Yes None
password The password, if the user must be created. No None
After you defined users by using the <user> element, you can map them to any of the following roles for authentication in the MobileFirst Operations Console:
  • worklightmonitor
  • worklightoperator
  • worklightdeployer
  • worklightadmin

To specify a type of storage for MobileFirst Operational Analytics

The <storage> element indicates which underlying type of storage MobileFirst Operational Analytics uses to store the information and data it collects.

It supports the following element:

Table 7. Inner element of the <storage> element
Element Description Count
elasticsearch ElasticSearch cluster 1

The <elasticsearch> element collects the parameters about an ElasticSearch cluster.

Table 8. Attributes of the <elasticsearch> element
Attribute Description Required Default
clusterName The ElasticSearch cluster name. No worklight
nodeName The ElasticSearch node name. This name must be unique in an ElasticSearch cluster. No worklightNode_<random number>
mastersList A comma-delimited string that contains the host name and ports of the ElasticSearch master nodes in the ElasticSearch cluster (For example: hostname1:transport-port1,hostname2:transport-port2) No Depends on the topology
dataPath The ElasticSearch cluster location. No Depends on the application server
shards The number of shards that the ElasticSearch cluster creates. This value can be set only by the master nodes that are created in the ElasticSearch cluster. No 5
replicasPerShard The number of replicas for each shard in the ElasticSearch cluster. This value can be set only by the master nodes that are created in the ElasticSearch cluster. No 1
transportPort The port used for node-to-node communication in the ElasticSearch cluster. No 9600
clusterName

Use the clusterName attribute to specify a name of your choice for the ElasticSearch cluster.

An ElasticSearch cluster consists of one or more nodes that share the same cluster name so you might specify the same value for the clusterName attribute if you configure several nodes.

nodeName

Use the nodeName attribute to specify a name of your choice for the node to configure in the ElasticSearch cluster. Each node name must be unique in the ElasticSearch cluster even if nodes span on several machines.

mastersList

Use the mastersList attribute to provide a comma-separated list of the master nodes in your ElasticSearch cluster. Each master node in this list must be identified by its host name, and the ElasticSearch node-to-node communication port. This port is 9600 by default, or it is the port number that you specified with the attribute transportPort when you configured that master node.

For example: hostname1:transport-port1, hostname2:transport-port2.

Note:
  • If you specify a transportPort that is different than the default value 9600, you must also set this value with the attribute transportPort. By default, when the attribute mastersList is omitted, an attempt is made to detect the host name and the ElasticSearch transport port on all supported application servers.
  • If the target application server is WebSphere Application Server Network Deployment cluster, and if you add or remove a server from this cluster at a later point in time, you must edit this list manually to keep in sync with the ElasticSearch cluster.
dataPath

Use the dataPath attribute to specify a different directory to store ElasticsSearch data. You can specify an absolute path or a relative path.

If the attribute dataPath is not specified, then ElasticSearch cluster data is stored in a default directory that is called analyticsData, whose location depends on the application server:
  • For WebSphere Application Server Liberty profile, the location is ${wlp.user.dir}/servers/serverName/analyticsData.
  • For Apache Tomcat, the location is ${CATALINA_HOME}/bin/analyticsData.
  • For WebSphere Application Server and WebSphere Application Server Network Deployment, the location is ${was.install.root}/profiles/<profileName>/analyticsData.
The directory analyticsData and the hierarchy of sub-directories and files that it contains are automatically created at run time, if they do not already exist when the MobileFirst Operational Analytics Service component receives events.
shards

Use the shards attribute to specify the number of shards to create in the ElasticSearch cluster.

replicasPerShard

Use the replicasPerShard attribute to specify the number of replicas to create for each shard in the ElasticSearch cluster.

Each shard can have zero or more replicas. By default, each shard has one replica, but the number of replicas can be changed dynamically on an existing index in the MobileFirst Operational Analytics. A replica shard can never be started on the same node as its shard.

transportPort

Use the transportPort attribute to specify a port that other nodes in the ElasticSearch cluster must use when communicating with this node. You must ensure that this port is available and accessible if this node is behind a proxy or firewall.

To specify an application server

Use the <applicationserver> element to define the parameters that depend on the underlying application server. The <applicationserver> element supports the following elements.
Note: The attributes and inner elements of this element are described in tables 6 through 12 of Ant tasks for installation of MobileFirst runtime environments.
Table 9. Inner elements of the <applicationserver> element
Element Description Count
websphereapplicationserver or was The parameters for WebSphere Application Server. 0..1
tomcat The parameters for Apache Tomcat. 0..1

To specify custom JNDI properties

The <installanalytics>, <updateanalytics>, and <uninstallanalytics> elements support the following element:
Table 10. Inner element of the <property> element
Element Description Count
property Properties 0..
By using this element, you can define your own JDNI properties.

This element has the following attributes:

Table 11. Attributes of the <property> element
Attribute Description Required Default
name The name of the property. Yes None
value The value of the property. Yes None
Parent topic: Reference