.KEYWORD addressimport
.FLYINGHEAD INTEGRATING PALM DEVICES WITH LOTUS NOTES
.TITLE Converting Notes Address Books to the Web for Palm devices and pagers
.OTHER
.SUMMARY As publishers of both PalmPower and DominoPower Magazines, we’ve noticed a surprisingly high cross-over in interest between the two products. In fact, we’ve gotten requests from readers of both publications for more information about how to integrate Notes applications with Palm devices. As is often the case, your wish is our editorial content. In this fine article, Dan Velasco takes you through a complete application that lets you download your Notes address book information into your Palm device — and you can do it from your favorite Web browser. Just so cool.
.AUTHOR Dan Velasco
.BEGIN_SIDEBAR
As publishers of both PalmPower and DominoPower Magazines, we’ve noticed a surprisingly high cross-over in interest between the two products. In fact, we’ve gotten requests from readers of both publications for more information about how to integrate Notes applications with Palm devices. As is often the case, your wish is our editorial content. Dan Velasco takes you through a complete application that lets you download your Notes address book information into your Palm device — and you can do it from your favorite Web browser.
If you’re not a Notes developer, you may find this article a little "hard-core". We like to bring readers a wide variety of useful and informative content and even if you’re not a Notes or Domino user, you may get some interesting insights by reading Dan’s fine article.
.END_SIDEBAR
This article describes a project that started festering in my brain after I took an Advanced LotusScript class this past December. It came to the surface and wouldn’t let go of me until I had proven it could be done.
Here was the challenge: get address information about individual users from a Notes database into a handheld device. There was a catch. I didn’t want to use any third-party tools and I wanted to allow users to get the information from a Web page.
I had two handheld devices in mind, the Palm computer and the PageWriter 2000. Just about everyone knows about the Palm Connected Organizer. Few, however, know much about the PageWriter 2000. The PageWriter 2000 is a two-way pager from Motorola that has a GUI and a little miniature keyboard. If you were one of those lucky people that got to go to Lotusphere (the big Lotus conference in Orlando) this year, you almost couldn’t throw a stick into the crowd without hitting somebody that had one.
I do have to issue one little disclaimer. I used to work for the Advanced Applications group at SkyTel, the company that provides the networks that all PageWriters are currently running on. I left last October before I had the skill set to create an application that created these address books online. Now, of course, I do — and I’m going to tell you all about it.
.H1 Understanding the devices
What these devices have in common is the ability to import address book information into each device via desktop software. All you need to do is to put the information in the proper CSV (comma-separated values) format and then import that file directly into the desktop software. For the Palm device, I used the Palm Desktop and for the PageWriter 2000, I used PageWriter 2000 Partner Software.
Here is the theory behind this. Sometimes there are just a few addresses that you really want and you don’t want to have to go through the trouble of using a third-party tool to connect to that database and extract that information. Not every database is worth syncing with. Sometimes you just want to select a few key addresses and insert them into the address book on your device. Replication or performing a Palm HotSync is not always a priority or even practical.
Also, in the case of the PageWriter 2000, there is no Palm-like HotSync software just yet. Whatever addresses you want on the device you either must enter in by hand (via the tiny keyboard), type in manually via the Partner software, or import into the Partner software via a specifically formatted CSV file. As you might guess, the last alternative is the easiest.
Analyzing the correct format for importing the information is as easy. Just export some information from Notes and look at how it has been formatted. Then you just model your generated file after that export file to easily import information into the Palm Desktop or PageWriter 2000 Partner software.
To save you some time, we’ve listed the formats for each of the two devices in Table A. While the formats shown have worked for this project, you might also want to try doing an export of your own to verify our findings, especially if you’re using later versions of the device software.
.BEGIN_TAB_TABLE A Device file formats
.TAB_TABLE_HEADER Palm Desktop 2.0 field order PageWriter 2000 field order
.TAB_TABLE_ROW 1. Last Name
2. First Name
3. Title
4. Company
5. Work Phone
6. Home Phone
7. Fax
8. Other Phone
9. Email
10. Physical Address
11. City
12. State
13. Zip
14. Country
15. Custom 1
16. Custom 2
17. Custom 3
18. Custom 4
19. Notes
20. Private Flag (0 for false, 1 for true)
21. Category (Business or Personal, for example) 1. Person Name
2. Pager Type
3. Pager PIN
4. Fax
5. Home Phone
6. Work Phone
7. Email
8. Notes
.END_TAB_TABLE
.H1 Reviewing the possible solutions
There are basically two ways of exporting information out of Notes using nothing but your bare hands and programming skills. The first way, in fact, doesn’t even require your programming skills. You can export information out of Notes via a view by selecting Export from the File menu and then following the instructions of the Export Wizard. The only problem is that the Wizard only allows you to export information in three generic formats: Structured Text, Tabular Text and as a Lotus 1-2-3 Worksheet. In order to import that information into the desktop software of the device of your choice, you still have to open that file in a spreadsheet and manually save it as a CSV file
The problem with this is that it created a few extra steps for the end-user. Those extra steps, while straightforward to experienced users, could cause a novice user to make a mistake somewhere along the line and be unable to import the addresses into the device. Simply put, there were two many points of possible failure.
The other option and the one that ended up in the final solution was to use LotusScript to create an ASCII flat file containing the same information and then save it with a ".csv" extension. This way, the file is ready for importing into the application as soon as it has been created. There is no need to open it up or manipulate it further in any way. Just redirect the user to a Notes document with the CSV file embedded into it and let her download it and import it into her application right away.
.H1 A picture of the final solution
I always like to give a big picture of the final solution before going into details about how I did it. In Figure A, you can see a screen shot of how the Address Book Creator application looks on the Web.
.FIGPAIR A Here’s a picture of how the Address Book Creator application looks on the Web
Get your copy now!
You can download a Notes database containing all of the elements of the solution at http://dan.velasco.com. You can also find all of the LotusScript code listed there as well. I won’t go over every element of the solution here, but will instead focus on the key parts that were difficult to figure out so you will have an easier time creating similar applications.
.H1 The five hurdles
Here are the five hurdles to creating the application that you should know about:
.BEGIN_LIST
.BULLET Overcoming the lack of native multiple-item selection on the Web;
.END_LIST
.BEGIN_LIST
.BULLET Using the DocumentContext property of the NotesSession class;
.END_LIST
.BEGIN_LIST
.BULLET Properly signing the agent so it has sufficient rights;
.END_LIST
.BEGIN_LIST
.BULLET Figuring out the correct file structure of the server so you can temporarily place a file there;
.END_LIST
.BEGIN_LIST
.BULLET Deleting the file off of the server once it has been created.
.END_LIST
Let’s go through these hurdles individually and I’ll detail how to overcome them.
.H2 Enabling multiple-item selection on the Web
Fortunately for me, this was a fairly easy problem to solve, courtesy of Steve Devoll of Workflow Designs in Dallas (the Top Gun class people). He had given a presentation at Advisor DevCon in October 1998 that outlined the solution to exactly this problem. What you do is to mix a little old-fashioned HTML and Posting commands into your view and view template and then use a "catcher" form to basically get a handle on multiple items by their UNIDs.
You can see how you can put checkboxes onto the page that will calculate to the UNID of the document in Figure B.
.FIGPAIR B The User Information View on the Web uses HTML to capture the UNID via a checkbox.
The other essential component for making the multiple-item selection work is the $$ViewTemplate for the User Information Web View. You can see how this form looks in Figure C.
.FIGPAIR C Here you can see the $$ViewTemplate form for the User Information Web View.
.PAGE
The key part of this form is the line of HTML that tells the browser to send all of the UNIDs of all of the documents selected to the "CreateAddressBookForm" and then tells the browser to create a new document. Here’s the code that makes this happen:
.BEGIN_CODE
form method=”post” action=”http:\//adecconet.adecco.com/adecconet/globalchange.nsf/createaddressbookform?createdocument”
.END_CODE
Remember to customize this code to point to the correct location of the CreateAddressBookForm, shown in Figure D on your server.
.FIGPAIR D The CreateAddressBookForm is the piece of the application where it all comes together.
The CreateAddressBookForm "catches" all of the UNIDs of the User Information Forms that were selected on the previous page. Since you are posting this information using the HTML POST command and specifying within the URL that a document is created, the document automatically saves itself. So you put a $$WebQuerySave field (works on Domino Release 4.5 and 4.6) on the "CreateAddressBookForm" that is a computed or computed for display field that calculates to the name of the agent (in my case, "WebSaveCreateAddressBook").
.H2 Using the DocumentContext property of the NotesSession class
In order to get to the information that the user has just entered onto a Web page you must use the DocumentContext property of the NotesSession class. Once you master this, you’ve got a great way to get at the information the user enters via the Web and to make things happen with it. Here is the snippet of code that sets all of this up:
.BEGIN_CODE
Set session = New NotesSession
Set db = session.CurrentDatabase
Set note = session.DocumentContext
.END_CODE
.H2 Properly signing an agent using an ID that has rights to run unrestricted agents on the server
The next step, after having created the agent and customizing it to do your bidding, is to get somebody with proper access to sign the agent so that it has sufficient rights to work. Since the agent creates and deletes files off of the server itself, you need to have somebody sign it — somebody that has access to run unrestricted agents on the server it will be running on. Hopefully, this person will be you, the developer. But if it isn’t, don’t fret. This is a harmless agent that cleans up after itself. It’s just using the file system as a temporary holding place for the file it’s creating and then deleting it as soon as it has been attached to another document.
.H2 Figuring out the correct file structure of the server so you can temporarily place a file there
One thing that you need to be aware of is that you will need to customize the example I’ve provided for your own server’s operating system if it is running Unix or Solaris or something that does not use the same directory structure as Windows NT. I actually customized the agent so that it would run on a Sun Solaris server and all I really had to do was to put in a forward slash "/" instead of a backslash "\" when calculating the directory variable (where to put the file).
.H2 Deleting (killing) the file off of the server once it’s been created
Have you ever searched for a command to do something and then just stumbled across it and it was the simplest thing in the world? That was what happened to me when I was trying to find a way to delete the file off of the server. Here is the format:
.BEGIN_CODE
kill
.END_CODE
Seems way too simple, doesn’t it? I guess the lesson is that things don’t have to be too complicated in order to work.
.H1 Conclusion
One of the main reasons I’ve enjoyed working with Notes so much is that my persistence usually pays off. I’ll stick with a problem until I’ve licked it or decided that it’s not worth licking anymore. I’m happy to say that I’m rarely unable to come up with a solution that works.
I hope that this article has helped remind you of a similar need in your company that is just waiting for you to fill it. Applications and solutions don’t always have to be complicated to be great. They can just help bridge that simple gap that exists between the user and the information he wants. And sometimes that bridge is just a LotusScript agent and a CSV file away. It’s kind of like looking at Nikolas Tesla in those newsreel films that show him with a metal pole in each hand and suddenly a continuous spark goes from one to the other.
.BIO
.DISCUSS http://powerboards.zatz.com/cgi-bin/webx?13@@.ee6cbea
