Ant tasks for installation of MobileFirst Server 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 MobileFirst authorization server, MobileFirst Analytics, and with Cloudant® in case Cloudant is used.

updatemobilefirstpush

The updatemobilefirstpush Ant task updates an already-configured MobileFirst Server 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:

Table 1. Attributes for the installmobilefirstpush, updatemobilefirstpush, and uninstallmobilefirstpush Ant tasks
Attribute	Description	Required	Default
id	To distinguish different deployments.	No	Empty
warFile	The WAR file for the push service.	No	The ../PushService/mfp-push-service.war file is relative to the MobileFirstServer directory that contains the mfp-ant-deployer.jar file.

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:

Table 2. Inner elements for the installmobilefirstpush, updatemobilefirstpush, and uninstallmobilefirstpush Ant tasks
Element	Description	Count
`<applicationserver>`	The application server.	1
`<analytics>`	The Analytics.	0..1
`<authorization>`	The authorization server for authenticating the communication with other MobileFirst Server components.	1
`<database>`	The databases.	1
`<property>`	The properties.	0..∞

To specify the authorization server

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

Table 3. Attributes of the `<authorization>` element
Attribute	Description	Required	Default value
auto	To indicate whether the authorization server URL is computed. The possible values are `true` or `false`.	Required on a WebSphere Application Server Network Deployment cluster or node.	`true`
authorizationURL	The URL of the authorization server.	If mode is not auto.	The context root of the runtime on the local server.
runtimeContextRoot	The context root of the runtime.	No	/mfp
pushClientID	The push service confidential ID in the authorization server.	Yes	None
pushClientSecret	The push service confidential client password in the authorization server.	Yes	None

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 MobileFirst 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 MobileFirst 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 MobileFirst Operations Console.

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

Table 4. Attributes for the `<property>` element
Attribute	Description	Required	Default value
name	The name of the property.	Yes	None
value	The value of the property.	Yes	None

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 MobileFirst Server 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:

Table 5. Inner elements of the `<applicationserver>` element
Element	Description	Count
`<websphereapplicationserver>` or `<was>`	The parameters for WebSphere Application Server. 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.	0..1
`<tomcat>`	The parameters for Apache Tomcat.	0..1

The attributes and inner elements of these elements are described in Table 5 through Table 14 of Ant tasks for installation of MobileFirst runtime environments.

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

Table 6. Inner element of the `<was>` element for Liberty collective
Element	Description	Count
`<collectiveMember>`	A Liberty collective member.	0..1

The <collectiveMember> element has the following attributes:

Table 7. Attributes of the `<collectiveMember>` element
Attribute	Description	Required	Default value
serverName	The name of the collective member.	Yes	None
clusterName	The cluster name that the collective member belongs to.	Yes	None

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 MobileFirst push service to an already installed MobileFirst Analytics service. It has the following attributes:

Table 8. Attributes of the `<analytics>` element
Attribute	Description	Required	Default
install	To indicate whether to connect the push service to MobileFirst Analytics.	No	`false`
analyticsURL	The URL of MobileFirst Analytics services.	Yes	None
username	The user name.	Yes	None
password	The password.	Yes	None
validate	To validate whether MobileFirst Analytics Console is accessible or not.	No	`true`

install

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

analyticsURL

Use the analyticsURL attribute to specify the URL that is exposed by MobileFirst 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 MobileFirst 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 Analytics is protected with basic authentication.

validate

Use the validate attribute to validate whether the MobileFirst 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:

Table 9. Attributes of the `<database>` element
Attribute	Description	Required	Default
kind	The kind of database (Push).	Yes	None
validate	To validate whether the database is accessible.	No	`true`

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

Table 10. Inner elements for the `<database>` element
Element	Description	Count
`<db2>`	The parameter for DB2® databases.	0..1
`<derby>`	The parameter for Apache Derby databases.	0..1
`<mysql>`	The parameter for MySQL databases.	0..1
`<oracle>`	The parameter for Oracle databases.	0..1
`<cloudant>`	The parameter for Cloudant databases.	0..1
`<driverclasspath>`	The parameter for JDBC driver class path (relational DBMS only).	0..1

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

Table 11. Attributes of the `<cloudant>` element
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
dbName	The Cloudant database name. Important: This database name must start with a lowercase letter and contain only lowercase characters (a-z), Digits (0-9), any of the characters `_`, `$`, and `-`.	No	`mfp_push_db`