IBM Worklight V6.0.0 Information Center

In se

ca of

IBM Worklight V6.0.0

Th l IB is is M su d es o W , r cu ork ef me lig er n h t o t is t o th p ffli e ro ne on vi u lin de se e d" rd us as o er is cu do ". me nt cu at m io en n ta tio n.

ta

en

rim

pe

Ex

򔻐򗗠򙳰

ii IBM Worklight V6.0.0

In se

ca of Th l IB is is M su d es o W , r cu ork ef me lig er n h t o t is t o th p ffli e ro ne on vi u lin de se e d" rd us as o er is cu do ". me nt cu at m io en n ta tio n.

ta

en

rim

pe

Ex

Contents Chapter 1. Overview of IBM Worklight . . 1 . . . . . . .

. . . . . . .

1 3 5 8 8 9 9

Chapter 2. What's new . . . . . . . . 13 What's new in IBM Worklight V6.0.0.2 . . . . . What's new in IBM Worklight V6.0.0.1 . . . . . What's new in IBM Worklight V6.0.0 . . . . . . New functional testing capabilities . . . . . New operational analytics feature . . . . . . Enhancing applications with location features . . Enhanced rapid application development . . . Features to optimize IBM Worklight applications Improved serviceability . . . . . . . . . Enhanced IBM Worklight API . . . . . . . Augmented support of mobile environments and operating systems . . . . . . . . . . . Miscellaneous modifications . . . . . . . .

13 14 14 14 15 15 16 17 19 20 22 22

Chapter 3. Tutorials and samples . . . 25 Chapter 4. Installing and configuring

rim

en

ta

IBM Worklight installation overview . . . . . . Installing Worklight Studio . . . . . . . . . Running post-installation tasks . . . . . . . Starting Worklight Studio. . . . . . . . . Installing mobile specific tools . . . . . . . Changing the port number of the internal application server . . . . . . . . . . . Installing IBM Mobile Test Workbench for Worklight Troubleshooting IBM Mobile Test Workbench for Worklight . . . . . . . . . . . . . . Installing Worklight Server . . . . . . . . . Installation prerequisites . . . . . . . . . Overview of the Worklight Server installation process . . . . . . . . . . . . . . . Running IBM Installation Manager . . . . . Distribution structure of Worklight Server . . . Manually installing Application Center . . . . Configuring Worklight Server . . . . . . . . Backup and recovery . . . . . . . . . . Optimization and tuning of Worklight Server . . Optimization and tuning of Worklight Server project databases . . . . . . . . . . . Security configuration . . . . . . . . . . Transmitting IBM Worklight data on the BlackBerry Enterprise Server MDS channel . . . Protecting your mobile application traffic by using IBM WebSphere DataPower as a security gateway . . . . . . . . . . . . . .

In

ca

se

of

pe Ex

Configuring SSL between IBM Worklight Servers and clients by using certificates that are not signed by a trusted certificate authority . . Handling MySQL stale connections . . . . . Installing the Application Center . . . . . . . Configuring the Application Center after installation . . . . . . . . . . . . . . Configuring WebSphere Application Server full profile . . . . . . . . . . . . . . . Configuring WebSphere Application Server Liberty Profile . . . . . . . . . . . . Configuring Apache Tomcat . . . . . . . Managing users with LDAP . . . . . . . Defining the endpoint of the application resources . . . . . . . . . . . . . . Configuring Secure Sockets Layer (SSL) . . . Typical topologies of an IBM Worklight instance Setting up IBM Worklight in an IBM WebSphere Application Server Network Deployment V8.5 cluster environment . . . . . . . . . . Setting up IBM Worklight in an IBM WebSphere Application Server Liberty Profile farm. . . . Installing and configuring the IBM WebSphere Analytics Platform. . . . . . . . . . . . Configuring Worklight Server for analytics . . Troubleshooting Worklight Server . . . . . . Troubleshooting to find the cause of installation failure . . . . . . . . . . . . . . . Troubleshooting failure to create the DB2 database . . . . . . . . . . . . . . Troubleshooting an installation blocked by DB2 connection errors . . . . . . . . . . .


Introduction to mobile application development Overview of IBM Worklight main capabilities . Introducing IBM Worklight components . . . IBM Worklight editions . . . . . . . . . System requirements for using IBM Worklight . Matrix of features and platforms. . . . . . Known limitations . . . . . . . . . .

35 35 35 36 37 37 39 40

41 41 42

43 47 62 66 83 83 84

86 88 94

95

Chapter 5. Upgrading from one version of IBM Worklight to another

106 116 118 118

119

120 121 121

139 143 145

147

161

174 176 177 177

177

178

. 181

Migrating from IBM Worklight V5.0.6 to V6.0.0 . Migrating an IBM Worklight project to use the Dojo library . . . . . . . . . . . . Manually migrating Facebook apps . . . . Migrating Worklight Studio to V6.0.0 . . . Migrating projects to a new Worklight Studio instance . . . . . . . . . . . . . Upgrading Worklight Server in a production environment. . . . . . . . . . . . Migrating from IBM Worklight V5.0.5 to V5.0.6 . Dojo iOS fixes . . . . . . . . . . . Dojo 1.8.3 code migration . . . . . . . Migrating from IBM Worklight V5.0.0.3 to V5.0.5

. 181

. 184 . 188 . 189

. 190 . . . .

191 224 228 228 229

Chapter 6. Developing IBM Worklight applications . . . . . . . . . . . . 233 Worklight Studio overview . . . . . . . IBM Worklight client-side API overview . . IBM Worklight server-side API overview . . Artifacts produced during development cycle

. . . .

. . . .

233 236 237 238

iii

ta

en

rim

In

ca

se

of

pe Ex

iv

239 240 241 242 244 246 246 247

Store internals . . . . . . . . . . JSONStore asynchronicity, callbacks, and promises . . . . . . . . . . . . Chain JSONStore functions and concurrency JSONStore events . . . . . . . . . JSONStore errors . . . . . . . . . JSONStore error codes . . . . . . . JSONStore support . . . . . . . . JSONStore performance . . . . . . . JSONStore multiple user support . . . . JSONStore security . . . . . . . . Worklight adapter integration for JSONStore Troubleshooting JSONStore and data synchronization . . . . . . . . . Push notification . . . . . . . . . . Possible IBM Worklight push notification architectures . . . . . . . . . . . Subscribe SMS servlet . . . . . . . Windows Phone 8 push notifications . . Sending push notifications from WebSphere Application Server – IBM DB2. . . . . IBM Worklight security framework . . . . IBM Worklight Security Overview . . . Security Tests . . . . . . . . . . Authentication realms . . . . . . . Authenticators and Login Modules . . . The authentication configuration file . . Configuring IBM Worklight web application authorization . . . . . . . . . . Configuring authenticators and realms . . Basic authenticator . . . . . . . . Form-based authenticator . . . . . . Header authenticator . . . . . . . . Persistent cookie authenticator . . . . Adapter authenticator . . . . . . . LTPA authenticator . . . . . . . . Configuring login modules . . . . . . Non-validating login module . . . . . Database login module . . . . . . . Single identity login module . . . . . Header login module . . . . . . . . WASLTPAModule login module . . . . LDAP login module . . . . . . . . Mobile device provisioning . . . . . . Configuring and implementing device provisioning . . . . . . . . . . . Device single sign-on (SSO) . . . . . Configuring device single sign-on . . . IBM Worklight application authenticity overview . . . . . . . . . . . . Developing globalized hybrid applications . Globalization in JavaScript frameworks. . Globalization mechanisms in IBM Worklight Globalization of web services . . . . . Globalization of push notifications . . . Developing accessible applications . . . . Location services . . . . . . . . . . Platform support for location services . . Triggers . . . . . . . . . . . . Setting an acquisition policy . . . . . Working with geofences and triggers . .

.

. 398

. . . . . . . . .

. . . . . . . . .

. .

. 410 . 410

. . .

. 411 . 413 . 415

. . . . . . .

. . . . . . .

416 417 417 421 423 424 424

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

426 426 427 428 429 429 429 430 431 432 432 433 434 434 434 436

. . .

. 439 . 440 . 440

. . .

. 441 . 445 . 445 456 . 465 . 466 . 469 . 470 . 472 . 472 . 474 . 475

399 399 400 400 401 403 405 406 407 407


IBM Worklight projects, environments, and skins . . . . . . . . . . . . . . . Creating IBM Worklight projects . . . . . . Creating an application in an IBM Worklight project. . . . . . . . . . . . . . . Creating the client-side of an IBM Worklight application . . . . . . . . . . . . . Integrating with source control systems . . . Developing hybrid and web applications . . . . Anatomy of an IBM Worklight project . . . . Anatomy of an IBM Worklight application . . Setting up a new IBM Worklight environment for your application . . . . . . . . . . The Worklight Development Server and the Worklight Console. . . . . . . . . . . Working with multiple Worklight Servers in Worklight Studio . . . . . . . . . . . Developing user interface of hybrid applications Using IBM Worklight Client API . . . . . . Connecting to Worklight Server . . . . . . Web and native code in iPhone, iPad, and Android . . . . . . . . . . . . . . Developing hybrid applications for iOS. . . . Developing hybrid applications for Android . . Developing hybrid applications for BlackBerry Development guidelines for desktop and web environments . . . . . . . . . . . . Developing native applications . . . . . . . Development guidelines for using native API Developing native applications for iOS . . . . Developing native applications for Android . . Developing native applications for Java Platform, Micro Edition . . . . . . . . . Optimizing IBM Worklight applications . . . . Including and excluding application features Application cache management in Desktop Browser and Mobile Web apps . . . . . . IBM Worklight application build settings . . . Minification of JS and CSS files . . . . . . Concatenation of JS and CSS files. . . . . . Developing the server side of an IBM Worklight application . . . . . . . . . . . . . . Overview of IBM Worklight adapters . . . . The adapter XML File . . . . . . . . . Creating an IBM Worklight adapter . . . . . Adapter invocation service . . . . . . . . Implementing adapter procedures . . . . . Encoding a SOAP XML envelope . . . . . . Calling Java code from a JavaScript adapter . . Features of Worklight Studio . . . . . . . Procedure invocation . . . . . . . . . . Invoking a back-end service . . . . . . . Deploying an adapter . . . . . . . . . JSONStore overview . . . . . . . . . . . JSONStore features comparison . . . . . . Enabling JSONStore . . . . . . . . . . JSONStore document . . . . . . . . . . JSONStore collection . . . . . . . . . . JSONStore store . . . . . . . . . . . JSONStore search fields . . . . . . . . . JSONStore queries . . . . . . . . . . . IBM Worklight V6.0.0

262

266

268 278 317 317

318 321 322 327

328 331 331 333 336 340 342 343 346 351 354 356

360 360 364 377 380 381 382 383 383 388 389 392 393 394 395 396 397 397 397 398

. . . . . . . .

663

Remotely disabling application connectivity . . Displaying a notification message on application startup . . . . . . . . . . . . . . Defining administrator messages from Worklight Console in multiple languages . . . Controlling authenticity testing for an app . . Administering push notifications with the Worklight Console. . . . . . . . . . . . Application Center . . . . . . . . . . . Concept of the Application Center . . . . . General architecture . . . . . . . . . . Preliminary information . . . . . . . . . Preparations for using the mobile client . . . Push notifications of application updates . . . The Application Center console . . . . . . Command-line tool for uploading or deleting an application . . . . . . . . . . . . . Publishing Worklight applications to the Application Center . . . . . . . . . . The mobile client . . . . . . . . . . . Advanced information for BlackBerry users . . Application review feature called from another application (advanced feature). . . . . . . Federal standards support in IBM Worklight . . . FDCC and USGCB support. . . . . . . . FIPS 140-2 support . . . . . . . . . .

663 665 665

Chapter 10. Monitoring, reports, and operational analytics . . . . . . . . 833

. . .

. 477 . 480 . 481

. . . .

. . . .

483 483 485 485

Chapter 7. API reference

. . . . . . 489

IBM Worklight client-side API . . . . . . . JavaScript client-side API . . . . . . . Objective-C client-side API for native iOS apps Java client-side API for native Android apps Java client-side API for Java ME apps . . . IBM Worklight server-side API . . . . . . JavaScript server-side API . . . . . . . Java server-side API . . . . . . . . . Internal IBM Worklight database tables . . . . HTTP Interface of the production server . . .

. 489 . 489 620 620 . 620 . 620 . 620 . 653 . 653 . 660

Chapter 8. Deploying IBM Worklight projects . . . . . . . . . . . . . . 663

rim

en

ta

Deploying IBM Worklight applications to test and production environments . . . . . . . . . Deploying an application from development to a test or production environment . . . . . . Building a project WAR file with Ant . . . . Deploying an IBM Worklight project . . . . Configuration of IBM Worklight applications on the server . . . . . . . . . . . . . Ant tasks for building and deploying applications and adapters . . . . . . . . Deploying applications and adapters to Worklight Server . . . . . . . . . . . Administering adapters and apps in Worklight Console . . . . . . . . . . . . . . High availability . . . . . . . . . . . Deploying to the cloud by using IBM PureApplication System . . . . . . . . . . Installing IBM Worklight support for PureApplication System . . . . . . . . . Working with the IBM Mobile Application Platform Pattern Type . . . . . . . . . Working with IBM Worklight PureApplication System Extension for Worklight Studio . . . . Building and deploying IBM Worklight virtual applications by using the command line interface . . . . . . . . . . . . . . Deployment of the Application Center on IBM PureApplication System . . . . . . . . .

714

730

733

735 738

740

740 742

747

748 750

ca

se

of

pe Ex

Chapter 9. Administering IBM Worklight applications . . . . . . . 755

In

758 761 761 765


Differentiating between indoor areas . . Securing server resources based on location Tracking the current location of devices . Keeping the application running in the background . . . . . . . . . . . Client-side log capture . . . . . . . . Server preparation for uploaded log data . Client-side logging in client apps . . . .

Administering IBM Worklight applications with Worklight Console. . . . . . . . . . . . 755 Direct updates of app versions to mobile devices . . . . . . . . . . . . . . 755 Direct updates of app versions to desktop apps 757 Locking an application . . . . . . . . . 757

Logging and monitoring mechanisms . . . . Vitality queries for checking server health . . Configuring logging in the development server Routing logging to Windows event log . . . Comparison of operational analytics and reports features . . . . . . . . . . . . . . Operational analytics . . . . . . . . . . IBM Worklight analytics components . . . Analytics event types. . . . . . . . . Analytics page . . . . . . . . . . . Capturing client analytic data . . . . . . Analytics data flow . . . . . . . . . Managing data throughput and accumulation Enabling analytics for existing applications . Logging additional data . . . . . . . . Integrating with the IBM Tealeaf CX Mobile server . . . . . . . . . . . . . . Troubleshooting analytics . . . . . . . Reports . . . . . . . . . . . . . . Using raw data reports . . . . . . . . Device usage reports . . . . . . . . . Predefined BIRT Reports . . . . . . . Installing BIRT on Apache Tomcat . . . . Installing BIRT on WebSphere Application Server Liberty Profile . . . . . . . . . Installing BIRT on WebSphere Application Server Full Profile . . . . . . . . . . Configuring BIRT reports for your application server by using Ant . . . . . . . . . Manually configuring BIRT Reports for your application server . . . . . . . . . . BIRT in Eclipse . . . . . . . . . . .

767 769 769 770 772 772 779 782 797

802 805 826

828 830 830 830

. 833 . 834 836 . 838

. . . . . . .

839 840 841 842 843 851 852 853 . 855 . 855

. . . . . . .

856 858 859 861 865 867 869

. 871 . 873 . 874 . 875 . 876

Contents

v

Notification reports database schema

.

.

.

. 889

B C D E F G H I. K L M N P R S T V W

. 889

Chapter 15. Notices . . . . . . . . . 903

. 890

Chapter 16. Support and comments

. 891 . 891

Index . . . . . . . . . . . . . . . 911

. 878

Chapter 11. Integrating with other IBM Mobile Foundation products . . . . . 881 881 882 883 884

885 887 888

Chapter 12. Migrating from the WebSphere Application Server Feature Pack . . . . . . . . . . . 889 Migration scenarios . . . . . . . . . . Migrating an application that uses the client programming model . . . . . . . . . . Migrating an application that uses the server programming model . . . . . . . . . . Considerations for applications that use JAX-RS, JSON-RPC, or proxying . . . . . . . . . Example: Migrating the Dojo showcase sample .

Chapter 13. Troubleshooting and known limitations . . . . . . . . . 893 Chapter 14. Glossary . . . . . . . . 895 .

.

.

.

.

.

.

.

of

In

ca

se

Ex

pe

rim

en

ta

A .

vi

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

896 896 897 897 897 898 898 898 898 898 899 899 899 900 900 901 901 901


Introduction to IBM Worklight integration options Integration with Cast Iron . . . . . . . . . Integration with reverse proxy. . . . . . . . Authentication at the gateway . . . . . . . IBM Endpoint Manager for Mobile Devices overview . . . . . . . . . . . . . . . Managing end points with IBM Endpoint Manager Useful links . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .


.

.

.

.

.

.

.

. 895

907

Chapter 1. Overview of IBM Worklight


Start here to learn about IBM® Worklight® product.

With IBM Worklight, you can extend your business to mobile devices. IBM Worklight provides an open, comprehensive, and advanced mobile application platform for smartphones and tablets. It helps organizations of all sizes to efficiently develop, test, connect, run, and manage mobile and applications. Using standards-based technologies and tools, IBM Worklight provides an integrated platform that includes a comprehensive development environment, mobile-optimized runtime middleware, a private enterprise application store, and an integrated management and analytics console, all supported by various security mechanisms. Read the following topics to learn more IBM Worklight.

Introduction to mobile application development

With IBM Worklight, you can develop mobile applications by using any of four different approaches: web development, hybrid development, hybrid mixed development, and native development.

IBM Worklight provides capabilities to help you respond to the fast-paced development of mobile devices. IBM Worklight is based on open standards such as HTML, CSS, or JavaScript, and solutions such as Apache Cordova, Eclipse Foundation, or the Android and Apple SDKs, for delivering mobile solutions. This gives you more flexibility when you implement your mobile communication channel, or release a new version of your application. You can evaluate what the best approach is for each case, according to skills, time, and functionality, without being limited by a specific approach to mobile application development.

In

Web development

By using the web development approach, your application runs inside the browser of the mobile device, and uses standard technologies such as HTML5, CSS3, and JavaScript. Your application is platform independent, so you do not need to develop a new application to support a new mobile platform. Modifications to your application might be required to support a different browser engine. Mobile web applications cannot access the platform functions because they rely only on the browser, and the associated web standards. Mobile web applications are not distributed through an application store. They are accessed through a link on a website, or a bookmark in the mobile browser of the user.

of

ca

se

Ex

pe

rim

en

ta

Four approaches exist to develop your mobile applications:

Hybrid development With the hybrid development approach, you can create applications that use parts of both the native development and web development approaches. Your hybrid application runs inside a native container and uses the browser engine to display the application interface, which is based on HTML and JavaScript. With the native container, your application can access device capabilities that are not accessible to web applications, such as the accelerometer, camera, and local storage on a

1

smartphone. Similar to native applications, hybrid applications are distributed through the application store of the platform.

Hybrid mixed development


You can enhance the hybrid development approach with hybrid mixed development. With the hybrid mixed development approach, you can create applications that use a container to access device capabilities, but also use other native, platform-specific components such as libraries, or specific user-interface elements to enhance the mobile application.

Native development

With the native development approach, you can create applications that are written for a specific platform and runs on that platform only. Your applications can fully use all platform functions such as accessing the camera or contact list, or interacting with other applications on the device. To support platforms such as Android, iOS, BlackBerry, and Windows Phone, you must develop separate applications with different programming languages, such as Objective-C for iOS, or Java™ for Android. Typically, native applications are distributed through an application store.

Aspects of each development approach

Each of these development approaches has advantages and disadvantages. You must select the appropriate development approach according to the specific requirements for an individual mobile solution. This choice depends heavily on the specificities of your mobile application and its functional requirements. Mapping your requirements to select an appropriate development approach is the first step in a mobile development project. Table 1 outlines the major aspects of the four development approaches, and can help you decide which development approach is appropriate for your specific mobile application.

2

Aspect

Web development

Hybrid development


Native development

Easy to learn

Easy

Medium

Medium

Hard

Application performance

Slow

Moderate

Moderate

Fast

Device knowledge required

None

Some

Some

A lot

Development lifecycle (build/test/ deploy)

Short

Medium

Medium

Long

Application portability to other platforms

High

High

Medium

None

Support for native device functionality

Some

Most

All

All

of

In

ca

se

Ex

pe

rim

en

ta

Table 1. Comparison of mobile development approaches


Table 1. Comparison of mobile development approaches (continued) Web development

Hybrid development


Native development

Distribution with built-in mechanisms

No

Yes

Yes

Yes

Ability to write extensions to device capabilities

No


Aspect

Yes

Yes

Yes

Overview of IBM Worklight main capabilities

With IBM Worklight, you can use capabilities such as development, testing, back-end connections, push notifications, offline mode, update, security, analytics, monitoring, and application publishing.

Development

IBM Worklight provides a framework that enables the development, optimization, integration, and management of secure applications that run on smartphones and other consumer environments. IBM Worklight does not introduce a proprietary programming language or model that users must learn. You can develop apps by using HTML5, CSS3, and JavaScript. You can optionally write native code (Java or Objective-C), and IBM Worklight provides an SDK that includes libraries that you can access from native code.

Testing

In

Back-end connections

Some mobile applications run strictly offline with no connection to a back-end system, but most mobile applications connect to existing enterprise services to provide the critical user-related functions. For example, customers can use a mobile application to shop anywhere, at any time, independent of the operating hours of the store. Their orders must still be processed by using the existing e-commerce platform of the store. To integrate a mobile application with enterprise services, you must use middleware such as a mobile gateway. IBM Worklight can act as this middleware solution and make communication with back-end services easier.

of

ca

se

Ex

pe

rim

en

ta

IBM Worklight includes IBM Mobile Test Workbench for Worklight for testing mobile applications. With the mobile testing capabilities of IBM Mobile Test Workbench for Worklight, you can automate the creation, execution, and analysis of functional tests for IBM Worklight native and hybrid applications on Android and iOS devices.

Push notifications With push notifications, mobile applications can send information to mobile devices, even when the application is not being used. IBM Worklight includes a unified notification framework that provides a consistent mechanism for such push notifications. With this unified notification framework, you can send push notifications without having to know the details of each targeted device or


3

platform, because each mobile platform has a different mechanism for these push notifications.

Offline


In terms of connectivity, mobile applications can operate offline, online, or in a mixed mode. IBM Worklight uses a client/server architecture that can detect whether a device has network connectivity, and the quality of the connection. Acting as a client, mobile applications periodically attempt to connect to the server and to assess the strength of the connection. An offline-enabled mobile application can be used when a mobile device lacks connectivity but some functions can be limited. When you create an offline-enabled mobile application, it is useful to store information about the mobile device that can help preserve its functionality in offline mode. This information typically comes from a back-end system, and you must consider data synchronization with the back end as part of the application architecture. IBM Worklight includes a feature called JSONStore for data exchange and storage, that provides the ability to create, read, update, and delete data records from a data source. Each operation is queued when operating offline. When a connection is available, the operation is transferred to the server and each operation is then performed against the source data.

Update

IBM Worklight simplifies version management and mobile application compatibility. Whenever a user starts a mobile application, the application communicates with a server. By using this server, IBM Worklight can determine whether a newer version of the application is available, and if so, give information to the user about it, or push an application update to the device. The server can also force an upgrade to the latest version of an application to prevent continued use of an outdated version.

Protecting confidential and private information is critical for all applications within an enterprise, including mobile applications. Mobile security applies at various levels, such as mobile application, mobile application services, or back-end service. You must ensure customer privacy and protect confidential data from being accessed by unauthorized users. Dealing with privately owned mobile devices means giving up control on certain lower levels of security, such as the mobile operating system. IBM Worklight provides secure, end-to-end communication by positioning a server that oversees the flow of data between the mobile application and your back-end systems. IBM Worklight gives you the possibility to define custom security handlers for any access to this flow of data. Because any access to data of a mobile application has to go through this server instance, you can define different security handlers for mobile applications, web applications, and back-end access. With this kind of granular security, you can define separate levels of authentication for different functions of your mobile application or avoid sensitive information being accessed from a mobile application entirely.

of

In

ca

se

Ex

pe

rim

en

ta

Security

Analytics The operational analytics feature enables searching across apps, services, devices, and other sources to collect data about usage or detect problems.

4


In addition to reports summarizing app activity, IBM Worklight includes a scalable operational analytics platform accessible in the Worklight Console. The analytics feature enables enterprises to search across logs and events that are collected from devices, apps, and servers for patterns, problems, and platform usage statistics. You can enable analytics, reports, or both, depending on your needs.


Application publishing

IBM Worklight Application Center is an enterprise application store. With the Application Center, you can install, configure, and administer a repository of mobile applications for use by individuals and groups across your enterprise. You can control who in your organization can access the Application Center and upload applications to the Application Center repository, and who can download and install these applications on to a mobile device. You can also use the Application Center to collect feedback from users and access information about devices on which applications are installed.

The concept of the Application Center is similar to the concept of the Apple public App Store or the Google Play store, except that it targets the development process. It provides a repository for storing the mobile application files and a web-based console for managing that repository. It also provides a mobile client application to allow users to browse the catalog of applications that are stored by the Application Center, install applications, leave feedback for the development team, and expose production applications to IBM Endpoint Manager. Access to download and install applications from the Application Center is controlled by using access control lists (ACLs).

Introducing IBM Worklight components

IBM Worklight consists of different components: Worklight Studio, Worklight Server, client-side runtime components, Worklight Console, Application Center, and IBM Mobile Application Platform Pattern.

v Develop rich HTML5, hybrid and native applications for all supporting modern devices by using native code, a bidirectional WYSIWYG, and standard web technologies and tools. v Maximize code sharing by defining custom behavior and styling guidelines that match the target environment. v Access device APIs by using native code or standard web languages over a uniform Apache Cordova bridge. Apache Cordova is preinstalled with Worklight, therefore do not download your own Apache Cordova version.

of

ca In

In a mobile development platform, cross-platform portability of the application code is critical for mobile device application development. Various methods exist to achieve this portability. With IBM Worklight, you can develop multiplatform applications by using Worklight Studio, which is an integrated development environment for mobile applications, to address the requirements of the organization. You can use Worklight Studio for the following tasks:

se

Ex

pe

rim

en

ta

Worklight Studio

v Use both native and standard web languages within the same application to balance development efficiency and a rich user experience. v Use third-party tools, libraries, and frameworks such as JQuery Mobile, Sencha Touch, and Dojo Mobile. Chapter 1. Overview of IBM Worklight

5

v Implement runtime skins to build apps that automatically adjust to environment guidelines such as form factor, screen density, HTML support, and UI input method.


Worklight Server The Worklight Server is a runtime container for the mobile applications you develop in Worklight Studio. It is not an application server in the Java Platform, Enterprise Edition (JEE) sense. It acts as a container for Worklight application packages, and is in fact a collection of web applications (optionally packaged as an EAR file) that run on top of traditional application servers. Worklight Server is designed to integrate into the enterprise environment and use its existing resources and infrastructure. This integration is based on adapters that are server-side software components responsible for channeling back-end enterprise systems and cloud-based services to the user device. You can use adapters to retrieve and update data from information sources, and to allow users to perform transactions and start other services and applications.

You can use Worklight Server for the following tasks: v Empower hundreds of thousands of users with transactional capabilities and enable their direct access to back-end systems and cloud-based services. v Configure, test, and deploy descriptive XML files to connect to various back-end systems by using standard Worklight Studio tools. v Directly update deployed hybrid and web applications, without going through the different app stores (subject to the terms of service of the vendor). v Automatically convert hierarchical data to JSON format for optimal delivery and consumption. v Enhance users interaction with a uniform push notification architecture. v Define complex mashups of multiple data sources to reduce overall traffic. v Integrate with the existing security and authentication mechanisms of the organization.

6

IBM Worklight provides client-side runtime code that embeds server functionality within the target environment of deployed apps. These runtime client APIs are libraries that are integrated into the locally stored app code. They complement the Worklight Server by defining a predefined interface for apps to access native device functions. Among these APIs, IBM Worklight uses the Apache Cordova development framework. This framework delivers a uniform bridge between standard web technologies (HTML5, CSS3, JavaScript) and the native functions that different mobile platforms provide.

of

In

ca

se

Ex

pe

rim

en

ta

Client-side runtime components


The client-side runtime components provide the following functions: v Mobile data integration: connectivity and authentication APIs v Security features: on-device encryption, offline authentication, and remote disablement of the ability to connect to Worklight Server v Cross-platform support: runtime skins, UI abstractions, and HTML5 toolkits compatibility v Mobile client functionality: hybrid app framework, access to device APIs and push notification registration v Reports and analytics: built-in reports and event-based custom reporting

v Resource serving: direct update of app web resources and HTML5 caching

Worklight Console


The Worklight Console is used for the control and management of the mobile applications. You can use the Worklight Console for the following tasks: v Monitor all deployed applications, adapters, and push notification rules from a centralized, web-based console. v Assign device-specific identifiers (IDs) to ensure secure application provisioning. v Remotely disable the ability to connect to Worklight Server by using preconfigured rules of app version and device type. v Customize messages that are sent to users on application launch. v Collect user statistics from all running applications. v Generate built-in, pre-configured user adoption and usage reports. v Configure data collection rules for application-specific events. v Export raw reporting data to be analyzed by the BI systems of the organization.

Application Center

With the Application Center, you can share mobile applications that are under development within your organization in a single repository of mobile applications. Development team members can use the Application Center to share applications with members of the team. This process facilitates collaboration between all the people who are involved in the development of an application.

In

1. The development team creates a version of an application. 2. The development team uploads the application to the Application Center, enters its description, and asks the extended team to review and test it. 3. When the new version of the application is available, a tester runs the Application Center installer application, which is the mobile client. Then, the tester locates this new version of the application, installs it on their mobile device, and tests it. 4. After the tests, the tester rates the application and submits feedback, which is visible to the developer from the Application Center console. The Application Center is aimed for private use within a company, and you can target some mobile applications to specific groups of users. You can use the Application Center as an enterprise application store.

of

ca

se

Ex

pe

rim

en

ta

Your company can typically use the Application Center as follows:

With the Application Center, you can manage native or hybrid applications that are installed on mobile devices. The Application Center supports applications that are built for the Google Android platform, the Apple iOS platform, and the BlackBerry OS 6 and 7 platform, but does not target mobile web applications. BlackBerry OS 10 is not supported by the current version of the Application Center.

IBM Mobile Application Platform Pattern With the IBM Mobile Application Platform Pattern, you can deploy the Worklight Server on IBM PureApplication™ System. With this pattern, administrators and businesses can respond quickly to changes in the business by taking advantage of Chapter 1. Overview of IBM Worklight

7


on-premises Cloud technologies. This approach simplifies the deployment process, and improves the operational efficiency to cope with increased mobile demand. The demand accelerates iteration of solutions that exceed traditional demand cycles. Deploying the IBM Mobile Application Platform Pattern on IBM PureApplication System also gives access to best practices and built-in expertise, such as built-in scaling policies.

IBM Worklight editions

IBM Worklight and IBM Mobile Foundation are available to you in different editions.

IBM Worklight Developer Edition

IBM Worklight Developer Edition is a free, non-warranted program that consists of a single plug-in for the Eclipse integrated development environment (IDE). It is available from the developerWorks® website. You must install it with P2 Eclipse update. It provides the same Worklight Studio functions that are available in the IBM Worklight Consumer Edition and the IBM Worklight Enterprise Edition, except for some security-related features. Support is only provided as a best-effort service. For full product support, choose the IBM Worklight Consumer Edition or the IBM Worklight Enterprise Edition. The P2 Eclipse update version of IBM Mobile Test Workbench for Worklight is also downloadable for free as a separate plug-in from the developerWorks website. After you install the IBM Worklight Developer Edition, you can then optionally install the test workbench in Eclipse.

IBM Worklight Consumer Edition and IBM Worklight Enterprise Edition

v A separate Worklight Studio component, which is available as an Eclipse plug-in (Eclipse P2 install) v A separate Worklight Server component, which is available as an Installation Manager package

of

v A separate, optional, IBM Mobile Test Workbench for Worklight component, which is available as an Eclipse plug-in (Eclipse P2 install)

ca

se

Ex

pe

rim

en

ta

IBM Worklight Consumer Edition and IBM Worklight Enterprise Edition are identical programs that differ in license only. These programs are supported through an IBM International License Agreement and available from IBM Passport Advantage®. The IBM Worklight Consumer Edition and the IBM Worklight Enterprise Edition contain:

Note: When you install and upgrade IBM Worklight Consumer Edition or IBM Worklight Enterprise Edition, you must make sure that the version numbers of your Worklight Studio and Worklight Server components stay in sync. You must not mix components across releases.

In

System requirements for using IBM Worklight Identify the operating systems, Eclipse versions, SDKs, and other software that are required or supported by IBM Worklight, and features in IBM Worklight that are available for each supported platform.

8


Read the IBM Worklight and IBM Mobile Foundation detailed system requirements web page at http://www.ibm.com/support/docview.wss?uid=swg27024838 to identify the system requirements for this release of IBM Worklight, including:


v The operating systems that support IBM Worklight, including mobile device operating systems v The needed hardware configuration v The editions of Eclipse that support Worklight Studio, which is an Eclipse-based integrated development environment (IDE) v The supported software development kits (SDKs) v The supported web browsers v The application servers, database management systems, and other software that are required or supported by IBM Worklight

Matrix of features and platforms

IBM Worklight provides many features and supports many platforms.

The technote at http://www.ibm.com/support/docview.wss?uid=swg27039422 lists the IBM Worklight features that are available on each of the platforms that IBM Worklight supports.

Known limitations

General limitations apply to IBM Worklight as detailed here. Limitations that apply to specific features are explained in the topics that describe these features. In this documentation, you can find the description of IBM Worklight known limitations in different locations: v When the known limitation applies to a specific feature, you can find its description in the topic that explains this specific feature. You can then immediately identify how it affects the feature.

Globalization

v The Worklight Studio and Worklight Console provide only partial support for bidirectional languages. v In Worklight Studio and Worklight Console, dates and numbers might not be formatted according to the locale. v Names of projects, apps, and adapters must be composed only of the following characters: – Uppercase and lowercase letters (A-Z and a-z) – Digits (0-9) – Underscore (_)

of

ca In

Note: You might find complementary information about product known limitations or issues in the product Technotes.

If you are developing globalized apps, notice the following restrictions: v Translated versions of the product are not supplied.

se

Ex

pe

rim

en

ta

v When the known limitation is general, that is, applies to different and possibly not directly related topics, you can find its description here.

v There is no support for Unicode characters outside the Basic Multilingual Plane.


9


The analytics platform has the following limitations in terms of globalization: v In reports, the format for dates and times do not follow the International Components for Unicode (ICU) rules. v In reports, the format for numbers do not follow the International Components for Unicode (ICU) rules. v In reports, the numbers do not use the user's preferred number script. v In reports, searching for Chinese, Japanese, and Korean characters (CJK) returns no results. v Messages that include non-ASCII characters and that are created with “WL.Analytics.log” on page 492 or with “WL.Logger.error” on page 588 are not always logged successfully. v The Analytics page of the Worklight Console does not work in the following browsers: – Microsoft Internet Explorer version 8 or earlier – Apple Safari on iOS version 4.3 or earlier v On Mozilla Firefox browser and Google Chrome browser, the locale that is used to display dates and time might differ from the locale that is set for the browser. v The dates on the X-axis are not localized.

10

For example: v You must define the user name and password of the Application Center with ASCII characters only. This limitation exists because IBM WebSphere® Application Server (full or Liberty profiles) does not support non-ASCII passwords and user names. See http://pic.dhe.ibm.com/infocenter/wasinfo/ v8r0/topic/com.ibm.websphere.nd.doc/info/ae/ae/csec_chars.html. v To deploy a virtual application, you must define the user name and ID in the corresponding Worklight configuration component with ASCII characters only. This limitation exists because IBM PureApplication System does not support non-ASCII passwords and user names. v On Windows: – To see any localized messages in the log file that the Worklight Test Server that is embedded in Worklight Studio creates, you must open this log file with the UTF8 encoding. – In the Worklight Test Server console in Eclipse, the localized messages are not properly displayed.

These limitations exist because of the following causes: – The Worklight Test Server is installed on IBM WebSphere Application Server Liberty Profile, which creates log file with the ANSI encoding except for its localized messages for which it uses the UTF8 encoding. – The Worklight Test Server console in Eclipse displays the content by using the ANSI encoding, not the UTF8 encoding.

of

In

ca

se

Ex

pe

rim

en

ta

You might also experience restrictions or anomalies in various aspects of globalization because of limitations in other products, such as browsers, database management systems, or software development kits in use.


.

Application Center mobile client


The Application Center mobile client follows the cultural conventions of the running device, such as the date formatting. It does not always follow the stricter International Components for Unicode (ICU) rules. The Application Center mobile client for BlackBerry has the following known limitations: v It supports only a limited set of languages. In particular, it does not fully support right-to-left languages, such as Arabic and Hebrew.

v It does not support Unicode characters outside the Basic Multilingual Plane. v It supports Unicode characters inside the Basic Multilingual Plane but how these characters are displayed depends on the fonts that are available on the device

Application Center mobile client: refresh issues on Android 4.0.x Android 4.0.x WebView component is known to have several refresh issues. Updating devices to Android 4.1.x should provide a better user experience.

If you build the Application Center client from sources, disabling the hardware acceleration at the application level in the Android manifest should improve the situation for Android 4.0.x. In that case, the application must be built with Android SDK 11 or later.

Rich Page Editor

The Rich Page Editor fails to show your page when the code that initializes it attempts to communicate with Worklight Server.

In general, however, the initialization code is not strictly necessary to get a reasonable visual rendering of your page. To avoid this limitation, temporarily remove the "display: none" style from the body element in your page. Your page then renders even if the initialization functions do not execute completely.

of

ca In

As an example, a failure occurs if your page calls an adapter procedure in the wlCommonInit() function or the wlEnvInit() function.

JSONStore resources for iPhone and iPad

se

Ex

pe

rim

en

ta

The Rich Page Editor simulates the mobile device environment without any connection to a real server. If the code that initializes your page tries to communicate with Worklight Server, a failure occurs. Because of this failure, the page content remains hidden, and you cannot use the Design pane of the Rich Page Editor.

When you develop apps for iPhone and iPad, the JSONStore resources are always packaged in the application, regardless of whether you enabled JSONStore or not in the application descriptor. The application size is not reduced even if JSONStore is not enabled.

Analytics page of the Worklight Console Response times in the Analytics page of the Worklight Console are dependent on several factors, such as hardware (RAM, CPUs), quantity of accumulated analytics data, and IBM Websphere Analytics Platform (IWAP) clustering. Consider testing Chapter 1. Overview of IBM Worklight

11

your load prior to integrating IWAP into production.

Deployment of an app from Worklight Studio to Tomcat


If you use Tomcat as an external server in Eclipse (for example to test and debug the applications directly in Worklight Studio), the following restrictions apply: v The context path that you set to your project is ignored. When you deploy your app from Worklight Studio to Tomcat, the default context path, which is the project name, is used instead of the context path. The URL of the Worklight Console for your app similarly uses the project name. v When you deploy your app from Worklight Studio to Tomcat, the deployed WAR file is not visible in the Server view of Eclipse (in Worklight Studio), even if the application is correctly deployed. To avoid these issues, keep the default value of the context path of your project, which is the project name.

Installation on a cluster of IBM WebSphere Application Servers Liberty Profile, that you administer with a collective controller

The following limitations apply if you install Worklight Server on a cluster of IBM WebSphere Application Servers, Liberty Profile, that you administer with a collective controller: v The Application Center installation with the Worklight Server installer does not use the collective controller. You must install Worklight Server on each server separately. v The Worklight console installation with the Ant task does not use the collective controller. You must run the Ant task for each server separately.

Support for Android Emulator 2.3.x

of

In

ca

se

Ex

pe

rim

en

ta

IBM Worklight does not support Android Emulator 2.3.x because of known issues, as detailed in the Android list of issues at https://code.google.com/p/android/ issues/list (search for issue 12987).

12


Chapter 2. What's new


This section details the new features and changes in IBM Worklight V6.0.0 and subsequent fix packs.

What's new in IBM Worklight V6.0.0.2

IBM Worklight V6.0.0.2 fixes many problems that were identified in previous versions.

Client-side log collection

Starting with IBM Worklight V6.0.0.2, you can now capture and receive uploaded client-side logs. For more information, see “Client-side log capture” on page 483.

Support for Android 4.4

You can now use IBM Worklight to develop applications that run on Android 4.4. For more information, see IBM Worklight Supports Android 4.4.

Changes to the WL.Client.init JavaScript client-side API method

v New showCloseOnDirectUpdateFailure property. v New showCloseOnRemoteDisableDenial property. v New message and downloadLink parameters for the onErrorRemoteDisableDenial property.

of

ca In

Significant improvements have been made on the amount of time the user must wait when IBM Worklight applications are started for the first time. The performance improvement applies to both Android and iOS. In cases where the web resources are not encrypted (that is, when encryptWebResources is set to the default value of false), a change has been made resulting in a significant improvement in the application startup time. v Maximum improvement is achieved with testWebResourcesChecksum and encryptWebResources set to their default value of false in the application descriptor file. v Setting the testWebResourcesChecksum value to true reduces the improvement slightly. v Setting the encryptWebResources value to true results in no improvement.

The “WL.Client.init” on page 509 method supports the following new properties and parameters:

se

Ex

pe

rim

en

ta

Application startup time improvement

Change in Remote Disable behavior When you use the Worklight Console to disable an application's access to the server, the default behavior is no longer to exit the application completely. For more information, see “Remotely disabling application connectivity” on page 758.

13

Deprecation of WL.OptionsMenu with Android 3.0, API level 11


If your application targets Android 3.0 (API level 11) or higher, WL.OptionsMenu might have no effect, depending on the device. For more information, see Creating an Options Menu in the Android Developers API Guides and “Options Menu and Application Bar API” on page 600.

Documentation improvements

v Clarification on how to use the WL.App.BackgroundHandler.hideView handler to hide the application splash screen. See “WL.App.BackgroundHandler.setOnAppEnteringBackground” on page 495.

List of fixes for IBM Worklight V6.0.0.2

For a complete list of issues that are fixed in IBM Worklight V6.0.0.2, see Version 6.0.0 Fix Pack 2.

What's new in IBM Worklight V6.0.0.1

IBM Worklight V6.0.0.1 fixes many problems that were identified in previous versions. For more information about the fixed issues, see Version 6.0.0 Fix Pack 1.

What's new in IBM Worklight V6.0.0

This section details the new features and changes in IBM Worklight V6.0.0 compared to the previous version of this product.

New functional testing capabilities

14

The accelerated delivery cycles of mobile applications requires fast and effective test cycles. IBM Worklight V6.0.0 now includes IBM Mobile Test Workbench for Worklight (IMTWW), which is an automated functional testing feature for Android and iOS native and hybrid applications.

Designed for use by developers and testers, IBM Mobile Test Workbench for Worklight automates functional testing. First, developers or testers record a sequence of actions on a mobile device, using a recording-ready app to generate a test script. Next, they edit and enhance the script using natural language syntax to add verification points and other instructions. Then, they can run the enhanced test script on a real device, simulator, or emulator. Results can be viewed and shared via a generated HTML report.

of

In

ca

se

Ex

pe

rim

en

ta

IBM Worklight V6.0.0 offers improved ability to create, run, and automate tests on mobile applications.


With IBM Mobile Test Workbench for Worklight, you can create, run, and automate tests on mobile applications. The main new key features are as follows: v Seamless experience: You create, run, and automate tests on mobile applications in Worklight Studio, that is, the same Eclipse environment that you also use to develop your apps. v Support for the most common needs: You can test native or hybrid apps for the two leading mobile platforms: Android and iOS.


v Complete: You can record your tests, edit your test definitions, and run your tests on mobile devices and on simulators. v Support for all JavaScript frameworks (with an additional support for JQuery Mobile components that are detected and registered as such in the test script) for building and for testing apps. v Natural scripting language: You can define test scripts with a natural language that non-IT people can understand. As a developer, you can use Worklight Studio to test your apps with IBM Mobile Test Workbench for Worklight. For more information about functional testing within Worklight Studio, see Testing with IBM Worklight As a developer, you can share apps that are ready for tests with IBM Mobile Test Workbench for Worklight with the testing team by using Application Center. For more information, see Using the Application Center and the Mobile Test Workbench to share applications.

New operational analytics feature

With IBM Worklight V6.0.0, you can now use the operational analytics feature to search across apps, services, devices, and other sources to collect data about usage or to detect problems.

In addition to BIRT reports, which are still supported, IBM Worklight V6.0.0 now also includes a scalable operational analytics platform that you can access from the Worklight Console. The analytics feature enables enterprises to search across logs and events that are collected from devices, apps, and servers for patterns, problems, and platform usage statistics. You can enable analytics, reports, or both, depending on your needs.

Note: If location services are enabled in your IBM Worklight application, geolocation and WiFi data is automatically included in captured operational analytics data. For more information about location services, see “Location services” on page 470

of

ca In

v Server-side logs that are captured in existing IBM Worklight log files.

For more information, see “Operational analytics” on page 840.

se

Ex

pe

rim

en

ta

Information that is accessible for operational analytics includes data from the following sources: v Crash events of an app on iOS and Android devices. v Interactions of any app-to-server activity. This data includes anything that is supported by the IBM Worklight client/server protocol, including push notifications.

To get started with the operational analytics feature of IBM Worklight, see the module Operational Analytics, under category 10, Moving to production, in Chapter 3, “Tutorials and samples,” on page 25.

Enhancing applications with location features IBM Worklight V6.0.0, contains new location capabilities to enhance your apps. Location is a powerful differentiator of mobile apps. Yet because location coordinates must be constantly polled to understand where a mobile device is Chapter 2. What's new

15

located, the resulting stream of geographic information can be difficult to manage without exhausting resources such as battery and network.


IBM Worklight V6.0.0 now defines location services to respond to geo events. These services handle multiple geo modalities such as GPS, WiFi sampling and interpolation, with policies for acquiring geo data and sending it in batch to optimize battery and network usage.

With the geolocation toolkit, business actions can be triggered when users reach a point of interest, or enter or exit a region (geo-fencing), and server-side logic can be run to react to important geo events.

For more information about the new location features in IBM Worklight V6.0.0, see “Location services” on page 470 and “Location services API” on page 553 for the corresponding API. To get started with the location features of IBM Worklight, see the module Location services, under category 9, Advanced topics, in Chapter 3, “Tutorials and samples,” on page 25.

Enhanced rapid application development

With IBM Worklight V6.0.0, you can use new features to accelerate the development of your hybrid applications, including templates, and improved Dojo and JavaScript tools.

Screen templates

Delivering an outstanding mobile UI experience requires conformance with continuously evolving mobile patterns of behavior specific to each OS family. IBM Worklight V6.0.0 now includes screen templates that automate the creation of mobile screens that reflect design best practices. Developers can choose from templates in four categories: Lists, Authentication, Navigation & Search, and Configuration. Each screen template can be previewed, used as provided, or further refined by using any combination of web and native technologies

16

Improved Dojo tools

IBM Worklight V6.0.0 provides tools to improve the build of IBM Worklight applications with Dojo. In particular, here are the changes that are now available: v Dojo source files are moved out of the IBM Worklight project into a separate Dojo Library project, which is on an internal Jetty server. Moving the Dojo files to a separate project keeps the IBM Worklight project light and easy to work with. The Dojo Library feature is where access to the full distribution of Dojo is initiated by linking to the internal server. An IBM Worklight project that uses Dojo is paired with a Dojo Library project. An IBM Worklight project that you created with a previous version of IBM Worklight has a mobile version of Dojo that is placed directly in it. Starting with IBM Worklight V6.0.0, your projects now embed a subset of Dojo resources, and also have a separate Dojo Library project. v Dojo Mobile applications that are built by using Worklight are created by using an optimized set of layers to help the quick development and deployment of your application. The pre-built layers are configured to support numerous locales; however, the application includes the locale for US English only, upon

of

In

ca

se

Ex

pe

rim

en

ta

For more information about screen template, see “Mobile patterns” on page 301.



project creation. On some mobile devices, if the locale is configured to anything other than US English, the application can crash due to a defect in Dojo. To correct this, supported locales must be added to the application. The NLS files can be found in your Dojo Library project's toolkit/dojo/dojo/nls folder, and they must be copied into your mobile application project's www/dojo/nls folder. After this change, the application can then be deployed to the device with various locale support. v Developers can focus on coding without having to evaluate which JavaScript modules they must bring into the project from the Dojo Library project before production deployment. The development environment provides full access to the Dojo widgets and API. Access is provided even if the JavaScript modules are not included in the IBM Worklight project. Developers can test the application without having to copy JavaScript modules into the IBM Worklight project, but rely on the Dojo Library project to supply the necessary modules. When developers test on an external device or emulator, IDE must be running and must have Internet connectivity. If the Dojo Library project's IP changes, then the app cannot access resources from the Dojo Library until it is rebuilt. For more information about improved Dojo tools, see “Using JavaScript toolkits” on page 279.

AMD module locator

IBM Worklight V6.0.0 provides improved JavaScript tools for you to locate the Asynchronous Module Definition (AMD) module that contains the API that you need. Type a few characters of the API that you require, and the locator identifies the AMD module that you must add to require().

Features to optimize IBM Worklight applications

In

During development, the applications you develop with Worklight Studio can demonstrate good performance. But when these apps are run on mobile devices, performance can be impacted by a number of factors. Worklight Studio V6.0.0 includes a number of features that can reduce the size of your IBM Worklight apps, or reduce the number of resources that must be loaded at start time. Using these features can improve both client-side performance and user satisfaction.

To get started with these features of IBM Worklight to optimize your apps, see the module General information when developing Mobile Web applications and the module General information when developing desktop applications, under category 3, Worklight client-side development basics, in Chapter 3, “Tutorials and samples,” on page 25.

of

ca

se

Ex

pe

rim

en

ta

With IBM Worklight V6.0.0, you can use a number of new features to reduce the size of your apps or enable them to start more quickly.

Including and excluding application features Application features such as JSONStore offer many benefits, if used in the application. If it is not used, however, the JSONStore resources greatly increase the size of your applications, in particular if they are simple, and thus increase their initial download time and start time. In IBM Worklight V6.0.0, you can choose which features to include in the build by editing the application-descriptor.xml file of your application with the Worklight Studio Application Descriptor editor. This selection is reflected in the new element in the Application Descriptor. This element enables users to Chapter 2. What's new

17

control the inclusion or exclusion of certain application resources. For more information about this feature, see “Including and excluding application features” on page 343.


Note: In IBM Worklight V6.0.0, only JSONStore resources on Android applications can be excluded with the element.

Controlling the application cache

Ideally, developers want mobile web applications to work when the user is offline. The release of HTML5 addressed this need with the introduction of the application cache, which provides improvements in offline browsing, speed, and reduced server load. The Cache Manifest is a text file that lists the resources that the browser is to cache for offline access. It contains a list of resources that are explicitly cached after the first time they are downloaded. In IBM Worklight V6.0.0, users can view and edit the Cache Manifest for web environments (Desktop Browser and Mobile Web applications). For more information about this feature, see “Application cache management in Desktop Browser and Mobile Web apps” on page 346.

Minification of application resources

Minification is a process that minifies web resources to make them smaller. The smaller size of the resources means less traffic between the Worklight application and Worklight Server, and can improve initial download time and application start time. In Worklight V6.0.0, you can minify certain Mobile Web and Desktop Browser resources (JavaScript and CSS files) at build time, with the Google Closure Compiler. For more information about this feature, see “Minification of JS and CSS files” on page 354.

In IBM Worklight V6.0.0, a new feature enables users to concatenate multiple web resources that are used by Mobile Web and Desktop Browser applications into a smaller number of files. By reducing the total number of JavaScript and Cascading Style Sheet files that are referenced by the application HTML, fewer browser requests are required. As a result, the application can start more quickly. For more information about this feature, see “Concatenation of JS and CSS files” on page 356.

of

Controlling your build settings to improve the app start time

In

ca

se

Ex

pe

rim

en

ta

Concatenation of application resources

In IBM Worklight V6.0.0, a new file is added to Worklight applications when they are first created: build-settings.xml. The purpose of the file is to prepare minification and concatenation configurations for each Mobile Web and Desktop Browser environment. These configurations are then used by the minify and concatenation engines during the build process. You can view and edit these build settings from within Worklight Studio, and use them to create appropriate configurations for different stages of the development cycle. For example, during development you can choose not to minimize or concatenate your web resources in each build. But when you move the application to production, you can enable minification and concatenation in the builds to

18


reduce application size or improve start time. For more information about this feature, see “IBM Worklight application build settings” on page 351.

Improved serviceability


IBM Worklight V6.0.0 improves how you deploy or configure your applications

No IBM Worklight project installed by default, no Worklight Console available by default

Important: In IBM Worklight V6.0.0, the installation process no longer installs a default IBM Worklight project, and so no longer creates the corresponding IBM Worklight Console by default.

Before you can open a Worklight Console, you must therefore first install IBM Worklight Server, which copies the deployment tools and production libraries on your computer, and then deploy a Worklight project WAR file as detailed in Chapter 8, “Deploying IBM Worklight projects,” on page 663.

Improved deployment process

of

ca In

Each IBM Worklight project can be connected to a different database or to the same database with distinct data storage area. To get started with the deployment of several IBM Worklight project WAR files to the same server, see the module Creating your first Worklight application, under category 2, Hello Worklight, in Chapter 3, “Tutorials and samples,” on page 25. v Create a single IBM Worklight project WAR file and use it for test or production environment without the need to repackage it. You only have to customize the project WAR file by using JNDI properties. For more information about how to configure a project WAR file with JNDI properties, see “Configuring an IBM Worklight project in production by using JNDI environment entries” on page 723. v Use Ant tasks to create and configure the IBM Worklight databases on the supported database types. For more information about these Ant tasks, see “Creating and configuring the databases with Ant tasks” on page 669. v Use Ant tasks to deploy the IBM Worklight project WAR file to the application server and configure the application server. For more information about these Ant tasks, see “Deploying a project WAR file and configuring the application server with Ant tasks” on page 694.

se

Ex

pe

rim

en

ta

With IBM Worklight V6.0.0, you can now perform the following actions: v Deploy several project WAR files to the same application server.

Improved Application Center With IBM Worklight V6.0.0, Application Center contains the following improvements: v The Application Center mobile client for iOS and Android is new, with additional functions: – Ability to manage a list of favorite applications per user. – Ability to sort applications by name, popularity, or last update date. – Ability to see more details on the application, including rating and reviews.


19

v v


v

For more information about the Application Center mobile client, see “The mobile client” on page 805. Users can be notified of new application update through push notification. The list of application on the catalog is filtered according to the capabilities of the device (OS level, iPad versus iPhone). The Application Center now supports federated repositories on IBM WebSphere Application Server 7 for the Access Control List (ACL) management. When installing Application Center on WebSphere Application Server 7, you can now configure the Access Control List by using the Virtual Member Manager (VMM) You can configure LDAP through VMM for WebSphere Application Server (full profile version 7)

v

v You can use Application Center to share applications that are instrumented by the IBM Mobile Test Workbench for Worklight for testing purpose, as introduced in “New functional testing capabilities” on page 14. v The Ant task to deploy applications to Application Center has been improved with the ability to provide more metadata on the app such as the description. You can also remove apps from the catalog. For more information about the Application Center, see “Application Center” on page 769.

Enhanced IBM Worklight API

IBM Worklight V6.0.0 enhances and extends the API that you can use to develop mobile applications.

Important: Some of the changes that are listed here have an impact on how your IBM Worklight applications behave. In some cases, you might have to manually modify your projects or applications that you created with previous versions of IBM Worklight. For more information about this potential impact, and any required manual migration, see “Migrating from IBM Worklight V5.0.6 to V6.0.0” on page 181.

IBM Worklight V6.0.0 supports recent versions of the following libraries, which you can use during the development of your apps: v Apache Cordova platform v Dojo toolkit v jQuery library v jQuery Mobile library v Sencha Touch framework

of

In

ca

se

Ex

pe

rim

en

ta

Support of updated libraries and toolkits

For more information, see “System requirements for using IBM Worklight” on page 8. To get started with using Apache Cordova in IBM Worklight, see the module Apache Cordova overview, under category 6, Adding native functionality to hybrid applications with Apache Cordova, in Chapter 3, “Tutorials and samples,” on page 25.

Updated JavaScript client-side API IBM Worklight V6.0.0 updated its JavaScript client-side API. Notice, in particular, the following changes:

20



v JSONStore now provides an API-compatible implementation that runs in supported browsers. With this feature, developers can create applications that use the JSONStore API on web-only environments, before they move to the production environments on iOS and Android. For more information, see “JSONStore overview” on page 393. v The new Analytics API is defined for you to enable and disable data collection, reset the analytics feature configuration, and log analytics data during IBM Worklight application run time. For more information, see “WL.Analytics” on page 491. v The WL.Logger API is redesigned with new features, such as packages, log levels, filtering, string output, pretty print objects, level and package tags, optional callback, stack traces.

For more information, see “WL.Logger methods” on page 584 and “Configuring the Worklight Logger” on page 574. v The new client-side Location API is defined for you to use Geo and WiFi locations to perform various actions in your apps. For more information, see “Location services API” on page 553.

Updated JavaScript server-side API

IBM Worklight V6.0.0 complements its JavaScript server-side API with further elements that you can use to extend the Worklight Server. Notice, in particular, the following changes: v The new server-side Location API is defined, as a complement to the client-side Location API: – WL.Server.createEventHandler – WL.Server.getClientDeviceContext – WL.Server.logActivity – WL.Server.setApplicationContext – WL.Server.setEventHandlers

In

Updated Objective-C client-side API for iOS

IBM Worklight V6.0.0 adds the following method to its Objective-C client-side API to develop native apps on iOS: v The method setHeartbeatInterval that sets the interval at which the client (device) sends a heartbeat signal to the server. You use this heartbeat signal to prevent a session with the server from timing out because of inactivity.

of

ca

se

Ex

pe

rim

en

ta

For more information, see “JavaScript server-side API” on page 620.

For more information, see “Objective-C client-side API for native iOS apps” on page 620.

Updated Java client-side API for Android IBM Worklight V6.0.0 adds the following method to its Java client-side API to develop native apps on Android: v The method setHeartBeatInterval that sets the interval at which the client (device) sends a heartbeat signal to the server. You use this heartbeat signal to prevent a session with the server from timing out because of inactivity.


21

For more information, see “Java client-side API for native Android apps” on page 620.


Note: IBM Worklight V6.0.0 includes no changes for the following APIs: v Java client-side API for Java Platform, Micro Edition (Java ME) v Java server-side API

Augmented support of mobile environments and operating systems

IBM Worklight V6.0.0 offers extended capabilities in terms of supported mobile environments and operating systems

Updated operating systems, hardware, and software support

The list of operating systems, hardware, and software supported by IBM Worklight V6.0.0 has changed. For more information about this list, see “System requirements for using IBM Worklight” on page 8.

Deprecated or removed environments

With IBM Worklight V6.0.0, the following environment is now deprecated: v Windows Phone 7.5

With IBM Worklight V6.0.0, the following environments are now removed: v iGoogle

v Mac OS/X Dashboard v Windows 7 / Vista Gadgets v Facebook

Alignment of the Push function between mobile environments

rim

en

ta

With IBM Worklight V6.0.0, you can now use the Push function also on the Windows Phone 8 environment, while it was available only on other environments in previous versions.

Support for more versions of hosts

With IBM Worklight V6.0.0, you can now run Worklight Server on the following hosts v WebSphere Application Server 8.5.5 v WebSphere Application Server ND 8.5.5

ca

se

of

pe Ex

For more information about Push for Windows Phone 8, see “Windows Phone 8 push notifications” on page 415.

In

Miscellaneous modifications

22


IBM Worklight V6.0.0 includes other miscellaneous modifications, including changes in project files and behaviors, changes in the development test server and the Worklight Console.

Changes in project files and behaviors


In IBM Worklight V6.0.0, several changes have an impact on different aspects of your work, such as the content or the organization of IBM Worklight projects, and how applications that are based on IBM Worklight API behave. In some cases, you might have to manually update your projects or applications. For a comprehensive description of these changes and their potential impact, see “Migrating from IBM Worklight V5.0.6 to V6.0.0” on page 181.

Changes in the installation process of Worklight Studio

Before IBM Worklight V6.0.0, you installed Worklight Studio Consumer Edition and Worklight Studio Enterprise Edition either with IBM Installation Manager, or with P2 Eclipse update. Since IBM Worklight V6.0.0, IBM Installation Manager for Worklight Studio is no longer provided. All editions are installed with P2 Eclipse update only.

Changes to the development server and Worklight Console

In previous versions of IBM Worklight, the embedded server that is used during development was provided by Jetty. In IBM Worklight V6.0.0, the Jetty server is replaced with an embedded instance of WebSphere Application Server Liberty Profile. This Liberty profile server is installed with Worklight Studio, and becomes the default test server.

of

ca In

A new menu option named Open Worklight Console opens an IBM Worklight Console window in your default web browser, in which you can view projects that are deployed to this test server. There are also changes to the URL used to start this default Worklight Console in the browser itself because this URL now must include the Worklight project name to define a root context. For more information about these changes, see “The Worklight Development Server and the Worklight Console” on page 266.

Changed location of PureApplication configuration

se

Ex

pe

rim

en

ta

As a result, you see a new Worklight Development Server element in your Eclipse Project Explorer view, even before you begin creating new projects and working with them.

In IBM Worklight V6.0.0, IBM Worklight PureApplication System Extension for Worklight Studio copies the PureApplication configuration into the WorklightServerConfig folder under your Eclipse workspace. In previous releases, the PureApplication configuration was copied into the WorklightServerHome folder.

Integration with Firebug in Worklight Studio no longer available In IBM Worklight V6.0.0, Worklight Studio no longer integrates with Firebug. The following functions are removed: Chapter 2. What's new

23

v Connecting to a Firebug JavaScript debugger from an Eclipse debug session. v Viewing the JavaScript debug stack, controlling breakpoints, and stepping through JavaScript code from within Eclipse.


You might still debug JavaScript code within your apps by using Firebug in Mozilla Firefox or by using other JavaScript debuggers.

Enhanced tutorials and samples

In IBM Worklight V6.0.0, the list of tutorials and samples is augmented and enhanced for you to learn how to get started with the new features of IBM Worklight.

For more information about the new or highly modified tutorials and samples, and how you can use to get started with IBM Worklight, see Chapter 3, “Tutorials and samples,” on page 25.

Specifying the remote server

of

In

ca

se

Ex

pe

rim

en

ta

Since IBM Worklight V6.0.0, the WorklightServerRootURL element is deprecated and no longer part of the application-descriptor.xml file. To specify the URL of the Worklight Server that your application uses, build your application by clicking Run As > Build for Remote Server. For more information about how to specify the remote server, see “Deploying an application from development to a test or production environment” on page 663.

24


Chapter 3. Tutorials and samples


Tutorials and samples help you get started with and learn about IBM Worklight, and evaluate what the product can do for you. You can get started with IBM Worklight by following the “Tutorials.”

You can further learn how to develop mobile applications with IBM Worklight by studying the following samples: v “Worklight Starter application samples” on page 33 v “JavaScript framework-based application samples” on page 33

You can find links to download compressed files that contain the materials for the tutorials and samples in “Additional resources” on page 33. Important: These materials were created for use with only the IBM Worklight Developer Edition and the Worklight Server inside Eclipse. If your configuration differs, you might have to adapt the exercise instructions, the code samples, or both.

Terms and conditions: The following resources are subject to these “Terms and conditions” on page 34, and may include applicable third-party licenses. Please review the third-party licenses before using any of the resources. The third-party licenses applicable to each sample are available in the notices.txt file that is included with each code sample.

Tutorials

Use the tutorials to learn the most important features of IBM Worklight.

In

v The sample, if any, is a compressed (.zip) file that provides pieces of code or script files that accompany and support the module. If a module has some exercises, you also have a companion sample that provides the solutions to these exercises. The modules and companion samples of the tutorials are organized in the following categories: 1. Setting up your development environment: With this category, you learn how to set up your development environment to work with IBM Worklight.

of

ca

se

Ex

pe

rim

en

ta

Each tutorial is composed of one module and generally one companion sample: v The module is a PDF presentation file that provides step-by-step guidance on how to get started with an important feature of IBM Worklight.

2. Hello Worklight: With this category, you learn how to create your first IBM Worklight app and preview it in different mobile operating systems. 3. Worklight client-side development basics: With this category, you learn how to use basic IBM Worklight APIs to develop your apps, how to build a multi-page application, how to work with the user interface framework, how to debug and optimize your app, and some general information that you must know to work in each specific environment.

25

4. Worklight server-side development: With this category, you learn how to develop the server code (adapters) that your mobile application requires to integrate with enterprise back-end applications and cloud services.


5. Advanced client-side development: With this category, you learn how to implement different features in your mobile application, such as controls, skins, offline access, translation, encryption of sensitive data. You also learn how to develop your client application by using native APIs 6. Adding native functionality to hybrid applications with Apache Cordova: With this category, you learn how to use Apache Cordova with IBM Worklight, and how to use native pages in hybrid applications. 7. Developing native applications with Worklight: With this category, you learn how to develop native applications with IBM Worklight. 8. Authentication and security: With this category, you learn how to protect your applications and adapter procedures against unauthorized access by using authentication, login modules, and device provisioning. 9. Advanced topics: With this category, you learn advanced topics that you can use with IBM Worklight, such as how to develop by using shells or how to handle notifications. 10. Moving to production: With this category, you learn how to move the apps that you create from your development environment to the production environment. 11. Integrating with other products: With this category, you learn how IBM Worklight integrates with some other IBM products, such as IBM PureApplication System or Tivoli® Directory Server.

Note: Compared to the previous version of IBM Worklight, some modules are new or highly revised. To help you identify these new or revised modules, their names are introduced with either NEW or Highly revised in the following table. Table 2. Getting Started modules and samples Module

Sample (if any) Description

Setting up your Worklight development environment

This module explains how to set up your environment.

Setting up your iOS development environment

This module complements the module "Setting up your Worklight development environment" with further steps that are required for iOS application development.

Setting up your Android development environment

This module complements the module "Setting up your Worklight development environment" with further steps that are required for Android application development.

of

In

ca

se

Ex

pe

rim

en

ta

1. Setting up your development environment

26


Setting up your BlackBerry 6 and 7 development environment

This module complements the module "Setting up your Worklight development environment" with further steps that are required for BlackBerry 6 and BlackBerry 7 application development.

Table 2. Getting Started modules and samples (continued) Module

Sample (if any) Description This module complements the module "Setting up your Worklight development environment" with further steps that are required for BlackBerry 10 application development.


Setting up your BlackBerry 10 development environment

Setting up your Windows Phone 8 development environment

This module complements the module "Setting up your Worklight development environment" with further steps that are required for Windows Phone 8 application development.

2. Hello Worklight

Highly revised: Creating your first Worklight application

Exercise and code sample

This module explains how to set up your first mobile application.

Previewing your application on iOS

This module explains how to preview your application in the iOS environment.

Previewing your application on Android

This module explains how to preview your application in the Android environment.

Previewing your application on BlackBerry 6 and 7

This module explains how to preview your application in the BlackBerry 6 and BlackBerry 7 environments.

Previewing your application on BlackBerry 10

This module explains how to preview your application in the BlackBerry 10 environment.

Previewing your application on Windows Phone 7.5

This module explains how to preview your application in the Windows Phone 7.5 environment.

Previewing your application on Windows Phone 8

This module explains how to preview your application in the Windows Phone 8 environment.


This module explains the basics of the IBM Worklight Client API.

Building a multi page application


This module explains how to build a multi-page application with IBM Worklight.

of

ca In

Learning Worklight client side API

Working with UI frameworks

se

Ex

pe

rim

en

ta

3. Worklight client-side development basics

This module explains how to work with the user interface (UI) frameworks of IBM Worklight.

Debugging your applications

This module explains how to debug the client applications.

Optimizing your application for various environments

This module explains how to optimize the application code for specific environments.

General information when developing for iOS

This module gives some general information that you must know to develop apps for the iOS environment.


27


Sample (if any) Description This module gives some general information that you must know to develop apps for the Android environment.


General information when developing for Android

General information when developing for BlackBerry 6 and 7

This module gives some general information that you must know to develop apps for the BlackBerry 6 and BlackBerry 7 environments.

General information when developing for BlackBerry 10

This module gives some general information that you must know to develop apps for the BlackBerry 10 environment.

General information when developing for Windows Phone 7.5

This module gives some general information that you must know to develop apps for the Windows Phone 7.5 environment.

General information when developing for Windows Phone 8

This module gives some general information that you must know to develop apps for the Windows Phone 8 environment.

Highly revised: General information when developing Mobile Web applications

This module gives some general information that you must know to develop mobile web applications.

Highly revised: General information when developing desktop applications

This module gives some general information that you must know to develop desktop applications.

4. Worklight server-side development

28

This module explains what adapters are in IBM Worklight, and how to work with them.

HTTP adapter Communicating with HTTP back-end systems


This module explains how to work with adapters to communicate with HTTP back-end systems.

SQL adapter - Communicating with SQL database


This module explains how to work with adapters to communicate with SQL databases. Note: This module has the same code sample as the module HTTP adapter Communicating with HTTP back-end systems.

of

In

ca

se

Ex

pe

rim

en

ta

Adapter framework overview


Cast Iron® adapter Communicating with Cast Iron JMS adapter - Communicating with JMS

This module explains how to work with adapters to communicate with Cast Iron. Exercise and code sample

This module explains how to work with adapters to communicate by using Java Message Service (JMS). Note: This module has the same code sample as the module HTTP adapter Communicating with HTTP back-end systems.

Table 2. Getting Started modules and samples (continued) Sample (if any) Description

Invoking adapter procedures from client applications


This module explains how to call the adapter procedures from the client application.

Advanced adapter usage and mashup


This module explains advanced details on how to use adapters.

Using Java in adapters


This module explains how to use Java in adapters. Note: This module has the same code sample as the module HTTP adapter Communicating with HTTP back-end systems.


Module

5. Advanced client side development Overview of client technologies

Common UI controls

This module explains the technologies that support IBM Worklight clients.


Supporting multiple form-factors using Worklight skins

This module explains how you can support multiple form factors by working with skins in IBM Worklight.

Working offline


This module explains how to detect application connectivity failures and corresponding actions.

Enabling translation


This module explains how to enable translation of the client applications.

Using Direct Update to quickly update your application

se ca

In

This module explains how to automatically update your applications with new versions of their web resources.


JSONStore - The client-side JSON-based database overview

This module explains how to work with the encrypted cache of the mobile device. This module introduces the JSONStore, and how you can work with JSON documents.

Highly revised: JSONStore Common JSONStore Usage


This module explains the common tasks that you can perform on a local JSON collection.

Highly revised: JSONStore Encrypting sensitive data with FIPS 140-2


This module explains how you can encrypt the sensitive data of your local JSON collection by using FIPS 140-2.

of

pe

rim

en

ta

Storing sensitive data in Encrypted Cache

Ex

This module explains the common user-interface controls in IBM Worklight.

6. Adding native functionality to hybrid applications with Apache Cordova Apache Cordova overview

iOS - Using native pages in hybrid applications

This module explains what Apache Cordova is, and how to use it with IBM Worklight. Exercise and code sample

This module explains how to use native pages in hybrid applications that are developed for the iOS environment.


29


Sample (if any) Description

iOS - Adding native functionality to hybrid application with Apache Cordova plugin


Android - Using native pages in hybrid applications


This module explains how to use native pages in hybrid applications that are developed for the Android environment. Note: This module has the same code sample as the module iOS - Using native pages in hybrid applications.

Android - Adding native functionality to hybrid application with Apache Cordova plugin


This module explains how to use Apache Cordova plug-ins to add native functionality to hybrid applications that are developed for the Android environment.

Windows Phone 8 - Adding native functionality to hybrid application with Apache Cordova plugin


This module explains how to use Apache Cordova plug-ins to add native functionality to hybrid applications that are developed for the Windows Phone 8 environment.


This module explains how to use Apache Cordova plugs-in to add native functionality to hybrid applications that are developed for the iOS environment.

Using Worklight API in native iOS applications

Exercise and code sample (app) and Exercise and code sample (native API)

This module explains how to create a Worklight native API, and to use its components in a native iOS application.

Using Worklight API in native Android applications


This module explains how to create a Worklight native API, and to use its components in a native Android application.

Using Worklight API in native Java ME applications


This module explains how to use Java API to develop Java Platform, Micro Edition (Java ME) applications.

Using Worklight API for push notifications in native iOS applications


This module explains how to use Worklight API to manage push notification a native iOS application.

Using Worklight API for push notifications in native Android applications


This module explains how to use Worklight API to manage push notification a native Android application.

of

In

ca

se

Ex

pe

rim

en

ta

7. Developing native applications with Worklight

8. Authentication and security

30



Sample (if any) Description This module explains how to protects your applications and adapter procedures against unauthorized access by using authentication.


Authentication concepts

Form-based authentication


This module explains how to work with the form-based authentication.

Adapter-based authentication


This module explains how to work with the adapter-based authentication.

Custom Authenticator and Login Module


This module explains how to work with custom login modules and authenticators when the default ones do not suffice.

Using LDAP Login Module to authenticate users with LDAP server


This module explains how to work with the LDAP login module to authenticate users with LDAP servers.

WebSphere LTPA-based authentication

This module explains how to work with the WebSphere LTPA-based authentication.

Device provisioning concepts

This module explains the basics of device provisioning.

Custom device provisioning


NEW: Application Authenticity Protection

This module explains how to create a custom provisioning that uses a certificate from an external service to authenticate a device. This module also explains how to implement a custom authenticator that connects to that service.

This module explains how to work with the application authenticity protection.

9. Advanced topics


This module explains how to develop Android applications by using shells.

iOS shell development

This module explains how to develop iOS applications by using shells.

This module explains how to allow mobile device to receive messages that are pushed from a server.

SMS notifications


This module explains how to configure mobile devices to receive notifications through SMS messages that are pushed from a server.

Integrating server-generated pages in hybrid applications


This module explains how to remotely load dynamic content, where the code (HTML, CSS, and JavaScript) is hosted externally.

of


ca In

This module explains the concepts that support the shell development and the inner applications.

Android shell development

Push notifications

se

Ex

pe

rim

en

ta

Shell development concepts


31

Table 2. Getting Started modules and samples (continued) Sample (if any) Description

NEW: Location services


This module explains how to use geo-location services with IBM Worklight.

NEW: Testing Worklight Mobile Applications with the Mobile Test Workbench

iOS mobile client sample application

This module explains how to test your applications with IBM Worklight.


Module

10. Moving to production

Highly revised: Moving from development environment to stand-alone QA and production servers

This module explains how to move the components from the development environment into the test or production environment.

Reports and analytics

This module explains the BIRT reports that you can use to collect the analytics data that pertains to applications and to devices that are accessing the Worklight Server.

NEW: Operational Analytics

This module explains how you can use the operational analytics features of IBM Worklight that replace much of the functionality of BIRT reports in earlier versions of IBM Worklight.

NEW: Distributing mobile applications with Application Center

This module explains how you can deploy and distribute your apps with IBM Worklight Application Center.

11. Integrating with other products


This module explains how to develop as a team by using Rational® Team Concert.

Introducing Worklight Server and Application Center on IBM PureApplication System

This module introduces how you can integrate IBM Worklight Server and Application Center with IBM PureApplication System.

Integrating IBM Tivoli Directory Server on IBM PureApplication System

This module introduces how you can integrate IBM Tivoli Directory Server with IBM PureApplication System.

Using Worklight application as Exercise and a container for code sample server-generated pages

This module explains how to remotely load dynamic content, where the code (HTML, CSS, and JavaScript) is hosted externally.

Container for advanced pages


This module complements the module "Using Worklight application as a container for server-generated pages" with advanced information about how you can remotely load dynamic content.

Integrating with SiteMinder


This module explains how you can integrate IBM Worklight with SiteMinder.

of

ca In 32


se

Ex

pe

rim

en

ta

Using Rational Team Concert™ to build your applications

Worklight Starter application samples Study the Worklight Starter application samples to learn how to use IBM Worklight to create mobile applications. These samples have no associated modules. Table 3. Worklight Starter applications Description

Worklight Starter application

This file contains the sample code of the IBM Worklight Starter application.

Worklight Starter application with jQuery Mobile

This file contains the sample code of the IBM Worklight Starter application with jQuery Mobile.

Worklight Starter application with Sencha

This file contains the sample code of the IBM Worklight Starter application with Sencha Touch.


Sample

Worklight Starter This file contains the sample code of the IBM Worklight Starter application with Dojo application with Dojo Mobile. Mobile

JavaScript framework-based application samples

IBM Worklight provides several support materials for developing with JavaScript frameworks, such as Dojo, Dojo Mobile, and jQuery Mobile. You can study the following samples to learn how to use IBM Worklight to develop applications that are based on such frameworks. These samples have associated modules that describe them.

In

Module

Sample

Description

Running the Dojo-based sample


This module and its companion sample show how to develop an application that is based on Dojo through a basic sample application.

Running Dojo-based Mysurance end-to-end sample


This module and its companion sample show how to develop an application that is based on Dojo through the end-to-end "MySurance" sample application.

Running Dojo Mobile-based Apache Cordova sample


This module and its companion sample show how to develop an application that is based on Dojo Mobile through an Apache Cordova sample application.

Running jQuery Mobile-based Flight Ticket sample


This module and its companion sample constitute an end-to-end application in the flight booking domain that is based on jQuery Mobile.

of

ca

se

Ex

pe

rim

en

ta

Table 4. JavaScript framework-based applications

Additional resources The following compressed files contain all the materials for the tutorials and samples: v All IBM Worklight tutorial modules v All IBM Worklight tutorial companion samples and application samples


33

Terms and conditions


Use of the IBM Worklight Getting Started modules, exercises, and code samples available on this page is subject to you agreeing to the terms and conditions set forth here: This information contains sample code provided in source code form. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample code is written. Notwithstanding anything to the contrary, IBM PROVIDES THE SAMPLE SOURCE CODE ON AN "AS IS" BASIS AND IBM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND ANY WARRANTY OR CONDITION OF NON-INFRINGEMENT. IBM SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY OR ECONOMIC CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR OPERATION OF THE SAMPLE SOURCE CODE. IBM SHALL NOT BE LIABLE FOR LOSS OF, OR DAMAGE TO, DATA, OR FOR LOST PROFITS, BUSINESS REVENUE, GOODWILL, OR ANTICIPATED SAVINGS. IBM HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS TO THE SAMPLE SOURCE CODE.

of

In

ca

se

Ex

pe

rim

en

ta

Please review the third party licenses before using any of the resources. The third party licenses applicable to each sample are available in the notices.txt file included with each sample.

34


Chapter 4. Installing and configuring


This topic is intended for IT developers and administrators who want to install and configure IBM Worklight.

This topic describes the tasks required to install and configure the different components of IBM Worklight. It also contains information about installing and configuring database and application server software that you need to support the IBM Worklight database.

For more information about how to size your system, see the following documents: v Scalability and Hardware Sizing (PDF) v Hardware Calculator (XLS)

IBM Worklight installation overview

IBM Worklight provides the following installable parts: Worklight Studio, Worklight Server, and IBM Mobile Test Workbench for Worklight. This section gives an overview of the installation process. Install IBM Installation Manager 1.6.3 or later separately before installing IBM Worklight. To ensure the correct installation of Worklight Server, see “Installation prerequisites” on page 42.

Installing Worklight Studio on Eclipse with a P2 update site

You install Worklight Studio into an existing Eclipse. You also must install extra software development kits and Eclipse plug-ins for each mobile environment (Android Development Toolkit, for instance).

rim

en

ta

Installing Worklight Server with Installation Manager

Worklight server-side components are installed on your application server, and databases are created on your database system. Some application server and database configurations are required

of

You install Worklight Studio from your existing Eclipse IDE workbench.

In

ca

se

Ex

pe

Installing Worklight Studio

Before you begin v All Worklight Studio editions are installed with a P2 Eclipse update. Since IBM Worklight V6.0.0, IBM Installation Manager for Worklight Studio is no longer provided. v Worklight Studio Developer Edition provides every Worklight Studio function available in Worklight Studio Consumer Edition and Worklight Studio Enterprise Edition, except for some security-related features.

35

To know more about the specificities of IBM Worklight Developer Edition, IBM Worklight Consumer Edition, and IBM Worklight Enterprise Edition, see “IBM Worklight editions” on page 8.


v Ensure that your computer meets the system requirements for the software that you install. For example, only Eclipse 4.2.2 (Juno) is supported (Java Enterprise Edition, or Classic). For more information, see “System requirements for using IBM Worklight” on page 8. Note: Errors happen immediately if you use another version of Eclipse. v Ensure that an Internet connection is available in case dependencies that are required by the installation are not already included in the Eclipse IDE.

About this task

v To install Worklight Studio Developer Edition, go to the IBM Mobile development website at https://www.ibm.com/developerworks/mobile/ worklight.html.

v To install Worklight Studio Consumer Edition or Worklight Studio Enterprise Edition, complete the following procedure.

Procedure

1. Start your Eclipse IDE workbench. 2. Click Help > Install new software.

rim

en

ta

3. Beside the Work with field, click Add. 4. In the Add Repository window, click Archive. 5. Browse to the location of the P2 update .zip file on the DVD, or of the archive file on your machine, and click Open. 6. Click OK to exit the Add Repository window. 7. Select the features of Worklight Studio that you want to install, and then click Next.

What to do next

Before you run Worklight Studio, determine whether you must run extra post-installation tasks.

of

pe Ex

8. On the Install Details page, review the features that you install, and then click Next. 9. On the Review Licenses page, review the license text. If you agree to the terms, click I accept the terms of the license agreement and then click Finish. The installation process starts. 10. Follow the prompts to complete the installation.

In

ca

se

Running post-installation tasks Before you run Worklight Studio, you may need to run additional post-installation tasks.

Running additional tasks for Rational Team Concert V4.0 You might need to clean the Eclipse environment before you run Worklight Studio.

About this task If your Eclipse workbench has IBM Rational Team Concert, version 4.0, Eclipse Client already installed, the Worklight Studio plug-ins might not be properly

36


activated when you open an existing workbench. For example, the wizard New > IBM Worklight Project might not be available. To work around this problem, follow these instructions.


Note: You need to perform these steps only the first time that you start the product.

Procedure

1. Stop the workbench. 2. Locate the eclipse.ini file in eclipse_installation_directory\eclipse\ eclipse.ini. 3. Make a copy of the eclipse.ini file, or back it up. 4. Open the eclipse.ini file in a text editor. 5. Append the following text on a new line: -clean 6. Save and close the file.

7. Start the product and select a workspace. You should be able to successfully open the workspace. 8. Remove the -clean line from the eclipse.ini file and save the file.

Starting Worklight Studio

Start Worklight Studio by running the Eclipse executable file.

Procedure

v On Linux systems, run the eclipse file. v On Windows systems, run the eclipse.exe file.

Installing mobile specific tools

When you develop mobile applications, you must install and use specialized tools (such as SDKs). These tools depend on the operating system that you develop the applications for (such as iOS or Android).

To build and sign applications for Adobe AIR, you must install the Adobe AIR SDK.

1. Download the Adobe Air SDK from the Air SDK on Adobe website. 2. Unpack the archive into a folder of your choice. 3. Set an environment variable (either locally or on the central build server) named AIR_HOME, pointing to the place where you opened the SDK. The Worklight Builder uses this environment variable to run the build and sign tool when building AIR applications.

of

ca In

Installing tools for Adobe AIR

Procedure

se

Ex

pe

rim

en

ta

This collection of topics details the required tools for each operating system.

Installing tools for iOS To build and sign applications for iOS, you must install the latest Xcode IDE (including the iOS simulator) on a Mac.

Procedure 1. Register as an Apple developer on the Apple Registration Center website at https://developer.apple.com/programs/register/. Chapter 4. Installing and configuring

37


2. Download Xcode from the Mac App Store at http://www.apple.com/osx/ apps/app-store.html. 3. Install Xcode on your Mac. For more information about the iOS development environment, see the module Setting Up Your iOS Development Environment, under category 1, Setting up your development environment, in Chapter 3, “Tutorials and samples,” on page 25.

Installing tools for Android

To build and sign applications for Android, you must install the Android SDK and the Android Development Tools plug-in for Eclipse.

Procedure

1. Install the Android SDK available at http://developer.android.com/sdk/. 2. Install the Android Development Tools plug-in for Eclipse available at https://dl-ssl.google.com/android/eclipse/. 3. Add SDK Platform and Virtual Devices to the SDK. For more information about the Android development environment, see the module Setting Up Your Android Development Environment, under category 1, Setting up your development environment, in Chapter 3, “Tutorials and samples,” on page 25. Note: On Ubuntu (Linux), you must check that the Android SDK works properly. You might need to add some .lib files. For more information, see http://developer.android.com/sdk/installing/index.html.

Installing tools for BlackBerry

To build and sign applications for BlackBerry OS 6, 7 or 10, you must install the WebWorks tools.

Procedure

38

2. Download WebWorks SDK from the same site, at https:// developer.blackberry.com/html5/download/, and install it to the folder of your choice. 3. (Only for BlackBerry 10) Set an environment variable (either locally or on the central build server) named WEBWORKS_HOME, pointing to the SDK root folder. The Worklight® Builder uses this environment variable when it builds BlackBerry 10 applications. On each build, the environment variable value is transferred to native\project.properties.

of

In

ca

se

Ex

pe

rim

en

ta

1. Download Ripple emulator available at https://developer.blackberry.com/ html5/download/ and install it.


Note: WEBWORKS_HOME must be set before you start Worklight Studio. This variable is important for the normal operation of the client. If you use Ant scripts to build and deploy the application to the device, and the WEBWORKS_HOME value is set incorrectly, your file structure might become corrupted, and produce a new directory with the incorrect WEBWORKS_HOME value name.

Note: BlackBerry OS 10 is not supported by the current version of the Application Center. 4. Download and install a simulator. For more information about the BlackBerry development environment, see the module Setting Up Your BlackBerry 6 and 7 Development Environment and Setting

up your BlackBerry 10 development environment, under category 1, Setting up your development environment, in Chapter 3, “Tutorials and samples,” on page 25.

Installing tools for Windows Phone 7.5


To build and sign applications for Windows Phone 7.5 (deprecated in IBM Worklight V6.0.0), you must install Microsoft Visual Studio Express 2010 or 2012 for Windows Phone, and Zune Software.

Procedure

1. Download and install Microsoft Visual Studio Express, available at http://www.microsoft.com/visualstudio/eng/products/visual-studio-2010express for the 2010 edition, and at http://www.microsoft.com/visualstudio/ eng/products/visual-studio-express-for-windows-phone for the 2012 edition. 2. Download Zune software from http://www.zune.net/enUS/products/ software/download/default.htm and install it.

Installing tools for Windows Phone 8

To build and sign applications for Windows Phone 8, you must install Microsoft Visual Studio Express 2012 for Windows Phone.

Procedure

Download Microsoft Visual Studio Express 2012 from http://www.microsoft.com/ visualstudio/eng/products/visual-studio-express-for-windows-phone and install it. For more information about the Windows Phone 8 development environment, see the module Setting Up Your Windows Phone 8 Development Environment, under category 1, Setting up your development environment, in Chapter 3, “Tutorials and samples,” on page 25.

Installing tools for Windows 8

Windows Store apps run only on Windows 8, so to develop Windows Store apps, you need Windows 8 and some developer tools.

Procedure

In

2. Click Download now under "Download the tools and SDK". 3. Download Microsoft Visual Studio Express 2012 from http:// www.microsoft.com/visualstudio/eng/products/visual-studio-express-forwindows-phone and install it. Microsoft Visual Studio Express 2012 for Windows 8 includes the Windows 8 SDK. It also gives you tools to code, debug, package, and deploy a Windows Store app. 4. Start Visual Studio Express 2012. You will be prompted to obtain a developer license. You need a developer license to install, develop, test, and evaluate Windows Store apps. 5. For more information about obtaining a developer license, see http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx.

of

ca

se

Ex

pe

rim

en

ta

1. After you install Windows 8, go to http://msdn.microsoft.com/en-us/ windows/apps/br229516.aspx.

Changing the port number of the internal application server If the default port number is already in use, edit the eclipse.ini file to change to a different port.


39

About this task


When you start Eclipse with Worklight Studio, an embedded application server is started automatically to host a Worklight Server instance for your adapters and apps. This internal server uses port 10080 by default. If port 10080 is occupied by another application that is running on your development computer, you can configure the Worklight Studio internal server to use a different port. To do so, follow these instructions:

Procedure 1. 2. 3. 4. 5.

Open the Servers view in Eclipse. Expand the Worklight Development Server list. Double-click Server Configuration [server.xml] worklight. In the Server Configuration window, click HTTP endpoint. Change the Port value to any port number of your choice.

Installing IBM Mobile Test Workbench for Worklight

You must install IBM Mobile Test Workbench for Worklight into an Eclipse IDE where Worklight Studio V6.0.0 or later is already installed.

Before you begin

v Your computer must meet the system requirements for the software that you install. For more information, see “System requirements for using IBM Worklight” on page 8. v Worklight Studio V6.0.0 or later must be already installed on your computer. v Ensure that an Internet connection is available in case dependencies that are required by the installation are not already included in the Eclipse IDE.

About this task

v To install IBM Mobile Test Workbench for Worklight on top of IBM Worklight Consumer Edition or IBM Worklight Enterprise Edition, complete the following procedure.

Procedure

1. Start your Eclipse IDE workbench.

of

2. Click Help > Install new software. 3. Beside the Work with field, click Add.

In

ca

se

Ex

pe

rim

en

ta

v To install IBM Mobile Test Workbench for Worklight on top of IBM Worklight Developer Edition, go to the IBM Worklight development website at https://www.ibm.com/developerworks/mobile/worklight/.

4. In the Add Repository window, click Archive. 5. Browse to the location of the P2 update .zip file on the DVD, or of the archive file on your machine, and click Open. 6. Click OK to exit the Add Repository window. 7. Select the features of IBM Mobile Test Workbench for Worklight that you want to install, and then click Next. 8. On the Install Details page, review the features that you install, and then click Next.

40


9. On the Review Licenses page, review the license text. If you agree to the terms, click I accept the terms of the license agreement and then click Finish. The installation process starts. 10. Follow the prompts to complete the installation.


What to do next

When IBM Mobile Test Workbench for Worklight is installed, you can install the mobile test client. For more information about the mobile test client installation, see Installing the mobile test client. To understand the various available features, see Testing with IBM Worklight. Make sure you add a JDK to your path in Eclipse. For more information, see “Troubleshooting IBM Mobile Test Workbench for Worklight.”

Troubleshooting IBM Mobile Test Workbench for Worklight

If you do not set Eclipse to use a JDK installed on your system, you cannot test Android applications with IBM Mobile Test Workbench for Worklight. The testing process fails and you get error messages.

About this task

To test Android applications with IBM Mobile Test Workbench for Worklight, you must add the path to the JDK in Eclipse.

Procedure

1. In Eclipse, go to Window > Preferences > Java > Installed JREs. 2. Select the JDK check box to set the JDK as the default JRE.

Installing Worklight Server

In

Important: Ensure that you use IBM Installation Manager 1.6.3.1 or later. This version contains an important fix for an issue identified in IBM Installation Manager 1.6.3. See http://www.ibm.com/support/docview.wss?uid=swg24035049.

The Worklight Server installer copies onto your computer all the tools and libraries that are required for deploying an IBM Worklight Project or the Application Center in production, and the IBM WebSphere Analytics Platform.

of

ca

se

Ex

pe

rim

en

ta

IBM installations are based on an IBM product called IBM Installation Manager. Install IBM Installation Manager 1.6.3.1 or later separately before you install IBM Worklight.

Worklight Server can also automatically deploy the Application Center at installation time. In this case, a database management system and an application server are required as prerequisites and must be installed before you start the Worklight Server installer. The installer can also help with upgrading an existing installation of Worklight Server to the current version. See Chapter 5, “Upgrading from one version of IBM Worklight to another,” on page 181. The following topics describe the installation of Worklight Server, installation prerequisites, and the procedures for a manual installation and configuration of Chapter 4. Installing and configuring

41


Application Center. After Worklight Server is installed, a Worklight project must be deployed to an application server. This deployment installs a Worklight Console that can be used to upload applications and adapters. The instructions in “Overview of the Worklight Server installation process” on page 43 are based on a simple installation scenario. For a complete description of the process of deploying a Worklight project, see Chapter 8, “Deploying IBM Worklight projects,” on page 663.

Installation prerequisites

For smooth installation of Worklight Server, ensure that you fulfill all required environment setup and software prerequisites before you attempt installation. You can find a complete list of supported hardware together with prerequisite software under: IBM Worklight and IBM Mobile Foundation detailed system requirements.

Important: If a version of Worklight Server is already installed, review Chapter 5, “Upgrading from one version of IBM Worklight to another,” on page 181 before you install Worklight Server and deploy a Worklight project on the same application server or databases. Failure to do so can result in an incomplete installation and a non-functional Worklight Server. Download the IBM Mobile Platform foundation package or the IBM Worklight package from the IBM Passport Advantage® site.

Ensure that you have the latest fix packs for the IBM Worklight product. If you are connected to the Internet during the installation, IBM Installation manager can download the latest fix packs for you. The package contains an Install Wizard that guides you through the Worklight Server installation.

You can use any of the following application servers: v WebSphere Application Server Liberty Core. v WebSphere Application Server. v Apache Tomcat.

You can use any of the following database management systems:

v v v v

IBM DB2® MySQL Oracle Apache Derby in embedded mode. Included in the installation image.

of

In

ca

se

Ex

pe

rim

en

ta

Worklight Server requires an application server and relies on a database management system.

Note: Apache Derby is supplied for evaluation and testing purposes only and is not supported for production-grade IBM Worklight servers. The IBM Worklight installer can install the Application Center and deploy it to your application server. In this case, the application server and the database management system (if different from Apache Derby) must be installed before you start the Worklight Server installer. If you do not need the Application Center or decide to install it manually, you do not need to install the application server and

42


database management system before starting the Worklight Server installer. However, you need them before deploying IBM Worklight projects.


The IBM Mobile Platform Foundation and IBM Worklight packages include the following installers: v IBM DB2 Workgroup Server Edition v IBM DB2 Enterprise Server Edition (on zLinux only) v IBM WebSphere Application Server Liberty Core

Overview of the Worklight Server installation process

Learn about the Worklight Server installation process based on a simple configuration that creates a functional Worklight Server that is usable for demonstration purposes or tests.

Before you begin

v Install Worklight Studio on your computer. You use Worklight Studio to create a simple IBM Worklight project. v Install Apache Ant on your computer. You use Apache Ant to deploy the IBM Worklight project. You can download Apache Ant from http://ant.apache.org/ bindownload.cgi.

About this task

This task shows you how to install the Worklight Server on a simple configuration and shows you where to find the following tools and information: v Tools to install a Worklight Server and the Application Center, and tools to deploy an IBM Worklight project. v Information about configuring the Worklight Server and the Application Center.

1. Install IBM WebSphere Application Server Liberty Core. The installer for IBM WebSphere Application Server Liberty Core is provided as part of the package for IBM Worklight or IBM Mobile Foundation. a. Load the repository for IBM WebSphere Application Server Liberty Core in IBM Installation Manager and install the product. b. During the installation process, take note of the installation directory of Liberty. You need this information later on in the procedure. 2. Create a server for Liberty. You use this server to install the Application Center and to deploy an IBM Worklight project and its console.

of

ca In

This task involves installing the following components: v An IBM WebSphere Application Server Liberty Core application server. v A Derby database (installed by the Worklight Server installer). v The Application Center. v A very simple IBM Worklight project and its console.

Procedure

se

Ex

pe

rim

en

ta

v Information about manual Worklight Server installation. Manual installation provides greater flexibility, but can make the diagnosis of issues more complex, and make the description of a configuration to IBM Support more difficult.

a. Go to the installation directory of Liberty. For example, on Windows, if the product is installed with Administrator rights, it is located by default in C:\Program Files\IBM\WebSphere\Liberty. Chapter 4. Installing and configuring

43

b. Type the command that creates a server. In this scenario, the chosen name is simpleServer. On UNIX and Linux systems: bin/server create simpleServer


On Windows systems: bin\server.bat create simpleServer

The server is created with all default settings. For more information about configuring a Liberty Server, read the file README.txt in the Liberty installation directory. Default settings are sufficient for this walkthrough. 3. Install Worklight Server. a. Load the repository for Worklight Server in IBM Installation Manager and install the product. 1) In the Configuration Choice panel, select the first choice. This option installs Application Center. 2) In the Database Choice panel, select Install Apache Derby. This database is not recommended for production use, but is sufficient for this walkthrough. 3) In the Application Server Selection panel, select WebSphere Application Server. 4) In the Application Server Configuration panel, select the installation directory for IBM WebSphere Application Server Liberty Core that is installed in step 2. 5) Select simpleServer as the server name. 6) Install the product. The files that are described in “Distribution structure of Worklight Server” on page 62 are installed on your computer.

4. Explore Application Center. Application Center is now functional. The artifacts of the Application Center are deployed into the Liberty Server, which now includes the features that Application Center requires, and a demonstration user account exists. The required Derby database also exists.

of

In

ca

se

Ex

pe

rim

en

ta

a. To test the Application Center, start the Liberty server.

44


On UNIX and Linux systems: bin/server start simpleServer

On Windows systems: bin\server.bat start simpleServer b. Open the Application Center by using the program shortcut that the installer creates: IBM Worklight Server > Application Center. Alternatively, you can enter the URL for the Application Center into a browser window. When a Liberty server is created with default settings, the default URL for Application Center is http://localhost:9080/appcenterconsole/. c. Log in to the Application Center with the demonstration account credentials (login: demo, password: demo) d. Explore further by using any of the following resources: v See “Configuring the Application Center after installation” on page 118. v See “Distribution structure of Worklight Server” on page 62 for a list of IBM Worklight applications that you can compile and upload to the application center. These applications provide access to the Application Center for mobile devices.


v If you are considering a manual installation of Application Center, see “Manually installing Application Center” on page 66. In some cases, manual installations can make the diagnosis of issues more complex, and can make the description of a configuration to IBM Support more difficult. 5. Create a simple IBM Worklight project. You create a project to deploy a console. a. Complete the following steps: 1) Install Worklight Studio on your computer. See “Installing Worklight Studio” on page 35. 2) Start Worklight Studio. 3) Create an IBM Worklight project (File > New > Worklight Project). 4) Assign the name simpleProject, and accept the default project template Hybrid Application. 5) In the next panel, name the application simpleApp, and then click Finish. b. Build the application. 1) In the Project Explorer view in Worklight Studio, open the project. 2) Open the apps folder, right-click the subfolder simpleApp, and then click Run As/Build and Deploy. 3) In the Project Explorer view, open the bin folder that was created by this task. Right-click simpleProject.war and click Properties. The properties show the path to the WAR file. This path is used in the next step. For example, if the path of the Eclipse workspace is C:\workspaces\WorklightStudioWorkspace, the path to the WAR file is C:\workspaces\WorklightStudioWorkspace\simpleProject\bin\ simpleProject.war.

of

ca In

a. Copy the /WorklightServer/ configuration-samples/configure-liberty-derby.xml file to a working directory so that you can edit it and create a modified version to deploy an IBM Worklight project to the Liberty application server. This file is an example of the use of Ant tasks to deploy an IBM Worklight project. See “Deploying an IBM Worklight project” on page 665. b. Open your local copy of the file and modify the seven properties that describe the deployment directories:

Note: The following values correspond to a default installation on Microsoft Windows with administrator rights. Check the actual values for your configuration.

se

Ex

pe

rim

en

ta

6. Create an Ant file to deploy an IBM Worklight project. For this step, Apache Ant must be installed on your computer. IBM Worklight uses the Apache Ant Java library and command-line tool to automate build and deployment tasks.

v For property worklight.project.war.file, the absolute path of the project that was created in step 5.

v For property worklight.server.install.dir, the installation directory for the Worklight Server that was installed in step 3.

v For property derby.databases.data.dir, choose the directory where you want to create the databases for Application Center.

v For property was.liberty.install.dir, the installation directory of Liberty, in step 1. Chapter 4. Installing and configuring

45

v For property was.liberty.server.name, the name of the server that was created in step 2.


v For property shortcuts.dir, the name of a directory to create a UNIX shortcut and a Windows shortcut to the console.

v For property reports.dir, the name of a directory to create BIRT reports.

7. Run the Ant script to create the databases for the deployed IBM Worklight project. a. In a console, type the following command: ant -f configure-liberty-derby.xml databases

Note: If you do not have the Ant command in your PATH variable, type the full path to the Ant command. 8. Run the Ant script to deploy the IBM Worklight project. In a console, type the following command: ant -f configure-liberty-derby.xml install

The output of the Ant task displays the details of the steps that are completed during deployment. At the end of the traces, it displays the Worklight Console. Take a note of the URL: it is used in step 9. [...] [configureapplicationserver] [configureapplicationserver] [configureapplicationserver] [configureapplicationserver] [configureapplicationserver] [configureapplicationserver] [configureapplicationserver] [configureapplicationserver]

[replace] Replacing in c:\simpleServerTest\shortcuts\worklight-console.url: @URL@ --> http://localhost:9080/worklight

cleanup: install:

BUILD SUCCESSFUL Total time: 24 seconds

9. Restart the Liberty server and open the Worklight Console. a. Go to the Liberty Installation Directory. Type the following command:

ta

bin\server.bat stop simpleServer

b. Restart the server with the following command:

c. Wait a few seconds while the Liberty server completes initializing and loads all its applications. d. Open a web browser and open the URL of the Worklight Console that you noted in step 8.

of

Ex

pe

rim

en

bin\server.bat start simpleServer

In

ca

se

What to do next If you want to explore the Worklight Console further, you can complete the following tasks: v Deploy an application as described in “Deploying applications and adapters to Worklight Server” on page 733. v Review Chapter 9, “Administering IBM Worklight applications,” on page 755. v Review “Deploying an IBM Worklight project” on page 665.

46


v Review “Configuration of IBM Worklight applications on the server” on page 714 and “Configuring an IBM Worklight project in production by using JNDI environment entries” on page 723


v Review the options to deploy an IBM Worklight project manually. In some cases, manual installations can make the diagnosis of issues more complex, and can make the description of a configuration to IBM Support more difficult. See “Deploying a project WAR file and configuring the application server manually” on page 710.

Running IBM Installation Manager

IBM Installation Manager installs the IBM Worklight files and tools on your computer.

IBM Installation Manager helps you install, update, modify, and uninstall packages on your computer. The installer for Worklight Server does not support rollback operations and updates from versions 5.x to 6.0 cannot be undone. The way you use IBM Installation Manager to upgrade from a previous release depends on your upgrade path.

You can use IBM Installation Manager to install IBM Worklight in several different modes, including single-user and multi-user installation modes. You can also use silent installations to deploy IBM Worklight to multiple systems, or systems without a GUI interface.

For more information about Installation Manager, see the IBM Installation Manager Information Center at http://pic.dhe.ibm.com/infocenter/install/v1r6/index.jsp.

Optional creation of databases

of

Creating the DB2 database for Application Center:

ca In

If you have sufficient database administration credentials, and if you enter the administrator user name and password in the installer when prompted, the installer can create the databases for you. Otherwise, you need to ask your database administrator to create the required database for you. The database needs to be created before you start the IBM Worklight Server installer. The following topics describe the procedure for the supported database management systems.

se

Ex

pe

rim

en

ta

If you want to activate the option to install the Application Center when you run the IBM Worklight Server installer, you need to have certain database access rights that entitle you to create the tables that are required by the Application Center.

During IBM Worklight installation, the installer can create the Application Center database for you. About this task The installer can create the Application Center database for you if you enter the name and password of a user account on the database server that has the DB2 SYSADM or SYSCTRL privilege, and the account can be accessed through SSH. Otherwise, the database administrator can create the Application Center database for you. For more information, see the DB2 Solution user documentation. Chapter 4. Installing and configuring

47

When you manually create the database, you can replace the database name (here APPCNTR) and the password with a database name and password of your choosing.


Important: You can name your database and user differently, or set a different password, but ensure that you enter the appropriate database name, user name, and password correctly across the DB2 database setup. DB2 has a database name limit of 8 characters on all platforms, and has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows.

Procedure 1. Create a system user, for example, named wluser in a DB2 admin group such as DB2USERS, using the appropriate commands for your operating system. Give it a password, for example, wluser. If you want multiple IBM Worklight Servers to connect to the same database, use a different user name for each connection. Each database user has a separate default schema. For more information about database users, see the DB2 documentation and the documentation for your operating system. 2. Open a DB2 command line processor, with a user that has SYSADM or SYSCTRL permissions: v On Windows systems, click Start > IBM DB2 > Command Line Processor v On Linux or UNIX systems, navigate to ~/sqllib/bin and enter ./db2. v Enter database manager and SQL statements similar to the following example to create the Application Center database, replacing the user name wluser with your chosen user names:

Creating the MySQL database for Application Center:

of

About this task

ca In 48

3. The installer can create the database tables and objects for Application Center in a specific schema. This allows you to use the same database for Application Center and for a Worklight project. If the IMPLICIT_SCHEMA authority is granted to the user created in step 1 (the default in the database creation script in step 2), no further action is required. If the user does not have the IMPLICIT_SCHEMA authority, you need to create a SCHEMA for the Application Center database tables and objects.

During the IBM® Worklight installation, the installer can create the Application Center database for you.

se

Ex

pe

rim

en

ta

CREATE DATABASE APPCNTR COLLATE USING SYSTEM PAGESIZE 32768 CONNECT TO APPCNTR GRANT CONNECT ON DATABASE TO USER wluser DISCONNECT APPCNTR QUIT


The installer can create the database for you if you enter the name and password of the superuser account. For more information, see Securing the Initial MySQL Accounts on your MySQL database server. Your database administrator can also create the databases for you. When you manually create the database, you can replace the database name (here APPCNTR) and password with a database name and password of your choosing. Note that MySQL database names are case-sensitive on Unix.

Procedure 1. Start the MySQL command-line tool. 2. Enter the following commands:


CREATE DATABASE APPCNTR CHARACTER SET utf8 COLLATE utf8_general_ci; GRANT ALL privileges ON APPCNTR.* TO ’worklight’@’Worklight-host’ IDENTIFIED BY ’password’; GRANT ALL privileges ON APPCNTR.* TO ’worklight’@’localhost’ IDENTIFIED BY ’password’; Flush privileges;

Here, you need to replace Worklight-host with the name of the host on which IBM Worklight runs.

Creating the Oracle database for Application Center:

During the IBM® Worklight installation, the installer can create the Application Center database or the user and schema inside an existing database for you. About this task

In

Procedure 1. If you do not already have a database named ORCL, use the Oracle Database Configuration Assistant (DBCA) and follow the steps in the wizard to create a new general-purpose database named ORCL: a. Use global database name ORCL_your_domain, and system identifier (SID) ORCL. b. On the Custom Scripts tab of the step Database Content, do not run the SQL scripts, because you must first create a user account. c. On the Character Sets tab of the step Initialization Parameters, select Use Unicode (AL32UTF8) character set and UTF8 - Unicode 3.0 UTF-8 national character set.

d. Complete the procedure, accepting the default values. 2. Create a database user either by using Oracle Database Control, or by using the Oracle SQLPlus command-line interpreter.

of

ca

se

Ex

pe

rim

en

ta

The installer can create the database or user and schema inside an existing database for you if you enter the name and password of the Oracle administrator on the database server, and the account can be accessed through SSH. Otherwise, the database administrator can create the database or user and schema for you. When you manually create the database or user, you can use database names, user names, and a password of your choosing. Note that lowercase characters in Oracle user names can lead to trouble.

v Using Oracle Database Control. a. Connect as SYSDBA.

b. Go to the Users page: click Server, then Users in the Security section. c. Create a user, for example, named APPCENTER. If you want multiple IBM Worklight Servers to connect to the same general-purpose database you created in step 1, use a different user name for each connection. Each database user has a separate default schema. d. Assign the following attributes: – Profile: DEFAULT – Authentication: password – Default table space: USERS – Temporary table space: TEMP Chapter 4. Installing and configuring

49

Status: UNLOCK Add role: CONNECT Add role: RESOURCE Add system privilege: CREATE VIEW Add system privilege: UNLIMITED TABLESPACE


– – – – –

v Using the Oracle SQLPlus command-line interpreter. The commands in the following example create a user named APPCENTER for the database: CONNECT system/@ORCL CREATE USER APPCENTER IDENTIFIED BY password; GRANT CONNECT, RESOURCE, CREATE VIEW TO APPCENTER; DISCONNECT;

Single-user versus multi-user installations

You can install Worklight Server in several different modes.

Administrator installation It is an administrator installation when Installation Manager is installed through the install command. In this case, it requires administrator privileges to run, and it produces multi-user installations of products.

When you have chosen an administrator installation of Worklight Server, it is advisable to run the application server from a non-administrator user account. Running it from an administrator or root user account is dangerous in terms of security risks. Because of this, during an administrator installation of Worklight Server, you have the option to choose an operating system user or an operating system user group. Each of the users in this group can: v Run the specified application server (if WebSphere Application Server Liberty Profile, or Apache Tomcat). v Modify the Application Center Derby database (if Apache Derby is chosen as your database management system).

50

Single-user installation It is a single-user installation when Installation Manager is installed through the userinst command. In this case, only the user who installed this copy of Installation Manager can use it.

of

In

ca

se

Ex

pe

rim

en

ta

In this case, the Worklight Server installer will set restrictive access permissions on the Liberty or Tomcat configuration files, so as to: 1. Allow the specified users to run the application server. 2. At the same time, protect the database or user passwords that these files contain.


The following constraints regarding user accounts on UNIX apply: v If the application server is owned by a non-root user, you can install Worklight Server in either of two ways: – Through a single-user installation of IBM Installation Manager as the same non-root user. – Through an administrator installation of IBM Installation Manager, as root, and afterwards change the owner of all files and directories added or modified during the installation to that user. The result is a single-user installation.

v If the application server is owned by root, you can install Worklight Server only through an administrator installation of IBM Installation Manager; a single-user installation of IBM Installation Manager does not work, because it lacks the necessary privileges.

Installing a new version of Worklight Server


Create a fresh installation of Worklight Server by creating a new package group in IBM Installation Manager.

Procedure

1. Start IBM Installation Manager. 2. On the IBM Installation Manager main page, click the Install button. 3. In the panel that prompts for the package group name and the installation directory, select Create a new package group. 4. Complete the installation by following the instructions that are displayed.

Upgrading Worklight Server from a previous release

The way that you use IBM Installation Manager to upgrade from a previous version of Worklight Server depends on your upgrade path.

Before you begin

Before you apply these instructions, see Chapter 5, “Upgrading from one version of IBM Worklight to another,” on page 181. It describes important steps to upgrade IBM Worklight applications, or to upgrade a production server in a production environment.

Procedure

1. Start the IBM Installation Manager. 2. Depending on your upgrade path, take one of the following actions:

In

Installing Worklight Server into WebSphere Application Server Network Deployment

To install Worklight Server into a set of WebSphere Application Server Network Deployment servers, run IBM Installation Manager on the machine where the deployment manager is running.

of

ca

se

Ex

pe

rim

en

ta

v To upgrade from V5.x to V6.0 or later: a. Click the Install button. b. In the panel that prompts for the package group name and the installation directory, select Use the existing package group. In this situation, installation of V6.0 or later automatically removes a V5.x installation that was installed in the same directory. v To upgrade from V6.x to a newer version, click the Update button.

Procedure 1. When IBM Installation Manager prompts you to specify the database type, select any option other than Apache Derby. IBM Worklight supports Apache Derby only in embedded mode, and this choice is incompatible with deployment through WebSphere Application Server Network Deployment. 2. In the installer panel in which you specify the WebSphere Application Server installation directory, select the deployment manager profile.


51


Attention: Do not select an application server profile and then a single managed server: doing so causes the deployment manager to overwrite the configuration of the server regardless of whether you install on the machine on which the deployment manager is running or on a different machine. 3. Select the required scope depending on where you want Worklight Server to be installed. The following table lists the available scopes: Table 5. Selecting the required scope Scope

Explanation

Cell

Installs Worklight Server into all application servers of the cell.

Cluster

Installs Worklight Server into all application servers of the specified cluster.

Node (excluding clusters)

Installs Worklight Server into all application servers of the specified node that are not in a cluster.

Server

Installs Worklight Server into the specified server, which is not in a cluster.

4. Restart the target servers by following the procedure in “Completing the installation” on page 62.

Results

The installation has no effect outside the set of servers in the specified scope. The JDBC providers and JDBC data sources are defined with the specified scope. The entities that have a cell-wide scope (the applications and, for DB2, the authentication alias) have a suffix in their name that makes them unique. So, you can install Worklight Server in different configurations or even different versions of Worklight Server, in different clusters of the same cell.

You need to complete the following additional configuration: v If you use a front-end HTTP server, you need to configure the public URL

You can use IBM Installation Manager to perform silent installation of Worklight Server on multiple machines or on machines where a GUI interface is not available.

of

ca In 52

What to do next

Silent installation

se

Ex

pe

rim

en

ta

Note: Because the JDBC driver is installed only in the specified set of application servers, the Test connection button for the JDBC data sources in the WebSphere Application Server administration console of the deployment manager might not work.


About this task Silent installation uses predetermined answers to wizard questions, rather than presenting a GUI that asks the questions and records the answers. Silent installation is useful when: v You want to install Worklight Server on a set of machines that are configured in the same way.

v You want to install Worklight Server on a machine where a GUI is not readily available, for example a production server behind a firewall that prevents the use of VNC, RDP, remote X11, and ssh -X.


Silent installations are defined by an XML file called a response file. This file contains the necessary data to complete installation operations silently. Silent installations are launched from the command line or a batch file.

You can use IBM Installation Manager to record preferences and installation actions for your response file in user interface mode. Alternatively, you can create a response file manually by using the documented list of response file commands and preferences. You can use one response file to install, update, or uninstall multiple products.

Using a response file, you can perform almost any action that you can perform by using Installation Manager in wizard mode. For example, with a response file you can specify the location of the repository that contains the package, the package to install, and the features to install for that package. You can also use a response file to modify installed packages, to apply updates, and to apply a license. For a list of the parameters created in the response file by the IBM Installation Manager wizard, see “Silent installation parameters” on page 55.

Silent installation is described in the IBM Installation Manager documentation, see Working in silent mode.

Procedure

In

of

ca

se

Ex

pe

rim

en

ta

1. Record a response file, by running IBM Installation Manager in wizard mode and with option -record responseFile on a machine where a GUI is available. For more details, see Record a response file with Installation Manager. The following code example shows a recorded response file:


53


2. Modify the response file to take into account differences between the machine on which the response file was created and the target machine. The following code example shows the same response file, edited so that it can be used in step 3. Note: This is an example file based on the file in step 1. It might not be suitable for your environment. It is important that you record your own response file, so that it contains the correct parameters for your requirements.

of

In

ca

se

Ex

pe

rim

en

ta

54



3. Install Worklight Server by using the response file on the target machine, as described in Install a package silently by using a response file. Silent installation parameters:

The response file that you create for silent installations by running the IBM Installation Manager wizard supports a number of parameters. Table 6. Parameters available for silent installation

When necessary

Description

user.appserver.selection2

Always

Type of application server. was means preinstalled WAS 7.0, 8.0, or 8.5. tomcat means Tomcat 7.0 or newer.

of

user.appserver.was.installdir ${user.appserver.selection2} WAS == was installation directory.

Allowed values

was, tomcat, none

The value none means that the installer will not install the Application Center. If this value is used, both user.appserver.selection2 and user.database.selection2 must take the value none. An absolute directory name.

In

ca

se

Ex

pe

rim

en

ta

Key


55

Table 6. Parameters available for silent installation (continued)

user.appserver.was.profile

${user.appserver.selection2} Profile into == was which to install the applications. For WAS ND, specify the Deployment Manager profile. Liberty means the Liberty profile (subdirectory wlp).

The name of one of the WAS profiles.

user.appserver.was.cell

${user.appserver.selection2} WAS cell into == was && which to ${user.appserver.was.profile}install the != Liberty applications.

The name of the WAS cell.

user.appserver.was.node

${user.appserver.selection2} WAS node == was && into which to ${user.appserver.was.profile}install the != Liberty applications. This corresponds to the current machine.

The name of the WAS node of the current machine.

user.appserver.was.scope

${user.appserver.selection2} Type of set of == was && servers into ${user.appserver.was.profile}which to != Liberty install the applications. server means a standalone server. nd-cell means a WAS ND cell. nd-cluster means a WAS ND cluster. nd-node means a WAS ND node (excluding clusters). nd-server means a managed WAS ND server.

server, nd-cell, nd-cluster, nd-node, nd-server

ta


When necessary

en rim In

ca

se

of

pe Ex 56

Description

Allowed values

Key


Table 6. Parameters available for silent installation (continued) Key

When necessary

Description

Allowed values The name of a WAS server on the current machine.

user.appserver.was.nd.cluster ${user.appserver.selection2} Name of WAS == was && ND cluster ${user.appserver.was.profile}into which to != Liberty && install the ${user.appserver.was.scope} applications. == nd-cluster

The name of a WAS ND cluster in the WAS cell.

user.appserver.was.nd.node

${user.appserver.selection2} Name of WAS == was && ND node into ${user.appserver.was.profile}which to != Liberty && install the (${user.appserver.was.scope} applications. == nd-node || ${user.appserver.was.scope} == nd-server)

The name of a WAS ND node in the WAS cell.

user.appserver.was.nd.server

${user.appserver.selection2} Name of WAS == was && ND server ${user.appserver.was.profile}into which to != Liberty && install the ${user.appserver.was.scope} applications. == nd-server

The name of a WAS ND server in the given WAS ND node.


user.appserver.was.serverInstance ${user.appserver.selection2} Name of WAS == was && server into ${user.appserver.was.profile}which to != Liberty && install the ${user.appserver.was.scope} applications. == server

In

user.appserver.was.admin.password2 ${user.appserver.selection2} Password of == was && WAS ${user.appserver.was.profile}administrator, != Liberty optionally encrypted in a specific way.

user.appserver.was.appcenteradmin.password ${user.appserver.selection2} Password of == was && appcenteradmin ${user.appserver.was.profile}user to add to != Liberty the WAS users list, optionally encrypted in a specific way.

of

ca

se

Ex

pe

rim

en

ta

user.appserver.was.admin.name ${user.appserver.selection2} Name of WAS == was && administrator. ${user.appserver.was.profile} != Liberty

user.appserver.was.serial

${user.appserver.selection2} Suffix that String of 10 == was && distinguishes decimal ${user.appserver.was.profile}the digits. != Liberty applications to be installed from other installations of Worklight Server.


57


When necessary

Description

Allowed values


user.appserver.was85liberty.serverInstance_ ${user.appserver.selection2} Name of WAS == was && Liberty Server ${user.appserver.was.profile}into which to install the == Liberty applications. user.appserver.tomcat.installdir ${user.appserver.selection2} Apache == tomcat Tomcat installation directory. user.database.selection2

Always

The value none means that the installer will not install the Application Center. If this value is used, both user.appserver.selection2 and user.database.selection2 must take the value none.

Always

true means a true, false preinstalled database management system, false means Apache Derby to install.

user.database.derby.datadir

${user.database.selection2} == derby

The directory in which to create or assume the Derby databases.

${user.database.selection2} == db2

The host name or IP address of the DB2 database server.

of se

ca In IBM Worklight V6.0.0

derby, db2, mysql, oracle, none

user.database.preinstalled

ta en rim pe Ex 58

Type of database management system used to store the databases.

An absolute directory name.

user.database.db2.host

An absolute directory name.

Table 6. Parameters available for silent installation (continued) Description

user.database.db2.port


The port A number where the between 1 DB2 database and 65535. server listens for JDBC connections. Usually 50000.


When necessary

user.database.db2.driver


user.database.db2.appcenter.password ${user.database.selection2} == db2

The password Non-empty used to access password. the DB2 database for Application Center, optionally encrypted in a specific way.

user.database.db2.appcenter.dbname ${user.database.selection2} == db2

The name of the DB2 database for Application Center.

user.database.db2.appcenter.schema ${user.database.selection2} == db2

The name of the schema for Application Center in the DB2 database.

${user.database.selection2} == mysql

The host name or IP address of the MySQL database server.


The port where the MySQL database server listens for JDBC connections. Usually 3306.

ta

The user name used to access the DB2 database for Application Center.

of

user.database.mysql.host

se ca

In

The absolute An absolute file name of file name. db2jcc.jar or db2jcc4.jar.

user.database.db2.appcenter.username ${user.database.selection2} == db2

en rim pe Ex

Allowed values

Key

user.database.mysql.port

Non-empty.

Non-empty; a valid DB2 database name.

A number between 1 and 65535.


59

Table 6. Parameters available for silent installation (continued) Description

user.database.mysql.driver


The absolute file name of mysqlconnectorjava-5.*bin.jar.

An absolute file name.

user.database.mysql.appcenter.username ${user.database.selection2} == mysql

The user name used to access the MySQL database for Application Center.

Non-empty.

user.database.mysql.appcenter.password ${user.database.selection2} == mysql

The password used to access the MySQL database for Application Center, optionally encrypted in a specific way.

user.database.mysql.appcenter.dbname ${user.database.selection2} == mysql

The name of the MySQL database for Application Center.


When necessary

user.database.oracle.port

${user.database.selection2} The port == oracle, unless where the ${user.database.oracle.appcenter.jdbc.url} Oracle is specified database server listens for JDBC connections. Usually 1521.

A number between 1 and 65535.

${user.database.selection2} == oracle

An absolute file name.

ta

${user.database.selection2} The host == oracle, unless name or IP ${user.database.oracle.appcenter.jdbc.url} address of the is specified Oracle database server.

of

In

ca

se

user.database.oracle.driver


Non-empty, a valid MySQL database name.

user.database.oracle.host

en rim pe Ex 60

Allowed values

Key

The absolute file name of ojdbc6.jar.


When necessary

Description The user name used to access the Oracle database for Application Center.

A string consisting of 1 to 30 characters: ASCII digits, ASCII uppercase and lowercase letters, '_', '#', '$' are allowed.

user.database.oracle.appcenter.username.jdbc ${user.database.selection2} == oracle

The user name used to access the Oracle database for Application Center, in a syntax suitable for JDBC.

Same as ${user.database.oracle.appcenter.username} if it starts with an alphabetic character and does not contain lowercase characters, otherwise it must be ${user.database.oracle.appcenter.username} surrounded by double quotes.

user.database.oracle.appcenter.password ${user.database.selection2} == oracle

The password used to access the Oracle database for Application Center, optionally encrypted in a specific way.

The password must be a string consisting of 1 to 30 characters: ASCII digits, ASCII uppercase and lowercase letters, '_', '#', '$' are allowed.

In

of

ca

se

Ex

pe

rim

en

ta


user.database.oracle.appcenter.username ${user.database.selection2} == oracle

Allowed values

user.database.oracle.appcenter.dbname ${user.database.selection2} The name of == oracle, unless the Oracle ${user.database.oracle.appcenter.jdbc.url} database for is specified Application Center.

Non-empty, a valid Oracle database name.

user.database.oracle.appcenter.jdbc.url ${user.database.selection2} The JDBC == oracle, unless URL of the ${user.database.oracle.host}, Oracle ${user.database.oracle.port}, database for ${user.database.oracle.appcenter.dbname} Application are all specified Center.

A valid Oracle JDBC URL. Starts with "jdbc:oracle:".


61

Table 6. Parameters available for silent installation (continued) Allowed values

When necessary

Description

user.writable.data.user

Always

The operating system user that is allowed to run the installed server.

An operating system user name, or empty.

The operating system users group that is allowed to run the installed server.

An operating system users group name, or empty.


Key

user.writable.data.group2

Always

Completing the installation

When installation is complete, you must restart the web application server in certain cases. You must restart the web application server in the following circumstances:

v If you are using WebSphere Application Server with DB2 as database type. v If you are using WebSphere Application Server and have it launched without the Application Security active before you installed Application Center or Worklight Server.

If you are using WebSphere Application Server Network Deployment and chose an installation through the deployment manager: v You must restart the servers that were running during the installation and on which the Worklight Server applications have been installed. To restart these servers with the deployment manager console, select Applications > Application Types > WebSphere enterprise applications > IBM_Application_Center_Services > Target specific application status. v You do not have to restart the deployment manager or the node agents.

of

In

ca

se

Ex

pe

rim

en

ta

The IBM Worklight installer must activate the Application Security of WebSphere Application Server (if not active yet) to install Application Center. Then, for this activation to take place, you must restart the application server after the installation of Worklight Server completed. v If you are using WebSphere Application Server Liberty Profile or Apache Tomcat. v After you upgraded from a previous version of Worklight Server.

Note: The installation has installed only the IBM Application Center into the application server. A Worklight Console is not installed by default. To install a Worklight Console, you need to follow the steps in Chapter 8, “Deploying IBM Worklight projects,” on page 663.

Distribution structure of Worklight Server The Worklight Server files and tools are installed in and below the Worklight Server installation directory.

62


Table 7. Files in the Worklight Server installation directory Description

analytics.zip

Archive for the IBM WebSphere Analytics Platform. See “Installing and configuring the IBM WebSphere Analytics Platform” on page 174 for instructions to install and configure this platform.


Item

Description

worklight-jee-library.jar

The Worklight server library for production. See Chapter 8, “Deploying IBM Worklight projects,” on page 663 for instructions on deploying an IBM Worklight Project and this library to an Application Server. The deployment is typically performed by using Ant tasks, but instructions for manual deployment are also provided.

worklight-ant.jar

A set of Ant tasks that help you build and deploy projects, applications, and adapters to your Worklight Server. See Chapter 8, “Deploying IBM Worklight projects,” on page 663 for detailed documentation of the Ant tasks that are provided in this library.

configuration-samples

Sample Ant files for configuring a database for the Worklight Server and deploying an IBM Worklight Project to an Application Server. See “Sample configuration files” on page 706 for instructions on how to use these Ant projects.

databases

SQL scripts to be used for the manual creation of tables for Worklight Server, instead of using Ant tasks for the automatic configuration of the tables for Worklight Server. These scripts are described in “Creating and configuring the databases manually” on page 678.

encrypt.bat and encrypt.sh

Tools to encrypt confidential properties that are used to configure a Worklight Server, such as a database password or a certificate. This tool is documented in “Storing properties in encrypted format” on page 721.

report-templates

Report templates to configure BIRT Reports for your Application Server. They are documented in “Manually configuring BIRT Reports for your application server” on page 875.

of

Item

In

ca

se

Ex

pe

rim

en

ta

Table 8. Files and subdirectories in the WorklightServer subdirectory

Table 9. Files and subdirectories in the ApplicationCenter subdirectory Item ApplicationCenter/installer

Description IbmApplicationCenter.apk The Android version of the Application Center Mobile client.


63

Table 9. Files and subdirectories in the ApplicationCenter subdirectory (continued) Description

ApplicationCenter/installer/ IBMAppCenterBlackBerry6

Contains the BlackBerry project for the mobile Client for OS V6 and V7. You must compile this project to create the BlackBerry version of the mobile client.


Item

ApplicationCenter/installer/IBMAppCenter

ApplicationCenter/console/

Contains the Worklight Studio project for the mobile Client. You must compile this project to create the iOS version of the mobile client. appcenterconsole.war The WAR file for the Application Center console user interface web application. applicationcenter.war The WAR file for the Application Center REST services web application.

applicationcenter.ear The enterprise application archive (EAR) file to be deployed under IBM PureApplication System.

ApplicationCenter/databases

create-appcenter-derby.sql The SQL script to recreate the application center database on derby.

create-appcenter-db2.sql The SQL script to recreate the application center database on DB2.

of

In

ca

se

Ex

pe

rim

en

ta

create-appcenter-mysql.sql The SQL script to recreate the application center database on mySQL.

64


create-appcenter-oracle.sql The SQL script to recreate the application center database on Oracle.

Table 9. Files and subdirectories in the ApplicationCenter subdirectory (continued) Item

android-sdk The directory that contains the part of the Android SDK required by the Application Center console.


ApplicationCenter/tools

Description

applicationcenterdeploytool.jar The JAR file that contains the Ant task to deploy an application to the Application Center. acdeploytool.bat The startup script of the deployment tool for use on Microsoft Windows systems.

acdeploytool.sh The startup script of the deployment tool for use on UNIX systems.

build.xml Example of an Ant script to deploy applications to the Application Center. dbconvertertool.sh The startup script of the database converter tool for use on UNIX systems.

dbconvertertool.bat The startup script of the database converter tool for use on Microsoft Windows systems. dbconvertertool.jar The main library of the database converter tool.

In

The directory that contains all Java™ Archive (JAR) files that are required by the database converter tool.

json4j.jar The required JSon4J Java archive file.

of

ca

se

Ex

pe

rim

en

ta

lib

README.TXT Readme file that explains how to use the deployment tool.

Table 10. Files and subdirectories in the License subdirectory Item

Description

License-mfce

License for IBM Mobile Foundation Consumer Edition

License-mfee

License for IBM Mobile Foundation Enterprise Edition

License-wce

License for IBM Worklight Consumer Edition Chapter 4. Installing and configuring

65

Table 10. Files and subdirectories in the License subdirectory (continued) Description

License-wee

License for IBM Worklight Enterprise Edition


Item

Manually installing Application Center

In some cases, you might want to reconfigure Worklight Server so that it uses a different database or schema from the one that was specified during installation of Worklight Server. The way that you do this reconfiguration depends on the type of database and on the kind of application server, as explained in the following topics. Note: Whether you install Application Center with IBM Installation Manager as part of the Worklight Server installation or manually, one point to bear in mind is that "rolling updates" (see “Deciding between in-place upgrade and rolling upgrade” on page 194) of Application Center are not supported. That is, you cannot install two versions of Application Center (for example, V5.0.6 and V6.0.0) that operate on the same database.

Configuring the DB2 database manually for Application Center

You configure the DB2 database manually by creating the database, creating the database tables, and then configuring the relevant application server to use this database setup.

Procedure

1. Create the database. This step is described in “Creating the DB2 database for Application Center” on page 47. 2. Create the tables in the database. This step is described in “Setting up your DB2 database manually for Application Center.” 3. Perform the application server-specific setup as listed below.

About this task

Procedure 1. Create a system user, worklight, in a DB2 admin group such as DB2USERS, by using the appropriate commands for your operating system. Give it the password worklight. For more information, see the DB2 documentation and the documentation for your operating system.

of

ca In 66

You can set up your DB2 database for Application Center manually using the procedures in this section.

Set up your DB2 database for Application Center by creating the database schema.

se

Ex

pe

rim

en

ta

Setting up your DB2 database manually for Application Center:


Important: You can name your user differently, or set a different password, but ensure that you enter the appropriate user name and password correctly across the DB2 database setup. DB2 has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows. 2. Open a DB2 command line processor, with a user that has SYSADM or SYSCTRL permissions: v On Windows systems, click Start > IBM DB2 > Command Line Processor.

v On Linux or UNIX systems, navigate to ~/sqllib/bin and enter ./db2. 3. Enter the following database manager and SQL statements to create a database called APPCNTR:


CREATE DATABASE APPCNTR COLLATE USING SYSTEM PAGESIZE 32768 CONNECT TO APPCNTR GRANT CONNECT ON DATABASE TO USER worklight QUIT

4. Invoke DB2 with the following commands to create the APPCNTR tables, in a schema named APPSCHM (the name of the schema can be changed). This command can be run on an existing database that has a page size compatible with the one defined in step 3.

db2 CONNECT TO APPCNTR db2 SET CURRENT SCHEMA = ’APPSCHM’ db2 -vf /ApplicationCenter/databases/create-appcenter-db2.sql -t

Configuring Liberty Profile for DB2 manually for Application Center:

If you want to manually set up and configure your DB2 database for Application Center with WebSphere Application Server Liberty Profile, use the following procedure. About this task

Complete the DB2 Database Setup procedure before continuing.

Procedure 1. Add the DB2 JDBC driver JAR file (download it from DB2 JDBC Driver Versions, or fetch it from the directory DB2_INSTALL_DIR/java on the DB2 server) to $LIBERTY_HOME/wlp/usr/shared/resources/db2. If that directory does not exist, create it. 2. Configure the data source in the $LIBERTY_HOME/wlp/usr/servers/ worklightServer/server.xml file (worklightServer may be replaced in this path by the name of your server) as follows:

In

of

ca

se

Ex

pe

rim

en

ta

Where worklight after user= is the name of the system user with "CONNECT" access to the APPCNTR database that you have previously created, and worklight after password= is this user's password. If you have defined either a different user name, or a different password, or both, replace worklight accordingly. Also, replace db2server with the host name of your DB2 server (for example, localhost, if it is on the same machine). DB2 has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows.


67

Configuring WebSphere Application Server for DB2 manually for Application Center:


If you want to manually set up and configure your DB2 database for Application Center with WebSphere Application Server, use the following procedure. About this task


Procedure 1. Add the DB2 JDBC driver JAR file (download it from DB2 JDBC Driver Versions, or fetch it from the directory DB2_INSTALL_DIR/java on the DB2 server) to WAS_INSTALL_DIR/optionalLibraries/IBM/Worklight/5.0/db2. If that directory does not exist, create it. 2. Set up the JDBC provider: a. In the WebSphere Application Server console, click Resources > JDBC > JDBC Providers > New. b. Set the scope of the JDBC connection to Node level. c. Set Database type to DB2.

d. Set Provider type to DB2 Universal JDBC Driver Provider. e. Set Implementation Type to Connection pool data source. f. Set Name to DB2 Universal JDBC Driver Provider.

g. Click Next. h. Set the class path to the set of JAR files in the directory WAS_INSTALL_DIR/optionalLibraries/IBM/Worklight/5.0/db2, one per line. i. Do not set Native library path. j. Click Next.

3. Create a data source for the IBM Application Center database: a. Select the new JDBC provider and click Data Source. b. Click New to create a data source. c. Set the Data source name to Application Center Database. d. Set JNDI Name to jdbc/AppCenterDS.

of

In

ca

se

Ex

pe

rim

en

ta

k. Click Finish. l. The JDBC provider is created. m. Click Save.

e. Click Next. f. Create JAAS-J2C authentication data, specifying the DB2 user name and password for Container Connection. g. Select the component-managed authentication alias that you created. h. Click Next and Finish. i. Click Save. j. In Resources > JDBC > Data sources, select the new data source. k. Click WebSphere Application Server data source properties. l. Select the Non-transactional data source check box. m. Click OK.

n. Click Save.

68


o. Click Custom properties for the datasource, select property currentSchema, and set the value to the schema used to create the Application Center tables (APPSCHM in this example).


4. Test the data source connection by selecting Data Source and clicking Test Connection. Configuring Apache Tomcat for DB2 manually for Application Center:

If you want to manually set up and configure your DB2 database for Application Center with Apache Tomcat server, use the following procedure. About this task


Procedure 1. Add the DB2 JDBC driver JAR file (download it from DB2 JDBC Driver Versions, or fetch it from the directory DB2_INSTALL_DIR/java on the DB2 server) to $TOMCAT_HOME/lib. 2. Update the $TOMCAT_HOME/conf/context.xml file as follows: ... ...

Where worklight after user= is the name of the system user with "CONNECT" access to the APPCNTR database that you have previously created, and password after password= is this user's password. If you have defined either a different user name, or a different password, or both, replace these entries accordingly.

You configure the Apache Derby database manually by creating the database and database tables, and then configuring the relevant application server to use this database setup.

of

ca In

Configuring the Apache Derby database manually for Application Center

Procedure

se

Ex

pe

rim

en

ta

DB2 has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows.

1. Create the database and the tables within them. This step is described in “Setting up your Apache Derby database manually for Application Center” on page 70 2. Configure the application server to use this database setup. Go to one of the following topics: v “Configuring Liberty Profile for Derby manually for Application Center” on page 70 v “Configuring WebSphere Application Server for Derby manually for Application Center” on page 71


69

v “Configuring Apache Tomcat for Derby manually for Application Center” on page 72 Setting up your Apache Derby database manually for Application Center:


You can set up your Apache Derby database for Application Center manually using the procedures in this section. About this task

Set up your Apache Derby database for Application Center by creating the database schema. Procedure 1. In the location where you want the database to be created, run ij.bat on Windows systems or ij.sh on UNIX and Linux systems. The script displays ij version 10.4. Note: The ij program is part of Apache Derby. If you do not already have it installed, you can download it from Apache Derby: Downloads. 2. At the command prompt, enter the following commands:

connect ’jdbc:derby:APPCNTR;user=APPCENTER;create=true’; run ’/ApplicationCenter/databases/create-appcenter-derby.sql’; quit;

Configuring Liberty Profile for Derby manually for Application Center:

If you want to manually set up and configure your Apache Derby database for Application Center with WebSphere Application Server Liberty Profile, use the following procedure. About this task

Complete the Apache Derby database setup procedure before continuing.

of

ca In 70

Configure the data source in the $LIBERTY_HOME/usr/servers/worklightServer/ server.xml file (worklightServer may be replaced in this path by the name of your server) as follows:

se

Ex

pe

rim

en

ta

Procedure


Configuring WebSphere Application Server for Derby manually for Application Center:


If you want to manually set up and configure your Apache Derby database for Application Center with WebSphere Application Server, use the following procedure. About this task

Complete the Apache Derby database setup procedure before continuing.

Procedure 1. Add the Derby JAR file from WORKLIGHT_INSTALL_DIR/ApplicationCenter/tools/ lib/derby.jar to WAS_INSTALL_DIR/optionalLibraries/IBM/Worklight/6.0/ derby. If that directory does not exist, create it. 2. Set up the JDBC provider. a. In the WebSphere Application Server console, click Resources > JDBC > JDBC Providers. b. Set Scope to Node level. c. Click New. d. Set Database Type to User-defined.

e. Set class Implementation name to org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource40. f. Set Name to Worklight - Derby JDBC Provider.

g. Set Description to Derby JDBC provider for Worklight. h. Click Next. i. Set the Class path to WAS_INSTALL_DIR/optionalLibraries/IBM/Worklight/ 6.0/derby/derby.jar. j. Click Finish.

In

of

ca

se

Ex

pe

rim

en

ta

3. Create the data source for the IBM Worklight database. a. In the WebSphere Application Server console, click Resources > JDBC > Data sources. b. Set Scope to Node Level.

Click New. Set Data source Name to Application Center Database. Set JNDI name to jdbc/AppCenterDS. Click Next. Select the existing JDBC Provider that is named Worklight - Derby JDBC Provider. h. Click Next. i. Click Next.

c. d. e. f. g.

j. Click Finish. k. Click Save. l. In the table, click the Application Center Database datasource that you created. m. Under Additional Properties, click Custom properties. n. Click databaseName. o. Set Value to the path to the APPCNTR database that is created in “Setting up your Apache Derby database manually for Application Center” on page 70. Chapter 4. Installing and configuring

71

Click OK. Click Save. At the top of the page, click Application Center Database. Under Additional Properties, click WebSphere Application Server data source properties. t. Select Non-transactional datasource. u. Click OK. v. Click Save.


p. q. r. s.

w. In the table, select the Application Center Database datasource that you created. x. Click test connection (only if you are not on the console of a WAS Deployment Manager).

Configuring Apache Tomcat for Derby manually for Application Center:

If you want to manually set up and configure your Apache Derby database for Application Center with the Apache Tomcat server, use the following procedure. About this task

Complete the Apache Derby database setup procedure before continuing. Procedure

1. Add the Derby JAR file from WORKLIGHT_INSTALL_DIR/ApplicationCenter/tools/ lib/derby.jar to the directory $TOMCAT_HOME/lib. 2. Update the $TOMCAT_HOME/conf/context.xml file as follows:

Configuring the MySQL database manually for Application Center You configure the MySQL database manually by creating the database, creating the database tables, and then configuring the relevant application server to use this database setup.

of

Procedure

In

ca

se

Ex

pe

rim

en

ta

...

1. Create the database. This step is described in “Creating the MySQL database for Application Center” on page 48. 2. Create the tables in the database. This step is described in “Setting up your MySQL database manually for Application Center.” 3. Perform the application server-specific setup as listed below. Setting up your MySQL database manually for Application Center: You can set up your MySQL database for Application Center manually using the procedures in this section.

72


About this task Complete the following procedure to set up your MySQL database.


Procedure 1. Create the database schema. a. Run a MySQL command-line client with options -u root. b. Enter the following commands:

CREATE DATABASE APPCNTR CHARACTER SET utf8 COLLATE utf8_general_ci; GRANT ALL privileges ON APPCNTR.* TO ’worklight’@’Worklight-host’IDENTIFIED BY ’worklight’; GRANT ALL privileges ON APPCNTR.* TO ’worklight’@’localhost’ IDENTIFIED BY ’worklight’; Flush privileges; USE APPCNTR; SOURCE /ApplicationCenter/databases/create-appcenter-mysql.sql;

Where worklight before the @ sign is the user name, worklight after IDENTIFIED BY is its password, and Worklight-host is the name of the host on which IBM Worklight runs.

2. Add the following property to your MySQL option file: max_allowed_packet=256M For more information about option files, see the MySQL documentation at MySQL.

Configuring Liberty Profile for MySQL manually for Application Center:

If you want to manually set up and configure your MySQL database for Application Center with WebSphere Application Server Liberty Profile, use the following procedure. About this task

In

Procedure 1. Add the MySQL JDBC driver JAR file to $LIBERTY_HOME/wlp/usr/shared/ resources/mysql. If that directory does not exist, create it. 2. Configure the data source in the $LIBERTY_HOME/usr/servers/worklightServer/ server.xml file (worklightServer may be replaced in this path by the name of your server) as follows:

of

ca

se

Ex

pe

rim

en

ta

Complete the MySQL database setup procedure before continuing.

where worklight after user= is the user name, worklight after password= is this user's password, and mysqlserver is the host name of your MySQL server (for example, localhost, if it is on the same machine).


73

Configuring WebSphere Application Server for MySQL manually for Application Center:


If you want to manually set up and configure your MySQL database for Application Center with WebSphere Application Server, use the following procedure. About this task

Complete the MySQL database setup procedure before continuing.

Procedure 1. Set up the JDBC provider: a. In the WebSphere Application Server console, click Resources > JDBC > JDBC Providers. b. Create a JDBC provider named MySQL. c. Set Database type to User defined. d. Set Scope to Cell.

e. Set Implementation class to com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource. f. Set Database classpath to the location of the MySQL JDBC connector .jar file.

g. Save your changes. 2. Create a data source for the IBM Application Center database: a. Click New to create a data source. b. c. d. e.

Type any name (for example, Application Center Database). Set JNDI Name to jdbc/AppCenterDS. Use the existing JDBC Provider MySQL, defined in the previous step. Set Scope to New.

h. Save your changes. 3. Set the custom properties of the new data source. a. Select the new data source. b. Click Custom properties. c. Set the following properties:

of

In

ca

se

Ex

pe

rim

en

ta

f. On the Configuration tab, select the Non-transactional data source check box. New. g. Click Next a number of times, leaving all other settings as defaults.

portNumber = 3306 relaxAutoCommit=true databaseName = APPCNTR serverName = the host name of the MySQL server user = the user name of the MySQL server password = the password associated with the user name

4. Set the WebSphere Application Server custom properties of the new data source. a. In Resources > JDBC > Data sources, select the new data source. b. Click WebSphere Application Server data source properties. c. Select the Non-transactional data source check box. d. Click OK. e. Click Save.

74


Configuring Apache Tomcat for MySQL manually for Application Center: If you want to manually set up and configure your MySQL database for Application Center with the Apache Tomcat server, use the following procedure.


About this task Complete the MySQL database setup procedure before continuing.

Procedure 1. Add the MySQL Connector/J JAR file to the $TOMCAT_HOME/lib directory.

2. Update the $TOMCAT_HOME/conf/context.xml file as follows: Context> ... ...

Configuring the Oracle database manually for Application Center You configure the Oracle database manually by creating the database, creating the database tables, and then configuring the relevant application server to use this database setup.

Procedure

Setting up your Oracle database manually for Application Center:

You can set up your Oracle database for Application Center manually using the procedures in this section.

of

ca In

3. Perform the application server-specific setup as listed below.

About this task

se

Ex

pe

rim

en

ta

1. Create the database. This step is described in “Creating the Oracle database for Application Center” on page 49. 2. Create the tables in the database. This step is described in “Setting up your Oracle database manually for Application Center.”

Complete the following procedure to set up your Oracle database. Procedure 1. Ensure that you have at least one Oracle database. In many Oracle installations, the default database has the SID (name) ORCL. For best results, the character set of the database should be set to Unicode (AL32UTF8). 2. Create the user APPCENTER, either by using Oracle Database Control, or by using the Oracle SQLPlus command-line interpreter. Create the user for the IBM Worklight database/schema, by using Oracle Database Control: Chapter 4. Installing and configuring

75

a. b. c. d.

Connect as SYSDBA. Go to the Users page. Click Server, then Users in the Security section. Create a user named APPCENTER with the following attributes:


Profile: DEFAULT Authentication: password Default tablespace: USERS Temporary tablespace: TEMP Status: UNLOCK Add role: CONNECT Add role: RESOURCE Add system privilege: CREATE VIEW Add system privilege: UNLIMITED TABLESPACE

To create the user by using Oracle SQLPlus, enter the following commands: CONNECT system/@ORCL CREATE USER APPCENTER IDENTIFIED BY password; GRANT CONNECT, RESOURCE, CREATE VIEW TO APPCENTER; DISCONNECT;

3. Create the database tables for the IBM Worklight database and IBM Worklight reports database: a. Using the Oracle SQLPlus command-line interpreter, create the required tables for the IBM Application Center database by running the create-appcenter-oracle.sql file:

CONNECT APPCENTER/@ORCL @/ApplicationCenter/databases/create-appcenter-oracle.sql DISCONNECT;

4. Download and configure the Oracle JDBC driver: a. Download the JDBC driver from the Oracle website at Oracle: JDBC, SQLJ, Oracle JPublisher and Universal Connection Pool (UCP): b. Ensure that the Oracle JDBC driver is in the system path. The driver file is ojdbc6.jar.

If you want to manually set up and configure your Oracle database for Application Center with WebSphere Application Server Liberty Profile, use the following procedure. About this task

Complete the Oracle database setup procedure before continuing.

Procedure 1. Add the Oracle JDBC Driver JAR file to $LIBERTY_HOME/wlp/usr/shared/ resources/oracle. If that directory does not exist, create it. 2. If you are using JNDI, configure the data sources in the $LIBERTY_HOME/wlp/usr/ servers/worklightServer/server.xml file (worklightServer may be replaced in this path by the name of your server) as shown in the following JNDI code example:

of

In

ca

se

Ex

pe

rim

en

ta

Configuring Liberty Profile for Oracle manually for Application Center:

76



where APPCENTER after user= is the user name, APPCENTER_password after password= is this user's password, and oserver is the host name of your Oracle server (for example, localhost, if it is on the same machine).

Configuring WebSphere Application Server for Oracle manually for Application Center:

If you want to manually set up and configure your Oracle database for Application Center with WebSphere Application Server, use the following procedure. About this task


Procedure 1. Set up the JDBC provider: a. In the WebSphere Application Server console, click Resources > JDBC > JDBC Providers > New. b. Set the scope of the JDBC connection to Node. c. Complete the JDBC Provider fields as indicated in the following table:

Table 11. JDBC Provider field values Field

Value

Database type

Oracle

Provider type

Oracle JDBC Driver

Implementation type

Connection pool data source

Name

Oracle JDBC Driver

d. Click Next.

In

The JDBC provider is created. 2. Create a data source for the IBM Worklight database: a. Click Resources > JDBC > Data sources > New. b. Set Data source name to Oracle JDBC Driver DataSource. c. Set JNDI name to jdbc/AppCenterDS. d. Click Next. e. Click Select an existing JDBC provider and select Oracle JDBC driver from the list. f. Click Next. g. Set the URL value to jdbc:oracle:thin:@oserver:1521/ORCL, where oserver is the host name of your Oracle server (for example, localhost, if it is on the same machine). h. Click Next twice.

of

ca

se

Ex

pe

rim

en

ta

e. Set the class path for the ojdbc6.jar file, for example /home/Oracle-jar/ ojdbc6.jar. f. Click Next.


77


i. Click Resources > JDBC > Data sources > Oracle JDBC Driver DataSource > Custom properties. j. Set oracleLogPackageName to oracle.jdbc.driver. k. Set user = APPCENTER. l. Set password = APPCENTER_password. m. Click OK and save the changes. n. In Resources > JDBC > Data sources, select the new data source. o. Click WebSphere Application Server data source properties. p. Select the Non-transactional data source check box. q. Click OK. r. Click Save.

Configuring Apache Tomcat for Oracle manually for Application Center:

If you want to manually set up and configure your Oracle database for Application Center with the Apache Tomcat server, use the following procedure. About this task


Procedure 1. Add the Oracle JDBC driver JAR file to the directory $TOMCAT_HOME/lib. 2. Update the $TOMCAT_HOME/conf/context.xml file as follows: ... ...

Deploying the Application Center WAR files and configuring the application server manually

of

In

ca

se

Ex

pe

rim

en

ta

Where APPCENTER after username= is the name of the system user with "CONNECT" access to the APPCNTR database that you have previously created, and APPCENTER_password after password= is this user's password. If you have defined either a different user name, or a different password, or both, replace these values accordingly.

The procedure to manually deploy the Application Center WAR files manually to an application server depends on the type of application server being configured, as detailed here. These manual instructions assume that you are familiar with your application server. Note: Using the Worklight Server installer to install Application Center is more reliable than installing manually, and should be used whenever possible. If you prefer to use the manual process, follow these steps to configure your application server for Application Center. You must deploy the

78


appcenterconsole.war and applicationcenter.war files to your Application Center. The files are located in /ApplicationCenter/console. Configuring WebSphere Application Server Liberty Profile for Application Center manually:


To configure WebSphere Application Server Liberty Profile for Application Center manually, you must modify the server.xml file. About this task

In addition to modifications for the databases that are described in “Manually installing Application Center” on page 66, you must make the following modifications to the server.xml file.

Note: In the following procedure, when the example uses worklight.war, it should be the name of your Worklight project, for example, myProject.war. Procedure

1. Ensure that the element contains at least the following elements: ssl-1.0 servlet-3.0 jdbc-4.0 appSecurity-1.0

2. Add the following declarations for the Application Center:

In

of

ca

se

Ex

pe

rim

en

ta


79

What to do next For more steps to configure the IBM Application Center, see “Configuring WebSphere Application Server Liberty Profile” on page 120.


Configuring WebSphere Application Server for Application Center manually: To configure WebSphere Application Server for Application Center manually, you must configure variables, custom properties, and class loader policies. Before you begin

These instructions assume that you already have a stand-alone profile created with an application server named Worklight and that the server is using the default ports.

Procedure 1. Log on to the WebSphere Application Server administration console for your IBM Worklight server. The address is of the form http://server.com:9060/ibm/ console, where server is the name of the server. 2. Enable application security. a. Click Security > Global Security. b. Ensure that the Enable administrative security check box is selected. Application security can only be enabled if administrative security is enabled. c. Ensure that the Enable application security check box is selected. d. Click OK. e. Save the changes.

of

In

ca

se

Ex

pe

rim

en

ta

For more details, see http://pic.dhe.ibm.com/infocenter/wasinfo/v7r0/topic/ com.ibm.websphere.base.doc/info/aes/ae/tsec_csec2.html. 3. Create the Application Center JDBC data source and provider. See the instructions in the appropriate subsection in “Manually installing Application Center” on page 66. 4. Install the Application Center console WAR file.

80


a. Depending on your version of WebSphere Application Server, click one of the following options: v Applications > New > New Enterprise Application v Applications > New Application > New Enterprise Application b. Navigate to the IBM Worklight Server installation directory WL_INSTALL_DIR/ApplicationCenter/console. c. Select appcenterconsole.war, and then click Next. d. On the How do you want to install the application? page, select Detailed, and then click Next. e. On the Application Security Warnings page, click Continue.

f. Click Next until you reach the Map context roots for web modulespage. g. In the Context Root field, type /appcenterconsole. h. Click Next. i. Click Finish. 5. Configure the class loader policies and then start the application:


a. Click the Manage Applications link, or click Applications > WebSphere Enterprise Applications. b. From the list of applications, click appcenterconsole_war. c. In the “Detail Properties” section, click the Class loading and update detection link. d. In the “Class loader order” pane, click Classes loaded with local class loader first (parent last).

Click OK. In the Modules section, click Manage Modules. From the list of modules, click the ApplicationCenterConsole module. In the “Class loader order” pane, click Classes loaded with local class loader first (parent last). i. Click OK twice. j. Click Save. k. Select the Select check box for appcenterconsole_war and click Start. 6. Repeat step 4, selecting applicationcenter.war in sub-step c, and using a Context Root of /applicationcenter in sub-step g. 7. Repeat step 5, selecting applicationcenter.war from the list of applications in sub-step b. 8. Configure the server to use the single class loader policy: a. Click Servers > Server Types > Application Servers > Worklight e. f. g. h.

b. Change the class loader policy from Multiple to Single. c. Change the class loading mode to Classes loaded with local class loader first (parent last). 9. Configure a JNDI environment entry to indicate the directory with binaries of the aapt program, from the Android SDK's platform-tools package. For a standalone server: a. Click Applications > WebSphere enterprise applications.

In

of

ca

se

Ex

pe

rim

en

ta

b. From the list of applications, select applicationcenter_war. c. In the "Web Module Properties" section, select Environment entries for Web modules. d. Assign to the variable android.aapt.dir the value WL_INSTALL_DIR/ ApplicationCenter/tools/android-sdk where WL_INSTALL_DIR is the Worklight Server installation directory.

For WebSphere Application Server Network Deployment, you must: a. Copy the WL_INSTALL_DIR/ApplicationCenter/tools/android-sdk directory to a location in the config directory of the deployment manager's profile. This will be propagated to the servers through the file synchronization service; for example, WAS_INSTALL_DIR/profiles/Dmgr01/config/cells/cellname/clusters/cluster-name/android-sdk. b. Configure the environment entry android.aapt.dir with value ${USER_INSTALL_ROOT}/config/cells/cell-name/clusters/cluster-name/ android-sdk. c. Click System administration > Nodes, select the nodes, and click Full Synchronize.


81

Results


You can now access the Application Center at http://:/ appcenterconsole, where server is the host name of your server and port is the port number (default 9080). What to do next

For additional steps to configure the Application Center, see “Configuring WebSphere Application Server full profile” on page 119. Configuring Apache Tomcat for Application Center manually:

To configure Apache Tomcat for Application Center manually, you must copy JAR and WAR files to Tomcat, add database drivers, edit the server.xml file, and then start Tomcat.

Procedure 1. Add the database drivers to the Tomcat lib directory. See the instructions for the appropriate DBMS in “Manually installing Application Center” on page 66. 2. Edit TOMCAT_HOME/conf/server.xml. a. Uncomment the following element, which is initially commented out: . b. Declare the Application Center console and services applications and a user registry:

of

In

ca

se

Ex

pe

rim

en

ta

82



where you fill in the element as described in one of the sections: v “Configuring Apache Tomcat for DB2 manually for Application Center” on page 69 v “Configuring Apache Tomcat for Derby manually for Application Center” on page 72

v “Configuring Apache Tomcat for MySQL manually for Application Center” on page 75 v “Configuring Apache Tomcat for Oracle manually for Application Center” on page 78

3. Copy the Application Center WAR files to Tomcat. v On UNIX and Linux systems: cp WL_INSTALL_DIR/ApplicationCenter/ console/*.war TOMCAT_HOME/webapps v On Windows systems:

copy /B WL_INSTALL_DIR\ApplicationCenter\console\appcenterconsole.war TOMCAT_HOME\webapps\appcenterconsole.war copy /B WL_INSTALL_DIR\ApplicationCenter\console\applicationcenter.war TOMCAT_HOME\webapps\applicationcenter.war

4. Start Tomcat.

For additional steps to configure the Application Center, see “Configuring Apache Tomcat” on page 121.

en

ta

What to do next

Consider your backup and recovery policy, optimize your Worklight Server configuration, and apply access restrictions and security options.

of

Ex

pe

rim

Configuring Worklight Server

In

ca

se

Backup and recovery You can back up the customization and the content (adapters and applications) outside the IBM Worklight instance, for example in a source control system. It is advisable to back up the IBM Worklight database as-is. When Reports are enabled, the database can become quite large. Consider the benefits of backing them up separately. Report tables can be configured to be stored on a different database instance.


83

Optimization and tuning of Worklight Server Optimize the Worklight Server configuration by tuning the allocation of JVM memory, HTTP connections, back-end connections, and internal settings.


For best results, install a Worklight Server on a 64-bit server.

JVM memory allocation

The Java instance of the application server allocates memory. Consider the following guidelines: v Set the JVM to have at least 2 GB memory. v In a production environment, set the minimum heap size and maximum heap size to the same value to avoid heap expansion and contraction. v Set the required memory size of the application server: – Liberty: set JAVA_ARGS in /Worklight/server/wlp/bin/ securityUtility. – WebSphere Application Server: Log in to the admin console. Go to Servers > Server types > WebSphere application servers: choose each server and set Java memory settings under Java Process definition > JVM arguments. – Apache Tomcat: find the catalina script and set JAVA_OPTS to inject memory.

For information about how to calculate memory size, see the following documents: v Scalability and Hardware Sizing (PDF) v Hardware Calculator (XLS)

Tuning HTTP connections

You tune HTTP connections by configuring threading and execution settings for the application server.

84

Apply the following settings: v Liberty: See the executor section: http://pic.dhe.ibm.com/infocenter/wasinfo/ v8r5/index.jsp?topic=%2Fcom.ibm.websphere.wlp.nd.multiplatform.doc %2Fautodita%2Frwlp_metatype_4ic.html.

v WebSphere Application Server: Log in to the admin console. Go to Servers > Server types > WebSphere application servers > server_name > Web container. By default, the maximum number of threads is 50. v Apache Tomcat: See http://tomcat.apache.org/tomcat-7.0-doc/config/http.html. By default, the maximum number of threads is 200.

of

In

ca

se

Ex

pe

rim

en

ta

Each incoming request requires a thread for the duration of the request. If more simultaneous requests are received than can be handled by the currently available request-processing threads, more threads are created up to the configured maximum.


Bear in mind the following points when you configure HTTP threads: v If, for example, the longest call takes 500 milliseconds and you configure a maximum of 50 threads, you can handle approximately 100 requests per second. v If your environment includes a back-end system that runs slowly, increase the number of default threads. In addition, increase the number of back-end connection threads (See “Tuning back-end connections” on page 85).

Tuning back-end connections Consider the following factors when you set the maxConcurrentConnectionsPerNode parameter in the connectivity element of the adapter.xml file:


v If the back-end system imposes no limitation on the number of incoming connections, set the number of connection threads per adapter to the number of HTTP threads in the application server. A more refined guideline would be to take account of the percentage of requests to each back-end system. v If the back-end system imposes a limitation on the number of incoming connection threads, do not exceed BACKEND_MAX_CONNECTIONS/ NUM_OF_CLUSTER_NODES connection threads, where BACKEND_MAX_CONNECTIONS is the maximum number of incoming connections that are defined in the back-end server, and NUM_OF_CLUSTER_NODES is the number IBM Worklight server nodes in the cluster.

Worklight Server internal configuration

Consider the following factors: v A session is an object that is stored in server memory for each connecting device. Among other things, it stores authentication information. The number of active sessions is the difference between the number of opened sessions and the number of sessions that are timing out because of inactivity. The serverSessionTimeout property configures the session timeout and affects the server memory consumption. The default session timeout is 10 minutes. v The mobile client "heartbeat" property causes the mobile client to ping the server while the app is in the foreground. This feature prevents the server session from timing out.

In

The following worklight.properties parameters affect the intervals of background tasks that perform various actions on the database and file system:

cluster.data.synchronization.taskFrequencyInSeconds Application and adapter files are read from the file system and are stored in the database that enables the synchronization of the deployment data between all cluster nodes. The parameter controls the synchronization interval of the file system with the database content. Every 2 seconds (the default interval), each Worklight Server node checks the database to see whether new adapters or applications are deployed in another Worklight server node. If new adapters or applications are found, they are deployed to the local file system. If you increase the interval, the database is queried less frequently but the Worklight Server nodes synchronize less frequently with the latest adapters and applications.

of

ca

se

Ex

pe

rim

en

ta

v When a mobile app runs in the background, it no longer interacts with the server or sends a “heartbeat”. The server session drops after the specified server session timeout period. v For example, suppose every minute 1,000 users start a session against the server. Even if they exit the application after 3 minutes, their sessions remain active on the server for 10 minutes, leaving 10 x 1,000 = 10,000 active sessions.

deployables.cleanup.taskFrequencyInSeconds Deletes unused deployables from the file system. The default frequency is 24 hours.


85


sso.cleanup.taskFrequencyInSeconds The SSO (single sign-on) mechanism stores session data in a database table. This parameter configures the interval for the SSO cleanup task that checks whether there are inactive accounts in the SSO table. If inactive accounts are found, they are deleted. The default frequency is 5 seconds. Accounts are considered inactive if they remain idle for longer than serverSessionTimeout.

Optimization and tuning of Worklight Server project databases General information about ways that you can improve the performance of the project databases or schemas that support Worklight Server is provided in this topic.

The following sections provide general information about database tuning, and techniques you can use to optimize your database performance for IBM Worklight. In the following sections, the examples that are provided are for the IBM DB2 database. If you use MySQL or Oracle, consult that vendor's documentation for the corresponding procedures.

Database disks

You can find some overview information about the Worklight Server project databases in the Database usage and size section of the Scalability and Hardware Sizing PDF document. Its accompanying Excel spreadsheet Hardware Calculator can aid you in computing the hardware configuration that is best suited to your planned server environment.

Database compression

For example, in tests that were performed on IBM DB2, adding COMPRESS YESto the SQL that creates the APP_ACTIVITY_REPORT table decreased the size of that table on the disk by a factor of 3 and decreased its I/O time by a factor of 2.

of

ca In 86

For example, whether you use DB2, MySQL, or Oracle, you can almost always speed up database performance by configuring the database to use separate disks to store its database logs, index, and data. This allows faster access to your data with every transaction because there is no contention resulting from the same disk attempting to write to its log files or access its index at the same time it processes the data transaction.

Using your database vendor's compression feature can decrease the size of the database and decrease I/O time.

se

Ex

pe

rim

en

ta

When you are computing your hardware needs, it is a good idea to consider servers that offer multiple disks because the correct use of them when you set up your Worklight Server project databases can greatly improve their performance.


CPU time might increase as a result of this compression, but it was not observed in the tests on the APP_ACTIVITY_REPORT table, possibly because most of the activity was INSERTs and the aggregation task was not monitored deeply.

On DB2, use the INLINE_LENGTH


If your database is DB2, consider using the INLINE_LENGTH option when creating the tables used for SSO information, and for other tables that contain data that is stored as large objects (LOBs), but which in actuality are not very large at all, usually a few kilobytes in size. By constraining the size of these LOBs, the performance of LOB data access can be improved by placing the LOB data within the formatted rows on data pages instead of in the LOB storage object. For more information about this technique, see Inline LOBs improve performance.

Database table partitions

A partition is a division of a logical database table into distinct independent parts. Using table partitions to map each of the table partitions to a different tablespace can enable performance improvements and facilitate purging accumulated data. This suggestion is primarily relevant only to the APP_ACTIVITY_REPORT table that holds the majority of the row data. Note: Partitioned tables are not the same thing as a partitioned database (DPF) environment, which is not suggested for use with IBM Worklight.

To show how database partitions can be used, consider this example from DB2:

v A partition is defined on the ACTIVITY_TIMESTAMP column in the APP_ACTIVITY_REPORT table. v Each partition contains one day's data.

v The number of partitions is the number of days of data you want to save. v Each partition is created in a different table space.

In

CREATE CREATE CREATE CREATE CREATE CREATE CREATE

TABLESPACE TABLESPACE TABLESPACE TABLESPACE TABLESPACE TABLESPACE TABLESPACE

app_act_rep_1; app_act_rep_2; app_act_rep_3; app_act_rep_4; app_act_rep_5; app_act_rep_6; app_act_rep_7;

CREATE TABLE "APP_ACTIVITY_REPORT" ( "ID" BIGINT NOT NULL , "ACTIVITY" CLOB(1048576) LOGGED NOT COMPACT , "ACTIVITY_TIMESTAMP" TIMESTAMP , "ADAPTER" VARCHAR(254) , "DEVICE_ID" VARCHAR(254) , "DEVICE_MODEL" VARCHAR(254) , "DEVICE_OS" VARCHAR(254) , "ENVIRONMENT" VARCHAR(254) , "GADGET_NAME" VARCHAR(254) , "GADGET_VERSION" VARCHAR(254) , "IP_ADDRESS" VARCHAR(254) , "PROC" VARCHAR(254) , "SESSION_ID" VARCHAR(254) , "SOURCE" VARCHAR(254) , "USER_AGENT" VARCHAR(254) ) IN app_act_rep_1, app_act_rep_2, app_act_rep_3, app_act_rep_4, app_act_rep_5, app_act_rep_6, app_act_rep_7 PARTITION BY RANGE (ACTIVITY_TIMESTAMP)

of

ca

se

Ex

pe

rim

en

ta

v Thus in the SQL example that follows, you create seven partitions in DB2:


87

(STARTING FROM (’2013-02-25-00.00.00.000000’) ENDING AT (’2013-03-04-00.00.00.000000’) EXCLUSIVE EVERY (1 DAY) );


Database purge Now that this high-volume data is allocated to separate tablespaces, the task of periodically purging the data is simplified. This suggestion is also primarily relevant only to the APP_ACTIVITY_REPORT table that holds the majority of the row data. The process that is used in this DB2 example is as follows: v Aggregate data either with an IBM Worklight process or with a client external process. v When the data is no longer needed (the aggregation task should successfully process the data), it can be deleted. v The most effective way to delete the data is to delete the partition. In DB2, this data purge can be done by detaching the partition to a temp table, then truncating that temp table and attaching a new day to the partition. The process can be implemented as a scheduled stored procedure process in the database, as in the following example: ALTER TABLE "APP_ACTIVITY_REPORT" DETACH PARTITION part0 INTO temptable; TRUNCATE TABLE temptable;

ALTER TABLE "APP_ACTIVITY_REPORT" ATTACH PARTITION part0 STARTING FROM (’2013-02-25-00.00.00.000000’) ENDING AT (’2013-03-26-00.00.00.000000’) EXCLUSIVE FROM temptable;

Security configuration

Configure the security of the Worklight Server as detailed here.

Database and certificate security passwords

Configuration of a Worklight Server typically includes the following credentials: v User name and password to the IBM Worklight database v User name and password to other custom databases v User name and password to certificates that enable the stamping of apps

of

In

ca

se

Ex

pe

rim

en

ta

When you configure a Worklight Server, you must typically configure database and certificate passwords for security.

All credentials are stored in the in JNDI properties of the application server. Defaults can be stored in the worklight.properties file. See “Configuration of IBM Worklight applications on the server” on page 714 for information about individual properties. You can encrypt any or all of these passwords. For more information, see “Storing properties in encrypted format” on page 721.

Apache Tomcat security options An optimal Apache Tomcat security balances ease of use and access with strengthening of security and hardening of access.

88


You must harden the Tomcat Server according to your company policy. Information on how to harden Apache Tomcat is available on the Internet. All other out-of-the-box services provided by Apache Tomcat are unnecessary and can be removed.

WebSphere Application Server security options


The WebSphere Application Server provides Java Platform, Enterprise Edition container and server security by supporting a variety of user registries and a common mechanism to secure EAR/WAR/services.

IBM Worklight provides an extensible authentication model as part of its core function. Follow the instructions to use WebSphere Application Server security to protect the application and adapters hosted on the IBM Worklight runtime environment.

of

In

ca

se

Ex

pe

rim

en

ta

There are three major phases to show how a device uses a typical IBM Worklight app running on WebSphere Application Server shown in the following diagram.


89


ta en rim In

ca

se

of

pe Ex

Figure 1. Phases in securing an IBM Worklight app

When the user first accesses the app, the app issues an authentication challenge, requiring the user to enter their credentials. If authentication is successful, an LTPA token is obtained. This token is used in subsequent calls.

90


The LTPA token can also be transmitted to back-end WebSphere applications or services that are in the same security domain as IBM Worklight Server.


You can secure IBM Worklight in a typical WebSphere Application Server runtime environment in either of two ways: v Option 1: Securing WebSphere Application Server using application security and securing the IBM Worklight WAR file. v Option 2: Securing WebSphere Application Server using application security but not securing the IBM Worklight WAR file. Each option has advantages and disadvantages. Both options use underlying WebSphere Application Security configuration, but in different ways. Choose an option based on your specific requirements. Table 12. WebSphere Application Security Options

BENEFITS

Option 1

Option 2

Uses the traditional WebSphere Application Server authentication and trust model.

Uses the traditional WebSphere Application Server authentication and trust model without the impact of modifying the IBM Worklight Project WAR.

The container enforces all security, so it can use existing third-party SSO products to secure the Java Platform, Enterprise Edition container.

The container enforces all security, so it can use existing third-party SSO products to secure the Java Platform, Enterprise Edition container.

The layered authentication of device, application, application instance, and user functions as intended.

of

USAGE

In

ca

se

Ex

pe

rim

en

ta

Flexibility in configuring specific security settings that are specific to the IBM Worklight runtime environment without being hindered by the underlying container security.

Suitable for scenarios where the devices can be trusted and access for rogue applications is restricted.

Suitable for scenarios where the devices or the apps on the devices cannot be trusted. The multi-step authenticity checking built into IBM Worklight ensures denial of service to devices subjected to unauthorized modifications, rogue applications, and unauthorized users.


91

WebSphere Application Server security option 1 procedure: To secure WebSphere Application Server, you can choose between two different configurations. The security option 1 procedure secures the IBM Worklight WAR file.


About this task Complete the following steps to perform the WebSphere Application Server security option 1 procedure and secure the IBM Worklight WAR file.

Procedure 1. Ensure that IBM Worklight is correctly installed on a WebSphere Application Server instance. The IBM Worklight instance contains all the necessary libraries to support WebSphere Application Server security. 2. When installation of the Worklight Server application on WebSphere Application Server is complete, open your WebSphere Application Server integrated solutions console. 3. Ensure that application security is enabled and configured to your enterprise user. The IBM Worklight project uses the existing login page and login error page and preconfigured realms as part of the Worklight Server installation on WebSphere Application Server. The Worklight Server application is secured by default using a generic role and using a login form and error page. The following code snippet shows the web.xml file of the Worklight Server WAR that is generated for WebSphere Application Server.

of

WebSphere Application Server security option 2 procedure:

In

ca

se

Ex

pe

rim

en

ta

Protected URI Protection area for what you want to protect, of course. /* GET POST All Authenticated users for our protected stuff. Role 3 NONE All Authenticated Users Role. Role 3

To secure WebSphere Application Server, you can choose between two different configurations. The security option 2 procedure disables the security at the Worklight Server WAR file level and authenticates users within the Worklight Server runtime environment. About this task Complete the following steps to perform the WebSphere Application Server security option 2 procedure, which disables the security at the Worklight Server

92


WAR file level and authenticates users within the Worklight Server runtime environment.


Procedure 1. Complete the same steps as for the Security Option 1, but do not secure the WAR file. To secure WebSphere Application Server and secure the Worklight Server application: 2. Do not enable security-constraint on the web.xml file. 3. Configure applicationDescriptor.xml. 4. Complete the remaining steps.

Running IBM Worklight in WebSphere Application Server with Java 2 security enabled

You can run IBM Worklight in WebSphere Application Server with Java 2 security enabled.

About this task

To run IBM Worklight in WebSphere Application Server with Java 2 security enabled, complete the following procedure to modify the app.policy file and then restart WebSphere Application Server for the modification to take effect.

In

1. Install IBM Worklight Server on a WebSphere Application Server instance. The IBM Worklight instance contains all the necessary libraries to support WebSphere Application Server security. 2. Enable Java 2 security in WebSphere Application Server. a. In the WebSphere Application Server console, click Security > Global security b. Select the Use Java 2 security to restrict application access to local resources check box. 3. Modify the app.policy file, /profiles// config/cells//node//app.policy. The app.policy file is a default policy file that is shared by all of the WebSphere Application Server enterprise applications. For more information, see "app.policy file permissions" in the WebSphere Application Server documentation. In order to run IBM Worklight in WebSphere Application Server with Java 2 security enabled, add the following content into the app.policy file.

of

ca

se

Ex

pe

rim

en

ta

Procedure

grant codeBase "file:${was.install.root}/worklight-jee-library-xxx.jar"{ permission java.security.AllPermission; };

// The war file is your WL server war. grant codeBase "file:worklight.war"{ //permission java.security.AllPermission; //You can use all permission for simplicity, however, it might // cause security problems. permission java.lang.RuntimePermission "*"; permission java.io.FilePermission "${was.install.root}${/}-", "read,write,delete"; permission java.io.FilePermission "C:/Windows/TEMP/${/}-", "read,write,delete";// In Linux need to set TEMP folder of Linux. permission java.util.PropertyPermission "*", "read, write"; permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; permission com.ibm.tools.attach.AttachPermission "createAttachProvider"; Chapter 4. Installing and configuring

93

permission permission permission permission };

com.ibm.tools.attach.AttachPermission "attachVirtualMachine"; com.sun.tools.attach.AttachPermission "createAttachProvider"; com.sun.tools.attach.AttachPermission "attachVirtualMachine"; java.net.SocketPermission "*", "accept,resolve";


4. Restart WebSphere Application Server for the modification of the app.policy file to take effect.

Transmitting IBM Worklight data on the BlackBerry Enterprise Server MDS channel If you install IBM Worklight in an environment that includes a BlackBerry Enterprise Server, you can use the BlackBerry MDS channel to transmit IBM Worklight data.

About this task

pe

rim

en

ta

Figure 2 shows an environment in which apps that are installed on BlackBerry devices transmit data by using the BlackBerry MDS channel. When you install IBM Worklight in environments such as these, you can configure IBM Worklight data to use the same channel.

of

In

ca

se

Ex

Figure 2. IBM Worklight with BlackBerry Enterprise Server

94


Procedure On the BlackBerry Enterprise Server, configure an MDS connection service to the IBM Worklight Server or to its intermediary proxy server. For information about how to configure an MDS connection service, see the BlackBerry Enterprise Server documentation.

Protecting your mobile application traffic by using IBM WebSphere DataPower as a security gateway You can use IBM WebSphere DataPower® in the DMZ of your enterprise to protect Worklight mobile application traffic.


Before you begin

Ensure that Worklight Studio is installed, and establish your stand-alone server environment on Liberty or WebSphere Application Server before you start this procedure.

About this task

Protecting mobile application traffic that comes into your network from customer and employee devices involves taking precautions to prevent the data from being altered, authenticating users, and allowing only authorized users to access applications. You can use the security gateway features of IBM WebSphere DataPower to protect mobile application traffic that is initiated by a client IBM Worklight application.

Enterprise topologies are designed to include different zones of protection so that specific processes can be secured and optimized. You can use IBM WebSphere DataPower in different ways in the DMZ and in other zones within your network to protect enterprise resources. As you start to build out Worklight applications to be delivered to the devices of your customers and employees, these methods can be applied to mobile traffic. The following procedure demonstrates the use of IBM WebSphere DataPower as a front-end reverse proxy and security gateway. It uses a multi-protocol gateway (MPGW) service to proxy and secure access to Worklight mobile applications. Two alternative authentication options are demonstrated: HTTP basic authentication and HTML forms-based login between the mobile client and DataPower.

In

1. Install and configure an IBM Worklight environment and test the installation with a simple application without DataPower acting as the reverse proxy. Test that your application logic works. 2. Configure an MPGW on DataPower to proxy the mobile application or the Worklight console. Part of the configuration involves selecting one of the following authentication options: v Use basic authentication for end user authentication with AAA, and generate a single sign-on (SSO) LTPA token for Worklight Server running on WebSphere Application Server if the user successfully authenticates.

of

ca

se

Ex

pe

rim

en

ta

Consider adopting the following phased approach to establishing IBM WebSphere DataPower as a security gateway:

v Use HTML form-based login with AAA, and generate a single sign-on (SSO) LTPA token for Worklight Server, running on WebSphere Application Server if the user successfully authenticates. 3. Test the reverse proxy: v Update the Worklight configuration on the server with the reverse proxy configuration (described later in this procedure). v Update the mobile security test configuration of each mobile application to use forms-based authentication so that the application requests the user to authenticate immediately upon application startup. Either HTTP basic authentication or HTML forms-based login is supported before the Chapter 4. Installing and configuring

95

application starts. For web widgets, widget resources are only accessible to the browser after a user has successfully authenticated.

Procedure


1. Set up Worklight-specific configuration. a. For each app that you are configuring, modify the authenticationConfig.xml file on the server to include the following security test, realm, and login module declarations:

com.worklight.core.auth.ext.WebSphereFormBasedAuthenticator com.worklight.core.auth.ext.WebSphereLoginModule

of

In

ca

se

Ex

pe

rim

en

ta

The authenticationConfig.xml file is usually available in this directory: /profiles//installedApps// IBM_Worklight_Console.ear/worklight.war/WEB-INF/classes/conf. b. Restart the Worklight Console enterprise application. 2. Update your client mobile app. a. In your client mobile app, add the following JavaScript to your HTML Worklight application: function showLoginScreen() { $("#index").hide(); $("#authPage").show(); } function showMainScreen() { $("#authPage").hide(); $("#index").show(); }

var myChallengeHandler = WL.Client.createChallengeHandler("WASLTPARealm"); var lastRequestURL; myChallengeHandler.isCustomResponse = function(response) { //A normal login form has been returned var findError = response.responseText.search("DataPower/Worklight Error"); if(findError >= 0) { return true; }

96



//A normal login form has been returned var findLoginForm = response.responseText.search("DataPower/Worklight Form Login"); if(findLoginForm >= 0) { lastRequestURL = response.request.url; return true; } //This response is a worklight server response, handle it normally return false;

};

myChallengeHandler.handleChallenge = function(response) { showLoginScreen(); }; challengeHandler1.handleFailure = function(response) { console.log("Error during WL authentication."); };

myChallengeHandler.submitLoginFormCallback = function(response) { var isCustom = myChallengeHandler.isCustomResponse(response); if(isCustom) { myChallengeHandler.handleChallenge(response); } else { //hide the login screen, you are logged in showMainScreen(); myChallengeHandler.submitSuccess();

}

of

ca In

//When the login button is pressed, submit a login form $("#loginButton").click(function(){ var reqURL = "/j_security_check"; alert(lastRequestURL); var options = {method: "POST"}; options.parameters = { j_username: $("#username").val(), j_password: $("#password").val(), originalUrl : lastRequestURL, login: "Login" };

options.headers = {}; myChallengeHandler.submitLoginForm(reqURL, options, myChallengeHandler.submitLoginFormCallback); });

se

Ex

pe

rim

en

ta

};

b. If you want to retrieve the LTPA key file used for authentication from the Worklight Server, you can also use the Worklight API function “WL.Client.login” on page 517: WL.Client.login(“WASLTPARealm”); This call triggers the myChallengeHandler.isCustomResponse method with a JSON response, where you can retrieve the LTPA key file. if (response.responseJSON.WASLTPARealm && response.responseJSON.WASLTPARealm.isUserAuthenticated) var sessionKey = response.responseJSON.WASLTPARealm.attributes.LtpaToken;

For any subsequent adapter calls that need to be proxied through the reverse proxy, you can include this sessionKey as a header within the request. Ensure that the HTML body for your Worklight app reflects the login information that is to be handled by DataPower. Chapter 4. Installing and configuring

97

c. To add the authentication test to an application or device, add a securityTest attribute to the environment's tag in the applicationdescriptor.xml file in your project to use the security test you declared in the authenticationConfig.xml file on the server side in step 1a. Here is an iPad example:


3. Define a multi-protocol gateway. a. In the IBM DataPower WebGUI, in the search box under Control Panel, enter Multi-Protocol, and then click New Multi-Protocol Gateway. b. On the General Configuration page, provide the following details: Table 13. General Configuration Field

Description

Multi-Protocol Gateway Name

Provide a name for your gateway.

Response Type

Select Non-XML. This allows HTTP Web application traffic (including JSON, JavaScript, and CSS) to pass through the appliance.

Request Type

Select Non-XML. This allows HTTP Web application requests to be handled by the appliance.

Front Side Protocol

Select HTTPS (SSL). For this type of interaction in which user credentials are passed between the client and server, HTTPS is appropriate. Provide the following additional front-side handler details:

of

In

ca

se

Ex

pe

rim

en

ta

Name

98


Enter a name for the configuration.

Port Number Enter a number for the listening port. This port number must match the port number that you specify if you define an AAA policy that uses HTML forms-based authentication. (See Table 15 on page 99.) Allowed Methods and Versions Select the GET method check box to enable support for HTTP Get.

SSL Proxy Select an SSL Reverse Proxy profile to identify the SSL server.

Table 13. General Configuration (continued) Description

Multi-Protocol Gateway Policy

Click +, and then create rules to define the policies listed in the following topics depending on the type of authentication you decide to use:


Field

v Policy worklight-basicauth for HTTP basic authentication: see “Rules for HTTP basic authentication” on page 100.

v Policy mpgw-form for HTML form-based login authentication: see “Rules for HTML forms-based authentication” on page 102.

Backend URL

Specify the address and port of the Worklight Server that is hosted on the WebSphere Application Server.

4. Create an AAA policy that supports the HTTP basic authentication or HTML forms-based login policy you defined in the previous step.

a. In the IBM DataPower WebGUI, in the search box under Control Panel, enter AAA, and then click the Add button. b. Provide information depending on the type of authentication you want to use: v For HTTP basic authentication, provide the information listed in the following table:

Table 14. AAA policy for HTTP basic authentication

Description

Extract Identity

In the Methods field, select HTTP Authentication Header.

Authenticate

Choose the authentication method. If WebSphere Application Server is using LDAP, configure LDAP here.

Extract Resource

Select URL Sent by Client.

Post processing

Generate an LTPA token. Specify LTPA Token Expiry, LTPA Key File, and LTPA Key File Password.

v Fir HTML forms-based login, provide the information listed in the following table:

Table 15. AAA policy for HTML forms-based authentication

Description

Extract Identity

In the Methods field, select HTML Forms-based Authentication. Select or create an HTML forms-based policy that has the Use SSL for Login option enabled, assigns SSL Port to the port number on which the MPGW is listening (that was specified in step 3), and has the Enable Session Migration option disabled.

Authenticate

Choose the authentication method. If WebSphere Application Server is using LDAP, configure LDAP here.

of

Phase

In

ca

se

Ex

pe

rim

en

ta

Phase


99

Table 15. AAA policy for HTML forms-based authentication (continued) Description

Extract Resource

Select URL Sent by Client.

Post processing

Generate an LTPA token. Specify LTPA Token Expiry, LTPA Key File, and LTPA Key File Password.


Phase

5. On the Advanced page, specify the advanced settings listed in the following table. Table 16. Advanced settings Field

Value

Persistent Connections

On.

Allow Cache-Control Header

Off

Loop Detection

Off

Follow Redirects

Off. This prevents the DataPower back-end user agent from resolving redirects from the back-end. Web applications typically require a client browser to resolve redirects so that they can maintain the context for “directory” along with setting an LTPA cookie on the client.

Allow Chunked Uploads

Off

MIME Back Header Processing

Off

MIME Front Header Processing

Off

Results

Rules for HTTP basic authentication

Add rules to define an HTTP basic authentication policy named worklight-basicauth.

of

You create the worklight-basicauth policy as part of the process of defining a multi-protocol gateway. See “Protecting your mobile application traffic by using IBM WebSphere DataPower as a security gateway” on page 95, Table 13 on page 98. Table 17. HTTP Basic Authentication properties Property

Value

Policy Name

worklight-basicauth

In

ca

se

Ex

pe

rim

en

ta

Your Worklight mobile application traffic is now protected by an IBM WebSphere DataPower secure gateway. Authentication is enforced on the DataPower device and the credentials (header or LTPA token) are forwarded downstream to Worklight Server to establish the user identity as part of the mobile traffic.

100


Table 17. HTTP Basic Authentication properties (continued) Property

Value

Order of configured rules

1. worklight-basicauth_rule_0: see Table 18


2. worklight-basicauth_rule_3: see Table 21 3. worklight-basicauth_rule_1: see Table 19 4. worklight-basicauth_rule_2: see Table 20

Table 18. Properties of worklight-basicauth_rule_0 Property

Value

Direction

Client to Server or Both Directions.

Match

v Type = URL

v Pattern = /favicon.ico

Advanced

"Set Variable" -> var://service/mpgw/skipbackside = 1

Result

Not applicable.


Value

Direction

Client to Server.

Match

v Type = URL v Pattern = *

AAA

BasicAuth2LTPA

v Output: NULL

Result

Not applicable.

Property

Value

Direction

Server to Client.

Match


of

Filter

In

ca

se

Ex

pe

rim

en

ta

Table 20. Properties of worklight-basicauth_rule_2

Provide a custom stylesheet that handles redirect and content-type rewrite. For a sample redirect stylesheet, see “Sample redirect stylesheet” on page 105. v Output: NULL

Result

Not applicable.


Value

Direction

Client to Server.


101

Table 21. Properties of worklight-basicauth_rule_3 (continued) Property

Value

Match

v Type = HTTP v HTTP header tag = Cookie


v HTTP value match = *LtpaToken*

AAA

VerifyLTPA

v Output: NULL

Result

Not applicable.

Rules for HTML forms-based authentication

Add rules to define an HTML forms-based authentication policy named mpgw-form.

You create the mpgw-form policy as part of the process of defining a multi-protocol gateway. See “Protecting your mobile application traffic by using IBM WebSphere DataPower as a security gateway” on page 95, Table 13 on page 98. Table 22. HTTP Form-Based Login properties Property

Value

Policy Name

mpgw-form

Order of configured rules

1. mpgw-form_rule_0: see Table 23 2. mpgw-form_rule_1: see Table 24

3. mpgw-form_rule_2: see Table 25 on page 103 4. mpgw-form_rule_3: see Table 26 on page 103 5. mpgw-form_rule_6: see Table 27 on page 103

Property

Value

Direction

Client to Server or Both Directions.

Match

v Type = URL

v Pattern = /favicon.ico

"Set Variable" -> var://service/mpgw/skipbackside = 1

Result

Not applicable.

of

Advanced

Table 24. Properties of mpgw-form_rule_1 Property

Value

Direction

Client to Server.

Match

v Type = HTTP

In

ca

se

Ex

pe

rim

en

ta

Table 23. Properties of mpgw-form_rule_0

v HTTP header tag = Cookie v HTTP value match = *LtpaToken* AAA

VerifyLTPA v Output: NULL

Result

102


Not applicable.


Value

Direction

Client to Server.

Match

v Match with PCRE = on


v Type = URL

v Pattern = /(Login|Error)Page\.htm(l)?(\ ?originalUrl=.*)?

Transform

Provide a custom stylesheet that builds either a Login or Error HTML page. For a sample stylesheet, see “Sample form login stylesheet.” Note: The HTML Login Form policy allows you to specify whether you retrieve the login and error pages from DataPower or from the back-end application server.

Advanced

Select the set-var action and specify the service variable: var://service/routing-url and value with the endpoint of your login page.

Result

Not applicable.


Value

Direction

Client to Server.

Match


Advanced

"Convert Query Parameter to XML". Accept default values for other selections.

AAA

Form2LTPA

Value

Direction

Server to Client.

Match


of

ca In

Property

Filter

se

Ex

pe

rim

en

ta

Table 27. Properties of mpgw-form_rule_6

Provide a custom stylesheet that handles redirect and content-type rewrite. For a sample redirect stylesheet, see “Sample redirect stylesheet” on page 105. v Output: NULL

Result

Not applicable.

Sample form login stylesheet You can use this sample stylesheet to generate the HTML form login page or error page when creating rules to define an HTML forms-based authentication policy. You provide a custom stylesheet when defining rule mpgw-form_rule_2. See “Rules for HTML forms-based authentication” on page 102, Table 25. Chapter 4. Installing and configuring

103


ta en rim In

ca

se

of

pe Ex 104