Introduction

When you work with documents it is often necessary to exchange information about them and to cooperate with other people on issues related to them. The collaboration services of the Knowledge Management (KM) Platform enable you to enter information that is related to documents and to automatically share it with other users. The information is accessible directly from the document, but its visibility is restricted, depending on permissions and the service that is involved.

Purpose of the Services

The available collaboration services are:

• Comments

You can express and share any thoughts related to a document in a comment. Comments are referred to as reviews on the Knowledge Management user interface.

• Feedback

Feedback allows you to review a document and enter remarks intended for the author.

• Rating

Rating allows you to express and store your assessment of a document using preset evaluation categories. Ratings, including past and average ratings, are visible for everyone who is allowed to read a document.

• Personal Notes

Personal notes allow you to write personal remarks about a document and to view these whenever required.

• Discussion

The discussion feature allows you to simulate a live discussion about a document. As in web news groups, you exchange ideas about a subject with other users.

Permissions and Visibility

The use of the collaboration functions and the visibility of items are controlled by KM access control lists (ACLs) and service permissions. These permissions are sometimes checked by the service and sometimes with other mechanisms, for example, by a security manager.

The table shows the permissions that are required for for different collaboration actions. Note that if a user has the service permission collaboration, all actions related to the service are permitted.

Summary of Required Permissions

User Action	Permission Required for Document	Comment
Add comments, feedback, personal notes and rating	Read
View comments of other users	Read
View rating of other users	Read	Only the average rating is visible for users who are not the author of the document.
View feedback of other users	Write	Only the author of a document can view feedback. However, if a document is subject to an approval process, the feedback can also be read by the approvers.
View personal notes of other users		Not possible
Delete comments	Write	Users can only delete comments if they have write permission for the document. The authors of comments can always delete them.
Delete feedback	Write	Users can only delete feedback if they have write permission for the document. The authors of feedback items can always delete them.
Delete rating	No permissions
Delete personal notes	Read	Only the author of a personal note can delete it

Configuration

Each of the services can be configured with a set of parameters that are available in the KM Configuration Framework. For more information, see help.sap.com/nw04->SAP NetWeaver ->Information Integration->KnowledgeManagement ->AdministrationGuide.

Working with Collaboration Services

The following sections use code extracts to explain how to:

• Preparefor the use of the collaboration services
• Addcomments, personal notes, feedback, rating to a resource
• Getcomments, personal notes, feedback, rating already assigned to a resource
• Delete comments, feedback, personal notes or rating assigned to a resource

Preparing for the Use of the Services

To work with a collaboration service, you need to get the resource involved and an instance of the service that you want to use. Proceed as follows:

1. Import the following Java packages:


import com.sap.wcm.repository.service.comment.IComment;
import com.sap.wcm.repository.service.feedback.IFeedback;
import com.sap.wcm.repository.service.rating.IRating;
import com.sap.wcm.repository.service.personalnote.IPersonalNote;
import com.sap.wcm.repository.service.discussion.IDiscussionManager;
import com.sap.wcm.repository.service.discussion.IDiscussion;
import com.sap.wcm.repository.service.discussion.IDiscussionItem;

2. Get access to the resource to which you want to apply collaboration services. To do this, first get the ResourceContext.

ResourceContext rContext = new ResourceContext(aUser);

3. Get the RID.

RID aRid = new RID (this.resource);

4. Get the resource with the help of the ResourceFactory.

IResourceFactory aResourceFactory = ResourceFactory.getInstance();
com.sap.wcm.repository.IResource aResource = aResourceFactory.getResource(aRid, rContext);

5. Get a ServiceFactory.

IRepositoryServiceFactory repServiceFactory = ResourceFactory.getInstance().getServiceFactory();

After the above steps, the procedure differs, depending on the collaboration service you want to use. A prerequisite for handling any collaboration items is an instance of the corresponding collaboration service. For more information, see:

Comments
Feedback
Rating
Personal Notes

Comments

An instance of the commnet service is a prerequisite for handling comments. You get a repository service from the RepositoryServiceFactory and cast it as a comment service.

IRepositoryService repositoryService = repServiceFactory.getRepositoryService(aResource, IWcmConst.COMMENT_SERVICE);
IComment commentService = (IComment)repositoryService;

• Add a comment to the resource with a personal text (String):

boolean erg = commentService.addComment(aResource, text);

• Get all comments for a resource and then use an iterator to access individual comment lines.

IResourceList list = commentService.getComment(aResource);

    // Loop at Ressourcelist
    try {
      iterator = resList.listIterator();
      while (iterator.hasNext() ) {
        singleComment = (IResource) iterator.next();
        // Do whatever you want
      }
    }
    catch (Exception e) {}

• Delete a comment:

CommentService.delComment(aResource,commentResource); 

Feedback

An instance of the feedback service is a prerequisite for handling feedback. Get the service as follows:

IRepositoryService repositoryService = repServiceFactory.getRepositoryService(aResource, IWcmConst.FEEDBACK_SERVICE);
IFeedback feedbackService = (IFeedback)repositoryService;

• Add feedback to a resource with a personal text (String):

boolean erg = feedbackService.addFeedback(aResource, text);

• Get all existing feedback assigned to a resource. Then use an iterator to access individual feedback items.

    IResourceList list = feedbackService.getFeedback(aResource);

    // Loop at Ressourcelist
    try {
      iterator = resList.listIterator();
      while (iterator.hasNext() ) {
        singleFeedback = (IResource) iterator.next();
        // Do whatever you want
      }
    }
    catch (Exception e) {}

• Delete a single feedback item for a resource:
  

   Boolean erg = feedbackService.delFeedback(aResource, singleFeedback);    

Rating

An instance of the rating service is a prerequisite for assigning or accessing rating. Get the service as follows: 

IRepositoryService repositoryService = repServiceFactory.getRepositoryService(aResource, IWcmConst.RATING_SERVICE);
IRating ratingService = (IRating)repositoryService;

• Add rating for a resource:

boolean erg = ratingService.addRating(aResource, rating);

• Get average rating assigned to a resource:

String average = getRatingAverage(aResource);

• Delete rating assigned to a resource by a specific user:

String userID = "MyUser";
deleteUserVoting(aResource, userID)

Personal Notes

An an instance of the personal note service is a prerequisite for handling personal notes. Access the service as follows: 

IRepositoryService repositoryService = repServiceFactory.getRepositoryService(aResource, IWcmConst.PERSONALNOTE_SERVICE);
IPersonalNote personalnoteService = (IPersonalNote)repositoryService;

• Add a personal note to a resource:

boolean erg = personalnoteService.addComment(aResource, text);

• Get the personal note assigned to a resource:

IResourceList list = personalnoteService.getComment(aResource);

Discussions

This section shows you how to handle a discussion with posts.

A discussion is comprised of IDiscussionItems in a tree structure. Each item is a contribution of a user and is referred to as a post. The whole structure of posts beneath a top-level post is referred to as a thread.

The following code extracts show you how to:

• Create or delete a discussion about a specific resource
• Add posts or delete posts from a discussion

In preparation for using the service, get an instance of the discussion service:

IRepositoryService repositoryService = repServiceFactory.getRepositoryService(aResource, IWcmConst.DISCUSSION_SERVICE);
IDiscussionManager discussionService = (IDiscussionManager)repositoryService;

• Creating and Deleting a Discussion

discussionService.createDiscussion(aResource);

To delete the discussion with all its replies, you use the deleteDiscussion(IResource resource)  method or the deleteDiscussion(IDiscussion) method of the IDiscussionManager:

discussionService.deleteDiscussion(IResource aResource);
discussionService.deleteDiscussion(IDiscussion aDiscussion);

• Adding a Post to an Existing Discussion

IDiscussion discussion = discussionService.getDiscussion(aResource);

//Create posts for the first discussion level
discussion.createItem(null, String postText, String postSubject);

//Create replies for an existing (parent) post
discussion.createItem(IDiscussionItem parentPost, null, String postText, null);

• Deleting a Post

You delete a post with the method deleteItem(IDiscussionItem item). If you want to delete more posts, you can use the method for deleting all replies to a post.

The deletion of a discussion or discussion items is restricted. An anonymous user may not delete an item. Authors can only delete items they have created which have no children. Users who have the service permission collaborationcan delete any discussions or items.

Note that permission checks are only carried out if the CollaborationSecurityManager is activated for the collaboration repository.

//Check permissions for deletion of a first level posts
Discussion.canDeleteItem(IDiscussionItem topic);

//Check, if post has replies
discussionItem.hasChildren();

//Delete the postdiscussion.delete
Item(IDiscussionItem item)

//Delete all replies of this post
discussion.deleteItemReplies(IDiscussionItem item)

//Get all first level posts
IDiscussionItemList firstLevelPosts = discussion.getTopics();

//Get all Children for a post or a first level post
IDiscussionItemList postList = discussion.getChildren(IDiscussionItem item)