magic ria client for blackberryftp.magicsoftware.com/ver/docs/downloads/unipaas...magic software...

Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel

Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com

Magic RIA Client for BlackBerry

For uniPaaS Version 2.0

Installation Guide



2

Contents Preface ................................................................................................................................................................. 3

Getting Started .................................................................................................................................................... 3

Prerequisites .................................................................................................................................................... 3

Setting-up the “build” environment ................................................................................................................ 3

Setting-up the uniPaaS environment .............................................................................................................. 4

Running the “build” tool .................................................................................................................................. 4

Usage ........................................................................................................................................................... 4

build_client.xml ........................................................................................................................................... 5

execution.properties ................................................................................................................................... 6

Deploying the Magic RIA client for BlackBerry .................................................................................................... 6

Installing and running the Travel Demo application ........................................................................................... 7

Travel Demo application walkthrough ............................................................................................................ 9



3

Preface The Magic RIA client for BlackBerry is a native BlackBerry OS application implementing the Magic RIA client

protocol. Using the Magic RIA client for BlackBerry, developers can deploy enterprise connected, highly

interactive RIA applications to BlackBerry OS devices.

Getting Started The BlackBerry platform provides a managed, controlled process for installing native applications on

BlackBerry devices. Each Magic application that you want to deploy on the BlackBerry platform must be

packaged as a separate, self-contained BlackBerry application with its unique name, icon and application

properties. The process of building a BlackBerry application involves editing configuration files and running a

“build” tool that creates a new, unique BlackBerry application that embeds the Magic RIA client engine. This

application can then be deployed on BlackBerry devices using the supported distribution mechanisms.

Prerequisites To successfully build a Magic RIA BlackBerry application, the following prerequisites are required:

uniPaaS Studio 2.0 (Enterprise or Jet Edition) – For developing and testing the application.

The BlackBerry JDE version 5.0.0 – For creating the final packaged BlackBerry application.

The Apache ANT build tool version 1.8.2 or above – For running the “build” script.

Code-signing keys – For creating a signed application that can run on BlackBerry devices. You can

read about code-signing keys here.

A BlackBerry device simulator (optional) – For testing the application on the desktop.

Setting-up the “build” environment 1. Register as a developer on the BlackBerry developer site. This will enable you to download the

necessary tools. Registration can be done here.

2. Apply to receive code-signing keys from RIM here. Once approved, you will receive an email with the

code-signing keys. Follow the installation instructions in the email.

3. Extract the build_magic folder from the Magic RIA client for BlackBerry zip file to a folder that does

not have spaces in its name (i.e. to the root of the C: drive).

4. Download the BlackBerry JDE (Java Development Environment) version 5.0.0 from here, and install it

using its setup program.

5. The build_magic folder contains two configuration files: build_magic.xml and execution.properties.

These files should be edited to reflect the current configuration before running the build tool.

After installing the BlackBerry JDE, edit the build_magic.xml configuration file and modify the

jde.home and jde.version properties to reflect the installed location and version of the JDE.

http://us.blackberry.com/developers/javaappdev/codekeys.jsp

https://origin-bdsc.webapps.blackberry.com/bdsc/?lang=na#register

https://www.blackberry.com/SignedKeys/

http://us.blackberry.com/developers/javaappdev/javadevenv.jsp



4

6. Download Apache ANT version 1.8.2 or above from here, and extract it into a new folder that does

not have spaces in its name. Follow the configuration instructions on this page to properly install and

configure this tool. Note that the configuration requires making changes in environment variables.

7. For testing purposes, a device simulator is recommended. Download and install a BlackBerry device

simulator from here. Choose a device with a minimum OS version of 5.0.0.

Setting-up the uniPaaS environment 1. Download and install the uniPaaS 2.0 Studio (Enterprise or Jet Edition).

2. Add the following lines at the end of the Magic RIA server magic.ini file:

[MAGIC_SPECIALS]

SpecialClientSecureMessages = N

If the Magic server is already running, restart it.

3. Edit the execution.properties file and modify the protocol, server and requester properties to

reflect the currently installed uniPaaS RIA server configuration.

4. In the execution.properties file, change the appname property to the name of your application.

5. In the execution.properties file, change the prgname property to the public name of the program

you want to run on client startup. This program must be defined in the application as External.

Running the “build” tool The build tool is a command file that handles the compilation and packaging of your application client. The

build tool has the following configuration files:

1. build_client.xml – This is the build configuration file. In this file you define the native BlackBerry

application properties such as application title, description and version.

2. execution.properties – This file is packaged together with the application file and is used by the

Magic RIA client to connect to the Magic RIA server. This file contains the server connection and the

Magic application details.

3. icon.png – This file will be is used as the application icon. It is recommended to use a 48x48 pixels

PNG file. Other file sizes are also acceptable, but will be resized to fit the device’s icon size.

Usage

From the build tool folder, run build.cmd. The build tool writes a log file of its operation. The log file is

named build.log and is created in the same folder as the build.cmd command file.

Note: Every build will overwrite the “output” folder. If you want to save previous build outputs, you need to

copy them elsewhere.

http://ant.apache.org/bindownload.cgi

http://ant.apache.org/manual/install.html#getting

http://us.blackberry.com/developers/resources/simulators.jsp

5

build_client.xml

This configuration file contains the following parameters, editable using a text editor:

build.password – This password is required by the BlackBerry application signing utility.

jde.version – The JDE version used during the build. The default is 5.0.0.

jde.home – The home directory of the JDE installation.

output.dir – The folder that will contain the built installers. It can be an absolute or relative path.

build.dir – A temporary folder location used during the build process. This folder is removed after a

successful build. It can be an absolute or relative path.

source.jar.name – The name of the source Magic RIA JAR file. This file contains the core Magic RIA

client module.

cod.name – The target module name that will be created during build. Module names must not

contain spaces.

OTA.dir – The target folder for the web installer files (Over-the-Air). A relative path is created in the

output folder.

Desktop.dir – The target folder for the BES or BlackBerry Desktop installer files. A relative path is

created in the output folder.

client.title – The application title as visible to the user.

client.version – The application version.

client.description – A longer application description.

client.vendor – The vendor details.

client.copyright – The copyright message.

Example build_client.xml parameters:

 <property name="build.password" value="******" /> <property name="jde.version" value="5.0.0" /> <property name="jde.home" location="C:\Program Files\Research In Motion\BlackBerry JDE 5.0.0" />  <property name="output.dir" location="output\" /> <property name="build.dir" location="output\build\" /> <property name="source.jar.name" value="Magic_RIA_20" /> <property name="cod.name" value="Magic_Travel_Demo" /> <property name="OTA.dir" value="OTA\" /> <property name="Desktop.dir" value="Desktop\" />  <property name="client.title" value="Magic Travel Demo" /> <property name="client.version" value="1.0.0" /> <property name="client.description" value="The Magic Travel Demo" /> <property name="client.vendor.name" value="Magic Software Enterprise Ltd." /> <property name="client.copyright" value="Copyright (c) 2011 Magic Software Enterprises Ltd." />



6

execution.properties

This configuration file contains the following parameters, which are editable using a text editor:

protocol – The name of the communication protocol used by the client. Can be HTTP or HTTPS.

server – The host name or IP address of the website hosting the Magic requester.

requester – The alias/virtual folder and module name of the Magic requester.

appname – The application name, as published to the Magic broker by the Magic RIA server.

prgname – The public program name to call on startup. This program is typically an application menu

or welcome screen.

Example execution.properties parameters:

<properties> <property key="protocol" val="http"/> <property key="server" val="127.0.0.1"/> <property key="requester" val="uniJetScripts/mgrqispi.dll"/> <property key="appname" val="unipax"/> <property key="prgname" val="mobile"/> </properties>

Deploying the Magic RIA client for BlackBerry The build process creates a native BlackBerry application that can be deployed like any other native

application. The BlackBerry platform supports several deployment methods for applications. A detailed

description of the different methods can be found in the following document. This document also contains

configuration instructions for the different deployment methods.

The build process creates two outputs that can be used for all supported distribution methods, in the

locations configured in the build_client.xml configuration files: OverTheAir and Desktop.

You can follow the instructions for both Over-the-Air (OTA) and Desktop installations in the referenced

document to install the client. Note that when using OTA deployment, it is necessary to change

configuration settings (MIME types) in the web server that is hosting the published application files.

Note: After deploying the application client, there is no need to redeploy it after every application change.

The application itself is not packaged as part of the client. All application changes are downloaded and

updated automatically, just like any other Magic RIA application. When you want to upgrade the core client

version (i.e. for a newer Magic release), you should rebuild the client and redistribute it to the devices.

http://supportforums.blackberry.com/rim/attachments/rim/Testing_and_Deployment_of_Applications@tkb/117/1/How_to_Deploy_and_Distribute_Applications_V1.pdf



7

Installing and running the Travel Demo application Please follow these instructions carefully for installing the demo application included with this release.

1. Follow the above installation instructions for setting up the uniPaaS RIA server and the build tool

environment.

2. From the package zip file, extract the unipax folder into any location.

3. On IIS, create a virtual folder named images, pointing to the images folder in the unipax folder that

you just extracted.

4. Create a new database entry as follows:

5. Make sure that the images Magic logical name is pointing to the full web URL of the images virtual

directory. Make sure that the IIS user has sufficient permissions for this folder.

6. Still on IIS, create (or modify) two new MIME types (so that you can install the application Over-the-

Air):

.cod = application/vnd.rim.cod

.jad = text/vnd.sun.j2me.app-descriptor

7. Modify the execution.properties configuration file to use the new unipax application. The public

program name is mobile. Make sure that you use the correct settings for the requester and server,

according to the uniPaaS RIA server settings.



8

8. Run the build tool. This will create two folders under the output folder (OverTheAir and Desktop).

9. On IIS, create a new virtual folder named install pointing to the OverTheAir folder in the output

folder. Make sure that the IIS user has sufficient permissions for this folder.

10. Run the Magic RIA server. You can open the application in the Studio and run the project.

11. On the BlackBerry, using the web browser, open the location where you created the client. Typically,

this location would be similar to http://localhost/install/TravelDemo.jad. You will be asked to

confirm the installation of the client. The installation will install an icon for the default download

folder.

12. Open the installed application on the BlackBerry.

http://localhost/install/TravelDemo.jad



9

Travel Demo application walkthrough The travel demo application is a showcase for a simple Enterprise Travel Management System with a mobile

front-end. The demo application has two interfaces: one for Desktop RIA deployment and the other for

BlackBerry RIA deployment.

The travel demo application supports multiple device resolutions and was tested on devices using BlackBerry

OS 5, OS 6 and OS 7, with touch screens or with keyboard only.

1. From the BlackBerry desktop, run the Magic Travel Demo application.

2. Enter the user credentials. The default user name is [email protected]. The default password is the

letter “a”.



10

3. Browse through the list of travel plans scheduled for Joe. Press Enter or click the Trackpad to view a

specific travel.

4. You can view Joe’s profile by selecting from the menu.



11

5. When selecting a travel plan, you can view and browse the travel segments (flights, car rentals,

hotels). Selecting a specific travel segment by pressing Enter or clicking the Trackpad will show the

travel segment details.

6. Watch the different travel segment types (Flights, Hotels, Car rental).



12

7. For each travel segment, you can view comments.

8. For flight segments, you can search for an airport from a popup dialog box.



13

The application runs properly on devices with multiple resolutions by utilizing “Placement” capabilities.

320x240 (OS5) 480x360 (OS6)

640x480 (OS7)



14

And using the same feature (Placement), it can run properly in landscape or portrait mode.

magic ria client for blackberryftp.magicsoftware.com/ver/docs/downloads/unipaas...magic software...

Documents