Plug-in Documentation

IBM MobileFirst Platform (formerly Worklight)

Overview

Overview

The IBM MobileFirst Platform plug-in provides functionality for deploying artifacts, including mobile application artifacts, to an IBM MobileFirst Server. IBM MobileFirst Platform was previously known as IBM Worklight.

To add the IBM MobileFirst Platform plug-in steps to processes, click Mobile > IBM MobileFirst in the step palette of the process editor.

Compatibility

The IBM UrbanCode Deploy automation plug-in for IBM MobileFirst Platform is compatible with IBM MobileFirst Platform Foundation versions 6.3, 7.0, 7.1, 8.0, Bluemix-Hosted and with IBM Worklight versions 6.0 through 6.2.

IBM Worklight prior to version 8 require the worklight-ant-deploy.jar. Follow the link to find the jar on your on-premise Worklight server. This is required and must be available for the agent to use.

This plug-in requires version 6.0.1 or later of IBM UrbanCode Deploy.

This plug-in is supported to run on all operating systems that are supported by the IBM UrbanCode Deploy agent.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode products.

History

Version 12

  • Updated server path description specifying respective server path for different versions of MobileFirst.

Version 11

  • RFE 115145 Support for web resource deployments on IBM MobileFirst Platform v8.0

Version 10

  • RFE 98468 Support for IBM MobileFirst Platform v8.0.
  • Updated Step names, descriptions, and default property values to match IBM MobileFirst v8.0.

Version 9

Secure property file encryption.

Version 8

Fixes APAR PI57417. Plug-in now checks the agent settings for acceptance of self signed certificates.

Version 7

Version 7 of the plug-in adds support for deploying multiple wlapp or adapters within a single step.

Version 6

Version 6 of the plug-in adds support for IBM MobileFirst Platform Foundation version 6.3, 7.0, and 7.1

Version 5

Version 5 of the plug-in includes a fix for a compatibility defect with IBM Urbancode Deploy version 6.1.0.4 and later.

Steps

Process steps in the IBM MobileFirst plug-in

Change Application Configuration

Changes an applications configuration on IBM MobileFirst.
Note: This step is for server 6.2 or later.

Input properties for the Change Application Configuration step
Name Type Description Required
Application Name String The application name to reconfigure. Yes
Configuration File String The .json or .xml file path containing the applications new configuration. Yes
Environment String The name of the environment. Yes
Password Password The users password to access the IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Runtime String The runtime on which to change the applications configuration. Yes
Secure Boolean Whether to transmit in a secure way. Utilized in versions 6.2 to 7.1. No
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access a secure IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Version String The name of the version. Yes
Worklight Ant JAR File Path String The path to the Worklight Ant Deployer JAR (worklight-ant-deployer.jar)
file. The Worklight 6.0.0 Server can use the value:
${PLUGIN_HOME}/lib/worklight-ant.jar. Required for
server versions less than 8.0.
No

Delete Adapter

Deletes the adapter from the IBM MobileFirst server.
Note: This step is for Worklight and IBM MobileFirst servers 6.2 and later.

Input properties for the Delete Adapter step
Name Type Description Required
Adapter Name String The adapter to delete from the IBM MobileFirst server. Yes
Password Password The users password to access the IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Runtime String The runtime on which to remove the adapter. Yes
Secure Boolean Whether to transmit in a secure way. Utilized in server versions 6.2 to 7.1. No
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access a secure IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Worklight Ant JAR File Path String The path to the Worklight Ant Deployer JAR (worklight-ant-deployer.jar)
file. The Worklight 6.0.0 Server can use the value:
${PLUGIN_HOME}/lib/worklight-ant.jar. Required for
server versions less than 8.0.
No

Delete Application

Delete an application from IBM MobileFirst.
Note: This step is for Worklight Server 6.2 or later.

Input properties for the Delete Application step
Name Type Description Required
Application Name String The name of the Worklight application to remove. Yes
Environment String The applications environment. Only required if using IBM MobileFirst v8+. No
Password Password The users password to access the IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Runtime String The runtime on which to remove the IBM MobileFirst application.
Note: This property is required for Worklight 6.2 or later.
No
Secure Boolean Whether to transmit in a secure way. Utilized in server versions 6.2 to 7.1. No
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access a secure IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Version String The applications version number. Only required if using IBM MobileFirst v8+. No
Worklight Ant JAR File Path String The path to the Worklight Ant Deployer JAR (worklight-ant-deployer.jar)
file. The Worklight 6.0.0 Server can use the value:
${PLUGIN_HOME}/lib/worklight-ant.jar. Required for
IBM MobileFirst versions less than 8.0.
No

Deploy Adapter

Deploys the adapter to IBM MobileFirst.

Input properties for the Deploy Adapter step
Name Type Description Required
Adapter Files String A list, separated by commas or newline characters, of IBM MobileFirst
Adapter (.adapter) files to deploy to the IBM MobileFirst Server.
Yes
Password Password The users password to access the IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Runtime String The runtime on which to deploy the adapter. Note: This property
is required for Worklight 6.2 and later.
No
Secure Boolean Whether to transmit in a secure way. Utilized in server versions 6.2 to 7.1. No
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access a secure IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Worklight Ant JAR File Path String The path to the Worklight Ant Deployer JAR (worklight-ant-deployer.jar)
file. The Worklight 6.0.0 Server can use the value:
${PLUGIN_HOME}/lib/worklight-ant.jar. Required for
server versions less than 8.0.
No

Deploy Application

Deploys an application to IBM MobileFirst.

Input properties for the Deploy Application step
Name Type Description Required
Application Files String A list, separated by commas or newline characters, of the Worklight
Application files to deploy to the Worklight Server. Specify
.wlapp files for IBM MobileFirst pre-v8 and .json or .xml files for IBM MobileFirst
v8+.
Yes
Password Password The users password to access the IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Runtime String The runtime on which to deploy the IBM MobileFirst application.
Note: This property is required for Worklight 6.2 or later.
No
Secure Boolean Whether to transmit in a secure way. Utilized in server versions 6.2 to 7.1. No
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access a secure IBM MobileFirst server.
Note: This property is required for Worklight 6.2 and later.
No
Worklight Ant JAR File Path String The path to the Worklight Ant Deployer JAR (worklight-ant-deployer.jar)
file. The Worklight 6.0.0 Server can use the value:
${PLUGIN_HOME}/lib/worklight-ant.jar. Required for
IBM MobileFirst versions less than 8.0.
No

Deploy Web Resource

Deploys a web resource compressed file (.zip) for a specific application version.
Note: This step is for MobileFirst 8.0 or later.

Input properties for the Deploy Web Resource step
Name Type Description Required
Application Identifier String The MobileFirst application in which to deploy the web resource archive. Yes
Environment String The MobileFirst applications environment in which to deploy the web resource archive. Yes
Password Password The user password that is required to access the Application Center. Yes
Runtime String The MobileFirst runtime in which to deploy the web resource archive. Yes
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access the Application Center. Yes
Version String The MobileFirst applications version number in which to deploy the web resource archive. Yes
Web Resource File String The name of the web resource (.zip) file to deploy to the IBM MobileFirst Server. Yes

Remove Application from Application Center

Removes the native application from the IBM MobileFirst Application Center.

Input properties for the Remove Application from Application Center step
Name Type Description Required
Application Center Ant JAR File Path String The path to the Application Center Deploy Tool Ant
JAR (applicationcenterdeploytool.jar) file. The
Worklight 6.0.0 Server can use the value: ${PLUGIN_HOME}/lib/applicationcenterdeploytool.jar.
Yes
Application Package String The package name of the application to remove from the Application Center. Yes
Context String The context of the Application Center. For example, applicationcenter. Yes
Disable SSL Security Checking Boolean Disables SSL security checking. Use of this flag is a security risk. No
JSON4J JAR File Path String The path to the JSON4J JAR (json4j.jar) file. The
Worklight 6.0.0 Server can use the value: ${PLUGIN_HOME}/lib/json4j.jar.
Yes
Operating System Enumeration:

  • all
  • Android
  • iOS
The operating system of the application to remove from the Application Center. No
Password Password The user password. The default value is: ${p:environment/applicationCenterPassword}. Yes
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access the Application Center. Yes
Version String The internal version (not the commercial version) of the application to remove from
the Application Center.
No

Upload Application to Application Center

Uploads the application to the IBM MobileFirst Application Center.

Input properties for the Upload Application to Application Center step
Name Type Description Required
Active Boolean Store the application in the Application Center as an active application. No
Application Center Ant JAR File Path String The path to the Application Center Deploy Tool Ant
JAR (applicationcenterdeploytool.jar) file. The
Worklight 6.0.0 Server can use the value: ${PLUGIN_HOME}/lib/applicationcenterdeploytool.jar.
Yes
Context String The context of the Application Center. For example, applicationcenter. Yes
Description String The description of the application to upload to the Application Center. No
Disable SSL Security Checking Boolean Disables SSL security checking. Use of this flag is a security risk. No
File String The Android application package (.apk) or iOS application (.ipa) file to upload to
the Application Center.
Yes
Force Upload Boolean Force existing applications to be uploaded to the Application Center. No
Installer Boolean Store the application in the Application Center with the installer flag. No
JSON4J JAR File Path String The path to the JSON4J JAR (json4j.jar) file. The
Worklight 6.0.0 Server can use the value: ${PLUGIN_HOME}/lib/json4j.jar.
Yes
Label String The fallback label in the Application Center. No
Password Password The user password. The default value is: ${p:environment/applicationCenterPassword}. Yes
Ready for production Boolean Store the application in the Application Center with the ready-for-production flag. No
Recommended Boolean Store the application in the Application Center with the recommended flag. No
Server Path String The URL to the IBM MobileFirst server and role of the MobileFirst authorized user.
For Worklight versions 7.1 and older, the default path is /worklightadmin.
For MobileFirst versions 8.0 and newer, the default path is /mfpadmin.
Yes
User String The user name that is required to access the Application Center. Yes

Usage

The IBM MobileFirst Platform plug-in for IBM UrbanCode Deploy is part of a complete process for building and deploying mobile applications.

Important properties in plug-in steps

Important information is in some of the process step properties.

Step properties are described briefly in the properties table for each step. This
section provides more information about the details and implications of selected
important properties.

Application Center Ant JAR File Path
The path to the Application Center Deploy Tool Ant JAR file,
applicationcenterdeploytool.jar. It is used to interact with the
Application Center.

The version of the Ant JAR file you use must match the version on the
target server. An Ant JAR file is included in this plug-in for deploying
artifacts to the Worklight Version 6.0.0 Server. The default path to use this
file is ${PLUGIN_HOME}/lib/applicationcenterdeploytool.jar.

Disable SSL Security Checking
Security Risk. This option allows you to publish on secure Application
Center hosts without verification of the SSL certificate.

Disabling the security checking can be helpful when testing localhost with
temporary self-signed certificates. It should never be done on production
or public systems.

JSON4J JAR file path
The path to the JSON4J JAR file, json4j.jar.

The version of the JSON4J JAR file you use must match the version on the
target server. An Ant JAR file is included in this plug-in for deploying
artifacts to the Worklight Version 6.0.0 Server. The default path to this file
is ${PLUGIN-HOME}/lib/json4j.jar.

Label
This property is in the Upload Application to Application Center step.

Normally, the label is taken from the application descriptor that is stored in
the file to be uploaded. If the application descriptor does not contain a
label, the fallback label is used.

Secure
Security Risk. Determines whether to communicate with the Worklight
server in a secure way. The default is No.

Set this value in accordance with your security policies. Transmitting
without security is a security risk, especially outside a firewall.

Worklight Ant JAR File path
The path to the Worklight Ant Deployer JAR file. The file to use differs by
Worklight server version.

  • Versions 6.2 and 6.1: Use worklight-ant-deployer.jar.
  • Version 6.0.0: Use worklight-ant.jar.

The version of the Ant JAR file you use must match the version on the
target server. An Ant JAR file is included in this plug-in for deploying
artifacts to the Worklight Version 6.0.0 Server. The default path to this file
is ${PLUGIN_HOME}/lib/worklight-ant.jar.

Rolling back mobile applications

There are a number of ways to roll back a mobile application that is deployed to
IBM Worklight Server. One option is to remove the native application from the
Application Center and then redeploy the application. Alternatively, you can
manually roll back deployments. With version 4.0 of the plug-in you can also
remove adapters, remove Worklight applications from the Worklight server, or
change Worklight application access rules.

You can choose an automated or manual method to roll back a mobile application
deployment.

Automated rollback

To automate rolling back a mobile application deployment,
create processes that use the following general steps:

    1. At the component level, create a process that removes the native application
      from the Worklight Application Center, and overwrite any deployed artifacts
      by redeploying the application:

      1. To remove the native application from the Worklight Application Center,
        add the Remove Application from Application Center step.Tip:When you configure the step, specifying the Operating System and
        Version removes a specific native application, such as the version
        related to a failed deployment.
      2. Any artifacts that were successfully deployed to the Worklight Console
        are not removed. To overwrite the deployed artifacts, add process steps to
        redeploy the mobile application as described in the topic Deploying
        mobile applications
        Alternatively, you can first remove or modify the artifacts on the
        Worklight Console by using these steps:

    2. At the application process level, create a process that includes the desired
      Rollback Component step and configure the step to call the component
      process that you created in the preceding steps. The Rollback Component step
      replaces the component version with an earlier version.

Manual rollback

To manually roll back a mobile application deployment:

  1. Delete the native application from the Worklight Application Center.
  2. In the Worklight Console, delete the adapters and applications. For details,
    see the topics in the section Administering adapters and apps in Worklight
    Console
    in the Worklight Information Center.
  3. Redeploy the previous version of the mobile application from UrbanCode
    Deploy.

Deploying mobile applications

You can use the process steps in the IBM Worklight plug-in to deploy mobile
applications to IBM Worklight Server.

Before you begin

  • If it is not already installed, install the IBM Worklight plug-in.
  • Install the plug-in that corresponds to the application server that is running your
    Worklight Server for deploying the WAR file to the Worklight Server. For
    example:

  • Verify that your process steps use the path to the JAR files that correspond to
    your IBM Worklight Server version. For example, if you are using IBM
    Worklight plug-in Version 2.0 or later and a version of IBM Worklight Server
    later than 6.0.0, you must update your process steps.Note: Worklight plug-in version 4.0 and later verifies that the provided JAR file
    matches the target Worklight server. If the versions do not match, a
    deployment can fail. This does not apply to steps for the application
    center.Tip: The following JAR files are available for use with IBM Worklight plug-in
    Version 2.0 or later:

    worklight-ant.jar
    Used to deploy artifacts to the IBM Worklight Server Version 6.0.0.
    worklight-ant-deployer.jar
    Used to deploy artifacts to the IBM Worklight Server Version 6.1.0
    or later.
    applicationcenterdeploytool.jar
    Used to interact with an Application Center installed on an IBM
    Worklight Version 6.0.0 Server or later.
    json4j.jar
    Used with the IBM Worklight Server Version 6.0.0 or later

About this task

In the process editor, you can modify component processes to include steps to
deploy the following mobile application artifacts to your Worklight Server:

  • Native applications (Android .apk or iOS .ipa)
  • Worklight Adapters (.adapter)
  • Worklight Applications (.wlapp)
  • Worklight project (.war)

The following sequence is a suggested order for deploying the mobile application
artifacts:

  1. Deploy the .war file to the application server by using a process step from the
    corresponding plug-in for the type of application server that is running the
    Worklight Server. For example, for WebSphere Application Server use the
    Install or Update Application step.
  2. The following artifacts can be deployed in parallel or in either order:
  3. Deploy the Android application package (.apk) or iOS application (.ipa) file to
    the Application Center by using the Upload Application to Application
    Center
    step.

Example

The following simple example process deploys a mobile application to the
Worklight Server Console and Application Center.

  1. The Download Artifacts step retrieves the binary files.
  2. The Install or Update Application step deploys the .war file to WebSphere
    Application Server (the application server that is used in this example).Note: The Install or Update Application step in this example is provided by
    the Application Deployment for WebSphere plug-in (not the Worklight
    plug-in).
  3. In parallel, the .adapter and .wlapp files are deployed to the Worklight Server
    Console by the Deploy Adapter to Worklight Server step and the Deploy
    Worklight Application to Worklight Server step.
  4. The .apk (Android) or .ipa (iOS) file is deployed to the Application Center by
    the Upload Native Application to the Application Center step.

Configuring the Worklight server

You must configure the IBM Worklight Server before you can run the process steps
to deploy mobile application artifacts.

About this task

For each Worklight project, you must configure the Worklight Server. The one time
Worklight Server setup and configuration options for the Worklight project WAR
file are described in the
Worklight Knowledge Center.

You can use any of the following methods to configure the Worklight Server:

  • Use Ant tasks to configure the server:
    • Use the command line to run the Ant script.
    • Use the Ant process step within UrbanCode Deploy to run the Ant script with
      the Worklight Ant tasks. To use the Ant process step, you must download and
      install the Ant plug-in for UrbanCode Deploy.
  • Use the Server Configuration Tool to configure the server.
  • Manually configure the server.

Tips:

  • Sample scripts are available for configuring the server and are in
    Worklight installation directory/Worklight/WorklightServer/
    configuration-samples. The sample script combines the two steps in the
    following procedure by creating a database and deploying the project
    WAR file.
  • For information about configuring a secure Worklight Console on
    Worklight 6.0 and 6.1 servers for IBM WebSphere Application Server
    Liberty Profile and, including the required values, see
    Testing the
    Worklight Console login screen.

Procedure

To configure the Worklight Server for a Worklight project:To configure the Worklight Server for a Worklight project:

  1. Create and configure a database for your server:
    Option Documentation
    Use Ant tasks to create and configure the
    databases
    Creating and configuring the databases with
    Ant tasks
    Use the Server Configuration Tool to create
    and configure the databases
    Deploying, updating, and undeploying a
    Worklight Server by using the Server
    Configuration Tool
    Manually create and configure the
    databases
    Creating and configuring the databases
    manually
  2. Deploy the project WAR file to the application server:
    Option Documentation
    Use Ant tasks to install the Worklight
    project
    Deploy a project WAR file and configuring
    the application server with Ant tasks
    Use the Server Configuration Tool to install
    the Worklight project
    Deploying, updating, and undeploying a
    Worklight Server by using the Server
    Configuration Tool
    Manually install the Worklight project Deploy a project WAR file and configuring
    the application server manually

Important:
If you are configuring multiple projects on a single server, then see
the Worklight topic
Configuring multiple IBM Worklight projects. If
you run multiple projects on a single server, install the .war files
from multiple Worklight projects in the same application server,
and then have them operate in parallel and independently.

Note:
The Worklight project WAR file deployment that is described in this step
is a one time configuration. When you deploy your mobile application,
update the WAR file on the application server by using the plug-in
process steps.

Adding mobile artifacts to UrbanCode Deploy

You can use the build scripts to add your build artifacts to IBM UrbanCode Deploy
for deployment to the IBM Worklight Server.

Procedure

You can use any of the following methods to add your build artifacts to
UrbanCode Deploy:

Copy the files into a user-defined file system
Copy the build artifacts to a location on the
UrbanCode Deploy servers file system for a
versioned file.
Push the files to the UrbanCode Deploy server
Use the Command-line client (CLI) to push
the build artifacts to the UrbanCode Deploy
server. The CLI is a command-line interface
that provides access to the UrbanCode
Deploy server.

You can use the CLI to push the build
artifacts to the UrbanCode Deploy server in
the following scenarios:

  • When the Jazz Build Engine and the
    UrbanCode Deploy server are not
    installed on the same build computer.
  • To support running the UrbanCode
    Deploy server on different operating
    systems.

Tip: You can use the following commands
to deploy binary files to the UrbanCode
Deploy server:

createVersion
Create the component version.
addVersionFiles
Upload the component files.
Copy the files into a source-code
management system
Copy the build artifacts into a source-code
management system, such as:

  • Git
  • IBM Rational Asset Manager
  • Subversion

Tip: Assign a version to the mobile application that is deployed to the Application
Center. This version must match the version that is assigned in UrbanCode
Deploy. For example, if the mobile application has a commercial version of 1.0
on the Application Center and the internal version from the latest build is 16,
assign version 1.0.16 to the application in UrbanCode Deploy. Keeping the
version numbers synchronized helps you to recover if you encounter a
problem. For example, if the latest version of the mobile application was not
deployed successfully to the Application Center.

Related information:

Creating components from a versioned file system

Creating components from source-code management systems

Command-line client (CLI) reference

createVersion

addVersionFiles

Building mobile applications


To set up a continuous integration and delivery cycle for your mobile applications,
you must build the mobile application artifacts before you deploy them to the IBM
Worklight Server. The IBM Rational solution for Collaborative Lifecycle
Management (CLM), IBM Worklight Studio, and IBM UrbanCode Deploy integrate
to help automate the build and deployment of mobile applications.

CLM contains the Rational Team Concert product that is delivered as an
application together with a Jazz Team Server. Rational Team Concert and the
Build System Toolkit work together to build your mobile applications. When
Rational Team Concert is installed on the Jazz Team Server, it manages the
workspaces, projects, source files, and builds of your mobile applications. The
Build System Toolkit runs the actual build tasks.

The following topics are covered in sections below:

Related information:

Building with Jazz Team Build

Build computer resources

Before you run a mobile application build script on a build computer, you must
ensure that the required resources exist on the build computer.

Workspace resources

The following workspace resources must exist on the build computer:

  • The mobile application project source code that you want to build
  • The Ant build scripts that direct the build

Using a Rational Team Concert repository workspace to manage your Worklight
project source code and build scripts offers the following advantages:

Source control advantages
Changes to source code and build scripts can be requested,
developed, reviewed, approved, delivered, and tracked based on
the requirements of your development project. Build scripts are
living files, just like the source code.
Build automation advantages
The Jazz Build Engine automatically loads the workspace to build
onto the build computer early in the processing of a build
request. You can create and use a dedicated build workspace for
each build definition. Do not point a build definition directly to a
stream or to a workspace that is meant for another purpose. For
example, do not point a build definition directory to the personal
workspace of a user or a team integration workspace.Note: The Jazz Build Engine is a component of the Build System
Toolkit; it refers to the process that runs on a build computer and
runs Ant scripts.

Static resources

The build administrator must manually install the static resources on each build
computer.

Tip: Install these resources into the same relative locations on each build computer.
You can specify the relative locations within either of the following types of
build dependency resources:

  • Build property files:
    Specify the relative locations of the static resources within the build
    property files. If you install static resources into different locations on
    different build computers, a location that is specified within a build
    property file that works on one build computer might fail on another
    build computer.
  • Build definitions within Rational Team Concert:
    Specify the relative locations of the static resources within the build
    definitions in Rational Team Concert. If you install static resources
    into different locations on different build computers, a build definition
    that works on one build computer might fail on another build
    computer.

The following static resources must exist on the build computer:

Oracle JDK
Use this JDK for running the Ant scripts and Android SDK tools that are
run by the build scripts. Ensure that you install a JDK, not a JRE,
because some Ant tasks require Java tools that are available only in the
JDK.
Apache Ant
Use Apache Ant to run the Ant scripts.
JAR library files
The following JAR library files provide and enable the Worklight Ant
tasks that are used in the build scripts:

  • worklight-ant.jar:
    Use the worklight-ant.jar file if you are building applications
    on IBM Worklight Server Version 6.0.0. This file is contained in
    the WorklightServer folder of the IBM Worklight Server
    installation.
  • worklight-ant-builder.jar:
    Use the worklight-ant-builder.jar file if you are building
    applications on the IBM Worklight Server Version 6.1.0 or 6.2.0.
    This file is contained in the WorklightServer folder of the IBM
    Worklight Server installation.

Important: Ensure that the version of the JAR library file that you use
(worklight-ant.jar or worklight-ant-builder.jar) matches the version
on the target server.

Tip: An alternative approach to preinstalling the JAR library files on
each build computer is to include them in your build workspace. This
approach allows your build definitions and engines to build with
different versions of Worklight. This approach also supports the
generation of reproducible builds.

The disadvantage of this approach is that the JAR library files can be
large. The large file size might affect the performance of builds and
build computers.

If you share a build system and build computers across multiple teams,
use this alternative approach to manage the JAR library files.

Optional: Dojo
Toolkit
Install the Dojo Toolkit on each build computer in the following
situations:

  • The mobile applications under development use Dojo.
  • The mobile application projects either include the Dojo Toolkit (in the
    workspace project) or access it over a Content Delivery Network.

SDKs

Install one of the following SDKs on each build computer:

Apple Xcode SDK
Install on OS X build computers that run builds to produce iOS
IPA applications. For more information about installing the Apple
Xcode SDK, see
Getting Started with IBM Worklight Module 02.1
Setting Up Your iOS Development Environment.
Android SDK
Install on build computers that run builds to produce Android
APK applications. For more information, see the
IBM MobileFirst Platform site.

Related Information:

Best practices: Setting up Jazz team build

Build scripts

You can create Ant build scripts for Worklight projects that contain applications
and adapters. By using these build scripts, you can automate your mobile
application builds.

Build script tasks

You can create build scripts that use the following types of Ant tasks:

Built-in tasks from
Apache Ant
Includes tasks such as:

  • <echo>
  • <report>
  • <mkdir>
  • <exec>
  • <replaceregexp>
Tasks from IBM Worklight
These tasks perform the following actions:

  • Build Worklight applications and adapters, such
    as
    <app-builder>
    and
    <adapter-builder>.
    IBM Worklight provides a set of Ant tasks that help
    you to build adapters and Worklight applications
    for your IBM Worklight Server.
  • Build IBM Worklight web archive projects. IBM
    Worklight provides the
    <war-builder> Ant task
    for building the Worklight project WAR file.
Tasks from the Rational
Team Concert Build
System Toolkit
These tasks provide information to the build results.
Tasks include:

  • <startBuildActivity>
  • <linkPublisher>
  • <artifactPublisher>

Sample build script task flow

You can create build scripts for Worklight projects that contain different numbers
of applications or adapters. The following sample task flow describes the overall
design of a build script for a Worklight project that has a single Worklight
application and a single adapter.

  1. Use Ant <property> elements to set the properties.
  2. Use a hybrid target to build Worklight applications, adapters, and Worklight
    web archive projects. The hybrid target contains the following actions:

    1. URLs that point to the Worklight Server Console and the Application Center
      are published to either the Ant build log or the Rational Team Concert build
      results.
    2. The Worklight <app-builder> Ant task builds the Worklight application.
    3. The resulting .wlapp file is stored in the build output.
    4. The Worklight <adapter-builder> Ant task builds the adapter.
    5. The resulting .adapter file is stored in the build output.
    6. The Worklight <war-builder> Ant task builds the Worklight web archive
      project.
    7. The resulting WAR file is stored in the build output.
    8. Optional. If you use Rational Team Concert, you can publish the .wlapp,
      .adapter, and WAR files to the Rational Team Concert build results.
  3. When you build an Android application, include the following actions to build
    the native Android APK file:

    1. Run the android command-line tool from the Android SDK to generate the
      Android build.xml file.
    2. Run the generated Android build.xml file to build the APK file.
    3. Optional. Publish the Android APK file to the location where you store your
      build output. For example, if you use Rational Team Concert, publish the
      APK file to the Rational Team Concert build results.
  4. When you build an iOS application, include the following actions to build the
    native iOS IPA file:

    1. Run the xcodebuild command-line tool from the Xcode SDK to build the
      iOS application.
    2. Run the xcrun command-line tools from the Xcode SDK to package the iOS
      application into an IPA file.
    3. Optional. Publish the iOS IPA file to the location where you store your build
      output. For example, if you use Rational Team Concert, publish the IPA file
      to the Rational Team Concert build results.
  5. Add your Worklight application, adapter, Worklight web archive project (WAR
    file), and native application (Android APK file or iOS IPA file) to UrbanCode
    Deploy as a new version.Tip: You can have multiple Worklight applications and adapters. If you have
    more than one Worklight application or adapter, repeat calls to tasks to
    build the mobile artifacts, add new property values, and then add the new
    artifacts to UrbanCode Deploy.


Related information:

Ant tasks for building and deploying

Building a project WAR file with Ant

Jazz build Ant task reference

Jazz Team Build

The Jazz Team Build system defines resources that are used to describe and
manage builds.

This section describes the following Jazz Team Build facilities:

Logical resources for builds

The Jazz Team Build system in Rational Team Concert defines the following types
of logical resources that are used to describe and manage builds:

Build definition
A build definition describes:

  • The workspace to process
  • The Ant scripts and targets to run against the workspace
  • The schedule for the build
  • The properties to simplify the configuration of the build
  • The build engines that can handle build requests for the build definition
Build engine
A build engine represents a Build System Toolkit Jazz Build Engine
running on a designated build computer. A Jazz Build Engine running on a
Worklight plug-in 7
build computer correlates itself to a build engine in Rational Team Concert
by specifying the unique identifier of the build engine.
Build request
A build request represents a scheduled or explicitly issued request to run a
build according to a specified build definition. Build definitions are
submitted to a build queue. A Jazz Build Engine receives and processes the
build request if its corresponding build engine in Rational Team Concert is
listed as a supporting build engine for the build definition.
Build result
A build result represents the output of a build.

Build system toolkit

Each build computer contains an installation of the Rational Team Concert Build
System Toolkit.

The Build System Toolkit consists of the following major components:

Jazz Build Engine
The Jazz Build Engine is a command-line tool that polls for and processes
build requests from Rational Team Concert. When the Jazz Build Engine is
started, it must identify a corresponding build engine in Rational Team
Concert. The Jazz Build Engine can then accept any build request whose
build definition is supported by the build engine. The Jazz Build Engine
runs the Ant script and targets that are specified in the build definition.
Each build is represented in Rational Team Concert by a build result.
Build toolkit
The build toolkit is a collection of Ant tasks. Ant scripts can use these tasks
to send information (such as build progress, results, links, artifacts) to
Rational Team Concert to include in the build result.
Build agent
The build agent is a lightweight process that handles agent-based builds
that support z/OS or IBM i build scenarios. For the Worklight plug-in,
use the Jazz Build Engine instead.Note: The Jazz Build Engine is a component of the Build System Toolkit; it
refers to the process that runs on a build computer and runs Ant
scripts.

Related information:

Building with Jazz Team Build

Build definitions

In Rational Team Concert, a build definition describes the key components of a
build.

The build definition describes the following components:

  • The workspace to process.
  • The Ant scripts and targets to run against the workspace.
  • The schedule for the build.
  • The properties that simplify the configuration of the build.
  • The build engines that can manage build requests for the build definition.

The following sections describe the considerations that apply when you build IBM
Worklight mobile applications.

Supporting build engines
When you specify a build engine to run build requests for the build definition, ensure that any required SDKs (such as the Android SDK or the Apple Xcode SDK) are installed and configured on the build engine.
Properties
You can use properties to customize the build for a specific build definition. For
example, you can set properties for the path to the build output or the native SDK.
Ant build file and targets
In the Build file field, use the following value to specify the location of the Ant
build script that is loaded with the workspace located in the following path:loadDir/${buildLabel}/project/
folder/scriptItems in the path are defined as follows:

  • project is the name of the project that contains the build scripts.
  • folder is the name of the folder within the project that contains the build scripts.
  • script isthe name of the build script XML file.

Tip: If you choose a different relative location for your build script in the
workspace, you must change the value of the loadDir property.

In the Build targets field, specify any specific targets that you want to run in your
build script. By default, build scripts run the all target.

Ant configuration
Ant configuration includes the following tasks:

  • Select the option to include the Jazz build toolkit tasks on the Ant library path.
  • In the Ant home field, specify the location on the build computer where Apache
    Ant is installed.
  • In the Ant arguments field, specify the -lib argument that includes the
    worklight-ant-builder.jar
    required library on the Ant library path. If you are
    building applications on the IBM Worklight Server Version 6.0.0 you can use the
    worklight-ant.jar
    file instead of the
    worklight-ant-builder.jar
    file.Important:
    Ensure that the version of the JAR library file that you use
    (worklight-ant.jar or worklight-ant-builder.jar) matches the
    version on the target server.Use the following format for the -lib argument:

    -lib path\JAR file name

    The parameters are defined as follows:

    • path is the path to the directory on the build computer that contains the JAR
      file. The path might be a location on the build computer where the JAR
      Worklight plug-in 9
      libraries were preinstalled. The path might also point to a location
      within the loaded workspace if you chose to include the JAR libraries in
      the build workspace.
    • JAR file name is the name of the JAR file that is included in the library.
  • In the Java home field, specify the location on the build computer where the
    Oracle JDK is installed.

Related information:

Building with Jazz Team Build

Getting Started with IBM Worklight Using Rational Team Concert to build
your applications

Building and deploying mobile applications

You can set up your development environment so that you can build your mobile
applications and, by using the IBM MobileFirst Platform plug-in for IBM UrbanCode Deploy,
deploy the build results to the IBM Worklight Server.

Before you begin

Ensure that the following software is installed and running:

  • IBM UrbanCode Deploy
  • IBM Worklight Server with the Application Center and Console running
  • IBM Worklight Studio

Extra software might be required, such as:

  • Source control management (SCM) system
  • Build engine
  • Application server
  • Database

About this task

Before you can build and deploy mobile applications to the Worklight Server, you
must complete the following configuration steps:

  1. Configure the build system.
  2. Configure UrbanCode Deploy, including the following steps:

    • Create components.
    • Create component processes or application processes that include steps from
      the IBM MobileFirst Platform plug-in to deploy the mobile application.
  3. Configure Worklight Server Console, including the following steps:
    • Create and configure a database.
    • Configure the Worklight project Web Archive (WAR) file.

Procedure

After you set up the build, UrbanCode Deploy and Worklight Server console, you
can build and deploy mobile applications by using the following high-level steps:

  1. Check in (commit) changes from IBM Worklight Studio into a source control
    management (SCM) system.
  2. Build the application and add a new version to UrbanCode Deploy.

    Tip: Assign a version to the mobile application that is deployed to the
    Application Center. This version must match the version that is assigned
    in UrbanCode Deploy. For example, if the mobile application has a
    commercial version of 1.0 on the Application Center and the internal
    version from the latest build is 16, assign version 1.0.16 to the application
    in UrbanCode Deploy. Keeping the version numbers synchronized helps
    you to recover if you encounter a problem. For example, if the latest
    version of the mobile application was not deployed successfully to the
    Application Center.

  3. Request deployment in UrbanCode Deploy.
  4. View the mobile artifacts in the Worklight Console, install, and test the
    application from the Application Center.

Results

The mobile application artifacts are deployed to the Worklight Server and can be
installed on the target device.

What to do next

Optionally, create extra component and application processes in UrbanCode
Deploy to roll back deployments (for example, to recover from an error condition
or an incomplete deployment.) See Rolling back mobile applications.

Troubleshooting

The following information can assist you in troubleshooting the IBM MobileFirst Platform plug-in:

  • To ensure that your IBM MobileFirst mobile applications are built correctly for continuous deployment, see How to build Worklight mobile applications for continuous deployment.
  • If an undefined error message is displayed when you upload an invalid plug-in in Microsoft Internet Explorer, see Undefined error message when uploading invalid plug-in.
  • If a request error (400 or 500) occurs when uploading files by using the addVersionFilesCommand command from the command-line interface (CLI), see Uploading files with old version of CLI fails with request errors.
  • If a SEVERE: Service Unavailable error message is displayed when you run concurrent instances of the plug-in component process step Deploy Worklight Application to Worklight Server, see Deploying Worklight applications in parallel fails with message Service Unavailable.
  • Note: You might see a REST 404 Not Found error message during an UrbanCode deployment that runs to completion. This error message is expected, and can occur in any of the plug-in steps when working with IBM Worklight Foundation Server 6.2. The error message occurs as the result of an attempt to connect to a different version of the IBM Worklight Server from the one currently running. For IBM Worklight Server 6.0 and 6.1, a REST request method is used and the error message is not displayed. For IBM Worklight Foundation 6.2, the REST request method is not available, and therefore the REST 404 Not Found error is returned. For IBM Worklight Foundation 6.2, a different method is used. As a result, the error message is displayed but the overall deployment can still run to completion. When debugging a problem where a deployment does not run to completion, ensure that REST 404 Not Found is not the only error in the logs.