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.