IBM MobileFirst Platform (formerly Worklight) - 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.

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:
  2. 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.
  3. 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 applicationsAlternatively, you can first remove or modify the artifacts on the Worklight Console by using these steps:
    • Remove Adapter from Worklight Server
    • Remove Worklight Application from Worklight Server
    • Change Worklight Application Access Rule on Worklight Server
  4. 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

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:

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:
    • Deploy the Worklight Adapter (.adapter) file to the Worklight Server Console by using the Deploy Adapter to Worklight Server step.
    • Deploy the Worklight Application (.wlapp) file to the Worklight Server Console by using the Deploy Worklight Application to Worklight Server step.
  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:

Tips:

### 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 |

  1. 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:

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:

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:

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:

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:

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:

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:

Tasks from IBM Worklight These tasks perform the following actions:

Tasks from the Rational Team Concert Build System Toolkit These tasks provide information to the build results. Tasks include:

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:
  3. 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.
  4. The Worklight <app-builder> Ant task builds the Worklight application.
  5. The resulting .wlapp file is stored in the build output.
  6. The Worklight <adapter-builder> Ant task builds the adapter.
  7. The resulting .adapter file is stored in the build output.
  8. The Worklight <war-builder> Ant task builds the Worklight web archive project.
  9. The resulting WAR file is stored in the build output.
  10. Optional. If you use Rational Team Concert, you can publish the .wlapp, .adapter, and WAR files to the Rational Team Concert build results.
  11. When you build an Android application, include the following actions to build the native Android APK file:
  12. Run the android command-line tool from the Android SDK to generate the Android build.xml file.
  13. Run the generated Android build.xml file to build the APK file.
  14. 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.
  15. When you build an iOS application, include the following actions to build the native iOS IPA file:
  16. Run the xcodebuild command-line tool from the Xcode SDK to build the iOS application.
  17. Run the **xcrun** command-line tools from the Xcode SDK to package the iOS application into an IPA file.
  18. 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.
  19. 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:

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

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:

The parameters are defined as follows:

Related information:

Building with Jazz Team Build

Getting Started with IBM WorklightUsing 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:

Extra software might be required, such as:

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

  1. Request deployment in UrbanCode Deploy.
  2. 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.

Back to …   Latest Version IBM MobileFirst Platform (formerly Worklight)        
All Plugins Deploy Plugins 13.1098510 Readme Overview Steps Troubleshooting Downloads