Social Collaboration

Content Engine APIs support document-collaboration operations that can be implemented in client applications. Users can create tags, comments, and recommendations and apply them to Document objects. Administrators can retrieve server-generated collaboration summaries and download histories.

Important: The Social Collaboration Base Extensions Add-on and prerequisite add-ons are required for social collaboration API support.

The Social Collaboration Base Extensions Add-on provides the following classes.

Tag

Tags are user-creatable objects, represented by the ClbTag class. Tags are created by using standard factory methods.

There can be one tag object per version in a version series. The same user can associate no more than one tag to a version in a version series. All tag objects are deleted when the associated version series is deleted.

To create a tag for a document, a user is required to have AccessRight.WRITE permission on the document.

The user who creates a tag can delete it. To delete a tag that is created by a different user, a user is required to have both AccessRight.DELETE and AccessRight.WRITE permission on the released (or current if released not available) document version.

Tag objects are independently securable objects, which inherit security from the tagged Document object through the ClbSummaryData object. The security inheritance from the ClbSummaryData flows from the ClbSecuringVersion property. Documents within a teamspace can have different security than the teamspace itself, and so it is possible for none of the members of a teamspace to have view rights for a document or a tag.

Document Comment

Comments are user-creatable objects, represented by the ClbDocumentComment class. Comments are created by using standard factory methods.

There can be multiple comment objects per version in a version series. The same user can associate more than one comment to a version in a version series. All comment objects are deleted when the associated version series is deleted.

A user with AccessRight.VIEW-CONTENT permission can create a comment on a Document object. Comment objects inherit their security from the document, through the ClbSummaryData object. The security inheritance from ClbSummaryData flows from the ClbSecuringVersion property.

Comments can be deleted only by the user who created them, or by a user who has AccessRight.DELETE permission on the teamspace to which the document belongs.

Recommendation

Recommendations are user-creatable objects, represented by the ClbRecommendation class. Recommendations are created by using standard factory methods.

There can be one recommendation object on a version series per user. All recommendation objects are deleted when the associated version series is deleted.

A user with AccessRight.VIEW-CONTENT permission can create a recommendation on a Document object. Recommendations are independently securable objects, but they also inherit security from the recommended Document object, through the ClbSummaryData object. The security inheritance from ClbSummaryData flows from the ClbSecuringVersion property.

Recommendations can be deleted only by the user who created them, or by a user who has AccessRight.DELETE permission on the teamspace to which the document belongs.

Download Record

Download records are represented by the ClbDownloadRecord class. The server generates a download record object the first time an authenticated user downloads a document in a version series. For subsequent downloads by the same user, the download record object is updated. Download records cannot be created, modified, or deleted by applications.

Note: Generation of download records can be disabled through the ClbCollaborationConfiguration object.

Download record objects inherit security from the Document object, through the ClbSummaryData object. The security inheritance from ClbSummaryData flows from the ClbSecuringVersion property.

The server responds as follows to document downloads:

Creates one download record instance for each authenticated user who downloads a version of a document.
Increments download counts on the associated ClbSummaryData object for each download by an authenticated or anonymous user. Note that there are separate counter properties on the ClbSummaryData class: one for authenticated user downloads and one for anonymous user downloads.
In the download record for an authenticated user, records the highest major and minor version of the document, and the time when that version was downloaded.
For an anonymous user, counts the download only; the server does not generate download record objects for anonymous users.
Suppresses generation of download records based on security credentials set in the ClbCollaborationConfiguration object.
Controls the download record lifetime based on the lifetime of the associated document version series. When the document version series is deleted, all child downloads objects are also deleted.

Summary Data

Summary data objects are represented by the ClbSummaryData class. A summary data object is created by the server when a social collaboration action is invoked. It is associated with a document version series, and contains enumerations and counters for all of the social collaboration objects that are associated with the version series. Applications cannot create, delete, or modify summary data objects.

The following actions trigger the creation of a summary data object:

User downloads a document.
User recommends a document.
User tags a document.
User comments on a document.
User files a document within a teamspace.

Summary data objects inherit security from the ClbSecuringVersion property. The server updates this property so it is always set to the released version of the document (or the current version if a released version is not available).

A summary data object is deleted when all versions of its associated document are deleted. Deleting a summary data object cascade-deletes all download records, tags, recommendations, and comments that are associated with the document.

Collaboration Configuration

The collaboration configuration object is represented by the ClbCollaborationConfiguration class. It controls download recording operation.

The collaboration configuration object is created by the server when the Social Collaboration Base Extensions Add-On is imported into an object store. The imported instance has a fixed object ID and is retrieved by using that fixed object ID. The server-generated instance must not be deleted.

The collaboration configuration object is intended solely for administrative use. It is typically accessed with IBM® Administration Console for Content Platform Engine, rather than with a custom application.