The Discussions category enables you to control Oracle Beehive's Discussions Service. This service enables organizations to host threaded, online discussion forums in which users can browse message boards, and post and respond to messages.

Refer to the section "Discussions Service" in the module "Oracle Beehive Services" in Oracle Beehive Concepts in Oracle Beehive Documentation Library.

A forum is a container for any number of topics.

A topic is a collection of discussion messages. It represents one threaded, online discussion among a forum's members.

A discuss this forum is a special forum that contains all topics about a particular bondable object that is being discussed.The DiscussThisForum resource is a marker interface and does not add any methods to Forum.

An announcement is a special type of topic. It represents an important or time-sensitive topic, and is generally be placed in a special announcement forum or at the top of a regular forum. In general, only moderators are allowed to post an announcement. It has an active and an expiration date. Before the active date, an announcement is kept hidden from non-moderators; after the expiration date, the announcement may be hidden, archived, or marked as expired.

The DiscussionMessage resource is a message with the added semantics of threading. A DiscussionsMessage has child DiscussionsMessages and optionally a parent DiscussionsMessage. The first DiscussionsMessage of a Topic does not have a parent DiscussionsMessage. Every DiscussionsMessage must have a parent topic that contains that message.

The DiscussionsDraft resource is a draft version of a discussions object; it can be a draft version of a new topic, a draft version of a new announcement, or a draft version of a reply to an existing topic/announcement (a draft of a DiscussionsMessage). The DiscussionsDraft has an intended destination that represents where it will exist once it is posted. In the case of a draft topic or announcement, the destination is a handle to the Forum where the new Topic or Announcement will be created when the draft is posted. In the case of a draft DiscussionsMessage, the destination is a handle to the DiscussionsMessage for which this draft is a reply. When the draft DiscussionsMessage is posted, it will be a new child message of the destination message.

The following table describes the relationships among Discussions category resources:

Resource	Permissible Child Elements
HeterogeneousFolder	DiscussionDraft: Zero or more
DiscussionsDraft	None
Workspace	Forum: Zero or more DiscussThisForum: Zero or more
Forum	Forum: Zero or more Announcement: Zero or more Topic: Zero or more
DiscussThisForum	DiscussThisForum: Zero or more Announcement: Zero or more Topic: Zero or more
Topic	DiscussionsMessage: One or more
Announcement	DiscussionsMessage: One or more
DiscussionsMessage	None

Discussions Programming Tips

This section covers the following topics:

• Required Privileges

• Working with DiscussThisForum

• Working with Topic

Required Privileges

The logged in user requires the FORUM_USER or FORUM_MGR to access his or her discussions messages. Refer to the section "Managing Privileges" in the module "Managing Oracle Beehive Access Control" in Oracle Beehive Administrator's Guide for more information.

Working with DiscussThisForum

A comment posted on a forum in response to an artifact is a discussion message that is stored in a DiscussThisForum, which is a forum created automatically to contain discussion messages on an artifact. For example, you may start a DiscussThisForum in response to a Document by creating a DiscussArtifactParameter, setting its ArtifactHandle to the Document's EID, then sending the DiscussArtifactParameter to the /adoc/discuss/ POST method.

You cannot start a new DiscussThisForum in response to a Topic, Announcement, DiscussThisForum, or DiscussionsMessage.

When you retrieve discussion messages from a forum, Oracle Beehive RESTful Web Services will not retrieve any discussion messages stored in DiscussThisForums. To retrieve these discussion messages, follow these general steps:

1. Retrieve the artifact that has comments associated with it.

2. From this artifact, retrieve the bond of type DISCUSS_THIS.

3. From this bond, obtain the DiscussThis forum that contains the comments.

Working with Topic

This section contains the following topics:

• Setting Permissions on Forums

Setting Permissions on Forums

The forum resource has two members, discussionMessageDeletePermissions and discussionsMessageUpdatePermissions, with which you define who may delete or update discussion messages in the forum and when these delete and update operations may be performed.

The discussionMessageDeletePermissions and discussionsmessageUpdatePermissions members contain three members:

• when: This member may have one of the following values. If this is not specified, the default is Always:

  • Always: Indicates that the user can always update/delete a message in the forum (unless prevented by another permissions setting).

  • No Replies: Indicates that the user can only update or delete a message in the forum if there are no replies to the message.

  • Never: Indicates that a non-moderator can never update or delete a message in the forum.

  • Defers: Indicates that the forum uses the permissions settings of its parent forum or workspace. If no When setting is specified, the default is Always.

• who: This member may have one of the following values. If this is not specified, the default value is Always.

  • Always: Indicates that the user can update or delete any user's messages in the forum.

  • Author Only: Indicates that only the creator of a discussions message (or the forum moderator) can update or delete a message.

  • Defers indicates that the forum uses the permissions settings of its parent forum or workspace.

• time limit: A non-negative, non-zero integer indicates the number of minutes during which a user is allowed to update or delete the discussions message. For example, if Time Limit is set to 5, non-moderators can no longer update or delete the message once five minutes have passed after its creation. A value of zero indicates no time limit; a non-moderator can update or delete the message at any time. A value of -1 indicates that the time limit setting defers to the setting of its parent forum or workspace. If no Time Limit setting is specified, the default is 0, or Always.