John Dillon – Senior Adjunct Professor

After a fair amount of research, experimentation, and poking around, I have finally found a way to return a Domino object (such as a NotesDocument, NotesDocumentCollection, or NotesDatabase) via a Web Service.

Now that I figured it out, it struck me that it’s not something that I’m likely to use because the DXL (Domino XML Language) markup is more complicated than I need. The only scenario I can imagine at this point is if you have a remote Domino server needing a Domino object that is accessible only via a Web Service.

Anyway, it’s worth documenting the process here so I can revisit it later.

For the purpose of this illustration, my code will open the Domino Directory (formerly, the “NAB”) and return the first document found in the People view.  It includes some basic error trapping.

Here’s the code:

 Public Class co_NotesDocument ' name of the "Port Type Class"

    ' note that %INCLUDE "lsxsd.lss" is defined in Options
    ' recommended Web Services tool: SoapUI from soapui.org

    Public Function getNotesDoc( aFault As WS_FAULT ) As String

        On Error Goto errHandler

        ' define basic Domino objects; note the "New" for session
        Dim s As New NotesSession
        Dim dbNAB As NotesDatabase
        Dim viewNAB As NotesView
        Dim doc As NotesDocument

        ' special object for exporting the Domino object 
        ' as a DXL thingie
        Dim exporter As NotesDXLExporter

        ' instantiate Domino objects for the Notes Address
        Set dbNAB = New NotesDatabase( "", "names.nsf" )
        Set viewNAB = dbNAB.GetView( "People" )
        Set doc = viewNAB.GetFirstDocument()

        ' Define exporter object for current document
        ' alternately you can define the input document with 
        ' Call exporter.SetInput( doc )
        Set exporter = s.Createdxlexporter( doc )

        ' return the string of text that is the DXL by assigning
        ' the Export() method's output the function's name
        getNotesDoc = exporter.Export( Doc )

        Goto Done 

errHandler:

        ' If you are using OpenLog.NSF (highly recommended), log 
        ' the error information with LogErrorEx().  This is for 
        ' internal use only (by the Domino developer)

        ' Call LogErrorEx( "Error " & Err & " in line " & Erl _ 
        ' & ": " & Error$, "ERROR", doc ) 

        ' define the return properties for the fault object
        ' this is deliberately generic for external users of 
        ' the web service so it reveals less information about
        ' your infrastructure

        ' assign actor an arbitrary name; maybe substitute calling user
        Call aFault.setFaultActor( "CLU Web Service" ) 

        Call aFault.setFaultCode( 1200 ) ' arbitrary fault code

        ' arbitrary and generic error message returned in the web service
        Call aFault.setFaultString( "Sorry, this program encountered an " _
        & "unexpected error. Ask your app developer to check the logs." )

        ' must do this or the fault is NOT returned
        Call aFault.setFault( True )

        Resume Done
Done:

    End Function
End Class ' ===================================================================================

Keywords: Returning a NotesDocument from a Web Service, IBM Notes, Lotus Notes, IBM Lotus Notes, IBM Notes Web Services, How to return a Domino object via web service

No comments

Yes, I’m late to the party, however…..

I’m finally beginning to create Domino Web Service providers.  (If you’re not family with the IBM Lotus Notes/Domino environment, you need read no further.)

I have located several good reference pages by Julian Rubichaux, but still felt like there was some information missing that I couldn’t seem to locate, so I began a series of experiments.

As a result, I’ve begun compiling a summary of thoughts and standards for my environment, some of which I’ll mention here.

Don’t put any code in your web service. Instead, have your web service class inherit from a class defined in a script library. This class in turn inherits many standard elements from a base class in another script library.  While it means you have to go through a couple of extra steps to refresh the service, it means you are able to employ code reuse on a massive scale.  It also means you get better “Intellisense” capability (or whatever IBM calls it).

Define standard classes for your common return values, especially arrays, lists, date/time things, and NotesDocuments, and include them in the base class mentioned a moment ago.

Develop and use a standard error handling approach for all errors. In my case, I leverage Julian’s OpenLog.NSF tool for capturing errors internally, but return a generic error to the web service so as to hide any details about our underlying data structures. I have augmented Julian’s code so that it generates a “cascading log” entry, similar to a stack trace, that shows the call history of the problem area. This helps me debug the problem in my code.

Give serious thought to security. I’m still trying to figure out how to pass Domino credentials into a web service, but I’ve come up with a fairly robust work-around in the meantime. Perhaps I’ll describe it another time, but since it relates to security, maybe not right away!

There’s a lot more that I still need to explore and develop.  I’ll update this entry as time allows.

Note: my environment uses Domino version 8.5.3 but I think these guidelines are generic enough that you can use them from version 7.0.1 on.

Recommended free tool to use when testing Web Services: SoapUI.  It saves you from having to debug two halves of the web service puzzle at the same time.

No comments

Here’s how to solve that problem.

Exit Notes.

Locate Notes.INI. (It used to be under c:\lotus\notes\ — not under data — but newer versions install under a different location.)

Find a line with AddInMenus

If the only item listed is for Adobe Acrobat, then comment out the whole line with a semi-colon

If there are other add-ins in the line, duplicate the line, then comment it out, then modify the one still active by removing the Adobe reference

Restart Notes to confirm it’s gone.

Comments are off for this post

A while ago (a long while ago now!) I played around with creating a database for storing my iTunes tracks. The reason behind it was simple: I wanted to be able to synchronize playlists and last-played data between copies on different computers.

More importantly, I wanted to learn more about working with external COM interfaces.

To that end, I built a Notes application and wrote the attached script library.

One should never apologize for their code, especially if it works, but I will point out that I never polished it up, so you may see some clunky bits. You’re welcome to play with it, adapt it to your own needs, or ignore it!

Anyway, attached is a LotusScript file that walks through your collection of tracks and creates or updates matching Notes documents. It requires the iTunes SDK version 7.7 or later (available from Apple),

Code is offered, of course, without warranty, guarantee, or support of any kind.

NOTE: For some reason I’m not allowed to upload text or lss or zip files, so the code is included in plain text below.

 Read more

No comments