ActivitiesAtomAPI-JP.pdf

IBM® Lotus® Connections 2.0 Activities: How Atomenabled clients communicate with the Atom API
David A Brooks
Senior Software Engineer
IBM Software Group, WPLC
Westford, MA
Judy Piper
Staff Software Engineer, Lotus Connections Activities
Software Developer, WPLC.J2EE/Portal/WebSphere-based technology
IBM Software Group, WPLC
Westford, MA
October 2008
© Copyright International Business Machines Corporation 2008. All rights reserved
Abstract: This article describes how Atom-enabled clients can communicate with IBM®
Lotus® Connections via its standard-based Atom API, with a focus on many of the
Activities component features that are new in release 2.0.
Contents
1 Introduction...................................................................................................................... 3
2 Basic HTTP authentication .............................................................................................. 3
3 HTTP and Atom API overview ...................................................................................... 4
3.1 Adding a new Atom entry document ........................................................................ 4
3.2 Modifying an existing Atom entry........................................................................... 5
3.3 Retrieving an existing Atom entry............................................................................ 6
3.4 Deleting an existing Atom entry ............................................................................... 6
3.5 Adding a file such as an image ................................................................................. 6
4 Introducing Connections Activities 2.0 API................................................................... 7
4.1 Sections ..................................................................................................................... 8
4.1.1 Adding the section “New Adventure” to the Knights Activity.......................... 8
4.2 Entries ....................................................................................................................... 9
4.3 Replies..................................................................................................................... 10
4.3.1 Adding a new reply entry to the newly created entry ...................................... 10
4.3.2 Adding multiple attachments to an entry via multi-part POST ....................... 11
4.3.3 Customizable fields.......................................................................................... 13
4.4 Add a new entry with various fields to the New Adventure section ...................... 14
5 Migrating from Activities 1.x API to version 2.0 API ................................................. 16
Conclusion ........................................................................................................................ 17
Resources .......................................................................................................................... 17
About the authors.............................................................................................................. 17
1 Introduction
Web content syndication has grown in popularity on the Web since the advent of blogs and has
become a primary technique for interoperability between Web 2.0 applications. IBM Lotus
Connections has adopted the Atom Syndication Format (ASF) and the Atom Publishing Protocol
(APP) for read access to Web content and as a corresponding standard-based content-authoring
API, respectively.
Together, the two offer a standard-based approach that enables easy integration via simple
Hyper-Text Transfer Protocol (HTTP) communication and no library dependencies.
This article explains how Atom-enabled clients can communicate with Lotus Connections via its
standard-based Atom API, focusing specifically on many of the new features introduced for the
Activities component in release 2.0.
2 Basic HTTP authentication
Atom-enabled clients can communicate with any of the Lotus Connections services and
manipulate Web resources without “knowing” anything about the underlying system architecture
of the server.
APP standardizes the way in which clients communicate with servers to create, edit, and retrieve
Web content via HTTP; therefore, it’s important to understand the basics of HTTP communication
before diving into the details of Atom and the Lotus Connections API.
Clients must establish credentials and authenticate with a server in order to securely access and
then manipulate protected Web content on the server.
The following code shows how a client can create an authorization string to establish a credential
with a server, given the user name “Don Quixote” and password “Rocinante”:
String authentication = Don Quixote + ":" + Rocinante;
authentication = "Basic " + new
sun.misc.BASE64Encoder().encode(authString.getBytes());
The “authentication” string is encoded in BASE-64 scheme and is equivalent to
RG9uIFF1aXhvdGU6Um9jaW5hbnRl. This is set as the value for the HTTP Request Header
“Authorization”.
Consider the following client GET request to retrieve the “example.html” file under the “private”
directory over SSL:
GET /private/example.html HTTP/1.0
Host: www.dulcinea.com
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
On a successful GET request, the server returns the HTTP response status code 200 with the
“example.html” content as the HTTP response body:
HTTP/1.0 200 OK
Date: Sat, 27 Nov 2006 10:19:07 GMT
Content-Type: text/html
<html>
<head><title>Example</title></head>
<body>This is just an example.</body>
</html>
3 HTTP and Atom API overview
HTTP is a standard Communication protocol that is used for data transfer across the Internet. In
previous section, the HTTP GET method is used by a client to request a read-only Web resource.
In this section, we finish discussing HTTP CRUD (Create, Read, Update, Delete) operations and
take a look at how APP standardizes on Atom documents and files transfers between Atomenabled server and client.
An application can discover whether a site supports the APP by inspecting the site’s main
homepage for its APP Service document link. For example, you can find the following link when
right-clicking the Activities main homepage and selecting View Page Source:
<link rel="introspection" type="application/atomsvc+xml" title="Atom Publishing
Protocol"
href="/activities/service/atom/service" />
This link is used by applications that perform both read and write operations and that can process
the linked service document to get a list of available collections for the authenticated user. More
information on APP service document can be found in the RFC document, “The Atom Publishing
Protocol.”
Consider a user, “Don Quixote,” who may have a collection “Knights” among many other
collections on an Atom-enabled server, “www.dulcinea.com”. Recall that all collections to which
Don Quixote has access are listed in his APP service document, which then can be discovered
from the main homepage. The “Knights” collection can accept both Atom entries and files as its
Web resources.
In this section, we show you how to add a new Atom entry to the collection, make some
modification to an existing entry, retrieve an existing entry, and then finally remove it from the
collection. We also show you how to add a file resource to the collection.
3.1 Adding a new Atom entry document
To create a new entry to the “knights” collection, you must send an HTTP POST request to its
collection URL (/atom/knights) with the entry document as the request body, as follows:
POST /atom/knights HTTP/1.1
Host: www.dulcinea.com
Content-Type: application/atom+xml
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
Content-Length: nnn
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Don Quixote</title>
<id>http://www.dulcinea.com/atom/knights/entry1</id>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<updated>2007-02-11T18:30:02Z</updated>
<content>Don Quixote begins his adventure to save Dulcinea del Toboso from the
evil windmills.
</content>
</entry>
Upon a successful POST, the server responds with the HTTP response status code 200, the
location of the newly created resource location, and a server-processed Atom entry document as
follows:
HTTP/1.1 201 Created
Date: Mon, 11 Jun 2007 20:07:13 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
Location: http://www.dulcinea.com/atom/knights/entry1
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Don Quixote</title>
<id>http://www.dulcinea.com/atom/knights/entry1</id>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<updated>2007-06-11T20:07:13Z</updated>
<link rel=”edit” href=”http://www.dulcinea.com/atom/knights/entry1” />
<content>Don Quixote begins his adventure to save Dulcinea del Toboso from the
evil windmills.
</content>
</entry>
3.2 Modifying an existing Atom entry
Let's make some modification to the newly created entry. To edit the “entry1" entry document, we
send an HTTP PUT request on the entry edit URL. For any “editable” Atom entry document, you
will see an atom:link with “edit” relation.
From the previous example, the edit link URL for the “entry1” is
http://www.dulcinea.com/atom/knights/entry1. All subsequent editing operations on the entry
should be sent on the edit URL:
PUT /atom/knights/entry1 HTTP/1.1
Host: www.dulcinea.com
Content-Type: application/atom+xml
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
Content-Length: nnn
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Don Quixote</title>
<id>http://www.dulcinea.com/atom/knights/entry1</id>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<updated>2007-06-11T20:30:02Z</updated>
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills. He believes that windmills are ferocious giants.
</content>
</entry>
On a successful PUT, a server responds with HTTP response code 200 OK.
3.3 Retrieving an existing Atom entry
To retrieve an existing Atom entry document, you must send a GET request on the entry's edit
URL:
GET /atom/knights/entry1 HTTP/1.1
Host: www.dulcinea.com
Content-Type: application/atom+xml
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
On a successful GET request, the server responds with HTTP response code 200 OK and the
Atom entry document “entry1” as the response body.
3.4 Deleting an existing Atom entry
To remove the "entry1" entry document from the "knights" collection, send an HTTP DELETE
request to the entry edit URL:
DELETE /atom/knights/entry1 HTTP/1.1
Host: www.dulcinea.com
Content-Type: application/atom+xml
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
On a successful DELETE, the server responds with HTTP 200 OK.
3.5 Adding a file such as an image
Adding a file to a collection is not much different from adding a new entry. To post an image file to
the "knights" collection feed, send an HTTP POST request to the server with the file as the
request body:
POST /atom/knights HTTP/1.1
Host: www.dulcinea.com
Content-Type: image/JPEG
Slug: Beautiful Dulcinea
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
Content-Length: nnn
...binary data for the image file...
On a successful POST, the server responds with HTTP Response Code 201 Created and the
Atom Entry document representation of the newly added file.
NOTE: Upon a successful POST, two resources, a Media Entry and a Media Link Entry, are
created. A Media Entry is the newly posted resource file itself, whereas a Media Link Entry is a
metadata about the file resource in Atom Entry format.
Now use the link with rel=”edit” to update the file data and use the link with rel=”edit-media” to
modify the file resource itself:
HTTP/1.1 201 Created
Date: Mon, 11 Jun 2007 20:07:13 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
Location: www.dulcinea.com/atom/knights/entry2
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Beautiful Dulcinea</title>
<link href="www.dulcinea.com/atom/knights/beautiful_dulcinea.JPEG" />
<id>http://www.dulcinea.com/atom/knights/entry2</id>
<link rel="edit" type="application/atom+xml"
href="http://www.dulcinea.com/atom/knights/entry" />
<link rel="edit-media" type="image/JPEG"
href="http://www.dulcinea.com/atom/knights/beautiful_dulcinea.JPEG" />
<updated>2007-06-11T21:33:41Z</updated>
<published>2007-06-11T21:33:41Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<link rel="alternate" type="application/xhtml+xml"
href="http://www.dulcinea.com/atom/knights/beautiful_dulcinea.html" />
<summary type="text">Beautiful Dulcinea's Photo</summary>
<content type="image/JPEG"
src="http://www.dulcinea.com/atom/knights/beautiful_dulcinea.JPEG" />
</entry>
4 Introducing Connections Activities 2.0 API
Having discussed the basics of Atom and HTTP, we can now delve into the new features of
Activities 2.0 Atom API.
Any client can communicate with the Activities server to manipulate Web resources via Atom API.
However, to make full use of the new features and manage Activities 2.0 data in a more
meaningful way, you must understand the social networking extensions that have been applied to
Activities resources in the version 2.0 API.
Note that throughout this article we use the “Knights” Activity collection with the URL
http://www.dulcinea.com/activities/service/atom2/activity?activityUuid=1D0G09219C738CDA1B0
5B28A32075A0000AC as our example Activity.
4.1 Sections
Sections are designed to provide an easy way to group related entries together within a single
Activity. A section is an Atom entry of type “section”. Its entry type is represented via the
atom:category element as follows:
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="section" label="Section"/>
4.1.1 Adding the section “New Adventure” to the Knights Activity
By default, if you don't specify a parent entry using the threading extension, then every entry is
created as a top-level entry of the Activity. Since you can only create a Section as a top-level
entry, you don't need to use the threading extension:
<entry xmlns="http://www.w3.org/2005/Atom">
<id>Unique id is provided by Activities server</id>
<title type="text">New Adventure</title>
<content type="text">Save beautiful Dulcinea</content>
<author>
<name>Don Quixote</name>
</author>
<published>2008-03-05T22:41:01.344Z</published>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type"
term="section">Section</category>
</entry>
Note that any attempt to create a section as a child of an entry or to move a section as a
response to another entry will result in a “HTTP 400 Bad Request” error.
On a successful POST, the server returns HTTP Response Status code 201, the location of the
newly created section entry, and the section entry document as a response body:
<entry xmlns="http://www.w3.org/2005/Atom">
<id>urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0</id>
<title type="text">New Adventure</title>
<updated>2008-03-06T05:02:01Z</updated>
<published>2008-03-06T05:02:01Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="section"
label="Section"></category>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:1D0G09219C738CDA1B05B28A32075A0000AC"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeU
uid=1D0G09219C738CDA1B05B28A32075A0000AC"
source="urn:lsid:ibm.com:oa:1D0G09219C738CDA1B05B28A32075A0000AC"
xmlns:thr="http://purl.org/syndication/thread/1.0"></thr:in-reply-to>
<link rel="edit" type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeU
uid=912G09219C738CDA1B05B28A32075A0000B0" ></link>
<content type="text">Save beautiful Dulcinea</content>
<---------------- omitted -------------------------->
</entry>
4.2 Entries
Entries are a base content type in Activities and provide a user with a convenient way to post
textual content that may optionally contain tags and custom fields. An entry is an Atom Entry,
much like a Section is, this time with a category of type “entry”.
To create an entry as a child of the section we just posted, you must specify the section as the
parent entry, using the threading extension. From the above example, the "New Adventure"
Section edit URL is
http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=912G09219C73
8CDA1B05B28A32075A0000B0
This will be the href attribute value of the thr:in-reply-to element, and the ref gets the section's id,
urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0:
<entry xmlns:thr="http://purl.org/syndication/thread/1.0"
xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
xmlns="http://www.w3.org/2005/Atom"><title type="text">Day 1</title>
<id>Ignored by Activities server on POST</id>
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills.</content>
<updated>2008-03-06T05:02:01.423Z</updated>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="entry"
label="Entry"></category>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeU
uid=912G09219C738CDA1B05B28A32075A0000B0" >
</thr:in-reply-to>
On a successful POST, the server returns the 201 status code and a newly created entry as a
response body:
<entry xmlns:thr="http://purl.org/syndication/thread/1.0"
xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
xmlns="http://www.w3.org/2005/Atom">
<id>urn:lsid:ibm.com:oa:6BCG09219C738CDA1B05B28A32075A0000B2</id>
<title type="text">Day 1</title>
<updated>2008-03-06T05:02:01Z</updated>
<published>2008-03-06T05:02:01Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="entry"
label="Entry"></category>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeU
uid=912G09219C738CDA1B05B28A32075A0000B0"
source="urn:lsid:ibm.com:oa:1D0G09219C738CDA1B05B28A32075A0000AC"
></thr:in-reply-to>
<snx:activity
xmlns:snx="http://www.ibm.com/xmlns/prod/sn">1D0G09219C738CDA1B05B28A
32075A0000AC</snx:activity>
<link rel="edit" type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeU
uid=6BCG09219C738CDA1B05B28A32075A0000B2" ></link>
<---------------- omitted -------------------------->
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills.</content>
</entry>
4.3 Replies
A reply is a lightweight entry that acts as a comment or response to another entry in an Activity. It
is represented as an Atom entry with a category of type “reply”. Each reply entry must have a
threading extension to specify its parent entry. Attempting to create a reply as a direct child of an
Activity or a section will result in a HTTP 400 - Bad Request error.
4.3.1 Adding a new reply entry to the newly created entry
Let's assume that we are adding a reply to a parent entry with
URL=”http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=326G092
19C738CDA1B05B28A32075A0000C3”
The client sends a POST request with a reply entry as a request body:
<entry xmlns:thr="http://purl.org/syndication/thread/1.0"
xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
xmlns="http://www.w3.org/2005/Atom">
<title type="text">RE:Don Quixote (Mulitvalue Fields)</title>
<updated>2008-03-06T05:02:02Z</updated>
<published>2008-03-06T05:02:02Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="reply"
label="Reply"></category>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:326G09219C738CDA1B05B28A32075A0000C3"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
326G09219C738CDA1B05B28A32075A0000C3"
source="urn:lsid:ibm.com:oa:1D0G09219C738CDA1B05B28A32075A0000AC" >
</thr:in-reply-to>
<content type="text">ticky tacky</content>
</entry>
On a successful POST, the server returns 201 status code and a newly created reply entry as a
response body:
<entry xmlns:thr="http://purl.org/syndication/thread/1.0"
xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
xmlns="http://www.w3.org/2005/Atom">
<id>urn:lsid:ibm.com:oa:24AG09219C738CDA1B05B28A32075A0000CB</id>
<title type="text">RE:Don Quixote (Mulitvalue Fields)</title>
<updated>2008-03-06T05:02:02Z</updated>
<published>2008-03-06T05:02:02Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
<snx:ldapid
xmlns:snx="http://www.ibm.com/xmlns/prod/sn">671G09219C736592F39F3EC6AE8F
1000000C</snx:ldapid>
</author>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="reply"
label="Reply"></category>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:326G09219C738CDA1B05B28A32075A0000C3"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
326G09219C738CDA1B05B28A32075A0000C3"
source="urn:lsid:ibm.com:oa:1D0G09219C738CDA1B05B28A32075A0000AC"
></thr:in-reply-to>
<link rel="edit" type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
24AG09219C738CDA1B05B28A32075A0000CB" ></link>
<content type="text">ticky tacky</content>
<---------------- omitted -------------------------->
</entry>
4.3.2 Adding multiple attachments to an entry via multi-part POST
Using the new custom field support in Activities, you can post an entry with as many attachments
as you want. We have enabled this in Atom via a multi-part POST with several file attachments,
each as their own part. This POST creates an entry of type="entry", and for each media
resource/attachment, a field with type="file" is created. Each field gets "File name" as its default
field name, unless the file part has a slug header value. The file name is set as the title attribute
value of the file link. The Content-Type should be multipart/related;type="application/atom+xml".
Let's now add an entry with three attachments to the "New Adventure" section:
URL:http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=912G09219
C738CDA1B05B28A32075A0000B0
Send a POST request with a complex entry with multi-valued fields properties and three
attachments as a request body:
<entry xmlns:thr="http://purl.org/syndication/thread/1.0"
xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
xmlns="http://www.w3.org/2005/Atom">
<title type="text">Don Quixote</title>
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills.</content>
<published>2008-03-06T05:02:02.985Z</published>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type"
term="entry"></category>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeU
uid=912G09219C738CDA1B05B28A32075A0000B0" >
</thr:in-reply-to>
</entry>
On a successful POST, the server returns 201 status code and a newly created entry as a
response body. Three attachment files are added as "file" field extensions to the entry by the
server:
<entry xmlns="http://www.w3.org/2005/Atom">
<id>urn:lsid:ibm.com:oa:61AG09219C738CDA1B05B28A32075A0000D2</id>
<title type="text">Don Quixote</title>
<updated>2008-03-06T05:02:03Z</updated>
<published>2008-03-06T05:02:03Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="entry"
label="Entry"></category>
<link rel="edit" type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
61AG09219C738CDA1B05B28A32075A0000D2" ></link>
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills.</content>
<snx:field name="Story Book" fid="B1CG09219C738CDA1B05B28A32075A0000DA"
position="4000" type="file" xmlns:snx="http://www.ibm.com/xmlns/prod/sn"><link
rel="enclosure" type="application/octet-stream; charset=ISO-8859-1"
href="http://www.dulcinea.com/activities/service/download/6A0G09219C738CDA1B05
B28A32075A0000DB/donquixote.jpg" size="-1"></link></snx:field>
<snx:field name="Story Book" fid="067G09219C738CDA1B05B28A32075A0000DC"
position="5000" type="file" xmlns:snx="http://www.ibm.com/xmlns/prod/sn"><link
rel="enclosure" type="application/octet-stream; charset=ISO-8859-1"
href="http://www.dulcinea.com/activities/service/download/409G09219C738CDA1B05
B28A32075A0000DD/dulcinea.txt" size="-1"></link></snx:field>
<snx:field name="Story Book" fid="DEEG09219C738CDA1B05B28A32075A0000DE"
position="6000" type="file" xmlns:snx="http://www.ibm.com/xmlns/prod/sn"><link
rel="enclosure" type="application/octet-stream; charset=ISO-8859-1"
href="http://www.dulcinea.com/activities/service/download/38EG09219C738CDA1B05
B28A32075A0000DF/donquixotestory.txt" size="-1"></link></snx:field>
<---------------- omitted -------------------------->
</entry>
Also, you can add more attachments to an existing entry document via multi-part PUT. Instead of
sending an HTTP POST request with multi-body parts on a collection URL, you send the HTTP
PUT request with new multi-body parts on the entry's edit URL.
4.3.3 Customizable fields
In Activities 2.0, you can customize entries and reuse them as entry templates by creating an
entry of type="entry" with field extensions (xmlns:snx="http://www.ibm.com/xmlns/prod/sn").
There are currently five customizable fields: date, link, text, person, and file, all of which have the
attributes of name, fid, position, type, and hidden. The "name" attribute is the field name, the "fid"
attribute is the universally unique id of the field, the "position" attribute is the position of the field in
the container's array of fields, and the "type" attribute is one of the field types. Also, you can
make a hidden field by setting the value of the "hidden" attribute to true.
NOTE: When an entry document is edited, fields are replaced and not updated. In other words, if
you want to keep all existing fields in the entry, they must be present in the updated entry
document; otherwise, the absent fields will be removed from the entry.
Date fields have a date value of Atom Date construct. Here we have a “birthday” date field with
December 18, 2008, as its value:
<snx:field name="birthday" fid="F6EG09219C7310DD5199A4DFF2D597000015"
position="1000" type="date">2008-12-18T22:57:39Z</snx:field>
Link fields are bookmark links. In Activities 1.x, a bookmark entry could have only one bookmark
link for the document. You can now create as many bookmark fields, in addition to other fields, in
one entry document. The following example shows a bookmark field “IBM Homepage” with the
atom:link as its child element that contains the actual bookmark URL:
<snx:field name="IBM Homepage"
fid="1DAG09219C7310DD5199A4DFF2D597000017" position="2000" type="link">
<link href="http://www.ibm.com" title="IBM Website" />
</snx:field>
Text fields are Atom Text constructs. A text field can be of type "text," "html," or "xhtml.” If the
content length is greater than 2K, its extended description is stored as a file, and the link will be
provided as a part of the text field.
Short text example:
<snx:field name="songtitle" fid="3EBG09219C7310DD5199A4DFF2D597000018"
position="4000" type="text">
<summary type="text">In Rainbow</summary>
</snx:field>
Long text example:
<snx:field name="teststring" fid="3EBG09219C7310DD5199A4DFF2D597000018"
position="5000" type="text">
<summary type="text">....a very long text...</summary>
<link type="text/plain"
href="http://localhost:8080/oa.web.coreui/service/download/99BG09219C7310DD5199
A4DFF2D597000019/activitiesExtendedDescription.txt" size="3634"/>
</snx:field>
Person fields have atom:name and atom:email as their children element:
<snx:field name="chair" fid="4DBG09219C7310DD5199A4DFF2D59700001A"
position="6000" type="person">
<name>Sancho Panza</name>
<email>[email protected]</email>
</snx:field>
File fields, as shown earlier, are created by the server when attachments are added to an entry
document via multi-part POST or PUT. The following field "resume" has two field values,
"oldresume.txt" and "newresume.txt":
<snx:field name="resume" fid="71BGC0A8022BB7E3649288E5203A4700008B"
position="7000" type="file">
<link type="text/plain"
href="http://localhost:8080/oa.web.coreui/service/download/D58GC0A8022BB7E36492
88E5203A4700008C/oldresume.txt" size="20" />
</snx:field>
<snx:field name="resume" fid="6A7GC0A8022BB7E3649288E5203A47000097"
position="8000" type="file">
<link type="text/plain"
href="http://localhost:8080/oa.web.coreui/service/download/EDEGC0A8022BB7E36492
88E5203A47000098/newresume.txt" size="20" />
</snx:field>
4.4 Add a new entry with various fields to the New Adventure
section
Here the client sends a POST request with a file metadata entry as a request body:
<entry xmlns:thr="http://purl.org/syndication/thread/1.0"
xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
xmlns="http://www.w3.org/2005/Atom">
<title type="text">Don Quixote (Mulitvalue Fields)</title>
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills.</content>
<published>2008-03-06T05:02:02.391Z</published>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="entry"></category>
<snx:field name="Politics" position="2000" type="text">
<summary type="text">Don Quixote's Adventure</summary></snx:field>
<snx:field name="Bookmark" position="1000" type="link">
<link href="http://en.wikipedia.org/wiki/Dulcinea" title="Dulcinea's Homepage"></link>
</snx:field>
<snx:field name="Assistant" position="3000" type="person">
<name>Sancho Panza</name>
<email>[email protected]</email>
</snx:field>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
912G09219C738CDA1B05B28A32075A0000B0" >
</thr:in-reply-to>
</entry>
On a successful POST, the server returns 201 status code and a newly created entry as a
response body:
<entry>
<id>urn:lsid:ibm.com:oa:326G09219C738CDA1B05B28A32075A0000C3</id>
<title type="text">Don Quixote (Mulitvalue Fields)</title>
<updated>2008-03-06T05:02:02Z</updated>
<published>2008-03-06T05:02:02Z</published>
<author>
<name>Don Quixote</name>
<email>[email protected]</email>
</author>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="entry"
label="Entry"/>
<thr:in-reply-to
ref="urn:lsid:ibm.com:oa:912G09219C738CDA1B05B28A32075A0000B0"
type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
912G09219C738CDA1B05B28A32075A0000B0"
source="urn:lsid:ibm.com:oa:1D0G09219C738CDA1B05B28A32075A0000AC"
/>
<link rel="edit" type="application/atom+xml"
href="http://www.dulcinea.com/activities/service/atom2/activitynode?activityNodeUuid=
326G09219C738CDA1B05B28A32075A0000C3" />
<content type="text">Don Quixote begins his adventure to save Dulcinea del Toboso
from the evil windmills.</content>
<snx:field name="Bookmark" fid="204G09219C738CDA1B05B28A32075A0000C5"
position="1000" type="link" >
<link href="http://en.wikipedia.org/wiki/Dulcinea" title="Dulcinea's Homepage" />
</snx:field>
<snx:field name="Politics" fid="137G09219C738CDA1B05B28A32075A0000C8"
position="2000" type="text" >
<snx:field name="Assistant" fid="96DG09219C738CDA1B05B28A32075A0000D8"
position="3000" type="person" xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
<name>Sancho Panza</name>
<email>[email protected]</email>
</snx:field>
<summary type="text">Thu Mar 06 00:02:02 EST 2008Don Quixote's
Adventure</summary>
</snx:field>
<---------------- omitted -------------------------->
</entry>
5 Migrating from Activities 1.x API to version 2.0 API
Let’s discuss what you need to know before migrating from Activities 1.x to Activities 2.0 API. If
you are not already familiar with Activities 1.x API, please see the Lotus Connections API version
1.0.2 information center for more details.
Atom path. The atom path of the Activities 2.0 API is "atom2" instead of "atom". For example,
version 2.0 API's service document URL is “/atom2/service,” and the current authenticated user's
activities feed URL is “/atom2/activities”.
The existing /atom path will remain available on Activities 2.0 servers to support non-upgraded
clients, but to take advantage of the new features described above, you should migrate to this
new API URL.
Default entry type. If no entry type is specified when a new entry is added to an activity, the
Activities server assigns a default entry type to the newly created entry. In Activities 1.x, the
default entry type of the entry was a "comment" (Message); in Activities 2.x, it is "entry".
Unsupported Activities 1.0 entries. You can no longer edit an entry of type="bookmark", or
type="comment", or type="file" in Activities 2.0 API. The Activities server will return a “HTTP
Response Code 400 (Bad Request)” error if you attempt to create an entry of the unsupported
Activities 1.x entry types.
All existing entries created by the version 1.0 API using the non-supported entry types are
surfaced in the 2.0 API as an equivalent 2.0 type. This allows for a seamless migration and
simultaneous support of new and old clients.
New entries created or edited with 2.0 features that are not supported by 1.0 clients will surface
as read-only to old clients with the additional data summarized in the content payload. This
avoids loss of data, such as fields, while allowing for a gradual migration of clients.
Conclusion
Lotus Connections Activities, an innovative business-ready social networking solution, is
designed based on a simple-yet-powerful concept that people should work around the activities
they perform, regardless of the software tools they use. Together, the Activities user experience
and Atom API provide a full set of features that enable teams to capture and re-use ad hoc
collaboration patterns in the context of how they work.
Because Activities service is fully compliant with Atom specifications, building context-sensitive
plug-ins that interact with the Activities API is clean and simple, with many of the Atom semantics
and HTTP CRUD operations already supported by existing utilities and tools that conform to IETF
specifications. Building a client or plug-in for Activities or any of the other Lotus Connections
services couldn't be easier.
Resources
•
Read the developerWorks Lotus article, “Deploying IBM Lotus Connections: Integrating
with other systems.”
•
Read the developerWorks Lotus article, “Deploying IBM Lotus Connections: Application
programming interface.”
•
Read the developerWorks article, "An overview of the Atom 1.0 Syndication Format."
•
Visit the developerWorks Lotus Connections page.
•
Browse the Lotus Connections wiki, where you can find and contribute information about
deploying, troubleshooting, and using Lotus Connections.
•
Consult the Lotus Connections documentation page for details on the installation,
configuration, and administration of Lotus Connections.
•
Participate in the Lotus Connections discussion forum.
•
Refer to the Lotus Connections Activities 2.0 API information center.
About the authors
David Brooks is the development lead for IBM Lotus Connections Activities and a key contributor
on the IBM Lotus Connections Technical Leadership team. He is responsible for the design and
development of the Activities service. Previously David was the development lead for IBM Lotus
Connections Dogear and evangelized social bookmarking as a key concept in IBM's entry into
business-ready social software.
David has worked for IBM and Lotus for seven years, during which time he has also worked on
developing search and expertise in IBM WebSphere Portal, IBM Lotus Workplace, and IBM Lotus
Discovery Server.
Judy Piper is the Lotus Connections Activities Atom API lead and brought Activities Atom APIs
into compliance with ASF and APP specifications. She has been actively involved in the Lotus
Connections team collaboration work to ensure consistency in both Connections 1.x and 2.x
Atom feeds throughout the Connections Services.
As an RIT Software Development team's coach, she enjoys the privilege to work with her brilliant
mentees on Lotus Connections integration projects and takes great pride in providing mentorship.
Judy joined IBM in 2004 after earning her BS degree in Computer Science.
Trademarks
• IBM and Lotus are trademarks or registered trademarks of IBM Corporation in the United
States, other countries, or both.
• Other company, product, and service names may be trademarks or service marks of others.
Similar pages