Best Practice Makes Perfect

New Best Practices Wiki

Andre Guirard — Tue, 10 Jan 2012 11:11:40 -0500

There's a new wiki about Domino development best practices. It was written by various experts in and out of IBM, and I followed up with a lot of edits myself, so I'm an after the fact contributor. It's brand new so there are probably some mistakes, which I hope you people who know what you're doing, will correct.

I think this will be a good resource for developers, and I'm adding a link to my list of links on the right.

In other news, if you'd like to read a short story by me (under my fiction alias of Tyler Tork), there's one in the December 2011 issue of Stupefying Stories, available for Kindle,
Nook or on iTunes.

New wiki document for the Notes client app developer

Andre Guirard — Thu, 17 Nov 2011 12:34:02 -0500

The new document, Controlling Document Editing in a Notes Client Application, is intended for novices and will probably not contain a lot of news for the regular readers of this blog. But for those experienced developers here, I welcome your comments, corrections, questions about what the heck I meant by this sentence, etcetera. This is where the collaboration part comes in. Thanks.

Overly Social

Andre Guirard — Tue, 15 Nov 2011 07:07:52 -0500

It seems like a lot of companies are still struggling to figure out how this social stuff can be used to aid their marketing. It might be just me, but some of them seem to be wandering far into the Too Much Information zone.

I'm not even talking about the information the companies themselves publish, though why anyone would want to subscribe to the Twitter feed of a Chinese buffet restaurant or a hotel has frankly been puzzling me for a while. No, I'm talking about the information the companies want to help us publish about ourselves and our use of their products.

Take for instance a certain restaurant chain. I ordered online from their website, and what do I see on the ordering page? Yes, that's a Facebook button. Really, there's not enough trivia on Facebook, the restaurant thinks everyone I know needs to know what I'm having for dinner? I try to keep my posts useful, entertaining, interesting.

Then there's another new thing on Facebook -- I sincerely hope it's a fad. The "Social Reader" application posts every article you open in a given publication onto Facebook. Once you've allowed this application the ability to write to your wall, the instant you follow a link to the article, everybody knows of your interest in celebrity plastic surgery or whatever.

I really value that my Facebook friends can share articles they've enjoyed. I find out some worthwhile things, experience different points of view, and learn something about the person. But, not speaking for anyone else, I can't tell whether an article is worth sharing just from the title. I read lots of things online, and a fairly small proportion are worth passing on. When I post, again, I want it to mean something -- not just to vainly share every tiniest detail of my life in the presumption that someone might be interested. We are drowning in a flood of trivia already.

I know, I can hide those updates in my own feed. And I have (the Social Reader ones -- I've never seen a red hot meal update from that restaurant chain, so I don't know whether I can filter them easily). I just don't understand why people would choose allow those Social Readers and so on access to speak for them. I can understand people might be curious to read the article, but go to the newspaper's website and search for it there. Don't publish a link until you know it's worth publishing!

The SQL Query of Doom

Andre Guirard — Thu, 10 Nov 2011 07:09:35 -0500

I suspect this can be simplified. Thought people might find it amusing.

LotusScript Gold Collection 1.3

Andre Guirard — Mon, 31 Oct 2011 12:03:12 -0500

A new version of the "LotusScript Gold Collection" toolkit is available on openntf.org. It includes the much requested NotesGroupManager library which used to be in the Lotus Sandbox, and a way to call Notes C API functions without having to check which OS you're using before each call. The latter might not work on all servers, but the problem has been reported to the LotusScript team in development. It works great on all clients (and you could easily make a server version, it's just not as efficient as you must load the classes for all supported OS instead of using dynamic loading).

And, if you're interested in the doing of my alter ego, Tyler Tork, you can read a Halloween tale on my other blog (link on right).

Searching for blank date fields, and what makes a supported feature

Andre Guirard — Mon, 31 Oct 2011 05:15:00 -0500

Timothy Briley asked:

I've noticed that over time you've written a bit about valid searches in Lotus Ntoes. Can you comment one way or another on whether or not this is a valid search method:
To find documents in a view containing an empty date field manually by using the search bar or programatically using notesView.FTSearch:
Not([fieldName] > 0)
If this is a valid method, why isn't it documented?

It is seems to work for you, fine. Many things are not documented. Sometimes this is because the developer didn't tell anyone about it, sometimes because it wasn't a planned feature (as I suspect is the case here), and sometimes because we don't want to commit to supporting it indefinitely. When you try to make each version of a product able to support applications created in all previous versions, you have to be careful about what you call a supported feature.
So in general, if something is not documented, you should use it with care and make a special point to test it out before you upgrade your Notes/Domino installation, to make sure it still works in the new version.
In this case, there's a supported way to do what you're looking to do. The "is present" syntax, which is documented, will let you find documents that do, or do not, contain a value in a given field.
However, depending on your application, this may not be the most efficient way to do your search. Please see the wiki article Searching for Documents for some guidelines.

Sametime server owners take note

Andre Guirard — Fri, 28 Oct 2011 08:55:19 -0500

http://www-01.ibm.com/support/docview.wss?uid=swg21569452

Please apply this security fix to your Sametime servers. Thanks

What I’ve been working on...

Andre Guirard — Wed, 8 Jun 2011 07:18:14 -0500

One reason I haven't been posting here much recently, is that I've been working on LotusLive configuration tools, and I didn't think that would be of general interest. These would be the NSFs that end users download to configure their workstations to access LotusLive Notes, and the one that the on-premises administrator in a "hybrid" organization uses to set up their servers to communicate with LotusLive's servers to deliver mail, etc. It's a lot of complicated application development for the Notes client, which is what I love.

So I can talk about some of the ins and outs of LotusLive client and hybrid server setup, how users are migrated, how we know when to delete their old mail files, and so on, if that's of interest here. Or if you have topics you'd like to see more about, please respond in comments.

Creating a replica ID item for adminp requests

Andre Guirard — Tue, 7 Jun 2011 07:15:00 -0500

When automatically generating an adminp request that applies to a specific database, there's an item in the request that you may find hard to create. If you create adminp requests manually and then examine the items in them, you can see for instance that you might have the item ProxyReplicaID with a date/time value. Doesn't look like you would expect a replica ID to look. How do you convert the value of (say) NotesDatabase.ReplicaID, a string, to the TIMEDATE value that gets stored in the note? All the bits are used, so there's a 100ths of a second value that you can't see, but it's in there. Likewise, the timezone is stored in there and has to be preserved.

If you had the value in an item in another document, it would be easy to copy the item to a new adminp request. But if you have to create it from scratch, you need a way to convert a replica ID hex string to a TIMEDATE value.

There is a way, fortunately. The constructor of the NotesDateTime class accepts a hex string as a possible input, so you can just write:

Dim replicaTD as New NotesDateTime(dbTarget.ReplicaID)

docAdminp.ReplaceItemValue "ProxyReplicaID", replicaTD

Though you can't get the NotesDateTime to tell you the exact value to 100th of a second, the exact TIMEDATE value is in there, as you can tell using @Text("ProxyReplicaID"; "*")

What is this boy doing?

Andre Guirard — Mon, 6 Jun 2011 08:10:16 -0500

This has nothing whatever to do with IBM products, but is just a fun little project of my own. So if you're bored or whatever, steer your browser to the Pounce blog and ask a question for Tyler to answer.
The site is pretty rough at the moment; I'll pretty it up as I have time over the coming days.

LS2J static method calls and a little introspection

Andre Guirard — Thu, 26 May 2011 11:49:02 -0500

I've been needing to use LS2J recently so that I could code DNS lookups and web page requests as part of a testing system I'm working on for LotusLive. The documentation is a little vague on how you work with methods in a Java class from LotusScript, so since I had to experiment to find out how it worked, I figured it would be nice to record the information here.

In most cases, you're writing the Java classes you're calling via LS2J, so you get to decide whether there are static members. But maybe you got the class from elsewhere and you don't want to have to modify it, or maybe you're just using a built-in class that you don't get to change. So it may occasionally be helpful to know how to use the static members. So here goes.

You can invoke a static method of a Java class using the JavaMethod.Invoke method with an object argument of Nothing. First you need to get a handle to the method. So for instance, to invoke the static method HTTPPing, which takes a String argument and returns an int, I would write:

Dim jses As New JavaSession
Dim jclass As Javaclass
Set jclass = jses.GetClass("TCPClient")
Dim result%, url$
url = "http://notes.lotuslive.com"
result = jclass.Getmethod("HTTPPing", "(Ljava/lang/String;)I").Invoke(Nothing, url)

The second argument to Getmethod, the method signature, can be a bit hard to come up with. The example in the help shows a sample value of "(I)Ljava/lang/String;", but a single example isn't much help unless the method you want has exactly that signature (and the example seems to be wrong anyway). Rather than try to puzzle out what the right signature might be for the method, I wrote an agent to scan the methods of a JavaClass object and display all the signatures.

Dim jses As New JavaSession

Dim jclass As Javaclass
Set jclass = jses.GetClass("TCPClient")
Dim jmc As Javamethodcollection
Dim jm As Javamethod
Set jmc = jclass.Getclassmethods
Set jm = jmc.Getfirst
Dim methods$
Do Until jm Is Nothing
methods = methods & {
} & jm.Methodname & " - '" & jm.Signature & "'"
Set jm = jmc.Getnext
Loop
MessageBox Mid$(methods, 2)

which gives the following output:

equals - '(Ljava/lang/Object;)Z' 
 hashCode - '()I' 
 toString - '()Ljava/lang/String;' 
 getClass - '()Ljava/lang/Class;' 
 notify - '()V' 
 notifyAll - '()V' 
 wait - '()V' 
 wait - '(J)V' 
 wait - '(JI)V' 
 ping - '(Ljava/lang/String;II)Z' 
 DNSLookup - '(Ljava/lang/String;)Ljava/lang/String;' 
 HTTPPing - '(Ljava/lang/String;)I'

So we can see from the last entry exactly what the signature argument should be.

Another way to make an efficient date/based view

Andre Guirard — Mon, 23 May 2011 15:50:14 -0500

This technique isn't applicable in all situations, but it's a way to make a date or time-based view whose index is only rebuilt when needed, and doesn't require that the date be hardcoded into a design element. The example is intended for use in the Notes mail file, where there's only one user who we're mainly concerned about. It could be used in a shared app context, but in that case it should be set up to use the server's time settings, not the client's as in this example, since different users would be plugging in different formulas and causing constant rebuilds based on their client's settings as opposed to someone else's.
The problem is how to get the view index to be rebuilt only when it is needed, and without "flashing" (i.e. we don't want to open the view and then notice it's out of date). I've been testing this solution and it seems to work.

In the folder, you define a UDC (user-definable column) whose item name is, say "$ZoneDay":

We use the profile name ColorProfile because the Inbox already contains another UDC with the same profile, and any given view can only use one profile doc for UDCs.

Now, you have to set up the profile document to contain the correct formula for the date-based value you'd like it to display. For this we can use the view's queryopen event, for instance:

Sub Queryopen(Source As Notesuiview, Continue As Variant) Dim db As NotesDatabase, sess As New notessession Set db = sess.CurrentDatabase Dim docPro As NotesDocument, curFormula$, newFormula$, midnight$, gmtMid Dim tmpTime As New NotesDateTime("") tmpTime.lslocaltime = Today ' which translates to today at midnight. gmtMid = tmpTime.LSGMTTime midnight = {@ToTime(@Text(@Date(} & Year(gmtMid) & {; } & Month(gmtMid) & {; } & Day(gmtMid) & {; } & Hour(gmtMid) & {; } & Minute(gmtMid) & {; 0)) + " GMT")} Set docPro = db.GetProfileDocument("colorprofile") curFormula = Replace(docPro.GetItemValue("$ZoneDay")(0), Chr$(13), "") newFormula = {todayMid := } & midnight & {; daysOld := (todayMid-PostedDate) / 86400; @If(daysOld <= 0; "today"; daysOld <= 1; "yesterday"; "older " + @Text(@Integer(daysOld)))} If curFormula <> newFormula Then docPro.ReplaceItemValue "$ZoneDay", newFormula docPro.Save True, False, True End If End Sub

Some comments about this approach:

On the line beginning "midnight =", we represent the date by using the @Date function with six arguments. This is done rather than just hardcoding the time constant [mm/dd/yyyy hh:mm:ss GMT] for instance, because we have no way to know the server's date formatting settings. The formula has to be comprehensible by the server, but this code executes on the client, so we can't just format the date as the client would by default.
If performance ends up being a problem and you want to find a way to format the date so the server understands it, you might:
- try using the @TimeMerge function.
- see whether the format [yyyy/mm/dd hh:mm:ss am/pm] is interpreted the same by all servers (note, however, that "/" might not be universally used as a date delimiter).
- I'm trying to get a way of representing date/times that's static across all platforms and settings, e.g. as a hex code. I need it for DXL, but as we can see here there are other applications for it.
When it's asked to open the view, the view indexer is smart enough to know that if the profile document (colorprofile in this case) has been modified since the view was last opened, that means that a column formula might evaluate differently for existing documents. So it knows in that case to rebuild the view index rather than refreshing. So don't save changes to the profile doc unless you mean it.
This approach is doesn't require Designer access for the end user, only enough authority to edit a shared profile document, which they need anyway to edit their own mail preferences. In other applications where users might not have enough muscle to do this, you might need to make the profile document contain an explicit Authors field to allow this access. It could get tricky, which is why I say this might not be applicable for all apps.
If you wanted to use the server's timezone settings to determine the day divisions, instead of the client's settings, you can get rid of the timezone stuff and just use the @Date function (you still can't hardcode the date in [brackets] without knowing how the server formats dates).
There's an extra argument to @Now to return the server's current time, and you can use that to determine what the server thinks the date is. This is not 100% obvious how to do; I think you'll have to use @Text in your Evaluate call with certain arguments, to get the time in the server's zone.

Good news for DXL exporting

Andre Guirard — Mon, 4 Apr 2011 09:09:24 -0500

The fix is in 8.5.3; DXL exporting of file attachments (and all base64) is now substantially faster, on the order of 50%. As always, no change can be considered final until the product is released.

Ripped off content

Andre Guirard — Wed, 16 Mar 2011 09:51:16 -0500

If you're reading this on the blog of Bruno Grange, please be advised that it was ripped off of the blog of Andre Guirard - http://www-10.lotus.com/ldd/bpmpblog.nsf . Much of this content seems to have been copied without permission.

Good news for LotusScript editing

Andre Guirard — Fri, 11 Mar 2011 12:03:29 -0500

I'd earlier reported a weird bug that caused one script library to suddenly get dozens of superfluous errors when another library that it includes, is edited. I got word this morning that a fix was submitted for 8.5.3. Caveat: As usual, nothing is final until it's released.

On improving performance of views with response docs

Andre Guirard — Tue, 1 Mar 2011 07:26:22 -0500

At Lotusphere 2011, I attended a session by Andrew Pollack (BP114, a nice presentation which you can download here). Andrew suggested replacing @IsResponseDoc in view selection formula with @AllDescendants as a way to help performance. (Actually he said @Responses but I think he meant @IsResponseDoc). At the time, I said I didn't think it was quite that simple; this is the promised follow-up to explain what I meant.

There are two important differences between @IsResponseDoc and @AllDescendants:

@AllDescendants fails if you enable the database option "Don't support specialized response hierarchy." Easy to fix, but you have to know to check.
The view indexer ignores the position of @AllDescendants in a logical expression, acting like the expression is always SELECT (rest of your expression) | @AllDescendants.

So you might not get the same set of documents after you make this change.

I created a sample database to illustrate what happens. Here's the "All" view.

Then I created some views that (supposedly) contain just the Active projects and their responses. Here's the one that uses @IsResponseDoc:

Looks OK, but there's a problem. @IsResponseDoc matches all responses, not just those whose main documents are also in the view. You can see the result by looking at the view index sizes in Domino Administrator, or you can prove it in the client by creating a full-text index and running a search.

Where did this document come from? This response's main document isn't in the view; the World Domination plan isn't at Active status (yet). So the response doc is not only taking up space in the view index uselessly, it's confusing matters by incorrectly being part of search results.
You can fix this by changing @IsResponseDoc to @AllDescendants. The resulting view looks exactly the same, but doesn't have the odd search behavior.

This view has been improved by making the replacement. I have no argument with that. So where's the problem? Consider this view:

We're no longer interested in seeing all responses. We have additional criteria for our response docs; they must also have been written since the start of 2010. Only two responses meet this criterion (actually, three, but one is a response to response whose parent, another response document, is too old to show up here, so it only shows up in searches. Tricky, eh?).

See what happens if we replace @IsResponseDoc in this formula with @AllDescendants:

There are more documents visible now. The response document "Wrote Chapter 1" appears in the view even though it doesn't meet the date criterion. That happens because the view indexer implements @AllDescendants by evaluating all the documents against the formula first, then for each matching document, it finds all that document's responses, and their responses, and sticks them in the view index also, without referring back to the formula to see whether they match any additional criteria. In any case, whatever the reason, the consequence is that replacing @IsResponseDoc with @AllDescendants doesn't yield an identical result. You can't just mindlessly make this substitution.

It would be nice to be able to specify that the view contain all responses that meet a certain rule, but only if they're responses to main docs in the view. However, that doesn't seem to be an option. I'll bring it up with the view indexing people, but for now, that's the limitation.

Download the sample database: allDescSample.zip

Expand sections on document open

Andre Guirard — Fri, 4 Feb 2011 11:58:43 -0500

A business partner approached me at Lotusphere with this problem, and after playing around with it a little, it seemed to me the workaround might be useful to others with similar requirements, so here it is.

Requirement: set up the Memo form so that if it contained collapsed sections (e.g. a reply thread), all the sections would be automatically expanded on open.

Problem: the function NotesUIDocument.ExpandAllSections doesn't work when used on a form that has a non-scrolling header, like the Memo form in the Notes mail file. You get the error message "Document command is not available." This was reported as SPR BHUY82WLWZ.

The corresponding @Command ([SectionExpandAll]) does work in this situation, but there was existing LotusScript code in the Postopen event that couldn't be rewritten in formula language.

You can't call a formula that uses the UI from LotusScript (well you can, but it doesn't do anything). So Evaluate and NotesAgent.Run were out. How do we combine the LotusScript event code with the formula command?

Answer: Fortunately, there are duplicate form opening events -- Postopen and onLoad -- so you can put your script in one and the formula in the other. They both execute, though I'm not sure offhand in what order.

Failing that (if it's for a different event), add a subform to the form and write formula for the subform event, and LotusScript for the form event (or vice versa).

Caveat: If there are no sections in the document, @Command ([SectionExpandAll]) returns an error value. If you want to ignore that error, you need another line in your formula to substitute a non-error return value. For instance:

@Command ([SectionExpandAll]);
""

Using a NotesNoteCollection as a ’manual’ note container

Andre Guirard — Thu, 3 Feb 2011 08:46:05 -0400

From a question in one of the BOFs here, I've learned that the documentation of the LotusScript NotesNoteCollection method (NotesCollection in the Java API) contains a significant error. The help for the BuildCollection method says, "You must build the collection before it is usable." This is wrong. The documentation writers were only imagining one use for the collection -- to search for notes.

But there's another use for a NotesNoteCollection -- as a generic container for notes that you find by some other means, and add to the collection with the Add method. If this is how you're using the object, there's no need to call BuildCollection.

This is a significant difference, because BuildCollection takes time to execute even if you haven't specified any search criteria. Speed things up by deleting the call.

Lotuspheres are contiguous

Andre Guirard — Tue, 1 Feb 2011 08:37:30 -0400

Waiting for the keynote to start...

It's always a kick to come to Lotusphere -- and when I'm here, it seems to be a continuation of previous years, as if the chunks of my life that are Lotusphere are yanked out of the rest and arranged consecutively. Certain things are constants -- shin splints for one, from the basic conflict between having to walk at least three miles a day, and IBM's suggestion that we should be somewhat formally dressed. The food service's lame idea of gluten-free. The familiar faces.

Speaking of familiar faces, I want to confess a failing... I'm very, very bad with faces; borderline prosopagnosia. It's generally been the case that more people at Lotusphere know who I am, than I know. But even people I've had dealings with, I don't necessarily recognize them when I see them. So if you greet me and I don't seem to know who you are, or have to sneak a peek at your badge to refresh my memory, it's nothing personal. It doesn't mean I don't remember you; just having difficulty linking the face to the identity. It's always amazed me how easily people recognize others; for me, it's hard.

This year's conference is a little more exciting than most owing to my receiving this year's Penumbra Prism award. I'm honored, and glad that I've been able to build a good relationship with the business partner community. It's encouraging that other see value in my activities around developer enablement and best practices, and I see my role within IBM as a spokesperson for the developer and partner community from the technical perspective; I want to make sure that the features and fixes that go in are the ones that'll make development simpler and free of nasty surprises. When we add a new feature, I want to make sure it's done in a way that actually makes it useful in applications. That's not to say that I'm always consulted, but I weigh in when I get a chance.

DXL importing issue -- you may want hotfix

Andre Guirard — Mon, 17 Jan 2011 11:48:43 -0500

From a service issue I've been working with one of our customers, I've discovered that there's a problem importing DXL containing large blocks of base64 data -- more than 4MB -- which would include any file attachments > 3MB, for instance. You would get this error message in the importer log: "Base64 byte stream contains invalid data or is too large to store in a single note item." (Of course, you can also get this error if your data really is invalid.)

This might happen in about 2% of cases involving large attachments or other large base64 blocks, and is essentially random (but consistent for a given input DXL).

I've come up with a fix for this in 8.5.3, and we're building a hotfix for at least one other version. If this may be an issue for your applications, please contact Lotus Support, referencing SPR #AGUD8D7V55. I'm also writing a technote, currently in internal review.