Installation Reference

Overview

Reference information about Ant tasks and configuration sample files for the installation of Persistent Mobile Foundation Server, Persistent Mobile Foundation Application Center, and Persistent Mobile Foundation Operational Analytics.

Jump to

• Ant configuredatabase task reference
• Ant tasks for installation of PMF Operations Console, PMF artifacts, PMF administration, and live update services
• Ant tasks for installation of PMF push service
• Ant tasks for installation of PMF runtime environments
• Ant tasks for installation of PMF Application Center
• Ant tasks for installation of PMF Analytics
• Internal runtime databases
• Sample configuration files
• Sample configuration files for PMF Analytics

Ant configuredatabase task reference

This reference information is for relational databases.

The configuredatabase Ant task creates the relational databases that are used by PMF administration service, PMF live update service, PMF push service, PMF runtime, and the PMF Application Center services. This Ant task configures a relational database through the following actions:

• Checks whether the PMF tables exist in the database and creates them if necessary.
• If the tables exist for an older version of PMF, migrates them to the current version.
• If the tables exist for the current version of PMF, does nothing.

In addition, if one of the following conditions is met:

• The DBMS type is Derby.
• An inner element <dba> is present.
• The DBMS type is DB2 , and the specified user has the permissions to create databases.

Then, the task can have the following effects:

• Create the database if necessary (except for Oracle 12c).
• Create a user, if necessary, and grants that user access rights to the database.

Attributes and elements for configuredatabase task

The configuredatabase task has the following attributes:

kind

PMF supports four kinds of database: PMF runtime uses MobileFirstRuntime database. PMF administration service uses the MobileFirstAdmin database. PMF Live Update service uses the MobileFirstConfig database. By default, it is created with MobileFirstAdmin kind. PMF push service uses the push database. PMF Application Center uses the ApplicationCenter database.

includeConfigurationTables

The includeConfigurationTables attribute can be used only when the kind attribute is MobileFirstAdmin. The valid value can be true or false. When this attribute is set to true, the configuredatabase task performs database operations on both the administration service database and the Live Update service database in a single run. When this attribute is set to false, the configuredatabase task performs database operations only on the administration service database.

execute

The execute attribute enables or disables the execution of the configuredatabase Ant task. The valid value can be true or false. When this attribute is set to false, the configuredatabase task performs no configuration or database operations.

The configuredatabase task supports the following elements:

For each database type, you can use a <property> element to specify a JDBC connection property for access to the database. The <property> element has the following attributes:

Apache Derby

The <derby> element has the following attributes:

The <derby> element supports the following element:

For the available properties, see Setting attributes for the database connection URL.

DB2

The <db2> element has the following attributes:

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

For the available properties, see Properties for the IBM Data Server Driver for JDBC and SQLJ.
The inner element <dba> specifies the credentials for the database administrators. This element has the following attributes:

The user that is specified in a <dba> element must have the SYSADM or SYSCTRL DB2 privilege. For more information, see Authorities overview.

The <driverclasspath> element must contain the JAR files for the DB2 JDBC driver and for the associated license. You can retrieve those files in one of the following ways:

• Download DB2 JDBC drivers from the DB2 JDBC Driver Versions page
• Or fetch the db2jcc4.jar file and its associated db2jcc_license_*.jar files from the DB2_INSTALL_DIR/java directory on the DB2 server.

You cannot specify details of table allocations, such as the table space, by using the Ant task. To control the table space, you must use the manual instructions in section DB2 database and user requirements.

MySQL

The element <mysql> has the following attributes:

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

For the available properties, see Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J.
The inner element <dba> specifies the database administrator credentials. This element has the following attributes:

The user that is specified in a <dba> element must be a MySQL superuser account. For more information, see Securing the Initial MySQL Accounts.

Each <client> inner element specifies a client computer or a wildcard for client computers. These computers are allowed to connect to the database. This element has the following attributes:

For more information about the hostname syntax, see Specifying Account Names.

The <driverclasspath> element must contain a MySQL Connector/J JAR file. You can download that file from the Download Connector/J page.

Alternatively, you can use the <mysql> element with the following attributes:

Note: If you specify the database with the alternative attributes, this database must exist, the user account must exist, and the database must already be accessible to the user. In this case, the configuredatabase task does not attempt to create the database or the user, nor does it attempt to grant access to the user. The configuredatabase task ensures only that the database has the required tables for the current PMF version. You do not have to specify the inner elements <dba> or <client>.

Oracle

The element <oracle> has the following attributes:

Note: 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 configuredatabase Ant task does not convert lowercase letters to uppercase letters in the user name. If the configuredatabase Ant task fails to connect to your 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.
The <oracle> element supports the following elements:

For information about the available connection properties, see Class OracleDriver.
The inner element <dba> specifies the database administrator credentials. This element has the following attributes:

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).

You cannot specify details of table allocation, such as the table space, by using the Ant task. To control the table space, you can create the user account manually and assign it a default table space before you run the Ant task. To control other details, you must use the manual instructions in section Oracle database and user requirements.

Note: If you specify the database with the alternative attributes, this database must exist, the user account must exist, and the database must already be accessible to the user. In this case, the task does not attempt to create the database or the user, nor does it attempt to grant access to the user. The configuredatabase task ensures only that the database has the required tables for the current PMF version. You do not have to specify the inner element <dba>.

Ant tasks for installation of PMF Operations Console, PMF artifacts, PMF administration, and PMF live update services

The installpmfadmin, updatepmfadmin, and uninstallpmfadmin Ant tasks are provided for the installation of PMF Operations Console, the artifacts component, the administration service, and the live update service.

Task effects

installpmfadmin

The installpmfadmin Ant task configures an application server to run the WAR files of the administration and live update services as web applications, and optionally, to install the PMF Operations Console. This task has the following effects:

• It declares the administration service web application in the specified context root, by default /mfpadmin.
• It declares the live update service web application in a context root derived from the specified context root of the administration service. By default, /mfpadminconfig.
• For the relational databases, it declares data sources and on WebSphere Application Server full profile, JDBC providers for the administration services.
• It deploys the administration service and the live update service on the application server.
• Optionally, it declares PMF Operations Console as a web application in the specified context root, by default /mfpconsole. If the PMF Operations Console instance is specified, the Ant task declares the appropriate JNDI environment entry to communicate with the corresponding management service. For example,

<target name="adminstall">
  <installpmfadmin servicewar="${mfp.service.war.file}">
    <console install="${mfp.admin.console.install}" warFile="${mfp.console.war.file}"/>

• Optionally, it declares the PMF artifacts web application in the specified context root /mfp-dev-artifacts when PMF Operations Console is installed.
• It configures the configuration properties for the administration service by using JNDI environment entries. These JNDI environment entries also give some additional information about the application server topology, for example whether the topology is a stand-alone configuration, a cluster, or a server farm.
• Optionally, it configures users that it maps to roles used by PMF Operations Console, and the administration and live update services web applications.
• It configures the application server for use of JMX.
• Optionally, it configures the communication with the PMF push service.
• Optionally, it sets the Mobile Foundation JNDI environment entries to configure the application server as a server farm member for the PMF administration part.

updatepmfadmin

The updatepmfadmin Ant task updates an already-configured PMF web application on an application server. This task has the following effects:

• It updates the administration service WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
• It updates the live update service WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
• It updates the PMF Operations Console WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed. The task does not change the application server configuration, that is, the web application configuration, data sources, JNDI environment entries, user-to-role mappings, and JMX configuration.

uninstallpmfadmin

The uninstallpmfadmin Ant task undoes the effects of an earlier run of installpmfadmin. This task has the following effects:

• It removes the configuration of the administration service web application with the specified context root. As a consequence, the task also removes the settings that were added manually to that application.
• It removes the WAR files of the administration and live update services, and PMF Operations Console from the application server as an option.
• For the relational DBMS, it removes the data sources and on WebSphere Application Server Full Profile the JDBC providers for the administration and live update services.
• For the relational DBMS, it removes the database drivers that were used by the administration and live update services from the application server.
• It removes the associated JNDI environment entries.
• On WebSphere Application Server Liberty and Apache Tomcat, it removes the users configured by the installpmfadmin invocation.
• It removes the JMX configuration.

Attributes and elements

The installpmfadmin, updatepmfadmin, and uninstallpmfadmin Ant tasks have the following attributes:

contextroot and id

The contextroot and id attributes distinguish different deployments of PMF Operations Console and the administration service.

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. Without this id attribute, two WAR files with the same context roots might conflict and these files would not be deployed.

environmentId

Use the environmentId attribute to distinguish several environments, consisting each of PMF administration service and PMF runtime web applications, that must operate independently. For example, with this option you can host a test environment, a pre-production environment, and a production environment on the same server or in the same WebSphere Application Server Network Deployment cell. This environmentId attribute creates a suffix that is added to MBean names that the administration service and the PMF runtime projects use when they communicate through Java Management Extensions (JMX).

servicewar

Use the servicewar attribute to specify a different directory for the administration service 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 PMF Operations Console. If you set this attribute, you can add the following files to that directory:

• mobilefirst-console.url - this file is a Windows shortcut. It opens the PMF Operations Console in a browser.
• mobilefirst-console.sh- this file is a UNIX shell script and opens the PMF Operations Console in a browser.
• mobilefirst-admin-service.url - this file is a Windows shortcut. It opens in a browser and calls a REST service that returns a list of the PMF projects that can be managed in JSON format. For each listed PMF project, some details are also available about their artifacts, such as the number of applications, the number of adapters, the number of active devices, the number of decommissioned devices. The list also indicates whether the PMF project runtime is running or idle.
• mobilefirst-admin-service.sh - this file is a UNIX shell script that provides the same output as the mobilefirst-admin-service.url file.

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 administration service web application is deployed and started before any other PMF runtime projects. If PMF projects are deployed or started before the web application, the JMX communication is not established and the runtime cannot synchronize with the administration service database and cannot handle server requests.

The installpmfadmin, updatepmfadmin, and uninstallpmfadmin Ant tasks support the following elements:

To specify a PMF Operations Console

The <console> element collects information to customize the installation of the PMF Operations Console. This element has the following attributes:

The <console> element supports the following element:

The <artifacts> element has the following attributes:

By using this element, you can define your own JNDI properties or override the default value of the JNDI properties that are provided by the administration service and the PMF Operations Console WAR files.

The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:

By using this element, you can define your own JNDI properties or override the default value of the JNDI properties that are provided by the administration service and the PMF Operations Console WAR files.

For more information about the JNDI properties, see List of JNDI properties for PMF administration service.

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.

The attributes and inner elements of these elements are described in the tables of Ant tasks for installation of PMF runtime environments.
However, for the inner element of the <was> element for Liberty collective, see the following table:

The <collectiveController> element has the following attributes:

To specify the live update service configuration

Use the <configuration> element to define the parameters that depend on the live update service. The <configuration> element has the following attributes.

The <configuration> element supports the following elements:

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

After you defined the users by using the <user> element, you can map them to any of the following roles for authentication in PMF Operations Console: configadmin.

For more information about which authorizations are implied by the specific roles, see Configuring user authentication for PMF administration.

Tip: If the users exist in an external LDAP directory, set only the role and name attributes but do not define any passwords.

The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:

By using this element, you can define your own JNDI properties or override the default value of the JNDI properties that are provided by the administration service and the PMF Operations Console WAR files. For more information about the JNDI properties, see List of JNDI properties for PMF administration service.

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:

The attributes and inner elements of these elements are described in the tables of Ant tasks for installation of PMF runtime environments.
However, for the inner element of the element for Liberty collective, see the following table:

The <collectiveMember> element has the following attributes:

Note: If the push service and the runtime components are installed in the same collective member, then they must have the same cluster name. If these components are installed on distinct members of the same collective, the cluster names can be different.

To specify Analytics

The <analytics> element indicates that you want to connect the PMF push service to an already installed Persistent Mobile Foundation Analytics service. It has the following attributes:

install
Use the install attribute to indicate that this push service must be connected and send events to Persistent Mobile Foundation Analytics. Valid values are true or false.

analyticsURL
Use the analyticsURL attribute to specify the URL that is exposed by Persistent Mobile Foundation Analytics, which receives incoming analytics data.

For example: http://<hostname>:<port>/analytics-service/rest

username
Use the username attribute to specify the user name that is used if the data entry point for the Persistent Mobile Foundation 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 Persistent Mobile Foundation Analytics is protected with basic authentication.

validate
Use the validate attribute to validate whether the PMF Analytics Console is accessible or not, and to check the user name authentication with a password. The possible values are true, or false.

To specify a connection to the push service database

The <database> element collects the parameters that specify a data source declaration in an application server to access the push service database.

You must declare a single database: <database kind="Push">. You specify the <database> element similarly to the configuredatabase Ant task, except that the <database> element does not have the <dba> and <client> elements. It might have <property> elements.

The <database> element has the following attributes:

The <database> element supports the following elements. For more information about the configuration of these database elements for relational DBMS, see the tables of Ant tasks for installation of PMF runtime environments.

Note: The attributes of the <cloudant> element are slightly different from the runtime. For more information, see the following table:

Ant tasks for installation of PMF push service

The installmobilefirstpush, updatemobilefirstpush, and uninstallmobilefirstpush Ant tasks are provided for the installation of the push service.

Task effects

installmobilefirstpush

The installmobilefirstpush Ant task configures an application server to run the push service WAR file as web application. This task has the following effects: It declares the push service web application in the /imfpush context root. The context root cannot be changed. For the relational databases, it declares data sources and, on WebSphere Application Server Full Profile, JDBC providers for push service. It configures the configuration properties for the push service by using JNDI environment entries. These JNDI environment entries configure the OAuth communication with the PMF authorization server, Persistent Mobile Foundation Analytics, and with Cloudant in case Cloudant is used.

updatemobilefirstpush

The updatemobilefirstpush Ant task updates an already-configured PMF web application on an application server. This task updates the push service WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.

uninstallmobilefirstpush

The uninstallmobilefirstpush Ant task undoes the effects of an earlier run of installmobilefirstpush. This task has the following effects: It removes the configuration of the push service web application with the specified context root. As a consequence, the task also removes the settings that were added manually to that application. It removes the push service WAR file from the application server as an option. For the relational DBMS, it removes the data sources and on WebSphere Application Server Full Profile – the JDBC providers for the push service. It removes the associated JNDI environment entries.

Attributes and elements

The installmobilefirstpush, updatemobilefirstpush, and uninstallmobilefirstpush Ant tasks have the following attributes:

Id

The id attribute distinguishes different deployments of the push service in the same WebSphere Application Server cell. Without this id attribute, two WAR files with the same context roots might conflict and these files would not be deployed.

warFile

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

The installmobilefirstpush, updatemobilefirstpush, and uninstallmobilefirstpush Ant tasks support the following elements:

To specify the authorization server

The <authorization> element collects information to configure the authorization server for the authentication communication with other PMF components. This element has the following attributes:

auto

If the value is set to true, the URL of the authorization server is computed automatically by using the context root of the runtime on the local application server. The auto mode is not supported if you deploy on WebSphere Application Server Network Deployment on a cluster.

authorizationURL

The URL of the authorization server. If the authorization server is the PMF runtime, the URL is the URL of the runtime. For example: http://myHost:9080/mfp.

runtimeContextRoot

The context root of the runtime that is used to compute the URL of the authorization server in the automatic mode.

pushClientID

The ID of this push service instance as a confidential client of the authorization server. The ID and the secret must be registered for the authorization server. It can be registered by installmobilefirstadmin Ant task, or from PMF Operations Console.

pushClientSecret

The secret key of this push service instance as a confidential client of the authorization server. The ID and the secret must be registered for the authorization server. It can be registered by installmobilefirstadmin Ant task, or from PMF Operations Console.

The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:

By using this element, you can define your own JNDI properties or override the default value of the JNDI properties that are provided by the push service WAR file.

For more information about the JNDI properties, see List of JNDI properties for PMF push service.

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:

The attributes and inner elements of these elements are described in the tables of Ant tasks for installation of PMF runtime environments.

However, for the inner element of the <was> element for Liberty collective, see the following table:

The <collectiveMember> element has the following attributes:

Note: If the push service and the runtime components are installed in the same collective member, then they must have the same cluster name. If these components are installed on distinct members of the same collective, the cluster names can be different.

To specify Analytics

The <analytics> element indicates that you want to connect the PMF push service to an already installed Persistent Mobile Foundation Analytics service. It has the following attributes:

install

Use the install attribute to indicate that this push service must be connected and send events to Persistent Mobile Foundation Analytics. Valid values are true or false.

analyticsURL

Use the analyticsURL attribute to specify the URL that is exposed by Persistent Mobile Foundation Analytics, which receives incoming analytics data.
For example: http://<hostname>:<port>/analytics-service/rest

username

Use the username attribute to specify the user name that is used if the data entry point for the Persistent Mobile Foundation 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 Persistent Mobile Foundation Analytics is protected with basic authentication.

validate

Use the validate attribute to validate whether the PMF Analytics Console is accessible or not, and to check the user name authentication with a password. The possible values are true, or false.

To specify a connection to the push service database

The <database> element collects the parameters that specify a data source declaration in an application server to access the push service database.

You must declare a single database: <database kind="Push">. You specify the <database> element similarly to the configuredatabase Ant task, except that the <database> element does not have the <dba> and <client> elements. It might have <property> elements.

The <database> element has the following attributes:

The <database> element supports the following elements. For more information about the configuration of these database elements for relational DBMS, see the tables in Ant tasks for installation of PMF runtime environments.

Note: The attributes of the <cloudant> element are slightly different from the runtime. For more information, see the following table:

Ant tasks for installation of PMF runtime environments

Reference information for the installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime Ant tasks.

Task effects

installmobilefirstruntime

The installmobilefirstruntime Ant task configures an application server to run a PMF runtime WAR file as a web application. This task has the following effects.

• It declares the PMF web application in the specified context root, by default /mfp.
• It deploys the runtime WAR file on the application server.
• It declares data sources and on WebSphere Application Server full profile JDBC providers for the runtime.
• It deploys the database drivers in the application server.
• It sets PMF configuration properties through JNDI environment entries.
• Optionally, it sets the PMF JNDI environment entries to configure the application server as a server farm member for the runtime.

updatemobilefirstruntime

The updatemobilefirstruntime Ant task updates a PMF runtime that is already configured on an application server. This task updates the runtime WAR file. The file must have the same base name as the runtime WAR file that was previously deployed. Other than that, the task does not change the application server configuration, that is, the web application configuration, data sources, and JNDI environment entries.

uninstallmobilefirstruntime

The uninstallmobilefirstruntime Ant task undoes the effects of an earlier installmobilefirstruntime run. This task has the following effects.

• It removes the configuration of the PMF web application with the specified context root. The task also removes the settings that are added manually to that application.
• It removes the runtime WAR file from the application server.
• It removes the data sources and on WebSphere Application Server full profile the JDBC providers for the runtime.
• It removes the associated JNDI environment entries.

Attributes and elements

The installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime Ant tasks have the following attributes:

contextroot and id

The contextroot and id attributes distinguish different PMF projects.

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 PMF administration service and PMF 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 invocation, for the administration service application.

warFile

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

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 PMF administration service web application is deployed and started before any other PMF runtime projects. If PMF projects are deployed or started before the web application, the JMX communication is not established and you cannot manage your PMF projects.

The installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime tasks support the following elements:

The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:

The <applicationserver> element describes the application server to which the PMF application is deployed. It is a container for one of the following elements:

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

It supports the following element for single-server deployment:

The element, which is used in this context, has the following attribute:

It supports the following elements for Liberty collective:

The <collectiveMember> element has the following attributes:

It supports the following elements for Network Deployment:

The <cell> element has no attributes.

The <cluster> element has the following attribute:

The <node> element has the following attribute:

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

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

The <database> element specifies what information is necessary to access a particular database. The <database> element is specified like the configuredatabase Ant task, except that it does not have the <dba> and <client> elements. However, it might have <property> elements. The <database> element has the following attributes:

The <database> element supports the following elements:

The <analytics> element indicates that you want to connect the PMF runtime to an already installed PMF Analytics Console and services. It has the following attributes:

install

Use the install attribute to indicate that this PMF runtime must be connected and send events to Persistent Mobile Foundation Analytics. Valid values are true or false.

analyticsURL

Use the analyticsURL attribute to specify the URL that is exposed by Persistent Mobile Foundation Analytics, which receives incoming analytics data.
For example: http://<hostname>:<port>/analytics-service/rest

consoleURL

Use the consoleURL attribute to the URL that is exposed by Persistent Mobile Foundation Analytics, which links to the PMF Analytics Console.
For example: http://<hostname>:<port>/analytics/console

username

Use the username attribute to specify the user name that is used if the data entry point for the Persistent Mobile Foundation 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 Persistent Mobile Foundation Analytics is protected with basic authentication.

validate

Use the validate attribute to validate whether the PMF Analytics Console is accessible or not, and to check the user name authentication with a password. The possible values are true, or false.

tenant

For more information about this attribute, see Configuration properties.

To specify an Apache Derby database

The <derby> element has the following attributes:

The <derby> element supports the following element:

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 mfp-ant-deployer.jar file is used within the installation directory of PMF, a <driverclasspath> element is not necessary.

To specify a DB2 database

The <db2> element has the following attributes:

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

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:

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

For more information about MySQL user accounts, see MySQL User Account Management.

The <mysql> element supports the following element:

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:

Note: 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 installmobilefirstruntime Ant task does not convert lowercase letters to uppercase letters in the user name. If the installmobilefirstruntime Ant task fails to connect to your database, try to enter the value for the user attribute in uppercase letters.

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

Note: 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 installmobilefirstruntime Ant task does not convert lowercase letters to uppercase letters in the user name. If the installmobilefirstruntime Ant task fails to connect to your 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 element:

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:

Ant tasks for installation of PMF Application Center

The <installApplicationCenter>, <updateApplicationCenter>, and <uninstallApplicationCenter> Ant tasks are provided for the installation of the Application Center Console and Services.

Task effects

installApplicationCenter

The <installApplicationCenter> task configures an application server to run the Application Center Services WAR file as a web application, and to install the Application Center Console. This task has the following effects:

• It declares the Application Center Services web application in the /applicationcenter context root.
• It declares data sources, and on WebSphere Application Server full profile, it declares also JDBC providers for Application Center Services.
• It deploys the Application Center Services web application on the application server.
• It declares the Application Center Console as a web application in the /appcenterconsole context root.
• It deploys the Application Center Console WAR file on the application server.
• It configures configuration properties for Application Center Services by using JNDI environment entries. The JNDI environment entries that are related to the endpoint and proxies are commented. You must uncomment them in some cases.
• It configures users that it maps to roles used by the Application Center Console and Services web applications.
• On WebSphere Application Server, it configures the necessary custom property for the web container.

updateApplicationCenter

The <updateApplicationCenter> task updates an already configured Application Center application on an application server. This task has the following effects:

• It updates the Application Center Services WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
• It updates the Application Center Console WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.

The task does not change the application server configuration, that is, the web application configuration, data sources, JNDI environment entries, and user-to-role mappings. This task applies only to an installation that is performed by using the task that is described in this topic.

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.

uninstallApplicationCenter

The <uninstallApplicationCenter> Ant task undoes the effects of an earlier run of <installApplicationCenter>. This task has the following effects:

• It removes the configuration of the Application Center Services web application with the /applicationcenter context root. As a consequence, the task also removes the settings that were added manually to that application.
• It removes both the Application Center Services and Console WAR files from the application server.
• It removes the data sources and, on WebSphere Application Server full profile, it also removes the JDBC providers for the Application Center Services.
• It removes the database drivers that were used by Application Center Services from the application server.
• It removes the associated JNDI environment entries.
• It removes the users who are configured by the <installApplicationCenter> invocation.

Attributes and elements

The <installApplicationCenter>, <updateApplicationCenter>, and <uninstallApplicationCenter> tasks have the following attributes:

id

In WebSphere Application Server full profile environments, the id attribute is used to distinguish different deployments of Application Center Console and Services. Without this id attribute, two WAR files with the same context roots might conflict and these files would not be deployed.

servicewar

Use the servicewar attribute to specify a different directory for the Application Center Services 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 Application Center Console. If you set this attribute, the following files are added to this directory:

• appcenter-console.url: This file is a Windows shortcut. It opens the Application Center Console in a browser.
• appcenter-console.sh: This file is a UNIX shell script. It opens the Application Center Console in a browser.

aaptDir

The aapt program is part of the PMF distribution: product_install_dir/ApplicationCenter/tools/android-sdk.
If this attribute is not set, during the upload of an apk application, Application Center parses it by using its own code, which might have limitations.

The <installApplicationCenter>, <updateApplicationCenter>, and <uninstallApplicationCenter> tasks support the following elements:

To specify an Application Center console

The <console> element collects information to customize the installation of the Application Center Console. This element has the following attributes:

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.

The attributes and inner elements of these elements are described in the tables of the page Ant tasks for installation of PMF runtime environments.

To specify a connection to the services database

The <database> element collects the parameters that specify a data source declaration in an application server to access the services database.

You must declare a single database: <database kind="ApplicationCenter">. You specify the <database> element similarly to the <configuredatabase> Ant task, except that the <database> element does not have the <dba> and <client> elements. It might have <property> elements.

The <database> element has the following attributes:

The <database> element supports the following elements. For more information about the configuration of these database elements, see the tables in Ant tasks for installation of PMF runtime environments.

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.

Ant tasks for installation of Persistent Mobile Foundation Analytics

The installanalytics, updateanalytics, and uninstallanalytics Ant tasks are provided for the installation of Persistent Mobile Foundation Analytics.

The purpose of these Ant Tasks is to configure the PMF Analytics Console and the Persistent Mobile Foundation Analytics service with the appropriate storage for the data on an application server. The task installs Persistent Mobile Foundation Analytics node that act as a primary node and data controller. For more information, see Cluster management and Elasticsearch.

Task effects

installanalytics

The installanalytics Ant task configures an application server to run Persistent Persistent Mobile Foundation Analytics. This task has the following effects:

• It deploys the Persistent Mobile Foundation Analytics Service and the PMF Analytics Console WAR files on the application server.
• It declares the Persistent Mobile Foundation Analytics Service web application in the specified context root /analytics-service.
• It declares the PMF Analytics Console web application in the specified context root /analytics.
• It sets PMF Analytics Console and Persistent Mobile Foundation 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 PMF Analytics Console.

updateanalytics

The updateanalytics Ant task updates the already configured Persistent Mobile Foundation Analytics Service and PMF 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 Persistent Mobile Foundation Analytics Service and the PMF Analytics Console web applications with their respective context roots.
• It removes the Persistent Mobile Foundation Analytics Service and the PMF 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:

serviceWar

Use the serviceWar attribute to specify a different directory for the Persistent Mobile Foundation 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:

To specify a PMF Analytics Console

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

warFile

Use the warFile attribute to specify a different directory for the PMF 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 PMF 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 PMF Analytics Console in a browser.
• analytics-console.sh: This file is a UNIX shell script. It opens the PMF 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, you can define your own JNDI properties.

The <property> element has the following attributes:

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.

After you defined users by using the <user> element, you can map them to any of the following roles for authentication in the PMF Operations Console:

• mfpmonitor
• mfpoperator
• mfpdeployer
• mfpadmin

To specify a type of storage for Persistent Mobile Foundation Analytics

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

It supports the following element:

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

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 Persistent Mobile Foundation 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 Persistent Mobile Foundation 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 the tables of Ant tasks for installation of PMF runtime environments.

To specify custom JNDI properties

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

By using this element, you can define your own JNDI properties.

This element has the following attributes:

Internal runtime databases

Learn about runtime database tables, their purpose, and order of magnitude of data stored in each table. In relational databases, the entities are organized in database tables.

Database used by PMF runtime

The following table provides a list of runtime database tables, their descriptions, and how they are used in relational databases.

Database used by PMF administration service

The following table provides a list of administration database tables, their descriptions, and how they are used in relational databases.

Database used by PMF live update service

The following table provides a list of live update service database tables, their descriptions, and how they are used in relational databases.

Database used by PMF push service

The following table provides a list of push service database tables, their descriptions, and how they are used in relational databases.

For more information about setting up the databases, see Setting up databases.

Sample configuration files

PMF includes a number of sample configuration files to help you get started with the Ant tasks to install the PMF.

The easiest way to get started with these Ant tasks is by working with the sample configuration files provided in the MobileFoundationServer/configuration-samples/ directory of the PMF distribution. For more information about installing PMF with Ant tasks, see Installing with Ant Tasks.

List of sample configuration files

Pick the appropriate sample configuration file. The following files are provided.

Note on MySQL: MySQL in combination with WebSphere Application Server Liberty profile or WebSphere Application Server full profile is not classified as a supported configuration. For more information, see WebSphere Application Server Support Statement. Consider using IBM DB2 or another database that is supported by WebSphere Application Server to benefit from a configuration that is fully supported by Persistent Support.

Note on configuration files for WebSphere Application Server Network Deployment: The configuration files for wasnd contain a scope that can be set to cluster, node, server, or cell. For example, for configure-wasnd-cluster-derby.xml, the scope is cluster. These scope types define the deployment target as follows:

• cluster: To deploy to a cluster.
• server: To deploy to a single server that is managed by the deployment manager.
• node: To deploy to all the servers that are running on a node, but that do not belong to a cluster.
• cell: To deploy to all the servers on a cell.

Sample configuration files for Persistent Mobile Foundation Analytics

PMF includes a number of sample configuration files to help you get started with the Ant tasks to install the Persistent Mobile Foundation Analytics Services, and the PMF Analytics Console.

The easiest way to get started with the <installanalytics>, <updateanalytics>, and <uninstallanalytics> Ant tasks is by working with the sample configuration files provided in the Analytics/configuration-samples/ directory of the PMF distribution.

Step 1

Pick the appropriate sample configuration file. The following XML files are provided. They are referred to as configure-file.xml in the next steps.

Note on configuration files for WebSphere Application Server Network Deployment:
The configuration files for wasnd contain a scope that can be set to cluster, node, server, or cell. For example, for configure-wasnd-cluster-analytics.xml, the scope is cluster. These scope types define the deployment target as follows:

• cluster: To deploy to a cluster.
• server: To deploy to a single server that is managed by the deployment manager.
• node: To deploy to all the servers that are running on a node, but that do not belong to a cluster.
• cell: To deploy to all the servers on a cell.

Step 2

Change the file access rights of the sample file to be as restrictive as possible. Step 3 requires that you supply some passwords. If you must prevent other users on the same computer from learning these passwords, you must remove the read permissions of the file for users other than yourself. You can use a command, such as the following examples:

On UNIX: chmod 600 configure-file.xml On Windows: cacls configure-file.xml /P Administrators:F %USERDOMAIN%\%USERNAME%:F

Step 3

Similarly, if your application server is WebSphere Application Server Liberty profile, or Apache Tomcat, and the server is meant to be started only from your user account, you must also remove the read permissions for users other than yourself from the following files:

• For WebSphere Application Server Liberty profile: wlp/usr/servers/<server>/server.xml
• For Apache Tomcat: conf/server.xml

Step 4

Replace the placeholder values for the properties at the beginning of the file.

Note:
The following special characters must be escaped when they are used in the values of the Ant XML scripts:

• The dollar sign ($) must be written as $$, unless you explicitly want to reference an Ant variable through the syntax ${variable}, as described in Properties section of the Apache Ant Manual.
• The ampersand character (&) must be written as &, unless you explicitly want to reference an XML entity.
• Double quotation marks (") must be written as ", except when it is inside a string that is enclosed in single quotation marks.

Step 5

Run the command: ant -f configure-file.xml install

This command installs your Persistent Mobile Foundation Analytics Services and PMF Analytics Console components in the application server. To install updated Persistent Mobile Foundation Analytics Services and PMF Analytics Console components, for example if you apply a PMF fix pack, run the following command: ant -f configure-file.xml minimal-update.

To reverse the installation step, run the command: ant -f configure-file.xml uninstall

This command uninstalls the Persistent Mobile Foundation Analytics Services and PMF Analytics Console components.