Ant tasks for installation of MobileFirst Data Proxy

Reference information for the <installdataproxy>, <updatedataproxy>, and <uninstalldataproxy> Ant tasks.

About the Ant tasks for installing MobileFirst Data Proxy

The purpose of these Ant Tasks is to configure the MobileFirst Data Proxy on an application server so that it can communicate with the following components:

a Cloudant® database (either Cloudant Managed or Cloudant Local)
an Authorization Server that is embedded in a MobileFirst runtime environment.

For a Liberty server, and a stand-alone WebSphere® Application Server, these Ant tasks install a Trust Association Interceptor (TAI), which acts as the front end for performing OAuth authentication of incoming requests to the MobileFirst Data Proxy.

Note: None of these Ant tasks install, update, or uninstall a MobileFirst runtime environment.

For more information about how to use these Ant tasks, see Installing the MobileFirst Data Proxy with Ant tasks.

For more information about installing a MobileFirst runtime environment, see Installing the MobileFirst runtime environment.

Important:

The MobileFirst Data Proxy is not supported on Apache Tomcat, or on versions of WebSphere Application Server Liberty profile earlier than V8.5.5.0.
You must install the TAI manually on WebSphere Application Server Network Deployment.

Task effects

<installdataproxy>

The <installdataproxy> Ant task configures an application server to run a MobileFirst Data Proxy. This task has the following effects:

It deploys the MobileFirst Data Proxy WAR file on the application server.
It configures a TAI on WebSphere Application Server Liberty and WebSphere Application Server standalone, and copies the requested files in the application server in the appropriate locations. On WebSphere Application Server standalone, it creates a configuration file for this TAI if that is required.
It declares the MobileFirst web application in the specified context root, by default /imf-data-proxy.
It sets MobileFirst Data Proxy configuration properties through JNDI environment entries.
On WebSphere Application Server Liberty, it configures the web container.

<updatedataproxy>

The <updatedataproxy> Ant task updates the MobileFirst Data Proxy web application, which is already configured, on an application server. This task has the following effects.

It updates the project WAR file. The file must have the same base name as the project WAR file that was previously deployed.
It updates the TAI files on WebSphere Application Server Liberty and WebSphere Application Server stand-alone.

The task does not change the application server configuration, which includes the web application configuration, data sources, and JNDI environment entries.

<uninstalldataproxy>

The <uninstalldataproxy> Ant task undoes the effects of an earlier <installdataproxy> run. This task has the following effects.

It removes the configuration of the MobileFirst Data Proxy web application with the specified context root.
It removes the MobileFirst Data Proxy WAR file from the application server.
It removes the associated JNDI environment entries.

Note: It does not remove the TAI JAR and feature manifest files from the application server.

Attributes and elements

The <installdataproxy>, <updatedataproxy>, and <uninstalldataproxy> tasks have the following attributes:

Table 1. Attributes for the <installdataproxy>, <updatedataproxy>, and <uninstalldataproxy> Ant tasks
Attribute	Description	Required	Default
contextroot	Common prefix in URLs to the application (context root)	No	/imf-data-proxy
id	Distinguishes different deployments	No	Empty
serviceWar	The WAR file for the MobileFirst Data Proxy.	No	The imf-data-proxy WAR file is in the directory Datastore, at the same level than the WorklightServer directory.
DBAccount	Cloudant database account, or host name of the MobileFirst Cloudant Local server.	Yes	None
DBAccountUser	User name for accessing the database.	Yes	None
DBAccountPassword	Password for accessing the database.	Yes	Queried interactively
validate	To validate whether the Cloudant database is accessible or not. The possible values are `true` or `false`.	No	`true`
cloudantPort	Port to access Cloudant.	No	443 or 80
useHttps	To indicate whether the access to Cloudant must use `https`. The possible values are `true` or `false`.	No	`true`

contextroot and id

The contextroot and id attributes distinguish different MobileFirst projects.

In WebSphere Application Server Liberty profiles, the contextroot parameter is sufficient for this purpose. In WebSphere Application Server full profile environments, the id attribute is used instead.

serviceWar

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

DBAccount

The DBAccount attribute identifies either an Cloudant Managed account name or a user name defined in the configuration of a MobileFirst Cloudant Local database.

DBAccountUser

Use the DBAccountUser attribute to specify the name of a user to connect to Cloudant.

This user name can be an administrator or a non-administrator user. In all cases, the user name you provide must exist in Cloudant as the Ant task does not create it.

DBAccountPassword

Use the DBAccountPassword attribute to specify the password associated to the user specified with attribute DBAccountUser.

validate

When set to true, the validate attribute enables you to check that the Cloudant database identified by attribute DBAccount is on a reachable system and can be accessed using the credentials provided with attributes DBAcountUser and DBAcountPassword. By default, this validation is enabled.

cloudantPort

With the cloudantPort attribute, you can specify a port to access a Cloudant database directly, or a Load Balancer port if a Cloudant haproxy service is used to access the Cloudant database. If this attribute is not specified, the default port is set to 443, unless the useHttps attribute is set to false. In this case, the default port is set to 80.

useHttps

With the useHttps attribute, you can indicate which of the http or https protocol the MobileFirst Data Proxy must use to connect to the Cloudant database. The default protocol used is https.

The <installdataproxy>, <updatedataproxy>, and <uninstalldataproxy> tasks support the following elements:

Table 2. Inner elements for the <installdataproxy>, <updatedataproxy>, and <uninstalldataproxy> Ant tasks
Element	Description	Count
authenticate	TAI	0 for WebSphere Application Server Network Deployment 1 for WebSphere Application Server Liberty profile and WebSphere Application Server full profile
applicationserver	application server	1

Important: You cannot specify an authenticate element for WebSphere Application Server Network Deployment environments.

To install a TAI

Use the <authentication> element to define the TAI and, optionally, the location of the files that implement it. The attributes of this element are described in Table 3.

Table 3. Attributes for the <authentication> element
Attribute	Description	Count	Required	Default
serverURL	The Authorization Server URL	1	Yes	None
taiJAR	The TAI JAR file	0..1	No	File com.ibm.worklight.oauth.tai_1.0.0.jar located in a subdirectory external-server-libraries of the directory where you find worklight-ant-deployer.jar
libertyFeatureManifest	The TAI feature manifest (for Liberty only)	0..1	No	File OauthTai-1.0.mf located in a subdirectory external-server-libraries of the worklight-ant-deployer.jar location

Note: The tairJAR and libertyFeatureManifest attributes are not mandatory. For WebSphere Application Server full profile environments, you might want to specify a taiJAR attribute. For Liberty profile environments, if you specify one of these attributes, you must also specify the other.

serverURL: Use the serverURL attribute to specify the URL of a MobileFirst project in the form http[s]://hostname:port/context-root, where <context-root> is the context root of a MobileFirst project.
taiJAR: Use the taiJAR attribute to specify a different directory for the MobileFirst Data Proxy TAI JAR file. You can specify the name of this JAR file with an absolute path or a relative path. By default, the Ant task uses the file com.ibm.worklight.oauth.tai_1.0.0.jar that is in a subdirectory external-server-libraries of the directory where worklight-ant-deployer.jar is.
libertyFeatureManifest: Use the libertyFeatureManifest attribute to specify a different directory for the Liberty feature manifest file. You can specify the name of this file with an absolute path or a relative path. By default, the Ant task uses the file OauthTai-1.0.mf that is in a subdirectory external-server-libraries of the worklight-ant-deployer.jar location.

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 element. The attributes and inner elements of this element are described in tables 6 through 12 of Ant tasks for installation of MobileFirst runtime environments.

Note: You cannot specify Apache Tomcat, as this application server is not supported by MobileFirst Data Proxy.

Table 4. Inner elements for the <applicationserver> element
Element	Description	Count
websphereapplicationserver or was	The parameters for WebSphere Application Server.	1