Using REST services for IBM Lotus Quickr administration

This article provides an introduction to the administration console, new in IBM® Lotus® Quickr™ 8.1, a short description of a new policy feature in Lotus Quickr 8.1, and a detailed look at the REST-based service that the console uses and that you can reuse to enhance your server's management.

Share:

Zhou Tian Shan (zhouts@cn.ibm.com), Staff Software Engineer, IBM

Zhou Tian Shan is a Staff Software Engineer at IBM, working with the IBM Lotus Quickr team in the China Software Development Lab, Beijing. You can reach Tian Shan at zhouts@cn.ibm.com.



Hu Sheng (husbj@cn.ibm.com), Software Engineer, IBM

Hu Sheng is a Software Engineer at IBM, working with the IBM Lotus Quickr team in the China Software Development Lab, Beijing. You can reach Hu Sheng at husbj@cn.ibm.com.



Yin Zhi Yong (yinzhiy@cn.ibm.com), Software Engineer, IBM

Yin Zhi Yong is a Software Engineer working with the IBM Lotus Quickr team in the China Software Development Lab, Beijing. You can reach Zhi Yong at yinzhiy@cn.ibm.com.



Al Maxwell (al_maxwell@us.ibm.com), Senior Software Engineer, IBM

Al Maxwell is a Senior Software Engineer working with the IBM Lotus Quickr team in Westford, MA. You can reach Al at al_maxwell@us.ibm.com.



Bruce Roberts (robertsb@us.ibm.com), Architect, IBM

Bruce Roberts is an Architect of IBM Lotus Quickr. You can reach Bruce at robertsb@us.ibm.com.



08 June 2009 (First published 10 June 2008)

Also available in Chinese

The IBM Lotus Quickr administration console is new in Lotus Quickr 8.1 services for Lotus Domino®. It offers a simple Web user interface that gives the Lotus Quickr server administrator a window onto the place activity on the Lotus Quickr server and a way to control the resources consumed by those places. This article provides an introduction to the capabilities of the console, a short description of a new policy feature in Lotus Quickr 8.1, and a detailed look at the REST-based service that the console uses and that you can reuse to enhance your server's management. After you learn about the REST service for administration and use the accompanying sample code, you can better understand how Atom-style services were used to build the console and how you can reuse the services for your own server administration.

Prerequisites

This article assumes that you are familiar with Lotus Quickr server and its major features. Preferably, you have experience with the QPTool. You should also have a basic understanding of C++, XML, and Web 2.0 technologies.

The sample application described in this article provides a simple C++ prototype to demonstrate how administration services can express a series of XML request-response messages. Each request-response message shows the actual administrative task's work results, which can help you understand the Atom XML format. Make sure that you have server administrator authorization before you access the administration services.


Overview

QPTool is a tool in Lotus Quickr for Domino that you run with arguments to perform administrative tasks. It provides the QPTool commands to complete the administrative tasks, such as generating reports about places and servers, sending mail to managers and members of places, updating statistics in the Place Catalog, and removing places or templates. QPTool, though, has a disadvantage: It is not convenient for the server administrators who cannot access the host server directly because it must be executed in the Lotus Quickr server directly. Lotus Quickr 8.1 for Domino provides a new administration tool for customers, an administration console, based on Representational State Transfer (REST) services and Dojo 1.0.

The goal of Lotus Quickr administrative REST services is to build more collaborative and more robust solutions for users' administrative work with as little effort as possible. The services are designed on open standards and Web 2.0 technologies. The design and implementation of the Lotus Quickr administration services are based on Atom Syndication Format as defined in RFC 4287 and Atom Publishing Protocol (APP) as defined in the RFC 5023 of this specification.

In the spirit of APP in the administration services, the Lotus Quickr server places are treated as APP collections, and the individual places are treated as APP resources. These concepts are also applied to policies and templates. The corresponding URLs are defined for each collection and resource so that the different administrative tasks in the administration console can be finished successfully by invoking the appropriate HTTP methods, such as GET, POST, PUT, and DELETE, on those URLs as defined by APP.


Lotus Quickr administration console

The administration console is a new and powerful administrative tool of Lotus Quickr 8.1 for Domino. Using this URL,
http://<<hostname>>:<<port>>/LotusQuickr/lotusquickr/admin.nsf/index.htm?Open
administrators can log on and execute their tasks, such as viewing all places, templates, and policies on the server, taking a detailed look at the information of a place, locking and unlocking a place, manipulating policies, and so on. All the administrative work in the administration console is implemented by the REST services, described in this article. Figure 1 shows an example of the administration console.

Figure 1. Administration console user interface
Administration console user interface

About the sample

Figure 2 presents a simple stand-alone demonstration, which helps you understand how the Lotus Quickr administration services are used to fulfill administrative tasks. You need to specify the server’s URL along with a user ID and password to connect to the server. When the authorization for the server can be passed successfully, users can execute the following administrative tasks, which are listed in the left pane of the DEMO window, and view the request-response XML patterns in the right panes of the Demo window:

  • Retrieving the list of places
  • Retrieving information about individual places
  • Locking a place
  • Creating a policy
  • Assigning a policy to a place
  • Deleting a policy
Figure 2. Admin Service DEMO user interface
Admin Service DEMO user interface

Retrieving the list of places

First, retrieve the list of places to get an overview of the Lotus Quickr server. The URL you use looks like this one:
http://mikebook.cn.ibm.com/myqcs/rest/places/feed
An HTTP GET method is used to send a request to retrieve the list of places. The HTTP response contains an Atom feed document in which every entry corresponds to a place (see listing 1). As you have noticed in the feed document, each entry has a URL to itself through the self link, which is a helpful pattern used in Atom to provide some information about the places for the administrative work.

Listing 1. Atom feed document for all places information
<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="http://mikebook.cn.ibm.com" xmlns="http://www.w3.org/2005/Atom" 
xmlns:td="urn:ibm.com/td">
	<id>http://mikebook.cn.ibm.com/myqcs/rest/places/feed</id>
	<title type="text">Quickr Place Collection</title>
	<link rel="alternate" type="text/html" 
	href="http://mikebook.cn.ibm.com/AdminConsole"/>
	<link rel="self" type="application/atom+xml" 
	href="http://mikebook.cn.ibm.com/myqcs/rest/places/feed?page=1&
	pagesize=20&sortby=&sortorder=1&total=1"/>
	<author>
		<name>qp</name>
	</author>
	<generator version="1.0" 
	uri="http://mikebook.cn.ibm.com/LotusQuickr">Quickr 8.1</generator>
	<entry xmlns:td="urn:ibm.com/td">
		<id>6B6E24213DA1364C882573A70002B497</id>
		<title>Mike Place</title>
		<published>2007-12-03T23:43:24Z</published>
		<updated>2007-12-03T23:29:36Z</updated>
		<link rel="alternate" type="text/html" 
		href="http://mikebook.cn.ibm.com/mikeplace"/>
		<link rel="self" type="application/atom+xml" 
		href="http://mikebook.cn.ibm.com/myqcs/rest/place/
		6B6E24213DA1364C882573A70002B497/entry"/>
		<td:locked>0</td:locked>
		<td:alert>0</td:alert>
		<td:size>2540</td:size>
		<td:policyname>Policy1</td:policyname>
		<td:lastmodified>2007-12-03T23:29:36Z</td:lastmodified>
	</entry>
</feed>

If users are interested in other Atom feed documents in the administrative work, such as policy and template documents, they can follow the sample code, chttpDlg.cpp, to implement them.


Retrieving the information of an individual place

After you retrieve the list of places, you need to get more detailed information for a place to finish your administrative work. The URL looks like this one:
http://mikebook.cn.ibm.com/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry
The APP Get operations retrieve the information of the individual place. The HTTP response contains an Atom entry document containing the detailed information (see listing 2).

Listing 2. Atom entry document for the individual place information
<?xml version="1.0" encoding="utf-8"?>
<entry xml:base="http://mikebook.cn.ibm.com" xmlns="http://www.w3.org/2005/Atom" 
xmlns:td="urn:ibm.com/td">
	<id>6B6E24213DA1364C882573A70002B497</id>
	<link href="/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry" 
	rel="self" />
	<link href="http://mikebook.cn.ibm.com/mikeplace" rel="alternate"/> <link 
	href="/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry" rel="current"/>
	<link href="/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry" 
	rel="edit"/>
	<updated>2007-12-03T23:29:36Z</updated>
	<author>
		<name></name>
		<email></email>
	</author>
	<td:loginuser>
		<name>qp</name>
		<email></email>
	</td:loginuser>
	<title>Mike Place</title>
	<td:placename>mikeplace</td:placename>
	<td:logincounts>0</td:logincounts>
	<td:placesize>2540</td:placesize>
	<td:lastaccessed></td:lastaccessed>
	<td:numdocs>3</td:numdocs>
	<td:numdrafts>0</td:numdrafts>
	<td:numattachs>0</td:numattachs>
	<td:numcustomforms>0</td:numcustomforms>
	<td:numofflineinstalls>0</td:numofflineinstalls>
	<td:nummanagers>1</td:nummanagers>
	<td:numauthors>0</td:numauthors>
	<td:numreaders>0</td:numreaders>
	<td:lastweekuses>0</td:lastweekuses>
	<td:lastweekreads>0</td:lastweekreads>
	<td:lastweekwrites>0</td:lastweekwrites>
	<td:lastmonthuses>0</td:lastmonthuses>
	<td:lastmonthreads>0</td:lastmonthreads>
	<td:lastmonthwrites>0</td:lastmonthwrites>
	<td:servername>mikebook.cn.ibm.com</td:servername>
	<td:islocked>0</td:islocked>
	<td:sizePolicyStatus>ok</td:sizePolicyStatus>
	<td:sizePolicyAction>unlock</td:sizePolicyAction>
	<td:agePolicyStatus>ok</td:agePolicyStatus>
	<td:agePolicyAction>unlock</td:agePolicyAction>
	<td:policy>
		<td:policyName>Policy1</td:policyName>
		<td:policyID>A54BE63EA15F4898882573A70003B39D</td:policyID>
		<td:policySize>
			<td:max>1</td:max>
			<td:warn>1</td:warn>
		</td:policySize>
		<td:policyAge>
			<td:max>1</td:max>
			<td:warn>1</td:warn>
		</td:policyAge>
	</td:policy>
</entry>

If users are interested in other Atom entry documents, such as policy and template documents, they can follow the sample code, chttpDlg.cpp, to implement them.


Locking a place

To get the detailed information about a specific place, you can start the corresponding administrative tasks in the individual place, such as locking a place, assigning a policy to a place, and so on. The URL that you use to lock a place looks like this one:
http://mikebook.cn.ibm.com/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry
The APP Put operations are used to update the lock information of the place. The request Atom XML document likes the one shown in listing 3.

Listing 3. Atom Put operations for locking a place
HTTP Request:
Method:POST
URL: http://mikebook.cn.ibm.com/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry
Content-Type:application/x-www-form-urlencoded
x-method-override: PUT

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
	<td:lock xmlns='urn:ibm.com/td'>true</td:lock>
</entry>

After successfully processing this request, the service returns a response with the status code 200.

If users are interested in other Atom Put operations for their administrative work, such as updating the existing policy, they can follow the sample code, chttpDlg.cpp, to implement them.


Creating a policy

Lotus Quickr 8.1 for Domino introduces a new concept for place management, named policies. The administration console can be used to apply named policies to templates or places to limit the disk usage of places and the length of time that the place can be inactive. When these limits are approached or reached, notifications to place members or managers can be sent with a message defined by the administrator, and the place can be locked if limits are exceeded. A background agent enforces these policy limits.

To define a named policy for a place, you can apply the policy directly to a place after it's created. A named policy can also be applied to a template, causing any place created from the template to inherit that policy by default. Finally, a system default policy is defined and is always available; the default policy is the enforced policy for a place that has no policy on it or on its template.

The URL for creating a policy operations look like this one:
http://mikebook.cn.ibm.com/myqcs/rest/policy/feed
The APP Post operations are used to create new policy administrative work (see listing 4).

Listing 4. Atom Post operations for creating a policy
POST http://mikebook.cn.ibm.com/myqcs/rest/policy/feed HTTP/1.0
Accept: */*
Accept-Language: zh-cn
Content-Type: application/x-www-form-urlencoded
Host: mikebook.cn.ibm.com
Content-Length: 2227
Pragma: no-cache
Authorization: Basic cXA6cXA=

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
	<published>2007-12-04T00:48:54Z</published>
	<updated>2007-12-04T00:48:54Z</updated>
	<title type="text">Policy2</title>
	<author>
      <name>Frank Upton Barry</name>
      <email>fubarry@work.com</email>
      </author>
	<link  href="/myqcs/rest/policy/0/entry"  rel="self"  
	type = "application/atom+xml" />
	<link  href="/myqcs/rest/policy/0/entry"  rel="edit"  
	type = "application/atom+xml" />
	<td:policy>
      <td:policyAge>
        <td:max>2</td:max>
        <td:warn>2</td:warn>
        <td:warnNotification>
        <td:notificationWho>1</td:notificationWho>
        <td:notificationSubject>Warning Notice about %Place Name% | 
        Details Inside</td:notificationSubject>
        <td:notificationBody>This place has not shown any recent activity. 
        Please visit or perform maintenance to this place to prevent it 
        from being locked. Contact your place admin for additional help. 
        <Enter the admin contact here></td:notificationBody>
          </td:warnNotification>
          <td:limitNotification>
            <td:notificationSubject>%Place Name% has been locked | 
            Details Inside</td:notificationSubject>
            <td:notificationWho>1</td:notificationWho>
            <td:notificationBody>This place has been locked because 
            there has been no activity over the past (insert violation limit). 
            Contact your admin to have this place unlocked. <Enter the admin 
            contact here></td:notificationBody>
            </td:limitNotification>
        </td:policyAge>
        <td:policySize>
            <td:max>2</td:max>
			<td:warn>2</td:warn>
			<td:warnNotification>
            <td:notificationWho>1</td:notificationWho>
			<td:notificationSubject>Warning Notice about %Place Name% | 
			Details Inside</td:notificationSubject>
			<td:notificationBody>This place is approaching the maximum size. 
			Please take the necessary actions to resolve this 
			or contact your place admin for help. 
			<Enter the admin contact here>
			</td:notificationBody>
		</td:warnNotification>
		<td:limitNotification>
			<td:notificationWho>2</td:notificationWho>
			<td:notificationSubject>%Place Name% has been locked | 
			Details Inside</td:notificationSubject><td:notificationBody>
			This place has been locked because it has exceeded the maximum 
			size. Contact your admin to have this place unlocked. <Enter the 
			admin contact here></td:notificationBody>
		</td:limitNotification>
	</td:policySize>
</td:policy>
</entry>

After successfully processing this request, the service returns a response with the status code 201.


Assigning a policy to a place

After creating a new policy, the administrator can assign the policy to the required place. The URL for creating a policy operation looks like this one:
http://mikebook.cn.ibm.com/myqcs/rest/place/6B6E24213DA1364C882573A70002B497/entry
The APP Put operations are used to assign the policy to the place to implement the administrative work (see listing 5).

Listing 5. Atom Put operations for assigning a policy to a place
POST http://mikebook.cn.ibm.com/myqcs/rest/place/
6B6E24213DA1364C882573A70002B497/entry HTTP/1.0
Accept: */*
Accept-Language: zh-cn
x-method-override: PUT
Content-Type: application/x-www-form-urlencoded
Pragma: no-cache
Host: mikebook.cn.ibm.com
Content-Length: 331
Authorization: Basic cXA6cXA=

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom>
	<published>2007-12-04T01:02:26Z</published>
	<updated>2007-12-04T01:02:26Z</updated>
	<td:policy_uuid xmlns='urn:ibm.com/td'>
	A54BE63EA15F4898882573A70003B39D</td:policy_uuid>
	<td:policy_title xmlns='urn:ibm.com/td'>Policy1</td:policy_title>
</entry>

After successfully processing this request, the service returns a response with the status code 200.


Deleting a policy

A policy can be deleted if it is not useful in the administrative work. You can use the APP Delete operation to delete a policy in the administrative work (see listing 6).

Listing 6. ATOM Delete operations for deleting a policy
POST http://mikebook.cn.ibm.com/myqcs/rest/policy/
37F6E75DB22FC9F5882573A700047A93/entry HTTP/1.0
Accept: */*
Accept-Language: zh-cn
x-method-override: DELETE
Content-Type: application/x-www-form-urlencoded
Pragma: no-cache
Host: mikebook.cn.ibm.com
Content-Length: 0

After successfully processing this request, the service returns a response with the status code 200.


Conclusion

Lotus Quickr 8.1 for Domino provides a new feature, the administration console, that offers a more convenient way to implement the server administrative work than previous releases. Because all of the administrative tasks are designed to be RESTful and administrative operations are described using Atom Publishing Protocol, the server administrative work can be finished more collaboratively and robustly. This article demonstrated how to use the services to perform basic operations on the places, policies, and templates and it explained the basic pattern for each request and response message.


Download

DescriptionNameSize
DemoQuickrDemo.zip42KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=312865
ArticleTitle=Using REST services for IBM Lotus Quickr administration
publish-date=06082009