Part 1

Part 2

Part 3

Part 4

August/2007    Mobilizing Domino Applications onto Blackberry Devices Part 1: Developing with MDS by Bill Buchan Table of contents Introduction Why BlackBerry? Architecture Building a pilot environment Which development environment to use About the author Web Services Introduction Web services and Domino LotusScript Web services in Domino 7 Testing your web service Creating your first MDS Studio application Installing BlackBerry MDS Studio Creating the MDS Studio application Using the simulator Improving the Application UI Redirect the starting page and the "Done" button Fix the screen titles Insert your own graphics Making the return string read-only Getting rid of the "Message Sent" dialogue Summary Download Bill's original .pdf version of this article here! (1,028 kb)    1. Introduction    This is the first of three articles discussing mobilizing Domino applications onto BlackBerry handsets. In this article, we shall discuss the fundamentals of publishing Domino data onto a BlackBerry handset, using one of the two development tools that BlackBerry provides - the BlackBerry MDS Studio. In the next article, I shall show enhancing the application and the process of deploying the application to your corporate BlackBerries. The last article will cover the more advanced BlackBerry development tool - the JDE. During this article and the next article, we shall develop an example application together - a simple contact application to demonstrate these techniques. This application allows the end user to view corporate contacts and ultimately create new ones. 1a. Why BlackBerry? Why is this article focusing on BlackBerry handsets? Aren't there other mobile solutions in our corporate world, such as Windows Mobile devices and Palm-based devices? I firmly believe that the solution that BlackBerry provides is superior: It is far more secure. Data is transmitted in encrypted (and compressed) form, using user-generated keys, between your data centre and the handset. Should the handset be lost, a “Kill” command can be sent which will destroy all data on the device. In comparison, data held on other mobile platforms is easily retrieved. The handset itself is far more robust. Just look at the second-user market on eBay for handsets, and you can see hundreds of older devices for sale. I have owned a Windows handset in the past, and found it to be far more physically fragile. Something worth considering when choosing a handset that will live with you (and your users) 24x7. Ease of use. The people who use these devices are probably not computer experts, and wish a simple, clear end user interface that works all the time in a predictable manner. The BlackBerry experience provides that. Scalable. I know of customers who have rolled out tens of thousands of BlackBerry handsets to their users who demand 24x7 service. Other mobile platforms require far more support in order to keep them going. Handsets. BlackBerry now has three physical handset formats, and seems to update these at a dizzying pace, adding camera, memory stick and now Wifi capability, whilst at the same time retaining the ease of use and battery life that our users demand. I do not for a second believe that this upgrade progress will slow down. Many users firmly believe that BlackBerry can provide only email, contact and calendar solutions - this series of articles shows how to mobilise business critical applications as well. If you already have a BlackBerry Domino solution in place, these techniques will allow you to gain more value from your existing investment and help deploy your applications to very influential end users. 1b. Architecture In order to appreciate fully the design decisions you must make, you must appreciate how the solution is architected. At the core of the BlackBerry solution is the BlackBerry enterprise server (BES). This is a Windows-based server which connects to your Domino environment - and indeed runs on a Domino server. This takes data from your corporate environment and pushes it out to the handsets. Out of the box, the BES server provides you with email, calendar and contact (often referred to as PIM) synchronisation. An optional installation - Mobile Data Suite ("MDS") Server - allows you to leverage application connectivity as well as PIM information. From a network point of view, the solution looks like: So we can expose Web services on our Domino servers, which are then consumed by the BES server and then passed to the handset via a secure encrypted link over the internet. The traffic is passed via RIMs servers which provide the capability to connect a corporate BES server to a handset regardless of carrier or country. In effect, we now have a secure VPN link from the handset right back to behind our firewall, using encryption keys that are unique to our corporation. In order for our Domino application to be exposed on our BlackBerry handset, therefore, we need to: Web service enable our Domino Application Write an application for the BlackBerry that consumes that Web service Thankfully, BlackBerry MDS studio provides us with a development environment that mimics this connectivity, as well as providing us with a simulator which allows us to write, deploy and test applications on a single development machine, without any of this infrastructure being in place. 1c. Building a pilot environment An important part of proposing this as a solution to management is to understand the costs of running this architecture. The initial costs for a pilot may preclude management buy-in. This section helps you understand the costs of each of the components and how to minimise these costs for a pilot. The BES server itself is an expensive software component, and needs to run either in a virtual machine image (such as VMware) or on dedicated hardware. This will require a license for the operating system and a domino server license. BES itself is sold as a software package, and you require a CAL for each BlackBerry handset you wish to connect to this. BlackBerry is running a promotion at the moment for Lotus Domino users where you can download and run a free 10-user BES server in your environment. To download the server, go here. Each handset then costs money - you must obtain handsets from your phone carrier, who will also sell you BES software and CALs. And lastly, your phone needs to come with an air-time plan that includes BlackBerry connection as well as data. For example, here in the UK, T-Mobile offer BlackBerry service with your airtime package for only £9/month extra. Should you require a large number of handsets, you may find that your existing corporate mobile phone provider is very flexible in terms of pricing and may even provide test hardware in order to demonstrate a pilot environment. Second-user handsets are of course available via eBay, and this route forms an invaluable source of cheap handsets suitable for testing, etc. 1d. Which development environment to use Both the BlackBerry MDS Studio and JDE development environments allow you to develop applications that will run on BlackBerry handsets. But which one is suitable for your application development requirements? The MDS Studio relies on the MDS server hosted on your BES and provides a virtual VPN between your handsets and your corporate infrastructure. These applications are then pushed out (over the air) to your users. MDS users must therefore be connected to BES servers that you control. This in turn means that MDS studio should only really be used for applications that will be used by corporate users in your environment. JDE allows you far more granular control over your applications and enables you to build far more complex applications - ones that can store data on the handset and connect to general services. These are more appropriate for developing applications that you might wish to provide for any user, regardless of how they are connected. The first two articles in this series will focus on the BlackBerry MDS Studio development environment. Both development environments are free and can be downloaded from http://na.blackberry.com/eng/developers. 1e. About the author Bill Buchan is a veteran and long-standing member of the Lotus Domino community. He regularly presents on stage at Lotusphere, The View and the Irish/Scottish/UK user group conferences. If you've ever seen a man in a kilt at a Domino event, chances are it's him. Come up and say "Hi" - he's not as scary as he looks. Outside of work (those precious few minutes!) he can be found being bossed around by his wife ("She Who Must Be Obeyed") and daughter ("Squid"), and tinkering with his beloved motorbike. He's a founder of HADSL and his personal blog can be found at http://www.billbuchan.com, where all his presentations and articles can be found. Return to Top   2. Web services    Web services are used to expose our Domino data to the MDS studio. So what are Web services, and how can we construct them? 2a. Introduction Web services are a platform and language independent application-to-application data connectivity methodology. In general, this means that one application - the Web service server - will allow Web service consumers to submit queries and receive answers. The data transport mechanism is usually (but not restricted to) http-style traffic, and the data is formatted using well formed and well defined XML constructs. Simple Object Application Protocol (SOAP) is a well known implementation of such a service. Remember, Web services are an industry wide standard and as such, lots of resources are available for you outside the Lotus Domino environment. Similarly, you may find that other applications within your environment can serve and consume Web services - so this methodology may be more beneficial than just providing BlackBerry handsets with data. 2b. Web services and Domino There are a number of different ways to provide a Web service server in Domino. We shall focus on the simplest approach, which is the ability of Lotus Domino 7 to provide a Web service based on LotusScript code that you write. Other methods include writing Java Servlets or writing simple LotusScript agents. These approaches may be more appropriate if you have to host your application on Domino servers older than ND7. These other approaches and their strengths and weaknesses are discussed in a Web article. 2c. LotusScript Web services in Domino 7 Writing a Web service in Lotus Domino 7 is simple. You: Create a new Lotus Notes Database. Open this database in Domino Designer and go to "Shared Code, Web services". Click on the "New" button. Enter some LotusScript code in the "Declarations" Section. Note that this code has to be contained in a class, and has to have one or more "public" functions that return simple data types (string, date, number, etc). In the next article, we shall discuss returning more complex data types. In our case, we shall create a class called "Contacts", and at this stage, just create a single function called "findUser". This function takes a single string as a parameter and uses this string to search the database for a record. If it finds a Notes document, it will return the users name as a string. Class Contacts Public Function findUser(searchString As String) As String ' Find a user based on the search information we've been provided. Return the users full name. Dim sSession As New NotesSession Dim dbThis As NotesDatabase Set dbThis = sSession.CurrentDatabase Dim dc As NotesDocumentCollection Set dc = dbThis.FTSearch(searchString, 1) If (dc.Count < 1) Then ' We have not been able to find any documents - return a blank string Msgbox "findUser: Couldnt find any documents using search string: " + searchString Exit Function End If Dim doc As NotesDocument Set doc = dc.GetFirstDocument() findUser = doc.GetItemValue("FullName")(0) ' You can use MsgBox in a back-end agent to echo information to the server console. Msgbox "findUser: Returning user: " + doc.GetItemValue("FullName")(0) + " from search criteria: " + searchString End Function End Class We need to remember to save this Web service. During the save process, we will be prompted to fill in the class name that we wish to expose to the Web service in the "PortType class" field. In this case, we have put the class name "Contacts" in this field. Now save the Web service. Web service consumer applications can ask the Web service to describe itself - it does so by passing back a well-formed piece of XML using a standard called the Web Services Description Language. We shouldn't worry too much about this, as the Domino 7 Web Services design element constructs this for us. In order to view the WSDL, click on the "Show WSDL" button. You should see something like this. Congratulations, you have just created your first Lotus Domino Web service! 2d. Testing your Web service A good initial test is to try to open the WSDL using a Web browser. Do this by opening a Web browser, and typing in the URL for the Web service. For instance, if our test server is called "Server", our database is called "contacts.nsf" and we have named our Web service "Contacts", then the URL will be: http://server/contacts.nsf/Contacts?WSDL. In terms of more comprehensive testing, I prefer using a Web service testing package called "SoapUI", which can be downloaded from: http://www.soapui.org/. This package allows you to examine all Web service calls provided and push test data into the Web service quickly and easily. Return to Top   3. Creating your first MDS Studio application    We can now start constructing our first BlackBerry MDS application. 3a. Installing BlackBerry MDS Studio Download and install BlackBerry MDS studio from http://na.blackberry.com/eng/developers. If in doubt, select defaults for all parts of the installation process 3b. Creating the MDS Studio application We can now create the MDS application: Within MDS Studio, click "File, New" Select "Quick Start Approach" Select "WebService Connector Plugin": Enter the URL for the Web service WSDL: Select all the Web services you wish this application to consume. In this case, there is only one service: Lastly, give the application a relevant name. In this case, we shall call this application "TestContacts1". The MDS Application has now been built, and looks like this: Without writing a line of code, we now have a fully featured (if slightly graphically challenging) MDS application which consumes our Web service. 3c. Using the simulator We can then test this application using the inbuilt BlackBerry simulator. Do so by right-clicking on the application name on the left hand object browser, and selecting "Test". This will then load the test environment and BlackBerry simulator, as well as compiling the application and loading it into the simulator. The simulator looks like this. Note that I've selected the BlackBerry Pearl (8100) as the target device. The Pearl has a slimmer screen than its larger Curve (8300) or 8800 handsets, and therefore it is useful to map your application onto this screen size. In terms of using the simulator, use the scroll wheel on your mouse to emulate the old "scroll wheel" on the BlackBerry handset itself, and click on the thumbwheel for "Enter". As you can see, the application "TestContacts1" has been added to the handset workspace, so it's just a case of selecting it, and pressing Enter: We can then view the application. The opening screen looks like this. Select the "Go" button and press "Enter". Selecting "Go" produces this screen. As I have a single test record in my database with my name, I choose to search on the string "Buchan". When I click Submit, an annoying "This message has been sent" dialog pops up for a second, and then I'm presented with the results of my Web service operation. So as you can see, we have now created a Domino Web service, and created an MDS Application which consumes that Web service. All without writing a single line of code in MDS Studio and only 30 lines of code in LotusScript! Return to Top   Sponsored by BlackBerry   Read this new white paper for an overview on effectively creating BlackBerry® applications that interact with Domino databases. If you have experience developing for Domino, you've already got all the skills you need! This overview document includes a sample application to help you get started quickly and easily. Download now at http://www.blackberry.com/go/techbrief. Return to Top   4. Improving the application UI    As previously noted, the application UI, whilst functional, is somewhat challenging. We seem to have an unnecessary screen at the start. This might make more sense later on when we have more functions available to us, but at the moment, this is just one more screen to click through. The titles of the screens are pretty ugly. The layout of each page could be improved. The result from the Web service is editable, and the labels to the left of the return text mean that the effect is somewhat squashed. We'd like to put our own graphics in there. There's an annoying "Message sent" dialog that pops up. Let us therefore fix all these issues. This exercise will give you a pretty good journey around the MDS studio IDE. Like all modern IDEs, you have an object browser on the left, some properties boxes down the right, and clicking on an item lets you view or update these properties. 4a. Redirect the starting page and the "Done" button We can choose which screen the application opens with by changing the "Entry Point" value on the Project Properties dialog. To do this: Right click on the application and choose "Project Properties". Now select the new entry point screen on the "Entry Point" drop-down box. In this case, we shall choose the screen that the user enters his search text - scrFINDUSERRequest. It should be noted that you can select both screens and JavaScript routines from this box, so take care to enter the correct screen name. Click on OK to save and close this dialog.   The second part of this exercise is to change the button on the results page so that when the user clicks on the button, it now goes to the same screen. To do this: Open the screen scrFINDUSERResponse. Select the "Done" button. On the properties pane on the right hand side, click on the button beside the OnClick event. On the dialog, keep the first selection as "Screen", and then choose the scrFINDUSERRequest screen from the drop-down list. Press OK to confirm these changes.   Now press the "Save" icon on the toolbar.   4b. Fix the screen titles In both of our user facing screens, the screen titles are automatically generated, and therefore look fairly unfriendly. Let's go change these by performing the following steps: Open each screen.   Click on an area on the screen that doesn't contain any screen controls. This will ensure that you have selected the screen itself.   On the properties box on the right, click on the Title property. On the dialog screen, change the "Title" text to something more relevant. Click on OK to save the new title.   Save each screen by pressing the "Save" icon on the toolbar.   4c. Insert our own graphics Thankfully, we can insert our own graphics to give the application a little more of a corporate feel. In this case, we shall put a header graphic on each page. Open each screen.   Click on the "Service Response" text and press delete.   Click on the icon and press delete.   You should now see a large square empty box in the GUI - this is a "layout region". Click on the "image" icon on the left and drag it onto the layout region. You should now see the Image Add dialog box. This dialog allows us to add new images to this application as well as selecting pre-installed images. In this case, click on the "Add" button and select an image from your hard drive. Once you have added a new image, click on it, and press OK. The image will then appear on the screen for the application. Now click on the "File Save" icon to save each screen.   4d. Making the returned string read-only When we return the users full name within our application, it is returned as an editable string in a hard box and has a label to the left hand side. This results in the string being wrapped, and looking pretty ugly. Lets go fix this. Open the screen scrFINDUSERResponse.   Click on the label text to the left of the return value.   Press delete. The label should now disappear. Click on the returned string field. On the properties box on the right hand side, change the "Read-only" property to "true". Click on the "File Save" icon to save this screen.   4e Getting rid of the "Message Sent" dialog When a user submits a new search, a dialog box pops up and says "Message Sent". This is quite annoying after a while. So lets go remove it: Open up the screen scrFINDUSERRequest.   Click on the submit button. On the properties box on the right, you can see the name of the script that this button will run. In this case, it'll run the FINDUSERRequest_onSubmit script. Open the script. As you can see, the second line of the script runs an event - scrMessageSent.display(). This javascript command literally runs the display event in the screen scrMessageSent - so as you can see, you can call other screens from script events within the MDS Application. Highlight this line, and press delete.   Click on the "File Save" icon on the toolbar to save this script.   As you have seen from this section, BlackBerry MDS studio is a fairly standard IDE. It shouldn't take long for you to become familiar with it. Return to Top   Summary    We've been on a whistle-stop tour around the whole BlackBerry enterprise development environment in this article, and got to the stage where we can: Expose some very simple application constructs using BlackBerry MDS studio Compile, deploy and test these applications Edit screen and script objects within MDS studio So we can quickly build and test some very basic applications. In the next article, we'll move on to passing complex class structures from your Domino Web services into the MDS studio, so you can start passing lists of user names or a complete person contact record. We'll also approach the whole issue of actually deploying these applications onto handsets. Return to Top           Copyright© 2007 LotusUserGroup.org Wellesley Information Services, and Lotus Education 990 Washington St., Suite 308s, Dedham, MA 02026.