Beyond The Yellow Bubble

The Inspector tool, provides a way of accessing some of the functionaility of the .Domino Framework from any Notes application.  Previous beta releases of the .Domino Framework have included the ability to Sign a database.  The 1.0 release will include additional capabilities to remove links to templates at the design element level as well as removing the "No refresh" flag that can be set for design elements.  These three operations are often executed as part of a deployment of code to production.  In the past I have had to use a range of tools to perform these tasks such as the Domino Administration cleint (Sign) and Teamstudio Design Manager (for the other two).  I am also working on a fourth option to Recompile the LotusScript code.

The 0.6 Beta of the .Domino Framework was published on OpenNTF on the weekend.  One of the last minute additions in this release is the abillity to access the XSLT/Skins feature of the .Domino Framework from within the Inspector tool.   The significance of this is that this the Inspector tool can be invoked against ANY Notes database.  So this tool now allows developers to apply XSLT transformations to design elements without the need to include any additional code in the applications themselves.  All the code (and XSLT) is held in the .Domino Framework database.

e.g. I frequently take on development for existing Notes applications in which the fonts used in forms an/views are inconsistent.  Using Inspector I can apply an XSLT from the .Domino Framework to all view/forms that change all fonts to Default Sans Serif saving me hours of manual (and boring) coding.

Earlier today Tim Tripcomy wrote a great article about Nexus, a new tool he has developed to allow databases to be assigned new replica ids.  After reading the article I decided to finally get around to adding a Read/Write ReplicaID property to the .Domino Framework's DominoDatabase class based upon this code.  (Thanks Tim, I remember seeing the breaking par code a long time ago and forgot where I had seen it).  I will also be updating the Inspector tool included with the fraemwork so that the replicaid becomes editable.  The code is as follows:-

 '/**
 ' *  Replica ID of database (NotesDatabase property is read-only)
 ' */
 Property Get ReplicaID As String
  If (iDB Is Nothing) Then Exit Property
  ReplicaID$ = iDB.ReplicaID$
 End Property
 Property Set ReplicaID As String
  Dim DB_Path  As String*256 
  Dim hDB    As Long
  Dim ReplicaInfo As DBReplicaInfo
  If (Len(ReplicaID$) < 16 Or Len(ReplicaID$) > 17) Then Exit Property  ' ReplicaID must be 16 characters with optional ":" in the middle (as used by @formulae)
  If iDB Is Nothing Then Exit Property
  Call OSPathNetConstruct(0, iDB.Server$, iDB.FilePath$, DB_Path)
  API_Return_Code = NSFDbOpen(DB_Path, hDb) 
  If (API_Return_Code <> 0) Then Exit Property
  API_Return_Code = NSFDbReplicaInfoGet(hDb, ReplicaInfo)
  If (API_Return_Code = 0) Then
   ReplicaInfo.ReplicaID.Byte(0) = Val("&H"+Right(ReplicaID$,8))
   ReplicaInfo.ReplicaID.Byte(1) = Val("&H" + Left(ReplicaID$,8))
   API_Return_Code = NSFDbReplicaInfoSet(hDb, ReplicaInfo)
  End If
  API_Return_Code = NSFDbClose(hDb)
 End Property

Some connected posts from Nathan Freeman, Andrew Pollak, and  Andrei Kouvchinnikov talk about the ability to set the Universal ID of a document.  This is pretty cool stuff.  So I thought it would be a worthwhile extension of the .Domino Framework to support this capability.  As is my way, I have stolen some of the code and ideas to support the updating of the Document UNID.

 

The Document UIND in the new Inspector tool is now read/write.  Simply type in a new UNID over the top of the existing value displayed, click save and the document will be assigned a new UNID.  Note: Because the save creates a new document, the original document is deleted (for which you need delete rights to the database).

 

I have also extended the DominoDocumentCollection class to implement some of Nathan's ideas:-

A new MakeResponse method has been added. This acts similar to the NotesDocument.MakeResponse method, except that it makes all documents in a collection the response documents for a nominated parent odcument.

A new CreateNewDocumentKey method has been added.  This takes as an argument a field name to be used as the key.  A new UNID is calculated based upon the value of the provided field (1st item for lists).  To minimize issues with response documents the MakeResponse method is called so that all reponse documents are now linked to the new UNID.

 

 '/**
 ' *  Creates new UNIDs based upon a key value.  This supports faster lookup of documents by key (as per Nathan Freeman)
 ' */  
 Sub CreateNewDocumentKey(KeyField As String)
  Dim NewUNID    As String
  Dim UNID     As String
  Dim CommandString As String
  Dim Result     As Variant
  Dim NextDoc    As NotesDocument
  Dim Children    As baseDominoDocumentCollection
  Dim OriginalDoc   As NotesDocument
  
  On Error 4091 Resume Next
  Set Doc = iDocumentCollection.GetFirstDocument
  While Not Doc Is Nothing
   Set NextDoc = iDocumentCollection.GetNextDocument(Doc)  
   If Doc.HasItem(KeyField$) Then
    UNID$ = Doc.UniversalID$
    CommandString$ = |@Password("| + Cstr(Doc.GetItemValue(KeyField)(0)) + |" )|
    Result = Evaluate(CommandString$)
    NewUNID$ = Mid$(Result(0),2,32)
    If NewUNID$ <> UNID$ Then    ' Document already keyed on this value
     Doc.UniversalID = NewUNID$
     Call Doc.Save(True,False)
     If Err = 0 Then        ' Indicates document UNID already exists
      Set OriginalDoc = Doc.ParentDatabase.GetDocumentByUNID(UNID$)
      If OriginalDoc.Responses.Count > 0 Then
       Set Children = New baseDominoDocumentCollection(OriginalDoc.Responses)
       Call Children.MakeResponse(Doc)
      End If
      Call OriginalDoc.Remove(True)
     End If
    End If
   End If
   Set Doc = NextDoc
  Wend
 End Sub

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:-

1. View and change database properties

2. Select another database

3. Perform actions against the database (e.g. Open, Sign)

4. View data documents, profile documents, design documents, and deletion stubs
5. Build a document collection using any combination of search, FT search, view, or manual selection
6. Enter a Notes URL, NoteID, or Document UNID to select a specific document
7. Display the documents contained in the document collection.
8. Navigate through document collection
9. Perform actions against the document collection (e.g Setting field values, removing template inheritance)
10. Display details about any one document in collection
11. Display a list of items in the document
12. Perform actions against the document (e.g. Delete, Sign)
13. Display and edit information about any item in a document (type, value, flags)
14. 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.

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  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:-

1. Save the NotesURLs as environment variables in the Notes.INI
2. Create a document in the other database with the NotesURL(s) placed inside a field
3. 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