1. Who am I?
• Bill Buchan, CEO of hadsl - one of the vendors on the
showfloor
s Come visit the booth - we don’t bite
• Dual PCLP in v3, v4, v5, v6, v7, v8, and v8.5
• Enterprise-level consultant on Domino since 1995
2. What we’ll cover
• Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
3. Introduction
• I am Bill Buchan. I am:
s A blogger - http://www.billbuchan.com
s A principal of HADSL - http://www.hadsl.com
s A Notes veteran of some 14 years
• You are
s Lotus Domino developers
s Interested in starting or enhancing Web Services in your
environment
s Familiar with LotusScript, and perhaps xPages/Java
4. • Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
What we’ll cover
5. A quick overview
• SOAP Stands for
s Simple Object Activation Protocol
• SOAP Based Web services are:
s A standard application to application protocol for exchanging structured data
„ Usually (but not always) using the http protocol
„ Usually (but not always) using XML
„ Usually we provide meta-information on what our service will do, using a
language called WSDL (Web Service Description Language) – formatted in
XML.
• Web services are Language independent, Platform independent, Data format
representation independent
• But hopefully you all knew this already...
6. Web Services Architecture
• The players:
s The Web Service server
„ Can answer questions on what it can do
„ Can accept requests from Web Service clients
„ Can respond to requests from Web service clients
s The Web Service client (or consumer)
„ Knows where the web service server is located
„ Knows the services that it requires
„ Knows how to prepare a Web Services Query
„ Knows how to interpret the returned data
7. 7
Web Services Protocol
§ A typical web service session looks like:
Client to Web Service Server
§ “Tell me the answer to this question”
Web Service Server
§ “Here it is”
§ Conclusion:
The clients drive the conversation
The Server cannot initiate a conversation with the client.
8. 8
Web Services Protocol (in more detail)
§ The Web Services Protocol:
The client decides it needs to ask the server for some information
It constructs the relevant XML based web services query (either
dynamically or in a static fashion depending on the complexity of the
application)
It then connects to the Web Service Server
§ Pushing the web request up as an HTTP 'Post' request
§ It waits for a response
The Web service server then 'Posts' back an XML payload representing the
answer
The client then unpacks and interprets the data.
9. 9
This sounds hard...
• Not really.
s Its a combination of web protocol and XML construction and
unpacking
s Most of the hard work is done for you by the various Web
Service servers and Consumers
s Its fairly easy to debug using the correct tools
10. What about REST?
• REST stands for:
„ REpresentational State Transfer
• REST Means
s The query is passed as the URL
s The results can be in XML or REST
s NO WSDL
• REST is
s Far more lightweight
s Easier to parse in JavaScript
• Choose the best approach…
10
11. REST versus Web Services?
• Is REST a Web Service ? Well, not really
• Which is best?
s Web services are good for delivering very structured, complex
information in nested XSL
s REST is very convenient to parse, and is better for lightweight
frameworks such as JavaScript
• Pick your architecture based on your consumer needs, and your
authentication requirements
11
12. Authentication
• Some web services or REST services can supply information
without authentication
s But we live in the real world
• Authentication is proving you are allowed to see this data
• Can be achieved by:
s Passing a Session Identifier in a cookie
s Passing a username/password pair to an application
s Authenticating using Kerberos/NTLM in an Active Directory
world
• A simple rule of thumb
s Lightweight consumers tend to use cookies
s Heavyweight data lifting services tend to use authentication
12
13. Authentication Gotchas
• Some frameworks – such as JavaScript or Flex – can re-use the
cookie provided on their launch page
s Very convenient for us. Just have the consumer launch the Rich
Internet Application from that page
• Some more complex applications require KERBEROS
authentication
s A C# Windows based service, for instance, might run under
specific service credentials, which can then be Single-Sign-On
authenticated to Domino
„ See SPNEGNO and/or IIS Websphere Plugin
• Otherwise
s You will have to hold encrypted username/password keys.
13
14. 14
A sample application
• Fairly simple Domino Contact Database
s A single ‘Contact’ form with some information
s Not meant to be a ‘real-world’ example - Its here to demonstrate
the techniques
• All example code is in the database
s Simple to figure out and ‘research’
s Probably is not best practice!
17. 17
How do we test a web service?
• I recommend SoapUI
s Its free!
• http://www.soapui.org
• It allows you to interrogate a web service
s And build test case with real data
19. • Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
What we’ll cover
20. 20
Domino Web Service Server
• By far the simplest is to use a LotusScript Web Service
s The majority of the work is done for you!
• Servlets should be avoided unless
s You are running on Domino v6.5.x or older
s You absolutely require persistence
21. 21
LotusScript Web Services
• Introduced in Lotus Domino 7
• Robust
• Code the web service using LotusScript
• Fairly high performance but
s Remember: Lack of persistence between calls, so
„ Be aware of what your code is doing!
„ Use ‘Agent Profiling’ to see timings…
22. 22
Profiling a Web Service
• LotusScript web services are
very similar to LotusScript agents
s So you can profile them.
s Enable Profiling on the Web
Services Properties tab
s View the last run profile:
„ Right click on the Web Service
„ View Profile Results
23. 23
A Sample Profile
• This shows how long the agent took to run, and how long the
agent spent inside the Notes Object Interface
s In our case, 761ms total, and 0ms within NOI
s One call to CurrentDatabase, and one call to Title.
s Obviously, this wasn’t a very interesting web service call…
24. 24
Designing a Web Service
• Spend time thinking about how your consumer will use this web
service.
s More time thinking, less time coding
s You do NOT want to change this web service interface often
„ Instead - roll out a new web service
s Think through client use cases
s Remember - you can use LotusScript to perform complex
business rules, and provide summary data to your consumer
„ Don’t assume the consumer has lots of CPU or memory
§ BlackBerry smartphones / Windows Mobile ?
• Put complex code in script libraries, and call them
„ It means you can put a normal agent ‘test harness’ around it
and debug it
25. 25
Contacts.nsf
• In our case we wish to:
s Be able to list all users by Name, by Department
s Be able to get details on a particular user
s Be able to search for users
• Do we
s Pass all fields back as web service items?
s Pass back an array of fields?
• In this case, we pass back Web Service Items
s Assume data mapping knowledge and responsibility.
26. 26
Web Service Design
• We design our web service interface within a ‘Class’ in
LotusScript.
s At this point, you probably wished that you studied the
Object Orientated LotusScript sessions I used to give…
• Our web service will expose all ‘public’ methods and
properties
s We do not have to put all the code in one ‘class’
s Beware of extending existing classes - you might expose
more than you want!
„ Beware over-exposure…
27. 27
Web Service Design
• LotusScript does NOT allow functions to return Arrays.
s This is a language limitation, not a Web Service Limitation
s It can return simple types - but not variants (web services
does not support them)
s Instances of other classes…
„ Which can contain other classes
• We need to use arrays to return results
s For instance, we need to return an array of Zero or more
entries to list our users. How do we do that?
• We can define a class and return an instance of that class…
28. 28
Returning complex types
• We can define a class called
‘ReturnArray’ which has a single
array as a public member.
s The constructor initialises the
array so that it has one blank entry.
• We can then populate this array
with one or more entries.
• Nd7 supports arrays with one
element or more - nd8 supports
‘empty’ arrays.
Class returnArray
Public S() As String
Sub new
Redim S(0)
S(0) = ""
End Sub
End Class
29. 29
Complex types…
• We shall return our Person
contact record using a class.
s We DON’T have a constructor
s All elements are Public - so it’ll
be exposed to the Web Service
as data.
s Our property names will be
used by the web service as
field names
s Since LotusScript is case
insensitive, the web service
field names will be
UPPERCASE.
Class Person
Public FirstName As String
Public MiddleInitials As String
Public LastName As String
Public FullName As String
Public Telephone As String
Public Cellphone As String
Public eMail As String
Public HomePhone As String
Public Department as String
Public Notes As String
End Class
30. 30
Lets make it better
• We need to add:
s Logging. We need to know when it works, and importantly,
when it does not
s Error Handling. We need to pass errors back to the consumer
s Security. We might want to harden this service somewhat
• We committed the following sins:
s We put all the code in the web service itself, making it hard to
test. Best to consider embedding most of the code in script
libraries
s We’ve tightly bound the data structures in our data to our
web service
„ If we add more fields to our contact record - we shall have
to change the web service. And therefore, all our clients
will have to be checked and/or recompiled.
„ If the data set is likely to change, construct a more flexible
data-mapping schema
31. 31
ND7 and ND8 differences
• Web services built or compiled in Notes 8 Designer WONT run
on ND7 anymore!
So be careful about what web services you host on which
servers, and which version of designer you use.
s Just bear this version difference in the same manner as all
other version differences.
32. 32
ND7 and ND8 differences
• In ND7, the class used for the web service has to reside in the
web service design element. In ND8, this can be in a script
library.
s This means that for complex services, you can place all the
business code in a script library, allowing simple
construction of a test harness.
• ND8 now supports code in Java Libraries
• ND8 supports more error handling SOAP elements
• ND8 supports ‘empty’ arrays - nd7 does not
33. • Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
What we’ll cover
34. 34
Consuming a web service
• Why consume web services?
s To gain access to information in other systems
s To prevent the synchronisation and replication of external data sources to
Notes
s Real time, up to date data lookup
• Where?
s We could use a scheduled Java agent in Domino to interrogate external
services - no UI means you have to monitor and check
s We could use client-driven code on the client workstation - be aware of network
issues between the clients and the remote service
35. 35
Overview
• Security
s Remote web services may require
„ Username/password login, Encrypted username/password
pairs in data, SSL.
• Things change
s You may have to change your web service consumer to
accommodate this
s The remote web service may move
s When designing, don’t hard-code…
36. 36
Consuming Web Services
• Summary:
s Notes 8 - Its very simple - It works in LotusScript and in Java
s It does a lot of work for you
• How do I construct a Web Service Consumer in LotusScript?
s Create a new, empty script library
s Click on the Import WSDL button
s It creates a Class definition
s You can then “use” the script library and class.
37. 37
Consuming Web Services
• On the nd8 basic client: create a new LotusScript Script
Library:
• Click on the WSDL button…
41. 41
Consuming Web Services
• It needs a WSDL file. What's that?
s You can open the WSDL
definition for your web
service in your browser
s Use View Source, and save that as
a WSDL file.
s Select it…
• Designer will then construct
helper classes and a main
class which we can then call
• That’s it!
Sub Initialize
Dim C As New Contacts
Dim V As Variant
Set V = C.listUsers()
Forall thisUser In V.S
Print "Found User: " + thisUser
End Forall
End Sub
42. 42
Gotchas
• The entire LotusScript library is taken up with the computed
Web service definition. Best not to make changes.
s Next time its refreshed, you will lose those changes!
• If you change the web service, you must remember to update
the Web Services consumer.
s It does not take long - so don’t forget it.
s And when you change the web service consumer script
library, you must recompile all the LotusScript that relies on
it.
„ ‘Tools, Recompile LotusScript’ is your friend
43. 43
Gotchas
• It requires the Notes 8 client to run on:
s We as Application Developers deploy solutions on users’
target notes clients
s Notes 8 may not yet be adopted in your environment
„ So catch up!
s This may help drive the upgrade process
• What if you need Web Service consumption now, and are not
yet on Notes 8?
s You can use MS COM objects
s You can hand-code Java-based agents which perform Web
Service calls
s But really. Upgrade
44. Summary
• Web Services
s Are pretty straightforward
s An important part of your armoury
s Help break down barriers between Domino and other systems
s Help prevent data duplication in your environment
• By now, you know enough to make a real difference
• Keep learning.
45. • Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
What we’ll cover
46. How difficult is it to provide REST from xPages?
• Its pretty simple
• It relies on the Extension Library
s (Its pretty straightforward, but we’ll not cover it here)
• What does REST look like?
46
47. So REST can be JSON or XML
• JSON is JavaScript Object Notation
s It can be directly parsed in JavaScript (and many other
languages)
s You can pass collections of objects (which may contain other
objects)
• Considerations:
s It can get large. You might want to keep it light:
„ So don’t try and pass back thousands of records. Let the
consumer ‘page’ through a reasonable set of results
s Everything is a String or a Number
„ So decide quickly how to pass back currency, dates, etc.
• See http://json.org for more information
47
48. Lets add a JSON based REST service:
• Add a new xPage. I called
mine RestService.xsp
• Drag in a REST object from
the Data Access Controls
area:
48
49. JSON REST Service:
• Give it a name: I called mine ‘all’
• Set ViewName to the name of
your view. In this case,
‘Contacts.FirstName’
• Set service to ‘xe:viewJsonService’
• Set ‘pathInfo’ to the URL you
wish to use. I set mine to ‘all’
• Set contentType. I set mine to ‘text/plain’, but ‘application/
JSON’ is better
• I set ‘compact’ to ‘false’ so we could read it. Set it to ‘true’
• Now set your columns…
49
50. JSON REST Service
• I set my columns to:
• But of course you could set more or
less columns, and compute variables
on the fly
• Lastly, I set SystemColumns to the computed value of ‘false’ to
skip the system computed columns
50
51. JSON Summary
• You don’t have to use xPages for all the site – you can use xPages
for the JSON part
• The REST based xPages JSON provider is pretty basic, but very
fast
s Matt White (of ideaJam and xPages101 fame) has measured this
API versus traditional web service pages, and found it to be at
least 10x faster
s It might be worth the effort to implement for that sort of
performance gain
51
52. • Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
What we’ll cover
53. Consuming Web Services from C#
• C# is part of Microsoft’s Visual Studio suite of langages
s Similar to Java in terms of being Object Orientated
s It’s a very useful tool in our corporate landscape
• So lets construct a C# Web Services client for this application:
s It’ll be simple – a console based application
s It’ll just pull data via web services
s It’ll ignore authentication, error handling, etc.
• But it will demonstrate the technique
53
54. C# Starter
• Create a new project in VS2010
s A console application
s C# Based
54
55. Adding the Service Reference
• Right click on your project (on the right, in the Solution Explorer
pane) and select ‘Add Service Reference’
55
56. Pass the WSDL for the service
56
• Enter the WSDL URL, and give a name to the web service, then
click ‘Advanced’
57. Add a Web Reference
• Now click on ‘Web Reference’
57
59. Now add a splash of code…
59
EndpointAddress endpoint =
new EndpointAddress(new Uri(DominoHostName));
BasicHttpBinding httpBinding = new BasicHttpBinding();
httpBinding.Security.Mode =
BasicHttpSecurityMode.TransportCredentialOnly;
httpBinding.Security.Transport.ClientCredentialType =
HttpClientCredentialType.Basic;
ws = new sr1.ContactsService();
ws.Credentials = new NetworkCredential(DominoUserName, DominoPassword);
Console.WriteLine("Program name is: " + ws.GETAPPLICATIONNAME());
60. C# Conclusion
• It’s a highly scalable, secure environment
• This is a trivial example –it can handle millions of records, and
very complex structures
• The LINQ structures within C# make data comparison and
reporting very simple
• Step through it with the debugger and all will be revealed.
60
61. What we’ll cover
• Introduction
• Web Services Overview
• Using Domino to provide Soap Based Web Services
• Using Notes to consume Web Services
• Using xPages to provide REST based Web services
• Consuming web services from C#
• Wrap up
62. Resources
• SOAPUI – http://www.soapUI.org
• The xPages Extension Library – http://www.openNtf.org
• xPages101 series of xPages tutorials – http://www.xpages101.net
• All my previous presentations are on http://www.hadsl.com
62
63. 7 Key Points to Take Home
• Web services are a platform and application agnostic way of
passing information around
• Both Web Services and REST are lightweight protocols and
should be used for smaller packets of information
• Use SoapUI to help debug SOAP based web services
• Authentication needs to be architected
• Lotus Domino servers can easily serve web services using classic
LotusScript and Java
• xPages can provide information via REST
• xPages REST is 10x faster than LotusScript based SOAP web
services
63
