Administrating applications through Ant

Overview

You can administer PMF applications through the pmfadm Ant task.

Jump to

• Comparison with other facilities
• Prerequisites

Comparison with other facilities

You can execute administration operations with Persistent Mobile Foundation in the following ways:

• The PMF Operations Console, which is interactive.
• The pmfadm Ant task.
• The pmfadm program.
• The PMF administration REST services.

The pmfadm Ant task, pmfadm program, and REST services are useful for automated or unattended execution of operations, such as:

• Eliminating operator errors in repetitive operations, or
• Operating outside the operator’s normal working hours, or
• Configuring a production server with the same settings as a test or preproduction server.

The pmfadm Ant task and the pmfadm program are simpler to use and have better error reporting than the REST services. The advantage of the pmfadm Ant task over the pmfadm program is that it is platform independent and easier to integrate when integration with Ant is already available.

Prerequisites

The pmfadm tool is installed with the PMF installer. In the rest of this page, product_install_dir indicates the installation directory of the PMF installer.

Apache Ant is required to run the pmfadm task. For information about the minimum supported version of Ant, see System requirements.

For convenience, Apache Ant 1.9.4 is included in PMF. In the product_install_dir/shortcuts/ directory, the following scripts are provided.

• ant for UNIX / Linux
• ant.bat for Windows

These scripts are ready to run, which means that they do not require specific environment variables. If the environment variable JAVA_HOME is set, the scripts accept it.

You can use the pmfadm Ant task on a different computer than the one on which you installed PMF.

• Copy the file product_install_dir/MobileFirstServer/mfp-ant-deployer.jar to the computer.
• Make sure that a supported version of Apache Ant and a Java runtime environment are installed on the computer.

To use the pmfadm Ant task, add this initialization command to the Ant script:

<taskdef resource="com/ibm/mfp/ant/deployers/antlib.xml">
  <classpath>
    <pathelement location="product_install_dir/MobileFirstServer/mfp-ant-deployer.jar"/>
  </classpath>
</taskdef>

Other initialization commands that refer to the same mfp-ant-deployer.jar file are redundant because the initialization by defaults.properties is also implicitly done by antlib.xml. Here is one example of a redundant initialization command:

<taskdef resource="com/ibm/mfp/ant/defaults.properties">
  <classpath>
    <pathelement location="product_install_dir/MobileFirstServer/mfp-ant-deployer.jar"/>
  </classpath>
</taskdef>

Jump to

• Calling the pmfadm Ant task
• Commands for general configuration
• Commands for adapters
• Commands for apps
• Commands for devices
• Commands for troubleshooting

Calling the pmfadm Ant task

You can use the pmfadm Ant task and its associated commands to administer PMF applications. Call the pmfadm Ant task as follows:

<pmfadm url=... user=... password=...|passwordfile=... [secure=...]>
    some commands
</pmfadm>

Attributes

The pmfadm Ant task has the following attributes:

url
The base URL preferably uses the HTTPS protocol. For example, if you use default ports and context roots, use the following URL.

• For WebSphere Application Server: https://server:9443/worklightadmin
• For Tomcat: https://server:8443/worklightadmin

secure
The default value is true. Setting secure=”false” might have the following effects:

• The user and password might be transmitted in an unsecured way, possibly even through unencrypted HTTP.
• The server’s SSL certificates are accepted even if self-signed or if they were created for a different host name than the specified server’s host name.

password
Specify the password either in the Ant script, through the password attribute, or in a separate file that you pass through the passwordfile attribute. The password is sensitive information and therefore needs to be protected. You must prevent other users on the same computer from knowing this password. To secure the password, before you enter the password into a file, remove the read permissions of the file for users other than yourself. For example, you can use one of the following commands:

• On UNIX: chmod 600 adminpassword.txt
• On Windows: cacls adminpassword.txt /P Administrators:F %USERDOMAIN%\%USERNAME%:F

Additionally, you might want to obfuscate the password to hide it from an occasional glimpse. To do so, use the pmfadm config password command to store the obfuscated password in a configuration file. Then, you can copy and paste the obfuscated password to the Ant script or to the password file.

The pmfadm call contains commands that are encoded in inner elements. These commands are executed in the order in which they are listed. If one of the commands fails, the remaining commands are not executed, and the pmfadm call fails.

Elements

You can use the following elements in pmfadm calls:

XML Format

The output of most commands is in XML, and the input to specific commands, such as <set-accessrule>, is in XML too. You can find the XML schemas of these XML formats in the product_install_dir/MobileFirstServer/pmfadm-schemas/ directory. The commands that receive an XML response from the server verify that this response conforms to the specific schema. You can disable this check by specifying the attribute xmlvalidation=”none”.

Output character set

Normal output from the pmfadm Ant task is encoded in the encoding format of the current locale. On Windows, this encoding format is the so-called “ANSI code page”. The effects are as follows:

• Characters outside of this character set are converted to question marks when they are output.
• When the output goes to a Windows command prompt window (cmd.exe), non-ASCII characters are incorrectly displayed because such windows assume characters to be encoded in the so-called “OEM code page”.

To work around this limitation:

• On operating systems other than Windows, use a locale whose encoding is UTF-8. This locale is the default locale on Red Hat Linux and macOS. Many other operating systems have the en_US.UTF-8 locale.
• Or use the attribute output=”some file name” to redirect the output of a pmfadm command to a file.

Commands for general configuration

When you call the pmfadm Ant task, you can include various commands that access the global configuration of the IBM PMF or of a runtime.

The show-global-config command

The show-global-config command shows the global configuration. It has the following attributes:

Example

<show-global-config/>

This command is based on the Global Configuration (GET) REST service.

The show-user-config command

The show-user-config command, outside of <adapter> and <app-version> elements, shows the user configuration of a runtime. It has the following attributes:

Example

<show-user-config runtime="mfp" format="xml"/>

This command is based on the Runtime Configuration (GET) REST service.

The set-user-config command

The set-user-config command, outside of <adapter> and <app-version> elements, specifies the user configuration of a runtime. It has the following attributes for setting the entire configuration.

The set-user-config command has the following attributes for setting a single property in the configuration.

Example

<set-user-config runtime="mfp" file="myconfig.json"/>

<set-user-config runtime="mfp" property="timeout" value="240"/>

This command is based on the Runtime configuration (PUT) REST service.

The show-confidential-clients command

The show-confidential-clients command shows the configuration of the confidential clients that can access a runtime. For more information about confidential clients, see Confidential clients. This command has the following attributes:

Example

<show-confidential-clients runtime="mfp" format="xml" output="clients.xml"/>

This command is based on the Confidential Clients (GET) REST service.

The set-confidential-clients command

The set-confidential-clients command specifies the configuration of the confidential clients that can access a runtime. For more information about confidential clients, see Confidential clients. This command has the following attributes:

Example

<set-confidential-clients runtime="mfp" file="clients.xml"/>

This command is based on the Confidential Clients (PUT) REST service.

The set-confidential-clients-rule command

The set-confidential-clients-rule command specifies a rule in the configuration of the confidential clients that can access a runtime. For more information about confidential clients, see Confidential clients. This command has the following attributes:

Example

<set-confidential-clients-rule runtime="mfp" id="push" displayName="Push" secret="lOa74Wxs" allowedScope="**"/>

This command is based on the Confidential Clients (PUT) REST service.

Commands for adapters

When you call the pmfadm Ant task, you can include various commands for adapters.

The list-adapters command

The list-adapters command returns a list of the adapters deployed for a given runtime. It has the following attributes.

Example

<list-adapters runtime="mfp"/>

This command is based on the Adapters (GET) REST service.

The deploy-adapter command

The deploy-adapter command deploys an adapter in a runtime. It has the following attributes.

Example

<deploy-adapter runtime="mfp" file="MyAdapter.adapter"/>

This command is based on the Adapter (POST) REST service.

The show-adapter command

The show-adapter command shows details about an adapter. It has the following attributes.

Example

<show-adapter runtime="mfp" name="MyAdapter"/>

This command is based on the Adapter (GET) REST service.

The delete-adapter command

The delete-adapter command removes (undeploys) an adapter from a runtime. It has the following attributes.

Example

<delete-adapter runtime="mfp" name="MyAdapter"/>

This command is based on the Adapter (DELETE) REST service.

The adapter command group

The adapter command group has the following attributes.

The adapter command supports the following elements.

The get-binary command

The get-binary command inside an <adapter> element returns the binary adapter file. It has the following attributes.

Example

<adapter runtime="mfp" name="MyAdapter">
  <get-binary tofile="/tmp/MyAdapter.adapter"/>
</adapter>

This command is based on the Adapter (GET) REST service.

The show-user-config command

The show-user-config command, inside an <adapter> element, shows the user configuration of the adapter. It has the following attributes.

Example

<adapter runtime="mfp" name="MyAdapter">
  <show-user-config format="xml"/>
</adapter>

This command is based on the Adapter Configuration (GET) REST service.

The set-user-config command

The set-user-config command, inside an <adapter> element, specifies the user configuration of the adapter. It has the following attributes for setting the entire configuration.

The command has the following attributes for setting a single property in the configuration.

Examples

<adapter runtime="mfp" name="MyAdapter">
  <set-user-config file="myconfig.json"/>
</adapter>

<adapter runtime="mfp" name="MyAdapter">
  <set-user-config property="timeout" value="240"/>
</adapter>

This command is based on the Application Configuration (PUT) REST service.

Commands for apps

When you call the pmfadm Ant task, you can include various commands for apps.

The list-apps command

The list-apps command returns a list of the apps that are deployed in a runtime. It has the following attributes.

Example

<list-apps runtime="mfp"/>

This command is based on the Applications (GET) REST service.

The deploy-app command

The deploy-app command deploys an app version in a runtime. It has the following attributes.

Example

<deploy-app runtime="mfp" file="MyApp/application-descriptor.json"/>

This command is based on the Application (POST) REST service.

The show-app command

The show-app command returns a list of the app versions that are deployed in a runtime. It has the following attributes.

Example

<show-app runtime="mfp" name="MyApp"/>

This command is based on the Application (GET) REST service.

The delete-app command

The delete-app command removes (undeploys) an app, with all its app versions, for all environments for which it was deployed, from a runtime. It has the following attributes.

Example

<delete-app runtime="mfp" name="MyApp"/>

This command is based on the Application Version (DELETE) REST service.

The show-app-version command

The show-app-version command shows details about an app version in a runtime. It has the following attributes.

Example

<show-app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1"/>

This command is based on the Application Version (GET) REST service.

The delete-app-version command

The delete-app-version command removes (undeploys) an app version from a runtime. It has the following attributes.

Example

<delete-app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1"/>

This command is based on the Application Version (DELETE) REST service.

The app command group

The app command group has the following attributes.

The app command group supports the following elements.

The show-license-config command

The show-license-config command shows the token license configuration of an app. It has the following attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <show-license-config output="/tmp/MyApp-license.xml"/>
</app-version>

This command is based on the Application license configuration (GET) REST service.

The set-license-config command

The set-license-config command specifies the token license configuration of an app. It has the following attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <set-license-config appType="B2E" licenseType="APPLICATION"/>
</app-version>

This command is based on the Application License Configuration (POST) REST service.

The delete-license-config command

The delete-license-config command resets the token license configuration of an app, that is, reverts it to the initial state.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <delete-license-config/>
</app-version>

This command is based on the License configuration (DELETE) REST service.

The app-version command group

The app-version command group has the following attributes.

The app-version command group supports the following elements:

The get-descriptor command

The get-descriptor command, inside an <app-version> element, returns the application descriptor of a version of an app. It has the following attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <get-descriptor output="/tmp/MyApp-application-descriptor.json"/>
</app-version>

This command is based on the Application Descriptor (GET) service.

The get-web-resources command

The get-web-resources command, inside an <app-version> element, returns the web resources of a version of an app, as a .zip file. It has the following attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <get-web-resources tofile="/tmp/MyApp-web.zip"/>
</app-version>

This command is based on the Retrieve Web Resource (GET) REST service.

The set-web-resources command

The set-web-resources command, inside an <app-version> element, specifies the web resources for a version of an app. It has the following attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <set-web-resources file="/tmp/MyApp-web.zip"/>
</app-version>

This command is based on the Deploy a web resource (POST) REST service.

The get-authenticity-data command

The get-authenticity-data command, inside an <app-version> element, returns the authenticity data of a version of an app. It has the following attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <get-authenticity-data output="/tmp/MyApp.authenticity_data"/>
</app-version>

This command is based on the Export runtime resources (GET) REST service.

The set-authenticity-data command

The set-authenticity-data command, inside an <app-version> element, specifies the authenticity data for a version of an app. It has the following attributes.

Examples

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <set-authenticity-data file="/tmp/MyApp.authenticity_data"/>
</app-version>

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <set-authenticity-data file="MyApp.ipa"/>
</app-version>

<app-version runtime="mfp" name="MyApp" environment="android" version="1.1">
  <set-authenticity-data file="MyApp.apk"/>
</app-version>

This command is based on the Deploy Application Authenticity Data (POST) REST service.

The delete-authenticity-data command

The delete-authenticity-data command, inside an <app-version> element, deletes the authenticity data of a version of an app. It has no attributes.

Example

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <delete-authenticity-data/>
</app-version>

This command is based on the Application Authenticity (DELETE) REST service.

The show-user-config command

The show-user-config command, inside an <app-version> element, shows the user configuration of a version of an app. It has the following attributes.

Examples

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <show-user-config format="json" output="/tmp/MyApp-config.json"/>
</app-version>

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <show-user-config format="xml" output="/tmp/MyApp-config.xml"/>
</app-version>

This command is based on the Application Configuration (GET) REST service.

The set-user-config command

The set-user-config command, inside an <app-version> element, specifies the user configuration for a version of an app. It has the following attributes for setting the entire configuration.

The set-user-config command has the following attributes for setting a single property in the configuration.

Examples

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <set-user-config file="/tmp/MyApp-config.json"/>
</app-version>

<app-version runtime="mfp" name="MyApp" environment="iphone" version="1.1">
  <set-user-config property="timeout" value="240"/>
</app-version>

Commands for devices

When you call the pmfadm Ant task, you can include various commands for devices.

The list-devices command

The list-devices command returns the list of devices that have contacted the apps of a runtime. It has the following attributes:

Examples

<list-devices runtime="mfp"/>

<list-devices runtime="mfp" query="john"/>

This command is based on the Devices (GET) REST service.

The remove-device command

The remove-device command clears the record about a device that has contacted the apps of a runtime. It has the following attributes:

Example

<remove-device runtime="mfp" id="496E974CCEDE86791CF9A8EF2E5145B6"/>

This command is based on the Device (DELETE) REST service.

The device command group

The device command group has the following attributes.

The device command supports the following elements.

The set-status command

The set-status command changes the status of a device, in the scope of a runtime. It has the following attributes:

The status can have one of the following values:

• ACTIVE
• LOST
• STOLEN
• EXPIRED
• DISABLED

Example

<device runtime="mfp" id="496E974CCEDE86791CF9A8EF2E5145B6">
  <set-status status="EXPIRED"/>
</device>

This command is based on the Device Status (PUT) REST service.

The set-appstatus command

The set-appstatus command changes the status of a device, regarding an app in a runtime. It has the following attributes:

The status can have one of the following values:

• ENABLED
• DISABLED

Example

<device runtime="mfp" id="496E974CCEDE86791CF9A8EF2E5145B6">
  <set-appstatus app="MyApp" status="DISABLED"/>
</device>

This command is based on the Device Application Status (PUT) REST service.

Commands for troubleshooting

You can use Ant task commands to investigate problems with PMF web applications.

The show-info command

The show-info command shows basic information about the PMF administration services that can be returned without accessing any runtime nor database. Use this command to test whether the PMF administration services are running at all. It has the following attributes:

Example

<show-info/>

The show-versions command

The show-versions command displays the PMF versions of various components:

• mfpadmVersion: the exact PMF version number from which the **mfp-ant-deployer.jar **file is taken.
• productVersion: the exact PMF version number from which the mfp-admin-service.war file is taken.
• mfpAdminVersion: the exact build version number of mfp-admin-service.war alone.

The command has the following attributes:

Example

<show-versions/>

The show-diagnostics command

The show-diagnostics command shows the status of various components that are necessary for the correct operation of the PMF administration service, such as the availability of the database and of auxiliary services. This command has the following attributes.

Example

<show-diagnostics/>

The unlock command

The unlock command releases the general-purpose lock. Some destructive operations take this lock in order to prevent concurrent modification of the same configuration data. In rare cases, if such an operation is interrupted, the lock might remain in locked state, making further destructive operations impossible. Use the unlock command to release the lock in such situations. The command has no attributes.

Example

<unlock/>

The list-runtimes command

The list-runtimes command returns a list of the deployed runtimes. It has the following attributes:

Examples

<list-runtimes/>

<list-runtimes inDatabase="true"/>

This command is based on the Runtimes (GET) REST service.

The show-runtime command

The show-runtime command shows information about a given deployed runtime. It has the following attributes:

Example

<show-runtime runtime="mfp"/>

This command is based on the Runtime (GET) REST service.

The delete-runtime command

The delete-runtime command deletes the runtime, including its apps and adapters, from the database. You can delete a runtime only when its web application is stopped. The command has the following attributes.

Example

<delete-runtime runtime="mfp" condition="empty"/>

This command is based on the Runtime (DELETE) REST service.

The list-farm-members command

The list-farm-members command returns a list of the farm member servers on which a given runtime is deployed. It has the following attributes:

Example

<list-farm-members runtime="mfp"/>

This command is based on the Farm topology members (GET) REST service.

The remove-farm-member command

The remove-farm-member command removes a server from the list of farm members on which a given runtime is deployed. Use this command when the server has become unavailable or disconnected. The command has the following attributes.

Example

<remove-farm-member runtime="mfp" serverId="srvlx15"/>

This command is based on the Farm topology members (DELETE) REST service.