Yellow is the New Blog

I haven't seen much discussion about how easy it really is to consume web services in Notes/Domino 8 (perhaps precisely because it is so easy), so I thought I'd outline exactly how one goes about providing and consuming services now.

Let's use a very basic example. Create a script library and toss this in the Declarations:

Public Class House
    Private currentColor As String
    Private currentValue As Long
    
    Public Sub buy (price As Long)
        Let Me.currentValue = price
    End Sub
    
    Public Function color() As String
        Let Me.color = Me.currentColor
    End Function
    
    Public Function value() As Long
        Let Me.value = Me.currentValue
    End Function
    
    Public Sub sell (price As Long)
        Let Me.currentValue = price
    End Sub
    
    Public Sub paint (newColor As String)
        Let Me.currentColor = newColor
    End Sub
End Class

Save that library, and create a web service. Include the library you just created via a Use statement in the Options, then in the properties of the service, specify House as the PortType class. The service doesn't need any code of its own, because it's aware of the House class via the Use statement and knows that's the class that defines the service methods.

Now it's time to consume the service. From within the service, click "Export WSDL", and save the file anywhere you can get to it later. In any Domino database (including, but not limited to, the database containing the web service), create a new script library (can be Java if you prefer, but in this example, we'll use LotusScript). At the bottom of the window you'll see a WSDL drop-down button. Click that and select "Import WSDL". It'll warn you that this will overwrite your script library (which is fine, since that's precisely what we want); click OK and select the file you just exported. Here's what you'll see:

%INCLUDE "lsxsd.lss"
Class House As PortTypeBase
    
    Sub NEW
        Call Service.Initialize ("UrnDefaultNamespaceHouseService", _
        "HouseService.Domino", "http://localhost", _
        "House")
        
    End Sub
    
    Sub BUY(PRICE As Long)
        Call Service.Invoke("BUY", PRICE)
    End Sub
    
    Function COLOR() As String
        Let COLOR = Service.Invoke("COLOR")
    End Function
    
    Function VALUE() As Long
        Let VALUE = Service.Invoke("VALUE")
    End Function
    
    Sub SELL(PRICE As Long)
        Call Service.Invoke("SELL", PRICE)
    End Sub
    
    Sub PAINT(NEWCOLOR As String)
        Call Service.Invoke("PAINT", NEWCOLOR)
    End Sub
    
End Class

Any of this seem familiar?

Only one change to the library is needed: replace the reference to "http://localhost" (in the Service.Initialize call) with "http://server/path/db.nsf/servicename?OpenWebService" (where server is the IP or DNS address of your Domino server, path/db.nsf is the full filepath of the database containing the service, and servicename is the name of the web service design element).

At this point, you can save the new library and include it anywhere you need to consume the service. And actually consuming it is this easy:

Dim myHouse As New House()
Call myHouse.buy(200000)
Call myHouse.paint("Purple")
Call myHouse.sell(5000000) 'Keep dreaming

But the real beauty of web services is that it allows you to execute functions against an application you know nothing about, whether it's inside your network or not. For example, if you download this file and import it into a script library in any of your applications, you can pull a random quote from my site as easy as this:

Dim Quotes As New Quotes()
Dim Quote As Quote
Set Quote = Quotes.getRandomQuote()
Msgbox Quote.Content & Chr(13) & "- " & Quote.Source