For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.
Ant tasks for installation of MobileFirst Analytics
The installanalytics, updateanalytics, and <uninstallanalytics> Ant tasks are provided for the installation of MobileFirst Analytics.
About these Ant tasks
The purpose of these Ant Tasks is to configure the MobileFirst Analytics console and the MobileFirst Analytics service with the appropriate storage for the data on an application server.
The task installs MobileFirst Analytics nodes that act as a master and data. For more information, see Cluster management and Elasticsearch.
Task effects
- <installanalytics>
The <installanalytics> Ant task configures an application server to run IBM MobileFirst™ Analytics. This task has the following effects:
- It deploys the MobileFirst Analytics Service and the MobileFirst Analytics Console WAR files on the application server.
- It declares the MobileFirst Analytics Service web application in the specified context root /analytics-service.
- It declares the MobileFirst Analytics Console web application in the specified context root /analytics.
- It sets MobileFirst Analytics Console and MobileFirst 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 Analytics Console.
- <updateanalytics>
The <updateanalytics> Ant task updates the already configured MobileFirst Analytics Service and MobileFirst 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 Analytics Service and the MobileFirst Analytics Console web applications with their respective context roots.
- It removes the MobileFirst Analytics Service and the MobileFirst 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 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 Analytics Services WAR file. We 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 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 Analytics Console
The <console> element collects information to customize the installation of the MobileFirst 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 Analytics Console WAR file. We 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 Analytics Console. If you set this attribute, we can add the following files to that directory:
- analytics-console.url: This file is a Windows shortcut. It opens the MobileFirst Analytics Console in a browser.
- analytics-console.sh: This file is a UNIX shell script. It opens the MobileFirst Analytics Console in a browser.
Note: These shortcuts do not include the ElasticSearch tenant parameter.
The <console> element supports the following nested element:
With this element, we can define your own JNDI properties.
Table 4. Inner element of the <console> element Element Description Count property Properties 0.. 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, we can map them to any of the following roles for authentication in the MobileFirst Operations Console:
- mfpmonitor
- mfpoperator
- mfpdeployer
- mfpadmin
To specify a type of storage for MobileFirst Analytics
The <storage> element indicates which underlying type of storage MobileFirst 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, we 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, we 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. We 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 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 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:
By using this element, we can define your own JNDI properties.
Table 10. Inner element of the <property> element Element Description Count property Properties 0.. 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: Installation reference