.Domino Framework

Why Notes?

2008-07-03T15:49:11-04:00

During my time as a Notes developer (mostly as an independent contractor/consultant) I have had the chance to work with a large number of companies on four separate continents. In all that time I cannot remember a single client in which the Notes development was ever considered "strategic". In fact, in many, the attitude towards Notes was (and often still is) decidedly hostile. So if Notes is often seen (unfairly?) as the ugly duckling in the programming world, why is there so many Notes databases out there and so many Notes developers still being employed?

One of the reasons for this seems to be that fact that unlike many other development platforms, Notes has always extended down to reach many people who would not be typically classified as programmers. People can start out with a Notes template such as TeamRoom or Discussion Library and get a small application up and running pretty quickly. These same people then find that with little or no formal programming experience they can add a few fields to a form, add another column to a view or even create a whole new view from scratch. Then using nothing more than a few simple forms, views, and little bit of @functions and @commands a whole new application can be built to automate a task that may have outgrown an Excel spreadsheet or fits some new process. A few of the more adventurous "non-programmers" even find some basic LotusScript within their capabilities. To a seasoned Notes programmer many of these applications look decidely ugly and badly written but they are highly effective. They provide the basic functionality that is needed by the business and because they have usually flown underneath the radar screen nobody has bothered to question whether Notes is the right tool to use.

It is usually only when the application breaks, the creator leaves/transfers, or there is a need to enhance the application that it suddenly appears on the radar screen of a Notes development group. As a developer I often get assigned to work on applications that were orginally developed this way. Whilst I may be tempted to curse the bad design, inefficient code, and the fact a production application is running on a development server, I can also be thankful that another business process has found a home in the Notes development arena giving me work and the chance to show what Notes can really do! I have worked for some companies with as many as 80,000 non-mail databases of which less than 20% were ever supported by a Notes development group!

This feeder base of applications is an important part of the Notes development food chain. Without these applications many companies may have been able to contemplate a life without Notes (and Notes programmers).

I am not sure if the role of this type of development is fully recognized when the future of Notes is being mapped out. Few of these "non-programmers" are represented on the various forums such as IdeaJam, Planet Lotus, and IBM's Notes discussion forums. And they probably are not heavily represented at events like LotusSphere. And they almost ceratinly do not get to be design partners evaluating the latest release of Notes.

With the Notes 8.5 beta having been released I have started to wonder what impact the new development tools and environment may have on Notes "non-programmers". A full-time developer (especially one who has developed with Java), probably loves the move of Designer to eclipse. Notes developers who have long struggled with design issues such as joining views or developing Notes/Web client or Web only applications probably love the new capabilities of X-Pages and the extended JavaScript language. The Notes development world is beginning to look a lot more like Java and ASP.Net development environments. But are these capabilities going to attract more "non-programmers" or less? IBM have not yet made public too much about what the Notes development environment will look like post Notes 8.5 but it does seem like eclipse will at least be part of that. My hope is that in acquiring some of the tools that Java and .Net developers take for granted we do not take the Notes development environment out of reach of the "non-Notes" programmers. At least not until more companies understand that Notes truly is a strategic platform and it is OK to make it the #1 choice for developing many applications.

Does LotusScript Have a Future?

2008-06-30T15:27:28-04:00

One thing that has struck me about the Notes 8.5 beta is that X-Pages implements JavaScript as the only option for both client-sided and server-sided scripting. Neither @Language nor LotusScript appear to be supported directly but the "JavaScript" language has been expanded to provide @Formula emulation. The new server-sided JavaScript now also seems to be able to do some of the things only done in the past using LotusScript... When X-Pages is made available for the Notes client I am expecting to see support for JavaScript only. We already have LotusScript able to run on the Notes client and Domino servers, so why is IBM going to so much trouble to extended JavaScript for server-sided scripting? Could it be that LotusScript is not part of the long term vision IBM has for Notes development? As a devoted LotusScript programmer (biggot) I am hoping I am wrong...

The next version of Notes (post 8.5) promises to be a very interesting one for Notes developers. Consider a scenario in which:-

X-Pages provides an alternative to Forms, Views, Pages, and Subforms with the added advantages of running on both a Web client and a Notes client, plus the ability to link to non-Notes data sources;
X-Pages supports "JavaScript" directly but not LotusScript or @Formula
There is little or no future extension of LotusScript language to make it a more modern OOP language;
There are few (if any) enhancement made to "old-style "design elements such as Forms, Views, Pages, Subforms, Framesets, Outlines;
The Eclipse IDE does not provide native support for these older style design elements - although we do get the LotusScript editor almost everyone has been waiting for.

It sounds to me like a completely new Notes II programming environment has been created. An environment in which many of the Notes development paradigms of the past have been replaced, including either the death (or significant downsizing) of the role of LotusScript. Will we have the choice of staying with what we know (e.g. LotusScript & @Formulas) or will we have to move to a new way of doing things (most likely JavaScript based0)? And where does Java fit with this? Hopefully IBM will soon provide a clearer picture to the public of its plans for Notes development post Notes 8.0.

Perhaps those more in the know than I can comment about where I am completely wrong.... "Whenever you have eliminated the impossible, whatever remains, however improbable, must be true".

.Domino Framework 0.5 Beta Released

2008-06-27T13:43:52-04:00

The latest beta of the .Domino Framework has been released at OpenNTF. This release inclorporates the new Inspector tool and adds an application template that can be used to build a new application from scratch that includes the generic application components of the .Domino Framework.

Wordle of .Domino Framework

A new Notes data management tool (Inspector)

2008-06-24T15:18:32-04:00

I am just putting the finishing touches on what I believe will the most useful tool to be provided as part of the .Domino Frramework yet. The tool is called Inspector and the following provides a brief summary of what its capabilities will include in its initial release:-

View and change database properties
Select another database
Perform actions against the database (e.g. Open, Sign)
View data documents, profile documents, design documents, and deletion stubs
Build a document collection using any combination of search, FT search, view, or manual selection
Enter a Notes URL, NoteID, or Document UNID to select a specific document
Display the documents contained in the document collection.
Navigate through document collection
Perform actions against the document collection (e.g Setting field values, removing template inheritance)
Display details about any one document in collection
Display a list of items in the document
Perform actions against the document (e.g. Delete, Sign)
Display and edit information about any item in a document (type, value, flags)
For LotusScript Libraries show details of the classes, methods, & properties contained in the design document.

This functionality can invoked from ANY Notes database regardless of whether or not it implements the .Domino Framework. This is done via a Toolbar "Magic Button" that passes information about the current database/document to the .Domino Framework database.

I see a LOT of potential for expanding the tool further to expose even more of the functionality built into the .Domino Framework. E.g. Providing the ability to apply XSLT to transform data and design documents using styles sheets that reside in the .Domino Framework database.

The 0.5 Beta of the .Domino Framework onm OpenNTF is planned for later this week.

Domino.Reflection Namespace Extended

2008-06-23T17:22:08-04:00

I have just finished expanding the Domino.Reflection namespace to allow the new Inspector tool to browse the contents of LotusScript libraries.

Inspector will be able to display information about data documents, profile documents, design documents, and deletion stubs found in ANY database. Inspector will be able to provide a list of all (or selected) design documents found in a database (Domino Designer is not required).

As part of the display information for Design documents I have decided to provide information about any classes found in a selected LotusScript library. Using the extended DominoScriptLibrary class (part of the Domino.Reflection namespace), I can now return a list of properties and methods for a nominated class. I can also get the code used for any one of the properties/methods. Combining these features together Inspector becomes (amongst other things) a basic class browser for LotusScript libraries.

Both the extended Domino.Reflection namespace and the new Inspector tool will be released as part of the 0.5 beta of the .Domino Framework planned for the end of this week.

NotesURL and Resolve

2008-06-20T13:15:46-04:00

NotesURL is a property available for the NotesSession, NotesDatabase, NotesView, NotesForm, NotesAgent, and NotesDocument classes. It was one of those properties I had never really paid much attention to. That was before I found myself needing to pass references to Notes objects from one application to another. It is not the only way to pass references to these objects but it is perhaps one of the simplest to implement and is consistent across each of thes objects.

At the other end, the NotesSession class has a Resolve method. This is basically the reverse of NotesURL, taking the URL and converting it back into an object (it also works with HTTP URLs too!).

So lets take the scenario in which a Services Oriented Architecture (SOA) is being built. One application (Notes database) provides one or more services to other applications. These services could operate against a database, view, document etc. To invoke the service I need to provide a failsafe way to provide details about the database/view/document against which the service operates. I can pass this in a number of ways:-

Save the NotesURLs as environment variables in the Notes.INI
Create a document in the other database with the NotesURL(s) placed inside a field
Invoke a Web service (increases the ability for Non-Notes applications ualso using the service)

The alternatives for a NotesDatabase include servername and filpath, or replicaid. Server/filepath requires two parameters to be provided or an artificial way to combine these together. Replicaids represent a single string but lack the ability to designate a specific server (I may have made a change to a document on one server which has not replicated to other servers and hence the serice may not operate against the latest data if it uses another replica).

Views are more difficult to define as the only other standrad way to access a view in LS is via NotesDatabase.GetView. This requires the name or alias of the view and this is not guaranteed to be unique. Plus I need to make sure the parent database is also known. NotesURL and Resolve gives us a way of ensuring the exxact same view is used within the service.

NotesDocumehts have a DocumentUNID that serves us well, but again we need to provide a reference to the parent database for this to work. The NotesURL gives us all this information in a single string.

Note: It is also possible to serialize a NotesDocumentCollection by passing an array of NotesURLs. This is a litlle messier as more code is needed on the other side to reconstruct the NotesDocumentCollection.

I have used the above in the latest beta of the .Domino Framework to implement the new Inspector tool. This tool will provide a "magic button" to view/edit the attributes of the current database, document collections, and document. The code for all this to work resides in the .Domino Framework template. To get this service to work against any database (regardless of whether it implements the framework or not) I have devised a ToolBar button that will save details about the currenty database, view, document etc. and pass them to the Inspector tool via Notes INI variables. For applicatuions that implement the framework the ablity to pass information about the currently selected documenyts ina view is added without using Notes.INI variables. Because this is a Notes 6.0 framework I have not (yet) developed a Web Service option.

The .Domino Framewokr has also been expanded so that the constructors for the DominoDatabase, DominoView, DominoDocumentCollection, and DominoDocument classes can take a NotesURL as a parameter for the constructor.

Notes: Because the object refered to by a NotesURL can represent any one of the supported Notes classes it is sugessted that it be resolved into variant first. Invalid NotesURLs throw an eror so it is also necessary to set the apporpriate error trapping to handle this.

Example: The following code is the DominoDocument class to locate a document using a key that could represent a NotesURL, HTTP URL, NoteID, or DocumentUNID.

'/**
' * Locates an existing document based upon the document's key
' * @param Key  Key that can be used to locate the existing document (NoteID, UNID, Notes URL or HTTP URL)
' */
Sub GetByKey(Key As String)
  Dim NotesObject As Variant

  On Error Resume Next        ' Prevent error if key is not a a valid NotesURL
  If Ucase(Left(Key,Len(STRING_NOTES_PROTOCOL_PREFIX))) = STRING_NOTES_PROTOCOL_PREFIX Or _
  Ucase(Left(Key,Len(STRING_HTTP_PROTOCOL_PREFIX))) = STRING_HTTP_PROTOCOL_PREFIX Then
   Set NotesObject = Session.Resolve(Key$)
   If NotesObject Isa "NotesDocument" Then
    Set iDocument = NotesObject
    Exit Sub
   End If
  End If
  Select Case Len(Key)
  Case 8  ' Possible NoteID in LS format
   Set iDocument = DB.GetDocumentByID(Key$)
  Case 9  ' Possible Note ID in @Language format
   Set iDocument = DB.GetDocumentByID(Left(Key$,8) + Right(Key,8))
  Case 32 ' Possible UNID
   Set iDocument = DB.GetDocumentByUNID(Key$)
  End Select
  Exit Sub
End Sub

Editing Design Properties Via DXL In Designer 8.5

2008-06-20T11:22:49-04:00

Whilst a native eclipse editor is not yet available in Designer 8.5 for Forms and View it seems that option is provided to edit the DXL for these design elements. This provides both raw DXL/XML code and a node/property tree for these design elements. There are times when this can be a distinct advantage over the traditional Domino Designer tool to find and set values (e.g. search and replace". Not all Design elements are supported (e.g. LotusScript Libraries).

Is Notes Programming As We Know It About To Change Forever?

2008-06-19T16:00:54-04:00

Let me first start by saying I am not a design partner and I do not have any inside contacts at IBM, so I have absolutely no inside information as to what IBM's plans are for the future of Notes programming. But because I am not subject to any non-disclosure agreements I am free to speculate and say whatever I like. If I start to take a closer look at the tea-leaves now forming at the bottom of my yellow mug I wonder if there may be a pattern forming I had not seen before....

I have been taking a much closer look at X-Pages, the new design element that is part of Notes 8.5. This design element looks nothing like any other existing Notes design element. And not just because of the new Eclipse editor. I see a whole bunch of new controls that remind me more of my time as an ASP.Net developer than they do of Notes development. I see the ability to bind these controls to data sources that include not just Notes documents and Notes views but also to SQL-databases and XML. Again, this is not unlike ASP.Net development (except for the ability to natively link to Notes databases). I also see that as I design an X-Page, it is building XML code which I can not only see but edit directly....

And when you look at the functionality of X-Pages, they seem to be able to do pretty much everything that many of the existing UI elements of Notes (Forms, Subforms, View, and Pages) can do. Except that I can now combine them in ways that were never possible with these other design elements. A number of other bloggers are starting to rave about the really cool stuff they can do using X-Pages.

I believe IBM are on record as saying they intend to make X-Pages available for the Notes client in a later release. So what does that mean? Unless X-Pages for Notes has a different set of controls that mirror more closely the existing set of controls I am probably going to be soon building new applications for the Notes client in a completely new way. And thanks to X-pages these applications will look and behave the same on a Web client.. If X-Pages provides the functionality of other design elements such as forms why would I use both in an application? Perhaps I am not supposed to? Perhaps in a post Notes 8.5 world I am now supposed to do most of my UI design using ONLY these new design elements such as X-Pages?

Perhaps round-tripping of DXL is not an issue for IBM because they see a future for us developers where we will be able to edit the XML from inside Notes. Perthaps IBM are not making a major push to develop Eclipse editors for Forms, Pages, and Views because they see these design elements going the way of the Navigator (i.e. no new features added in future releases). Perhaps there is no need to extend other Notes design elements such as views to support style sheets for the same reason.

It is not immediately clear If LotusScript will form a key component of the brave new world. I am hoping so, because one of the reasons I believe the world has as many Notes applications as it does is that non-programmers (and many programmers) are often better able to teach themselves to program in BASIC-based programming languages much more so than they have ever been able to with Java, C, or JavaScript like languages...

The tea-leaves are still swirling around and so the future may show that I am completely wrong. (But I do hope the dead fly floating at the top is Sharepoint!). But just in case I am not completely wrong , I would suggest Notes Developers take a very close look at X-Pages - even if you do not do a lot of Web development. X-Pages (and custom controls) just might provide an insight into how you will be building Notes client and dual client applications in the years to come. Oh... and read the blogs of those that are design partners. They may not be able to say a lot just yet... but look at what they don't say!

Defensive Programming

2008-06-18T16:24:22-04:00

Defensive programming involves writing code in such a way as to handle unforseen circumctances. Too often when I look at code that is developed for Notes applications I see little or no evidence of defensive programming being used.

Notes applications more than any other of the major development platforms cries out for defensive programming. Unlike SQL-based databases, Notes databases do not have a data schema and hence do not require that every document (row) contain the same finite list of fields (columns). Nor does Notes require that each field (column) be of the same data type. Notes fields also do not restrict if it can represent a single value or a list. So there is always the real risk that the data may not contain what you expect.

As an example, lets look at an employee record which has an EmployeeNo field.

The following LotusScript code could result in an error for for many reasons:-

EmpNo = Doc.EmployeeNo(0)

The variable Doc may not yet be instantiated (i.e. be connected to an existing Notes document)
The field EmployeeNo may not exist in the current document
The value inside the EmployeeNo may not be of the same type as the variable EmpNo. (it is not even clear from the code whether EmpNo is text or a number.
Unlikely, but should EmployeeNo ever become a method or a property of the NotesDocument class then the code would no longer work.

The following alternative code protects us from many of the above potential problems.

If Not Doc Is Nothing Then

If Doc.HasItem("EmployeeNo" Then

EmpNo$ = CStr(Doc.GetItemValue("EmployeeNo"(0))

End If

We are making sure that we have a Notes document
We are making sure the document has an EmployeeNo field
We have made it clear in the code that we are expecting a string (The $ in EmpNo$ causes LotusScript to make sure EmpNo has been declared as a String)
We are making a reasonable (but not complete) effort to convert any non-text values to a text value (assuming the values should be text). i.e. This works for numbers or dates but would fail for a Rich Text field.

This of course results in a lot of extra code being required each and every time you attempt to access the contents of a Notes field. Which probably expains why people often don't bother!!!

Another approach that can result in a reduction in the amount of code required and making the code easier to follow is to adopt Object Oriemted Programming techniques to make EmployeeNo a property of an Employee Class

Class Employee

Property Get EmployeeNo$ As String

If iDocument Is nothing Then Exit Property

If iDocument.HasItem("EmployeeNo$) Then EmployeeNo$ = Cstr(iDocument.GetItemValue("EmployeeNo"(0))

End Property

End Class

Now each time I need to access the EmployeeNo field in my application I can write the code as

EmpNo$ = Employee.EmployeeNo$ or If Employee.EmployeeNo$ <> "" Then

You will notice within the .Domino Framework that this technique is used repeatedly, especially when using the DominoDOcument class and extensions of that class. The .DominoFramework also provides a property generator tool that automatically generates the LotusScript code for a property based upon the property name, notes field name, and the intended data type. This takes a lot of the hack work out of creating all the property definitions needed when creating a new class.

Note: The above is but one of many defensive proramming techniques that could be employed. In many cases it comes down to personal preference, coding style and/or coding standards.

Retaining Month End Dates

2008-06-17T16:28:46-04:00

When calculating milestones based upon a starting date it can often be necessary to treat the "last day of the month" a little different to other dates. That is, if the base date is 28 Feb 2007, then "next month" is usually held to be March 31 2007 and "next year" is usually held to be 29 Feb 2008. Whereas if the base date is 27 Feb 2007 then "next month" is usally held to be 27 March 2007, and "next year" is held to be 27 February 2008. This result can be achived by always adding one day to the starting date, incrementing it by the required amount and then subtracting 1 day. When a starting date is the last day of the month,adding 1 day moves the date to the 1st of the next month. After adjusting the date subtracting 1 day will move dates still on the first of a month back to the last day of the previous month. This not only accounts for differences in the number of days in each month but also those pesky leap years.

DominoUIDocument Class Goes

2008-06-17T12:58:59-04:00

When developing the .Domino Framework I always had problems distinguishing the relationship between the DominoDocument (NotesDocument) and DominoUIDocument (NotesUIDocument) classes. It didnt seem like the DominoUIDocument class should have many properties or methods as these should typically be part of the DominoDocument class. Typically an extension of the DominoUIDocument class would only have event handlers. Regardless of whether I accessed a document via the foreground or background I really needed to have the same set of rules applied to the object. E.g. The same validation/transformation/logging needs to be applied to the property of an object when it is edited on a form, edited via in-view editing, and/or assigned a value in an agent.

So after giving this a lot of thought I have decided to remove the DominoUIClass as part of the next release. The DominoDocument class will now extend both the NotesDOcument and NotesUIDocument classes. By passing a NotuesUIDocument to the constructor of the DominoDocument class the framework is able to establish that the document is being accessed in the foregorund and make available those additional features that only apply when editing a document via a form. I feel confident this will lead to a cleaner, simpler solution for working with Notes documents in an object oriented way.

Note: One of the reasons the .Domino Framework is still in beta is so that I can do this (remove/rename classes and/or change the footprint of methods/properties).

Notes 8.5 Will Not Be Supported

2008-06-16T15:08:18-04:00

Having undertaken a review of the Notes 8.5 public beta I have decided that I will not be developing a version of the .domino framework for the 8.5 release. My current plans were (and still are) to release 1.0 of the .Domino Framework later this year that is fully supported with Notes 6.0+. After this initial release I had planned to then jump to Notes 8.5 and start developing functionality specific to this release.

I find Notes 8.5 to be a major disappointment for Notes client development and see no compelling reason to develop a version of the .Domino Framework for this release. For one thing there is little or no new features in this release specific to Notes Client functionality. The design elements such as X-Pages and Custom controls are supported on the Web client only. Then there is the new eclipse IDE which does a great job for these new design elements but leaves all the existing design elements worse off than before. (And don't get me started about the absence of an eclipse editor for LotusScript!!!). So until IBM starts to get fair dinkum with providing something new for Notes client development All post 1.0 releases of the .Domino Framework will be developed for the Notes 8.0 stream. This includes support for composite applications - something I am quite excited about. I suspect a lot of people will bypass this release of Notes anyway and wait for the REAL 8.5 release to become available.

DominoDocumentCollection.Sort

2008-06-13T15:30:49-04:00

DominoDocumentCollection.Sort - verb - origins unknown - Geek speak for sorting a collection of documents...

Sorting algorithms are typically implemented to only sort scalar values (text, numbers, dates). The .Domino Framework implements a combination of the QuickSort and SelectionSort algorithms as part of a generic atfSort function included within the Domino.@Functions namespace. The next beta release of the .Domino Framework will contain an enhancement to this function to sort vectors. Vectors are a way of storing complex data structures by separating them into two components (1) The object itself and (2) a key value. The .Domino Framework implements vectors via a simple DominoVector class which is found in the base Domino namespace.

The sorting of document collections therefore becomes one of creating a collection (array) of vectors in which the value is a NotesDocument and the key is whatever value is desired to sort the collection (e.g. UNID, date last modified, or the value of a specific field). Following my posting yesterday on the DominoDocumentCollection class Nathan Freeman provided some cool code for sorting a document collection based upon a specific view. Thanks to Nathan's contribution I have now been able to extend the functionality of the new Sort method to allow the documents to be sorted in the same order they appear in a designated view.

The 0.5 beta release (which includes this new method) is expected to be published on the 29th of June .

Tip: A Simple Implementation of .Domino Framework

2008-06-12T14:55:32-04:00

For those of you have have asked the question "How do I use the .Domino Framework in my applications?"... The simplest approach is as follows:-

1) Copy the following LotusScript Libraries from the template to your application:-

base.Domino

base.Domino.Applications

base.Domino.Errors

base.Domino.@Functions

Domino

Domino.Applications

Domino.Errors.OpenLog

2) Create a new LotusScript Library Domino.Applications.applicationname and include the statement Use "Domino.Applications".

3) Create new classses within this LotusScript library that extend the classes found in Domino.Applications (e.g. DominoDocument). These classes add proprerties/methods that are specific to your application.

Note: You can exclude Domino and Domino.Applications libraries, but your application will now be extending classes such as baseDominoDatabase, baseDominoDocument instead of DominoDatabase, DominoDocument and the include becomes Use 'base.Domino.Applications"

The above provides the core Business Logic Layer of the .Domino framework implemented via LotusScript. Presentation Layer components and advanced business logic components require additional design elements to be copied from the template. The template does document the design elements used by specific components.

DominoDocumentCollection Class

2008-06-12T12:54:29-04:00

The next beta release of the .Domino Framework will contain a significant extension of the DominoDocumentCollection class.

Unlike the NotesDocumentCollection class, it DOES have a constructor making it possible to gather a wide range of document collections, including an EMPTY document collection.

The NotesDocumentCollection extended by this class depends on the type of parameter passed to the constructor:-

Nothing: Creates an empty document collection for the current database
NotesDocumentCollection: Extends a NotesDocumentCollection you provide
NotesDatabase: Collection with all documents in the database
NotesSession: The list of documents an agent or view action is set to run against
NotesNoteCollection: A collection of the design notes
NotesViewEntryCollection: Converts the view entry collection to a document collection
NotesDocument: Creates a document collection with a single document
NotesView: Creates a document collection with all documents in the view
ENUM_COLLECTION_TYPE_CONFLICTS (Constant): Collection of all conflict documents in current database
ENUM_COLLECTION_TYPE_LOCKED (Constant): Collection of all locked documents in current database
ENUM_COLLECTION_TYPE_READERS (Constant): Collection of all documents in current database with reader fields
ENUM_COLLECTION_TYPE_AUTHORS (Constant): Collection of all documents in current database with author fields
String Array: Builds a document collection assuming the elements in the array represent any combination of Note IDs, Document UNIDs, Notes URLs, and/or HTTP URLS.

The class will also contain an AddDocuments method. Similar to the NotesDocumentCollection.AddDocument method, this will provide the ability to add multiple documents to the document collection, including most of the options provided in the constructor.

Application Template

2008-06-10T13:06:49-04:00

The 0.5 Beta release of the .Domino Framework will contain an application template. This is another one of the many missing pieces of the framework that I wish to complete before the framework is ready for a 1.0 release. The .Domino Framework contains so many pieces that it is often difficult to establish which components should be included when building an application based upon the .Domino Framwork. The new template will contain all the components that can be used in building a Notes application. Notes developers can then delete the components that are not required for an application (e.g. exporting to Excel, importing holidays, managing keywords etc.). I am also working on the documentation contained in the templates and the wiki to help developers better understand how to create applications using the .Domono Framework as a component library as well as how to extend the framework within each application.

Note: Every Notes application I now build is based upon the .Domino Framework and it is halving the time it takes me to build these applications.

LotusScript Revamp (20 Things I'd Like To See)

2008-06-09T13:36:06-04:00

It has been a long time since the LotusScript language received any major attention. The time is rapidly approaching where the language needs a major upgrade to compete with other programming languages such as Java, C#, and VB.Net. The following is a list of the 20 features that I would most like to see added to LotusScript: (many of which are already posted on IdeaJam)-

Allow the extension of product classes such as NotesDocument
Provide a construct (similar to .NET LINQ) allowing LotusScript to perform SQL operations such as joins on views.
Allow method overloading (defining a single method with multiple options for the parameters - # and type)
100% Fideltity exporting and importing data using DXL.
Expand the list of properties exposed by product classes to include all those other properties already available within the C API.
Add a Try/Catch construct as an alternative to On Error Goto (with VB.Net it is Try Catch End Try)
Allow optional parameters for a method (sub/function)
Add "enumerations" (as per .Net) as a construct within a class. This would allow keywords to be added without necessarily having to assign keywords specific value.
Add the ability to serialize a class into text, XML, and/or binary formats. This would be especially usefull when passing data via a Web Service.
Allow field events to be trapped outside the form (e.g. allow an external class to trap when a field value has changed)
In addition to Public/Private classes, add the ability to define abstract and sealed classes.
Provide greater support for polymophism, including the ability to cast a object from one class to another.
Add the ability to define extension methods as a way of adding to/modifying the behviour of classes (as per C# 3.0)
Provide a constructor for the NotesDocumentCollection class
Add an AllDocuments property to the NotesView returning a NotesDocumentCollection.
Extend the NotesUIWorkspace class so that access can be gained to any window presently open on the workspace.
Implement interfaces as a way of specifying properties/methods that must exist in a class implementing a specific interface.
Add Reflection, in which it is possible to establish if a class has a specific property/method.
Devise a simple way to tell if a Rich Text field is empty
Add iterators for document collections. e.g. Forall NotesDocument in NotesVIew or ForAll NotesDocument in NotesDocumentCollection.

.Inspector

2008-06-06T11:24:09-04:00

I am presently working on the next piece in the . Domino Framework puzzle for the next beta release (0.5). It is a data administration tool I have assigned the name .Inspector. It seekes to bridge the gap between simple document editing found in those "Magic Buttons" and full-blown data management products such as NoteMan and ScanEz. Using the DominoDatabase, DominoDocumentCollection, and DominoDocument classes developed as part of the .Domino Framework the tool allows a developer or administrator of an application the ability to:

View information about the database, document collection, document, and items
Use a range of techniques to build a collection of documents from a database
Perform a wide range of tasks against each of the above items (e.g. sign a database, remove a field from all documents in collection)
Display information about profile documents, design documents, deletion stubs etc. held in a database.

If anyone has any ideas of the type of features the could/should be provided in a FREE data management tool, please let me know....

Dirty Reads

2008-06-04T14:04:11-04:00

A "Dirty Read" occurs when a document you open a document in read mode and somebody subsequently edits the document. You now have a copy of the document which is no longer valid. If document locking is enabled for an application then Notes detects this situation and prompts the user to close the document and reopen it from the view. The document remains in read mode. In Notes 6.0 at least, if you again attempt to edit the document it actually allows you to edit the document without having re-opened it.

A a way of preventing dirty reads the .Domino Framework has added a PreventEditIfLocked method to the DominoDocument class (See previous blog). This method now supports two ways of handling the situation. The first is to close and reopen the document. But this does not seem to always refresh the document. The second (new) option is to display the same Notes error message and remain in read mode via a new DirtyReadAlert method. This exposed what appears to be a "bug" in Lotus Notes (NO.... I hear you say!!). It would seem that the document locking mechanism does not handle the situation in which a QueryModeChange event returns false and the document does not switch to edit mode. The edit lock is already in place and because the document is now not in edit mode is does not unlock the document when it is closed leaving the document permanently locked. To address this scenario the DIrtyReadAlert also unlocks the document.

'/**
' * If document is locked by another person then prevent document from being edited. Used with document lcoking, this prevents potential conflicts that can occur
' * if a document is placed in edit mode after another has changed the document on another server. Action taken can be either to repeat the same message generated
' * the first time by Notes, or to close and re-open the document
' *
' * @param Source     The NotesUIDocument to be protected
' * @param DisplayMessage True = Display message each time, False = close and re-open document
' */
Sub PreventEditIfLocked(Source As NotesUIDocument,DisplayMessage As Boolean)
  If Me.IsLockedBySomeoneElse Then
   If DisplayMessage Then
    On Event QueryModeChange From Source Call DirtyReadAlert
   Else
    On Event QueryModeChange From Source Call ReloadDocumentFromView
   End If
  End If
End Sub
Private Sub DirtyReadAlert(Source As NotesUIDocument,Continue As Variant)
  On Error Resume Next
  Call Source.Document.UnLock
  Msgbox "Document has been modified since opening, reopen in edit mode from view.",,"Lotus Notes"
  Continue = False
End Sub

Testing Workflow Applications

2008-06-04T11:49:22-04:00

Testing worklow applications can often present challenges if the application itself is not set up with testing in mind. Amongst the issues workflow introduces into application testing is ensuring that people outside of the test group do not end up being recipients of unwamted email notifications. To help me test Notes applications I have developed the practice of calling a specific method to send an e-mail. This method would devise some way of testing for a "production" application. If the application is not running in "production" then the e-mail notification would be modified to replace the recipients with the current user. The list of original recipients are then appended to the bottom of the e-mail so that the tester can verify that the distribution list is valid. Because the tester now receives all the notifications generated they do not need to run around to other people to verify that they got the necessary notifications...

An example of the code is provided within the .Domino Framework as part of the baseDominoMessage class contained within the Domino.MailServices namespace. This implementation assumes the presence of a profile document that contains applications settings, including a designation of the environment of this instance of the application (e.g. Development, QA, Production). The method also provides an option to bypass sending any message when not running on a production server.

Sub Notify(testSend As Boolean)

  If Application.ApplicationSettings.isTestServer Then
   If Not TestSend Then Exit Sub
   Call Me.AppendText("",1)
   Call Me.AppendText(Ustring$(80,"_",1)
   Call Me.AppendText("This notification has been generated from a test database",1)
   Call Me.AppendText("In production the recipients would be: ",1)
   Call Me.AppendText("To: " + Join(Me.SendTo,",",1)
   Me.SendTo = Session.UserName
   Call Me.AppendText("CC: " + Join(Me.CopyTo,",",1)
   Me.CopyTo = ""
   Call Me.AppendText("BCC: " + Join(Me.BlindCopyTo,",",1)
   Me.BlindCopyTo = ""
  End If
  Call iDocument.Send(True)

End Sub

Notes 8.5 Disappointment

2008-06-03T11:23:58-04:00

IBM did such a great job with Notes 8.0 in improving the overall UI and the Mail database and bridged the gap between Notes and Outlook. Finally it looked like "we" (IBM and the Notes community) were moving forward again with Lotus Notes. While I would have loved to have seen a lot more done for developers in 8.0 I can understand IBM's need to focus on bring the Notes client into the 21st century. I am not sure if it was just me, but somehow I developed an expectation that the needs of the Notes developer would be the central theme with Notes 8.5. As a result I was already looking forward to the release of 8.5 even before I got to use 8.0.

Over the weekend I downloaded the first public beta of 8.5 and almost immediately jumped into the new eclipse version of Domino Designer to see what goodies were there for me to use. There were some obvious signs of a slicker interface as per the Note 8 client. Useful but not really something I was hanging out for. I had heard all the talk about what an eclipse IDE would do for things such as LotusScript so the first thing I did was open up a LotusScript library from the .Domino Framework to see what I could now do. There was a new property box eating up space at the bottom of the screen and.... THAT WAS IT. The property box did not even provide any useful data. It just sat there empty consuming space. Where was the class browser? Where was typeahead for anything but production classes? OK so the new IDE is still not there yet, surely there is a swag of other new development features for me to use.

X-Pages, these look really cool but I rarely get to do much Web development so this is not a big gain.
Server-Sided JavaScript, again great if you do a lot of Web development
Themes, works with X-Pages only, which work for Web client only....
Dojo, another cool Web development tool (A pattern is emerging)
New LotusScript methods for NotesDocumentCollection GetAllReadDocuments, GetAllUnreadDocuments, Intersection. Something I guess but I don't recall ever needing methods like this. Where is the constructor for NotesDocumentCollection? That would at least be useful!
YES , finally an extension to the LotusScript language! Oh, the ability to set the system date and time. In 15 years of Notes development I don't recall ever needing to do that. I thought we had operating systems that managed the clock!

So after all the hype and all the wait I get practically NOTHING to help me build Notes Client applications. It makes me envious of all the Domino Web developers who did at least get something in this release. I can only hope something new appears before the final 8.5 release because IBM have gone nowhere in bridging the gap between Domino Designer and modern IDEs such as Visual Studio. Perhaps we are not important in IBM's plans after all. Which begs the question, why go to all the trouble to revamp the Notes client with 8.0 and then do so little for developers who develop applications that run on that client?

.Domino Framework 0.4 (Beta) Released

2008-06-02T15:45:44-04:00

The next beta of the .Domino framework has now been released an OpenNTF.

The features covered in this release include:-

A modified UI that incorporates Web 2.0 Framesets
Tools for handling conflict resolution
Tools for managing document locking
The start for adding an RSS Feed to an application
A tool to add a watermark to design documents
A large number of small improvements to the class libraries
Further building out of the .Domino Framework Wiki

Note: This is still beta code and a lot mor\e work is required to fully test and fine tune the features already included.

Document Locking Bug

2008-05-29T18:53:52-04:00

With Notes 6.0 there appears to be a bug with document locking in the scenario in which UserA is editing a document and UserB then attempts to edit the same document on another server while UserA is still editing the document. When this happens UserB will be able to open the document but it will remain in read mode while UserA is editing the document. When UserA has finished editing the document UserB can then place the document in edit mode. The first time this is attempted a warning message is issued that USerB must re-open the document from the parent view and the document remains in Read mode. If UserB ignores the message and again attempts to edit the document without reopening it from the parent view the document actually opens in edit mode. If UserB then closes the document without making any changes, a lock is placed on the document by UserB that is not released after the document is closed. This can lead to an accumulation of locked documents in the database.

To solve this scenario I have extended the .DominoFramework as follows:-

A property has been added to the DominoDocument class that allows the detection of a document that is locked by somebody else:-

Property Get IsLockedBySomeoneElse As Boolean
IsLockedBySomeoneElse = iDocument.LockHolders(0) <> "" And Isnull(Arraygetindex(iDocument.Lockholders,Session.UserName))
End Property

A new PreventEditIfLocked method can then be invoked by the PostOpen event on the form. This adds additional code to the QueryModeChange event to trap the scenario in which a locked document is subsequently placed in edit mode:-

Sub PreventEditIfLocked(Source As NotesUIDocument)
If Me.IsLockedBySomeoneElse Then On Event QueryModeChange From Source Call Reload
End Sub

The Reload method that is now triggered by the OnQueryModeChange event then closes the document and re-opens the document. This is done via an agent as I was unable to find any other way of forcing the current document to be closed and the re-opened. It was also necessary to unlock the document at this stage as it appears this is where the forgotten lock is enabled.

Sub Reload(Source As NotesUIDocument, Continue As Variant)
  Dim Agent As NotesAgent

  On Error Resume Next
  Call Source.Document.UnLock
  Call Source.Close(True)
  Set Agent = DB.GetAgent("aReopenDocument"
  If Not Agent Is Nothing Then Call Agent.Run(iDocument.NoteID$)
End Sub

And finally, the agent to open the document is as follows:-

Sub Initialize
Dim Session As New NotesSession
Dim UIW   As NotesUIWorkspace
Dim Agent  As NotesAgent
Dim Doc   As NotesDocument

If Session.IsOnServer Then Exit Sub
Set Agent = Session.CurrentAgent
Set Doc = Session.CurrentDatabase.GetDocumentByID(Agent.ParameterDocID$)
If Doc Is Nothing Then Exit Sub
Set UIW = New NotesUIworkspace
Call UIW.EditDocument(True,Doc,,,False)

End Sub

All of the above code will be included as part of the 0.4 beta of the .Domino Framework planned for this weekend.

Removing Duplicates

2008-05-28T13:48:14-04:00

Today I had an application in development in which an LEI Activitiy was somehow creating a small number of duplicate records. Rather than try to figure out why LEI was creating duplicates I chose to simply create an agent to delete the duplicates. I have extended the .Domino Framework to add a RemoveDuplicates method for the DominoView class.

To Make this work:-

Create a view that sorts documents by the "key" with the key being in a column (for partial keys concatenate the values).
(Optional) add a second columns that sorts the documents in such a way that the duplicate to be retained is at the top (e.g. creation date)
Invoke the method using an action button on the view, and agent (manual or scheduled).

The methods created takes a column number as a parameter for the column containing the key anbd returns a count of the number of duplicates removed.

'/**
' * Remove all duplicate entries in view by retaining the first entry listed for each duplicate value
' *
' * @param ColumnPos The column number to be used to identify the unique values
' * @return  The number of documents deleted from the view
' */
Function RemoveDuplicates(ColumnPos As Integer) As Long
  Dim AllEntries   As NotesViewEntryCollection
  Dim Doc     As NotesViewEntry
  Dim LastDoc   As NotesViewEntry
  Dim NextDoc   As NotesViewEntry

  If iView Is Nothing Then Exit Function
  Set AllEntries = iView.AllEntries
  Set LastDoc = AllEntries.GetFirstEntry
  Set Doc = AllEntries.GetNthEntry(2)
  While Not Doc Is Nothing
   Set NextDoc = AllEntries.GetNextEntry(Doc)
   If Doc.ColumnValues(ColumnPos%) = LastDoc.ColumnValues(ColumnPos%) Then
    RemoveDuplicates = RemoveDuplicates + 1
    Call Doc.Document.Remove(True)
   Else
    Set LastDoc = Doc
   End If
   Set Doc = NextDoc
  Wend
End Function

View Action:

Sub Click(Source As Button)
Dim Count As Long
Count& = View.RemoveDuplicates(0)
If Count& > 0 Then
Msgbox Cstr(Count& + " duplicate documents deleted",MB_OK+MB_ICONINFORMATION
Else
Msgbox "No duplicates found",MB_OK+MB_ICONINFORMATION
End If
End Sub

ODS 48 And Unfiled Documents

2008-05-19T16:20:22-04:00

This is an FYI for those currently in the process of migrating to Domino 8.0/8.0.1.....

One of my clients is migrating from 7.0 to 8.0.1. They have customized their mail template to include a view that displays documents not filed in any folders. This view uses the special view type "Shared, contains documents not in any folders". It was found that when a user's mail database was upgraded to the lated ODS (48), this view would no longer work. The view simply does not display inside the mail database and the Domino server reports error trying to process the view. For now we have held off on upgrading mail files to ODS 48 pending a solution to the issue.

Document Locking

2008-05-19T16:11:57-04:00

One of the projects I am presently working on involves enabling document locking for an application using the Document Locking feature introduced with Notes 6.0. I had done this before with Notes 6.0 and recall there are issues with documents sometimes remaining locked even after the user has finished editing the document. And sure enough, when we started UAT we got reports of document being locked even though no-one was still editing the document. As part of the process for resolving this I have added Document Locking as a new feature within the .Domino Framework.

A new view ($Locked) has been created as a way of clearly displaying those documents that are presenty locked (i.e. the $Writers fields is present).

I have added a view action to remove the lock by deleteing the $Writers and $WritersDate field from the document . This allows people without Manager access to maintain the locks.

Testing done so far has shown that when the lock fails to be removed, the $writers field is present but the $WritersDate field is not present. I have therefore added a RemoveInvalidLocks method to the DominoDatabase class that will remove any document in the ($Locked) view for which this situation arises. By creating an agent the runs periodically against the database invoking this method it is possible to locate and correct these issues as they occur.

Note: Further testing is still required to ensure that only invalid locks are being removed and that this technique is identifying all the document locks that persist after they are no longer needed....

Replication And Merging

2008-05-14T13:17:44-04:00

Today I was testing an application to make sure that changes made to ensure replication merged changes at the field level rather than the default document level. To do this we set up replicas on two different dev servers. Because the two servers do not normally repolicate with each other (and because we didn't want to wait that long) I decided to replicate the databases manually from my workstation. When I did, I found that the documents did not merge changes at the field level but at the document level. My initial thoughts were that there was a problem with the field level merging. Later we figured out a way to get the servers to do the replication. When the servers initiated the replication the field level merging took place as intended.

It would appear that replication that is initiated from the Notes client (Notes 6.0) does not perform field level replication. I need to do some further tests to confirm this, but obvioulsy I need to be careful when I use my workstation to replicate databases as this may very well result in a different outcome for applications designed to merge changes at the field level... Yikes

Adding an RSS Feed To A Notes Application

2008-05-12T16:15:39-04:00

On of my challenges for last week was to find an easy way to add an RSS feed to a Notes application. After doing some research on the topic I found that the XML required for an RSS feed is fairly simple and there were already a number of excellent examples out there within the Notes community. In the spirit of the .Domino Framework I wanted a generic solution which could easily applied to multiple applications. In the end I based some of my my code on the OpenNTF Blogsphere (thanks Declan).

I have created a new DominoRSS Feed class. This is intented to be part of a new Domino.Applications.RSS namespace but I have been having technical problems getting the same code to run as a Web agent when placed in a LotusScript library. So, for now, the class definition is included as part of the agent.

A new agent has been developed with an alias of content.rss that invokes various methods/properties in the class to generate the necessary XML. The code for the agent is as follows:-

Sub Initialize
Dim RSSEngine As DominoRSSFeed

Set RSSEngine = New DominoRSSFeed(Nothing)
RSSEngine.NotesLinks = True
Call RSSEngine.GenerateHeader
Call RSSEngine.GenerateViewContent("($RSS)",0)
Call RSSEngine.GenerateFooter
Call RSSEngine.WriteXML
End Sub

The NotesLinks property is used to determine if the RSS Feed should publish links using http protocol (default) or Notes protocol. In my case I wanted the documents to launch in the Notes client as the source application is not Web-enabled.
The GenerateHeader method creates the initial XML for the feed/channel
The GeneratViewContent method creates the XML for the feed based upon the contents of the provided view. The view can be any view with the programatic column name for each column used to create XML elements. Use any of the available RSS feed attributes such as "title", "description","author","pubDate" to map the view content to the RSS feed.
The GenerateFooter method creates the closing XML
The WriteXML method takes the XML held internally within a NotesStream and writes it back to the screen.

I can now make any application RSS enabled by simply adding the agent (with the DominoRSSFeed Class) and having a view that meets the requirements above.

Note: The code for the class will be published as part of the next beta of the .Domino Framework later this month. .Domino Framework wiki will provide documentation on the RSS Feed XML. I will also be working on an enhancement to define various RSS attributes (e.g. Description) as part of the Application Settings.

Universal Time

2008-05-09T14:17:09-04:00

The following property has been added to the DominoDateTime class to allow a date/time value to be represented in a format consistent with ISO 8601's Universal Time (UTC). This will be available as part of beta 0.4 later coming this month.

'/**
' * ISO Coordinated Universal Time (UTC) format for date
' */
Property Get UTC As String

  Dim UTCDayName As String
  Dim UTCDay    As String
  Dim UTCMonth   As String
  Dim UTCYear   As String
  Dim UTCTime   As String
  Dim UTCSign   As String
  Dim UTCZone   As String

  If iDate Is Nothing Then Exit Property

  UTCDayName$ = Format$(iDate.LSLocalTime, "ddd"
  UTCDay$= Format$(iDate.LSLocalTime, "dd"
  UTCMonth$ = Format$(iDate.LSLocalTime, "mmm"
  UTCYear$ = Format$(iDate.LSLocalTime, "yyyy"
  UTCTime$ = Format$(iDate.LSLocalTime, "hh:nn:ss"
  If Sgn(iDate.TimeZone) < 0 Then UTCSign$ = "-" Else UTCSign$ = "+"
  If iDate.TimeZone < 10 Then UTCZone$ = "0" + Cstr(Abs(iDate.TimeZone)) Else UTCZone$ = Cstr(Abs(iDate.TimeZone))
  UTCZone$ = UTCSign$ + UTCZone$ + "00"
  UTC$ = UTCDayName$ + ", " + UTCDay$ + " " +UTCMonth$+ " " +UTCYear$ + " " +UTCTime$ + " " + UTCZone$

End Property

Programming Events In both @Language and LotusScript

2008-05-08T16:04:05-04:00

Have you ever wished it was possible to program an event such as QuerySave in both @Language and LotusScript? Sometimes the most efficient (or only) way to perform a specific task is to code the event using @Formula and @Commands. That works fine until a request comes along in which LotusScript is the only solution. Using Evaluate within LotusScript can sometimes be a solution but there is another way to achieve this.

1) Create a class

2) In the constructor for the class create an event handler for the event and set it to invoke a sub of that class

3) Create the method using the same signature as the event with the LotusScript code and put all the LotusScript code in there

4) In the QueryOpen event create an instance of the class passing the NotesUI object (this can be any event invoked prior to the called event - QueryOpen is usually the first and is usually the best)

5) Place the @Language component in the actual event on the form/page.view

When the event is fired the @Language coded in the the actual event will be executed and then the eventhandler coded in the class will be executed....

Form example:

Class MyClass

Sub New(Source As NotuesUIDocument)

On Event QuerySave From Source Call OnQuerySaave

End Sub

Sub OnQuerySave(Source as NotesUIDocument,Continue As Variant)

' Place all LS QuerySave code here

End Sub

End Class

Dim Var As MyClass

Sub QueryOpen(Source As NotesUIDocument)

Set Var = New MyClass(Source)

End Sub