Connecting To Domino From ASP.NET / SharePoint

I got asked recently by a customer how they could have a SharePoint site talk to a Domino web server to obtain information from it. Obviously there are lots of options, but the one I ended up suggesting was Web Services.

Before making the suggestion I wanted to be extra sure it was a) possible and b) as easy as I thought it would be. To do this I created a very simple test. Here's how.

Step 1: Create a Web Service in Domino

The first thing I did was create a database called WebServces.nsf and open it in Designer. Then I created a Web Service Provider, called SimpleService, like so:


I chose to make it Java-based, but it could equally be LotusScript for the simple case I'm about to cover.

Next I renamed the Untitled.java file in the Web Service to SimpleService.java and then specified this class as the "port type" for the Service, as below:


Then, I opened the SimpleService.java file and added a simple method called getServerName() which does nothing other than return the name of the Domino server the Web Service is running on.


And that's it for Domino side of things! Nice and simple.

Step 2: Connect To Domino From ASP.NET

As I didn't have a SharePoint setup to hand I used a new ASP.NET MVC website to test it from the C# side of things.

After launching Visual Web Developer (free download) I created a new Project called "DominoFromMVC", and chose "MVC 3 Web Application", as below:


On the next screen of the dialog above I chose "Internet Application" so that it would create a basic site for me to work with.

Now, in the Solution Explorer pane I right-clicked the "Service References" section and chose "Add Service Reference..." option, as below:


At this point you need to make sure that the Domino Web Service is accessible by an Anonymous user (it took me a while to work this one out - doh)!

In the dialog that appears we need to tell it where the Domino Web Service is by specifying its URL, like so:


Notice that I called it "SimpleDominoService", which we'll see referenced again below (although it's called "DominoWebService" in some screenshots as it took two attempts to get them right!).

At this point Visual Studio interrogates the WSDL for the Web Service and creates the corresponding classes in C# so we can use then in our code.

To use the Domino Web Service in C# the first thing I did was open up the HomeController.cs file ("controllers" are the C in MVC), as below, and then added the lines highlighted in yellow:


The first line I added tells the code we're going to use new service. The other two lines and to use the service and are simply:

SimpleServiceClient dominoServiceClient = new SimpleServiceClient();
ViewBag.DominoServerName = dominoServiceClient.getServerName();

The second line adds the result of the getServerName() method to the "ViewBag" object which lets us refer to it from the view (the V in MVC).

Here's the "home" view, again the line in yellow is what I added:


Notice there's a reference to the new property I added to the viewbag.

All I needed to do then was press Run and here's what I saw in the browser:


Hey presto! Simple wasn't it!? I only had to write about three lines of code on each side - Domino and ASP.NET.

I went on to try out adding some more complicated methods to the Domino Web Service and making various other changes, but, as a proof of concept, the above solution worked well enough.

Although what I've shown is very simple it goes without saying that it gets more complicated when you start thinking about using it in a real world scenario. For starters you're probably going to want to authenticate users of the Web Service.

Is there any interest in this whole topic? I'll talk more about it if so. Or is it old news?

And what about SharePoint - would it be of interest if I covered how to connect to Domino from there?


    • avatar
    • Tom S
    • Wed 11 Apr 2012 05:31 AM

    I used the web services to link our domino and PHP sites (in both directions). The PHP is pretty simple too, once you have the right libraries installed. Much easier than trying to connect Domino to the MySQL database.

    Unfortunately, Web Services don't work in XPages (at least not without importing a whole gang of java classes yourself, which is more effort than I'm prepared for), so I'm going to have to fall back to some agents for my new project. I'm sure IBM will get that added in whichever version of Domino is first out after I've finished.

      • avatar
      • Jake Howlett
      • Wed 11 Apr 2012 05:47 AM

      Why can't use XPages *and* Web Services? They accessing the same data. Is it because the logic and code library is already in XPages and you'd need to duplicate it in "classic Domino" to use the code in a Web Service?

    • avatar
    • Tom S
    • Wed 11 Apr 2012 05:55 AM

    Sorry, that wasn't entirely clear - you can create web service *providers* which you're talking about (as you suggest, the domino front end is irrelevant for that).

    Web Service *Consumers*, even in Java, can't be accessed from XPages (yet) - so I can't access my MySql/PHP data from XPages - I'd have to import it via an agent first.

    Technically you can import and configure all the Apache libraries for SOAP, but it's a real pain and I gave up and changed approach after brick wall syndrome hit.

  1. You could also leverage native REST services from Domino coming with extlib or 853UP1. For navigating views, documents etc you have no code at all to do on the domino side. And the performance will be slightly better that the java agent solution.

      • avatar
      • Jake Howlett
      • Wed 11 Apr 2012 06:23 AM

      Interesting. Very interesting. I had no idea that was going to happen. I'm so out of touch.

  2. Obviously you're under no obligation to fulfill our wish lists of how to topics, but if you want to put one together that does cover how authentication works in the above scenario I'm sure it would be very handy to more than a few.

    The reason I say so is that the web service concept works well for the simple scenario above. So far, in my experience, adding security is still something of a challenge but I haven't tried with 8.5 / .NET yet. It would be really a joy to find out it's as simple, or at least on par with, the exercise you show here. But I suspect you'll quickly run into certificate signing and having to set up a domain certifier that works for both environments or at least can be imported into Active Directory so that .NET can authenticate to Domino.

    Generally, as far as interop goes, (while I'm glad to see web services have come far enough so as to actually be easy to use), web services are the "heavy" answer when you look at everything happening... the generation of the WSDL, generation of a class just to connect to the service as defined by same... and when the service provider decides to change their port description/signature, the connecting service either fails or has to have a failover mode to requery the WSDL and regenerate the class, which may need to cause a rewrite of the code.

    In the end, I still favor simple services that are just a version of query string parameters and text returned without all the XML in between. It's generally quicker and lighter in terms of maintenance and implementation if you have a couple of free classes on hand.

    But having to do it with Web Services, I'm certainly thankful you've published this guide and remain hopeful you share the solutions to the security implementation as it would be very helpful to any future person asked to use this in a real environment that requires security.

      • avatar
      • Jake Howlett
      • Wed 11 Apr 2012 08:17 AM

      You may be right - I did a little digging after writing all teh above and quickly found that authentication with Web Services is *complicated* - way more than I'd have imagined, even though, like you say, Web Services are the heavy-handed "enterprise" approach.

      The thing I do like about Web Services is that they're almost self-documenting. At my end, as the provider, I can code-up all the methods and then send over the URL to the WSDL to the other (consuming) developer. They can either try and decipher the WSDL to see what methods are available and what they return or they can import it in to a Visual Studio project and use the Object Explorer to browse what's there in a nice GUI interface.

      Show the rest of this thread

  3. My vote is also for REST. It's easy to write up an agent that writes back a response in XML, JSON, or your preferred Microsoft-friendly format. And, you can use plain old HTTP authentication.

    • avatar
    • Leif Lagebrand
    • Wed 11 Apr 2012 10:01 AM

    Authentication the other way around seems easy, maybe. Havn't tested it.


    • avatar
    • Rishi
    • Wed 11 Apr 2012 11:32 AM

    I would love to see SharePoint connecting Lotus Notes with authentication in place.

    • avatar
    • Chris C
    • Wed 11 Apr 2012 03:31 PM

    I would love to see this working with authentication.

  4. It used to be web services authentication only worked with basic auth (non-session).

      • avatar
      • Jake Howlett
      • Thu 12 Apr 2012 01:16 AM

      When I talked about "authentication" I was talking about something other than standard Domino authentication. Looking back at what I wrote this wasn't clear at all.

      I was thinking of something like giving consumers of the Web Service and "number" and "key" pair. Basically two random strings that would need to match. These would then be soft-coded in to the service-consuming code in the other system.

  5. Hi Jake,

    regarding the authentication:

    I'm calling webservices from MS Excel (in the context of (XPages based) web browser applications, where the user should be able to import or synchronize data which then can be read/filtered/edited in the browser). As there is the infamous webservice Toolkit for Excel this is in this case easier than using REST services (which might be better suited for the SharePoint scenario). Works pretty good.

    As the authentication part is often very complicated (the customer in question is using a Kerberos based single-sign-on, no way I could do that from Excel) I am calling the webservice as an anonymous user (anonymous has no access to the database, but the webservice has the "public access flag" enabled). The user has to provide her/his username and password in an Excel form, which will be transferred in the webservices payload, and I'm just looking this up against the domino directory within the webservice (hashing the entered password and comparing it with the hashed password in the user's person document). Based on that I decide whether to process the request or returning an error code.

    Benefit: very easy to setup and maintain

    Drawback: I have to do the authorization parts by myself - the code is running with the signers credentials, so I have to check readernames fields etc. explicitely in my code.

  6. Jake,

    As always an excellent article. Been looking at XPages consuming webservices with (from memory Apache axis and others being suggested).

    Kinda thought (although I am more than likely wrong) that as part of the standard "boilerplate" (for want of a better word) that you set parameters for username and password (for basic authentication).

    Was keen to progress - if you get the answer I am sure there are loads of Notes / XPages / Java etc people would be interested in having a look.

    If I get a chance to follow up I will - from memory JSF / Java was the route for my searches etc..

    Good stuff though!

      • avatar
      • Jake Howlett
      • Thu 12 Apr 2012 03:23 AM

      Thanks Chris!

      Likewise I assume that Web Services has some kind of inbuilt auth mechanism. I just need to find out if it's simple enough to be practical.

      If I find out anything useful I'll report back. Or maybe you'll beat me to it?

      Hide the rest of this thread

      1. The "ditch medicine" approach we used for some accounting web service calls seemed to work OK and passed the customer's security groups scrutiny.

        It was a bit more complex than just a straight up, out of the box web service but we avoided huge infrastructure adaptations for the sake of better "proper" security.

        The process was basically a handshake. The intent was to prohibit non-authorized calls to the provider WS that would effect a data breach. This is a bit tricky to explain without a diagram but I'll give it a go.

        Consumer "Domino" makes an initial request to provider "Warehouse" with an initial account key.

        This kicks off a process on the provider which immediately connects back to the known Domino application that should be allowed to request account data, calling a separate domino provider webservice that receives the accounting information and stores it in a secure database, returning the docid to provider "Warehouse".

        The response docid is the response sent back to consumer "Domino" as a response to the initial ws call.

        This is all a synchronous event that takes less than a second (inside a corporate network). The initial domino consumer does a lookup within the secure db, using Domino credentials, to find the document id returned from the data warehouse provider response and then pulls the accounting information into the UI.

        Yes - a UI display of results after all that bouncing around.

        So, abbreviated:

        D (account number)->

        W (accounting codes)->

        D (doc id)->

        W (doc id)->

        D (dblookup with doc id) ->

        D (accounting codes)->

        web UI

        So we got past the authentication by ensuring a call to the provider could only return a piece of information that was useful only to the correct consumer and the consumer, the domino app, was the only process id (agent signer) with proper access to the deposited data.

        It was complicated, but it worked fast enough and got us around the need for both SSL and some form of authentication.

    • avatar
    • David Frostad
    • Mon 13 Aug 2012 11:05 AM

    I have tried to implement your example, but when I try to save the Web Service in Domino Designer, I get this error message: The Web Service has not been changed because the WSDL Interface would be changed. What am I missing?

      • avatar
      • Jake Howlett
      • Mon 13 Aug 2012 03:02 PM

      Yeah, I remember that error. Never made any sense to me and I can't remember the workaround I came up with. PITA.

    • avatar
    • Mark Crosby
    • Thu 18 Oct 2012 02:59 PM

    Great article Jake. It seems I frequently end up doing the same type of work as you, only I've been lucky to be doing it after you've posted something to make it easier, although I did marry a Karen before you did! :-)

    Anyway, David Frostad, I think you have the "Warn if the WSDL interface is modified" checkbox checked on the Basics properties tab of the web service.

Your Comments


About This Page

Written by Jake Howlett on Wed 11 Apr 2012

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »

More Content