ds external reference specification - collabnet external... · terminology: email may also be used...

Discussion Service External Reference Specification

1

CollabNet Discussion Service

External Reference Specification

Version 2.3


2

Table of Contents

..............................................................................................................................1 CollabNet Discussion Service External Reference Specification .......................................................................................... 1

Introduction ............................................................................................................................................................................ 4

End User Scenarios ............................................................................................................................................................... 4

User: Tony, Technical Developer ..................................................................................................................................... 4

Scenario 1: Signing up for a new discussion .............................................................................................................. 4

Scenario 2: Reading a topic ........................................................................................................................................ 9

Scenario 3: Replying to a message .......................................................................................................................... 11

Scenario 4: Posting a new message......................................................................................................................... 14

User: James, Project Manager ....................................................................................................................................... 15

Scenario 1: Approving messages for posting ........................................................................................................... 15

Scenario 2: Deleting messages from a discussion ................................................................................................... 20

Scenario 3: Adding subscribers to a discussion ....................................................................................................... 23

Scenario 4: Designating additional moderators ........................................................................................................ 27

Scenario 5: Adding a new discussion ....................................................................................................................... 28

User Permissions................................................................................................................................................................. 31

Processing Flows ........................................................................................................................................................... 32

Examples........................................................................................................................................................................ 33

Unmoderated Discussions.............................................................................................................................................. 33

Moderated Discussions .................................................................................................................................................. 34

Trusted Discussions ....................................................................................................................................................... 36

Error Conditions.............................................................................................................................................................. 38

Administration ...................................................................................................................................................................... 39

Host Admin ..................................................................................................................................................................... 39

Email Configuration:.................................................................................................................................................. 39

Domain Admin ................................................................................................................................................................ 41

Project Owner................................................................................................................................................................. 42

Discussion Owner........................................................................................................................................................... 43

Discussion Information Administration...................................................................................................................... 43

Moderator Administration.......................................................................................................................................... 48

Subscriber Administration ......................................................................................................................................... 48

Deleted Message Administration .............................................................................................................................. 49

What Has Changed?............................................................................................................................................................ 51

Mailing List Differences .................................................................................................................................................. 51

Discussion Forum Differences........................................................................................................................................ 53

Index .................................................................................................................................................................................... 54


3

Table of Figures Figure 1: Tony’s Start Page ................................................................................................................................................... 5

Figure 2: Widget Project’s Home Page.................................................................................................................................. 6

Figure 3: Widget Project’s Discussions Index Page .............................................................................................................. 7

Figure 4: Developers Summary Page.................................................................................................................................... 8

Figure 5: Subscription Settings Page .................................................................................................................................... 9

Figure 6: Topic View Showing Message Context ................................................................................................................ 10

Figure 7: Topic View Showing all Replies............................................................................................................................ 11

Figure 8: Replying to a Message ......................................................................................................................................... 12

Figure 9: Message Reply Showing Quoted Text ................................................................................................................. 13

Figure 10: Post Message Screen......................................................................................................................................... 14

Figure 11: Post Message Screen with Attachment.............................................................................................................. 15

Figure 12: Discussion Index Seen by Administrator ............................................................................................................ 16

Figure 13: Pending Approval Seen by Moderator................................................................................................................ 17

Figure 14: Topic View Seen by Moderator .......................................................................................................................... 18

Figure 15: Topic View of Message After Approval............................................................................................................... 19

Figure 16: Topic Index for Administrator.............................................................................................................................. 20

Figure 17: Topic Index Showing All Replies ........................................................................................................................ 21

Figure 18: Topic Index Marking Messages for Deletion ...................................................................................................... 22

Figure 19: Deleted Messages Warning Indication ............................................................................................................... 23

Figure 20: Subscribers Page ............................................................................................................................................... 25

Figure 21: Browse Users Page............................................................................................................................................ 26

Figure 22: Adding Subscribers to the Discussion ................................................................................................................ 27

Figure 23: Moderators Page ................................................................................................................................................ 28

Figure 24: Add Discussion Page Showing Discussion Information ..................................................................................... 29

Figure 25: Add Discussion Page Showing Discussion Settings .......................................................................................... 30

Figure 26: Discussion Permission Summary ....................................................................................................................... 31

Figure 27: Flow of control in message posting .................................................................................................................... 32

Figure 28: Host Admin Configuration................................................................................................................................... 39

Figure 29: Mail Reader Configuration Options .................................................................................................................... 40

Figure 30: Domain Admin Configuration.............................................................................................................................. 42

Figure 31: Project Owner Configuration .............................................................................................................................. 43

Figure 32: Discussion Owner Configuration – Discussion Information................................................................................ 44

Figure 33: Discussion Owner Configuration – Discussion Settings..................................................................................... 44

Figure 34: Discussion Owner Configuration – Email Content.............................................................................................. 46

Figure 35: Discussion Owner Configuration – Advanced Email Content............................................................................. 47

Figure 36: Administrator Moderators Screen....................................................................................................................... 48

Figure 37: Administrator Subscribers Screen ...................................................................................................................... 49

Figure 38: Administrator Deleted Messages Screen ........................................................................................................... 50


4

Introduction The Discussion Service (DS) is a set of Java services and user interfaces that work together to provide threaded Discussions to users via a web interface and also via email messages. This specification describes the DS from an external point of view; that of its users. The service’s web interface consists of several discrete screens. In this specification, we introduce the most important screens first using two user scenarios that were developed for initial customer presentations. Additional screens not covered by these scenarios are presented last. Note: In the following screen shots, the terms forum and thread are sometimes used instead of discussion and topic that appear in the text. This is due to the incomplete status of the terminology change that is underway and will be corrected once the screens are updated. The terms discussion and topic are to be preferred while discussion and thread are deprecated.

End User Scenarios

User: Tony, Technical Developer Tony is a software engineer at a software company that uses CollabNet Enterprise Edition for development. He is part of a team that consists of 12 developers and QA engineers, plus James, the Project Manager. Because the team spans several continents and time zones, many conversations about the project are carried out asynchronously in CollabNet “Discussions.”

Scenario 1: Signing up for a new discussion Tony has just become a member of the widgets project. He knows that a discussion named Developers exists for project. From Tony’s start page, he can see a list box containing all of the Discussions in all of the projects to which he has already subscribed. Terminology: A Discussion is a collection of Topics, each of which may contain many textual Messages. The messages contained within each topic reflect an asynchronous dialog of comments made by the participants within a single discussion. Subscription is the process that allows users to indicate their interest in certain discussions. When a user subscribes to a discussion, that discussion will appear on the user’s start page and any recent activity will be indicated. Subscription also enables Email Notification, and users may subscribe to any discussion that they have permissions to view. When a user subscribes to a discussion using any of the notification options, that discussion will be enabled to show on the user’s start page as indicated below. In this display, the citation for each discussion will only be present if that discussion


5

has messages that are recent. Recent messages are defined to be those that have been received within the last 48 hours. Terminology: A subscriber may also use this page to unsubscribe from a discussion which is no longer of interest. Unsubscribing will cause the discussion to be removed from the user’s start page and all notifications will cease. Terminology: A user may use an email client to subscribe to a discussion if that user has necessary permission to view it. To subscribe to a discussion, send an email message addressed to <discussion>-subscribe@<project>.<domain>. If you have the needed permission you will receive a confirmation email from the system. Upon receipt of this confirmation, you must reply to it in order to activate your subscription. A user may additionally unsubscribe from a discussion via email by sending a message addressed to: <discussion>-unsubscribe@<project>.<domain>.

Figure 1: Tony’s Start Page

1. Tony clicks the link for widgets, and goes to the project’s home page. The

project home page has a My Tools section in the left navigation bar. This section contains a link to the Discussions page for the project.


6

Figure 2: Widget Project’s Home Page

2. He clicks “Discussions” in the left navigation to go to the discussions index

page. The index page shows each of the discussions that have been created for the project, along with summary information of interest to readers of each discussion. If the user has not subscribed to a particular discussion, it will appear grayed-out as below.


7

Figure 3: Widget Project’s Discussions Index Page

3. Tony sees that Developers has a grayed-out icon indicating he is not

subscribed. He clicks the link for Developers. This page shows summary information for a particular discussion, including its description, email address, web URL, creation information and a summary of each of its message topics.


8

Figure 4: Developers Summary Page

4. Tony wants to subscribe to this discussion. He clicks “My subscription

settings” at the top of the page. This page shows his current subscription status for the discussion and the notification option that has been selected

Terminology: Discussions have three notification modes as shown below: Message-by-message notification causes an email to be sent to Tony’s registered email address each time any user posts to the discussion. Digest-format notification will send an email every day that contains all postings since the previous day as attachments. My start page only indicates that no email notification is desired and that Tony prefers to read messages on the web.


9

Figure 5: Subscription Settings Page

5. He checks “Subscribed.” The default notification setting is automatically

set to “Message-by-message.” 6. He clicks “Save.” A message confirms that he is subscribed to the

discussion “Message-by-message.” 7. Now that Tony is a subscriber to this discussion he will receive email

notifications each time a user posts to the discussion. Terminology: Email is an alternative way to read and post to discussions that may be enabled by the discussion owner. Any user who has permission to post to a discussion may post via email. The email address of a discussion is specified when the discussion is created (see Figure 23) and has the form: <discussion name>@<project name>.<domain>.

Scenario 2: Reading a topic Tony sees a topic in the index that appears to be relevant to what he’s working on. He wants to read the entire conversation. From the topic index page for the discussion (Figure 3):


10

1. Tony clicks the link “Project Requirements?” which takes him to the top of the topic. He wants to read all the messages in this topic, but does not want to click on each message.

Figure 6: Topic View Showing Message Context

2. Tony clicks “Show all messages in topic.” He scrolls down and reads the

entire conversation in one page.


11

Figure 7: Topic View Showing all Replies

Terminology: Email may also be used to read a message. If a user is a subscriber to a discussion he will receive an email notification message each time somebody posts via email or the web interface. If he has selected the “Digest” form of delivery, he will receive a single email each day containing all of the postings received that day.

Scenario 3: Replying to a message Tony has something to add to the conversation. At the bottom of the topic (Figure 7):

1. Tony clicks the “Reply” link. He sees that the original message he is replying to is at the bottom.


12

Figure 8: Replying to a Message

2. He wants to quote the message, so he clicks “Quote original.”

Terminology: Message Quoting is a common practice in mailing lists, and is supported my most email clients when replying to another message. It causes the entire context of a message topic to be repeated in each message posting. This can result in unnecessary clutter, obfuscating the reply with too much text. In our web interface, we discourage quoting as the message display pages automatically will show the previous message context.

Terminology: Attachments may be added to the reply if desired. Clicking the “Attach a file” link will allow the user to add attachments to the reply that will be stored in the archive and also transmitted to subscribers who have selected the “message-by-message” notification option. Attachments are never sent to subscribers who have selected “message-digest” option. Terminology: The default behavior is to send the reply to the list, as indicated by the check box next to Topic. This causes the message to be saved in the archive and all subscribers to be notified. If the user checks Author (directly in email) then the author will also receive a notification, even if the author is not a current


13

subscriber. Checking only the Author box will send the author notification only and not post the message to the archive. Finally, additional Other recipients addresses may be added which will cause other email recipients to receive notification messages. Terminology: Email may also be used to reply to a message. If a user is a subscriber to a discussion and receives an email notification message, pressing his mail client’s <reply-to> button will create a new email message that is properly addressed to post the reply to the original message. Depending on mail client settings, the original message is often ‘quoted’ in the reply. Adding text (and attachments) to the message is followed by pressing the <send> button. The mail will be received by the discussion and the message will be added as a reply, just as though the web interface had been used as above.

Figure 9: Message Reply Showing Quoted Text

3. He types the subject and body text that he wishes to post. Note that the

subject of a reply does not need to be the same as that of the original message. This allows the subject index to become more informative as individual messages may have their own subjects. This is also the case for email replies by users employing RFC 2822-compliant email clients.


14

(Unfortunately, not all of the Microsoft email clients are compliant at this time, though we understand this will be corrected in the future)

4. He clicks “Save.” His submission requires moderator approval before it is posted.

Scenario 4: Posting a new message Tony wants to suggest a possible photo to be used for the widgets project. He’s already taken a photo and wants to post it.

1. Tony clicks “Post message” in the task navigation (Figure 4).

Figure 10: Post Message Screen

2. Tony types the subject and body of his message. 3. He wishes to attach the screenshot, so he clicks “Attach a file.” He clicks

“Browse…” (or “Choose File” on Safari) to select the screen shot. Terminology: Attachments may be appended to postings as described previously. The user may also specify Other recipients in a manner similar to the cc


15

Terminology: Email may also be used to post to a discussion. Any attachments that are added to the email will be added as attachments to the message in the discussion’s archive. The email address of each discussion is shown on its summary page (see Figure 4).

Figure 11: Post Message Screen with Attachment

4. He clicks “Save.” His submission also requires moderator approval before

it is posted.

User: James, Project Manager James is a project manager for the widgets team of 12 developers and QA engineers, including Tony. As a project owner, James has administrative rights to the discussions in the project, which lets him add subscribers, designate moderators, and change the discussion settings.

Scenario 1: Approving messages for posting James notices on the Discussions index page that there are new

messages that are awaiting moderator approval before they can be posted. The


16

link to Developers is in red and has a tool tip saying “New post(s) requiring moderator approval.” Since he created the discussion, he is the moderator by default. Terminology: All messages posted to moderated discussions need to be screened by a moderator before they are added to this discussion. Moderators are designated users that have the ability to perform this review.

Figure 12: Discussion Index Seen by Administrator

1. James clicks Pending approval. This takes him to the discussion’s

pending approval page .


17

Figure 13: Pending Approval Seen by Moderator

2. He sees the topic “RE: Project Requirements” was posted by tony.” He

clicks on the link for the topic, which takes him to the top of the topic.


18

Figure 14: Topic View Seen by Moderator

3. He sees that message, which is in yellow, is the message awaiting

approval. He clicks on the message.


19

Figure 15: Topic View of Message After Approval

4. James reads the message and it appears okay for posting. He clicks

“Approve message for posting.” The message is now approved. Terminology: Email Moderation is also supported by discussions. If a user is a moderator to a discussion and a message is received that requires moderation, the user may read and approve or disapprove the posting using a standard email client. To approve a message for posting, the moderator merely needs to click <reply to> and <send>. The approval is automatic. To disapprove a message, the moderator can do nothing, in which case the message will be automatically rejected after a few days. Alternatively, the moderator can press <reply all>, delete the addressee that contains the –approve– keyword and press <send>. Terminology: If a moderator wishes to send a message to the poster of a rejected moderated message, the moderator can add text between the two %%% delimiter lines in the rejection message. This text will be sent as an email to the original poster. If a moderator wishes to include an initial comment to the body of an approved moderated message, the moderator can add text similarly in the approval message.


20

Scenario 2: Deleting messages from a discussion While he’s there, James wants to clean up the discussion by manually deleting some messages.

1. James clicks “Discussion index” in the task navigation to see the list of topics.

Figure 16: Topic Index for Administrator

2. He wants to delete individual messages, not entire topics, so he needs to

expand the topics to see all the replies. He clicks the link “Show replies for each topic.”


21

Figure 17: Topic Index Showing All Replies

3. James selects some messages and clicks the “Delete selected” button at

the bottom.


22

Figure 18: Topic Index Marking Messages for Deletion

4. He gets a confirmation page informing him that he can delete only the

selected messages, or include all associated replies as well.


23

Figure 19: Deleted Messages Warning Indication

5. He clicks “Delete messages only.” The messages are marked as deleted.

Note: deleted messages are not actually removed from the archive and may be reviewed by discussion owners where they may be restored to undeleted status or permanently removed from the archive.

Terminology: The Discussion Service maintains messages in a tree structure, where the replies to each message or reply are ‘contained’ within it, much as in an index (see Figure 14). Delete messages only is a deletion option that deletes the message and any attachments to it, but not its place in the tree. Delete messages and replies will delete the messages and any replies under it in the tree.

Scenario 3: Adding subscribers to a discussion James wants to add two team members, user4 and user5, to the discussion.

1. James clicks “Edit discussion” in the topic index. This takes him to the edit discussion page. This page has tabs that allow him to edit the general


24

information, moderators, subscribers and deleted messages. He clicks on the subscribers tab.

Terminology: Any user with the ability to view a discussion through its web interface may also subscribe to the discussion. Subscribers will receive email messages that notify them of postings to the discussion. Terminology: While the typical subscriber to a discussion will be a CEE user, there are actually four types of subscribers that can be indicated. If a user is present in more than one of a discussions’ subscriber lists, only a single email notification will be sent.

1. CEE User Subscribers are denoted by their user name. For CEE users, it is not necessary to include the site’s domain name (e.g. tony instead of tony@domain is sufficient).

2. Anonymous Subscribers are denoted by a full email alias, including their domain name (e.g. [email protected]). Anonymous subscriptions must be verified before they are activated. The DS will send a probe email to the subscriber’s alias and the subscription will not be activated until an affirmative response email is received.

3. Discussion Subscribers are denoted by the full email alias of the discussion (e.g. [email protected]). When a discussion is indicated as a subscriber, an email will not be sent to that discussion itself. Instead, the subscribers to that discussion will be added to the distribution list of the parent discussion’s notification and its users will receive that notification. Creating infinite loops of discussion subscribers is not recommended, though the system handles it gracefully. In order to add a discussion subscriber, the user performing the operation must have admin permission and post without moderation permission on the target discussion.

4. Group Subscribers are denoted by an email alias with the following format: <group>@<domain>. Notifications sent to a group subscriber will be sent to all of the current members of the group each time a notification is sent. In order to add a group subscriber, the user performing the operation must have the “User Group – View” permission.


25

Figure 20: Subscribers Page

2. To make sure he enters the user names correctly, rather than typing them

in manually, he decides to select them from the list of available users. He clicks “Browse users.”


26

Figure 21: Browse Users Page

3. James checks “doodala” and “reguser”, and clicks “Add.” He returns to the

Subscribers page, noting that they are now on the “User name(s)” field.


27

Figure 22: Adding Subscribers to the Discussion

4. He clicks “Add.” The users have been added.

Scenario 4: Designating additional moderators James would like veena to be a moderator as well.

1. James clicks “Moderators” in the task navigation. This takes him to the Moderators page.

Terminology: Moderators are users who are designated to review and approve messages for posting to Moderated Discussions. Unmoderated Discussions do not require the approval of moderators and posting occurs as soon as the user enters the message.


28

Figure 23: Moderators Page

2. He clicks “Browse users.” (Figure 21) 3. James checks veena, and clicks “Add.” The “User name(s)” field has been

populated with veena on the Moderators page. 4. He clicks “Add.” The user has been added.

Scenario 5: Adding a new discussion James wants to add a new high-level discussion for planning topics about the project. To return to the Discussions index page:

1. James clicks “Discussions” in the left navigation (Figure 12). 2. He clicks “Add discussion” in the task navigation.


29

Figure 24: Add Discussion Page Showing Discussion Information

3. He enters the title for the new discussion, and enters the email alias and

description. Terminology: The Title of a discussion is used in the web interface when the discussion must be referenced by a short name. The title may be changed after the discussion is created. The Email address of a discussion is the address to which email messages may be sent for electronic mail posting. The Email Address may be set once when a discussion is created but may not be changed after that. Email addresses must be unique within all of the discussions of a project. The Description is a longer description of the discussion that is used when a more detailed description is needed by the user interface. It may also be changed after the discussion is created.

4. Now he wants to set up the permissions for the discussion. He doesn’t want nonmembers of the project to be able to see the planning discussion, so he checks “Private.”

5. He wants this to be a moderated discussion, but there are certain project leads that do not need moderation. He checks “Moderated” and “Trusted posts” to configure these options.


30

6. Anonymous subscription and guest posting are inappropriate for this discussion, so he leaves those boxes unchecked.

Figure 25: Add Discussion Page Showing Discussion Settings

7. James wants to permit members to post directly from their email accounts.

He checks “Email posting.” Terminology: Anonymous users are users who have not registered for a domain account. If enabled for a discussion, these users may subscribe for email notification just like registered users. Guest posting indicates that anonymous users are allowed to post to a discussion. Email posting indicates that users are allowed to post to this discussion via email messages. If guest posting and email posting are both enabled, then anonymous users may post via email.

8. He clicks “Add discussion.” The discussion has been added.


31

User Permissions The Discussion Service requires users to have various permissions in order to perform operations on discussions. The following table summarizes the permissions that are required for the six types of discussions that are supported by the DS. As in the rest of CEE, permissions are given to users within the context of a project to perform certain actions on certain resources of the project.

Discussion Type

Access Viewing & Subscribing

Moderated Posting

Unmoderated Posting

Public View Post Unmoderated Private View +

Private Post +

Private

Public View Post Post + Trusted Trusted

Private View + Private

Post + Private

Post + Trusted + Private

Public View Post Moderated

Private View + Private

Post + Private

Figure 26: Discussion Permission Summary View permission on a discussion in a project allows a user to read the messages that have been posted to the discussion and to subscribe to email notifications of changes to the discussion Private permission on a discussion in a project allows a user to have access to private discussions within the project Post permission on a discussion in a project allows a user to post messages, either via the web or via email to suitably enabled discussions. Trusted permission on a discussion in a project allows a user to post messages without moderation to moderated discussions that have been enabled to allow trusted posting.


32

Processing Flows The following figure illustrates the flow of processing in the DS as the various discussion option and user authorization checks are made.

Figure 27: Flow of control in message posting


33

Examples The following examples illustrate some common posting use cases and the order of processing that occurs:

Unmoderated Discussions Unmoderated discussions are the most open style of discussion. Users with appropriate permission may post and reply to unmoderated discussions without additional controls. 1) User posts a message on an unmoderated discussion:

a) If the discussion is marked private and the user does not have discussion-

use-private permission, then the posting is not allowed and an error is thrown. i) If the posting was via then the poster will receive an email notification

advising of this fact. b) If the user does not have discussion-post permission, then the posting is

not allowed and an error is raised. i) If the posting was via email it is dropped and the user will receive an

email notification advising of this fact. c) If the posting is via email and the discussion does not have email posting

enabled, then the poster will receive an email notification advising of this fact.

d) If the posting size exceeds the maximum posting size for the discussion, then it is not allowed and an error is thrown. i) If the posting was via email then a notification is returned to the poster

advising of this fact. e) If the message contained denied or blocked attachments then these are

removed from the message prior to posting. i) If the posting was via email then the original poster will receive a

notification describing the attachments that were deleted. f) If the poster has indicated any Other-recipients, then an immediate copy

of the posting will be emailed to those recipients. i) If the posting was done via email, then the poster’s email client would

have done the same action. g) The DS archives the message and sends a notification email to all the

subscribers of the discussion who are subscribed message-by-message. i) Subscribers that subscribed digest-message will receive a digest

containing the messages that have been received once per day. Digest messages do not contain any of the attachments from the original posting.

ii) Subscribers that are subscribed my-start-page-only will have the message marked as unread on their discussion index view. Reading it will cause it to be marked as read.


34

h) If the discussion is enabled for guest subscribers, then any guest subscribers will also receive notifications as above i) Guest subscribers may only receive email notifications. They cannot

select my-start-page-only notification, for they have no start page.

2) User replies to a message on an unmoderated discussion: a) Preprocessing authorizing and filtering checks are performed as in 1)a)-e,

above. b) The following Reply-to options are independent of each other, and any

combination may be selected (including none, in which case the reply is ignored): i) If the user has checked Reply to Author, the DS sends the reply as an

immediate email to the author of the original message ii) If the user has included any Other recipients on the web page, then

copies of the reply will be immediately sent to them too. iii) If the user has checked Reply to Topic, the DS archives the reply and

sends notification emails to all the subscribers of the discussion as in 1)g).

3) Guest posts a message on an unmoderated discussion :

a) If the discussion owner has selected Allow guest posting then the DS

performs authorization and filtering, archives the message and sends notification emails to all the subscribers of the discussion as in 1). i) If the discussion is not enabled for guest posting, then the poster will

receive an email notification advising of this fact. (1) If the posting is via email it is dropped as an anti-SPAM measure.

4) Guest replies to a message on an unmoderated discussion:

a) If the discussion owner has selected Allow guest posting then the DS performs authorization and filtering, archives the message and sends notification emails to all the subscribers of the discussion as in 2). i) If the discussion is not enabled for guest posting, then the poster will

receive an email notification advising of this fact. (1) If the reply is via email it is dropped as an anti-SPAM measure

Moderated Discussions Moderated discussions are the most restrictive style of discussion. Every posting from the user community is first screened by one of a set of designated moderators before it is allowed.


35

5) User posts a message on a moderated discussion: a) Preprocessing authorizing and filtering checks are performed as in 1)a)-e),

above. b) If the poster has indicated any Other-recipients, then an immediate copy

of the posting will be emailed to those recipients. i) If the posting was via email, then the poster’s email client would have

done the same action. c) The posting is archived in the DS but placed in an unmoderated state.

i) If the user is a moderator of the discussion, then the posting will be placed in the accepted state. This is allowed since the moderator can accept his own message postings anyway. Moderation is skipped and processing continues at (e), below.

d) The moderators of the discussion will receive an email notifying them that the message has been posted. i) Any moderator may reply to a moderation email to either approve or

reject it (1) If the moderator wishes to send rejection comments to the original

poster then these may be included in the moderation rejection email

(2) If the moderator wishes to include acceptance comments that are pre-pended to the body of the message then these may also be included in the moderation acceptance email

ii) Any moderator may use the web interface to accept or reject messages

iii) Once a message is rejected it is removed from the DS archive (hard delete)

e) Once a moderator has accepted a message, its status is marked accepted for viewing by all users and notification emails are sent as in 1.g above.

6) User replies to a message on a moderated discussion:

a) Preprocessing authorizing and filtering checks are performed as in 1)a)-e, above.

b) The following Reply-to options are independent of each other, and any combination may be selected (including none, in which case the reply is ignored): i) If the user has checked Reply to Author, the DS sends the reply as an

immediate email to the author of the original message ii) If the user has included any Other recipients on the web page, then

copies of the reply will be immediately sent to them too. iii) If the user has checked Reply to Topic, the DS the reply is archived in

the DS but placed in an unmoderated state. (1) If the user is a moderator of the discussion, then the posting will be

placed in the accepted state. This is allowed since the moderator


36

can accept his own message postings anyway. Moderation is skipped and processing continues at 5)e), above.

(2) The moderators of the discussion will receive an email notifying them that the message has been posted as in 5)d)above.

(3) Once a moderator has accepted a message, its status is marked for viewing by all users and notification emails are sent as in 1)g) above.

7) Guest posts a message on a moderated discussion:

a) If the discussion owner has selected Allow guest posting then the DS

performs authorization and filtering, archives the message and sends moderation and notification emails as in 5). i) If the discussion is not enabled for guest posting, then the posting is

ignored and an error is thrown. (1) If the posting is via email it is dropped. If the guest user would

otherwise have posting permission for the discussion, the guest will receive an email notification that the posting was declined. This could occur, for example, if the guest user had discussion-post permission for other discussions in the project.

8) Guest replies to a message on a moderated discussion:

a) If the discussion owner has selected Allow guest posting then the DS performs authorization and filtering, archives the message and sends moderation and notification emails as in 6). i) If the discussion is not enabled for guest posting, then the posting is

ignored and an error is thrown. (1) If the posting is via email it is dropped. If the guest user would

otherwise have posting permission for the discussion, the guest will receive an email notification that the posting was declined. This could occur, for example, if the guest user had discussion-post permission for other discussions in the project.

Trusted Discussions Trusted discussions offer moderated posting midway between unmoderated and moderated discussions. For most users, they behave like moderated discussions; however certain users may be designated as trusted and for them these discussions behave like unmoderated discussions. Currently, a user must be a subscriber of a trusted discussion in order to obtain the trusted posting capability.


37

9) User without trusted permission posts a message on a trusted discussion:

a) The message will be handled in the same manner as if the discussion

were moderated as in 5), above. 10) User without trusted permission replies to a message on a trusted

discussion:

a) The message will be handled in the same manner as if the discussion were moderated as in 6) above, above.

11) User with trusted permission posts a message on a trusted discussion:

a) The message will be handled in the same manner as if the discussion were unmoderated as in 1) above, above.

12) User with trusted permission replies to a message on a trusted

discussion:

a) The message will be handled in the same manner as if the discussion were unmoderated as in 2) above, above.

13) Guest without trusted permission posts a message on a trusted

discussion: a) The message will be handled in the same manner as if the discussion

were moderated as in 7), above. 14) Guest without trusted permission replies to a message on a trusted

discussion:

a) The message will be handled in the same manner as if the discussion were moderated as in 8), above.

15) Guest with trusted permission posts a message on a trusted

discussion: a) The message will be handled in the same manner as if the discussion

were unmoderated as in 1), above.


38

16) Guest with trusted permission replies to a message on a trusted discussion:

a) The message will be handled in the same manner as if the discussion

were unmoderated as in 4), above.

Error Conditions In the web interface, the following error conditions are checked when the user presses the save button to post or reply to a message. If any of these conditions is violated then an error message will be displayed:

• Total message size – the size of the message and its attachments may not be greater than the discussion’s Message Size setting

• Individual attachment size – the maximum size of attachments may be limited at the domain level. It may not be overridden.

• Block all attachments – no attachments are allowed • Block denied MIME types – certain attachment types are not allowed • Wrong user name – CEE user names are checked and verified • Guest posting disabled – guests will not be allowed

For email postings, the same error conditions are checked when messages are received by the DS. If any of these conditions is violated and the sender otherwise has posting rights to the discussion, then an email message will be sent back to the sender of the message explaining the error condition and what was done.

• Total message size – the size of the message and its attachments may not be greater than the discussion’s Message Size setting. An email notification will be sent advising the sender that the message was rejected.

• Individual attachment size – the maximum size of attachments may be limited at the domain level. It may not be overridden. An email notification will be sent advising the sender which attachments were rejected.

• Block all attachments – no attachments are allowed. All attachments will be stripped from the posting and an email notification will be sent advising the sender that this occurred.

• Block denied MIME types – certain attachment types are not allowed. Offending MIME types will be stripped from the posting and an email notification will be sent advising the sender this occurred.

• Wrong user name – CEE user names may not be entered via email postings

• Guest posting disabled – guests will receive an email notification • Email posting disabled – all posters will receive an email notification


39

Administration The following sections describe the administrative screens that configure the various options for discussions.

Host Admin Two discussion attributes may be configured at the host admin level: This section allows control over the indexing that is provided for discussions within the domains maintained by the host.

Figure 28: Host Admin Configuration

Email Configuration: Email communication is an important part of collaboration, and many CEE services send email messages to users to notify them of important events that occur within the system, and discussion posting notifications constitute a major portion of these notifications.


40

Mail Reader Service: The Mail Reader Service (MRS) communicates with the site’s Postfix mail transport agent (MTA) using the SMTP protocol. It has several configuration options that may be set at the site level. Currently, these are contained in the system-ext.properties configuration file that is managed by Operations. The MRS receives all incoming email addressed to the site, except for end user emails that are routed to their proper email accounts elsewhere.

## Mail Reader Service # # The port that the SMTP server will listen on MailReaderService.serverPort=2525 # The number of listener connections MailReaderService.serverConnections=25 # The size of the LRU cache used to eliminate duplicate messages MailReaderService.cacheSize=1000 # Number of hours to wait before VERP messages are processed MailReaderService.verpTimeoutHrs=168 # Number of hours to wait before running VERP check # e.b. 4 hrs MailReaderService.verpLockoutHrs=4

Figure 29: Mail Reader Configuration Options SMTP Listeners: The MRS supports a set of serverConnections listener topics that respond to SMTP commands from Postfix. These topics listen on serverPort.

Email Duplicate Detection Policy: Email delivery is not guaranteed to be ‘at most once’. Because of temporary routing issues within the internet, a given email sent by a user may be received more than once by its recipient. Within the MRS, duplicates are detected if they occur within cacheSize messages of each other. This value is adjustable by system administrators so that, in most cases, duplicate messages are ignored by the MRS and duplicate postings to the discussion service do not occur. Email Bounce Policy: When users move to another ISP or when temporary circumstances prevent the delivery of these notifications, they bounce. Bounced emails are returned to the MRS with information about the email address that could not be delivered. Upon receipt, they are recorded in the VerpMessage table in the database.


41

Every verpLockoutHrs (configurable, 4 hrs by default), a process is awakened to interrogate this database. If any bounced messages are within it that have been there for more than verpTimeoutHrs (configurable, 7 days by default) then the following occurs:

• For each VerpMessage’s user email address a report is compiled that contains references to all of the email notifications that have bounced.

• A probe message is then sent to each user that contains the report of missed notifications

• If the probe message itself bounces, then the user’s email address is deemed to be broken and the following actions occur:

o Registered CEE users have an entry added to the BadUserAlias table in the database. This will suspend all subsequent email notifications to that user until the user clears this condition via the web interface.

o Guest users that receive notifications by virtue of being subscribed anonymously to various discussions will have their subscriptions deleted. They must re-subscribe via the web interface at a later date in order to receive notifications again.

Domain Admin Domain administrators the ability to control the behavior of indexing and the following screen describes these options. Terminology: Maximum prefix size. This governs the maximum size of discussion prefixes, for all discussions in the domain. Terminology: Anonymous Subscribers are individuals who do not have a CEE account on this host. Anonymous Users (i.e. guests) are allowed to subscribe to discussions if this checkbox is enabled and if the similar checkbox is enabled on the discussion’s admin page. Anonymous subscribers are generally discouraged because their subscriptions tend to accumulate on a discussion without any means of identifying the true identity of the subscriber. This is particularly problematic when notifications to these addresses bounce, as there is no recourse but to delete the subscription. Terminology: Default discussions. This governs the default discussions that are created for new projects within the domain. NOTE: In order to direct replies from the automatic posting discussions (commits & issues) into the general project Developers discussion, these default discussions have their Reply-To attributes set to ‘dev’. Discussion administrators may override this if desired.


42

Figure 30: Domain Admin Configuration

Project Owner The screen below is used by the project owner to configure discussions that are created within that project. These options relate to which default discussions are created for the project and its subprojects, size limits, notification subject conventions and whether or not to include content in email notifications. Terminology: Maximum attachment size. This governs the maximum size of attachments, for all discussions in the project. Terminology: Send posting subjects provides an added level of security for discussions with sensitive subjects and is used in conjunction with email notifications, below. Terminology: Content in email may be constrained by the project owner so that they do not contain any of the content of the original message. This is the most secure form of notification, and they contain web links back to the posting so that the secure web access mechanism must be used to access the content.


43

Figure 31: Project Owner Configuration

Discussion Owner Discussion owners have considerable control over the configuration of their discussions, and the following screens illustrate these settings.

Discussion Information Administration This screen allows the settings that were made when the discussion was created to be edited, plus additional settings that received default values at that time. Please see the discussion in Scenario 5: Adding a new discussion for definitions of fields not described below.


44

Figure 32: Discussion Owner Configuration – Discussion Information

Figure 33: Discussion Owner Configuration – Discussion Settings


45

Terminology: A Prefix is a short string that is pre-pended to the subject field in email notifications produced by the discussion. The prefix can help to distinguish postings from different discussions and can serve to tie the various topics of a discussion together. A Private discussion is one that can only be accessed by users having access to private discussions of a project. Project members typically are the only users with this permission. As discussed above, Moderated discussions require moderation of all message postings. If indicated, a Moderated discussion may allow Trusted posters to post to it without moderation. Trusted posting permission would typically be given only to certain project members. Terminology: Anonymous users are users who have not registered for a domain account. If enabled for a discussion, these users may subscribe for email notification just like registered users. Guest posting indicates that anonymous users are allowed to post to a discussion. Email posting indicates that users are allowed to post to this discussion via email messages. If guest posting and email posting are both enabled, then anonymous users may post via email. Terminology: Reply to sender indicates that email notification messages that are sent to subscribers of the discussion will, by default, be configured to reply to the sender of the posting. Reply to list indicates that email notifications will be configured to reply to the discussion itself. This keeps the communication centered on the discussion and its community of users rather than encouraging communication between individual users. Reply to X indicates that email notifications will be sent to yet a different email address.


46

Figure 34: Discussion Owner Configuration – Email Content

Terminology: Send full text of posted message tells the discussion to include the full text of each message posting in email notifications sent to its subscribers. As this is only as secure as normal email messages, the Send email notification with link only option avoids sending content by sending a link to the content. The user must then be authorized to view the message content. Message size allows the discussion administrator to place an upper bound on the size of messages that may be posted to the discussion. The Footer text box allows a different footer to be included with each email notification. Allow all instructs the discussion to allow all MIME types to be attached to messages posted either by email or web interface. Block denied MIME types causes a discussion-specified list of types to block posting. Block all causes any attachments to prevent posting. An additional pane of advanced email settings may be shown by clicking on the “Advanced email settings” link to show the following information:


47

Figure 35: Discussion Owner Configuration – Advanced Email Content

Terminology: The Reject MIME types text box contains a list of attachment types that will cause an email posting to be rejected and returned to the sender. The Drop MIME types text box contains a list of attachment types that will be dropped from email postings without rejecting the posting. If an attachment is dropped, a notice to that effect is pre-pended to the message body. The Remove headers text box contains a list of email headers that will be removed from incoming email postings. The Add headers text box contains a list of email headers and values that will be added to each incoming posting. Note that the values may contain patterns that will be substituted with actual values for each posting. The Reject headers text box contains a list of regular expressions that will cause message rejection if they match any email header. Similarly, the Reject content text box contains a list of regular expressions that will cause message rejection if they match the Subject or Body of any incoming posting.


48

Moderator Administration This section was described above in the section titled Scenario 3: Adding subscribers to a discussion. Please refer to that section for details.

Figure 36: Administrator Moderators Screen

Subscriber Administration This section was described above in the section titled Scenario 4: Designating additional moderators. Please refer to that section for details.


49

Figure 37: Administrator Subscribers Screen

Deleted Message Administration Messages that have been marked as deleted by a discussion administrator are not actually deleted from the archive. This screen allows administration of “soft” deleted messages; either to un-delete them or to purge them permanently from the archive. Messages that have been un-deleted will reappear in the topic index in their original positions. Messages that are permanently deleted are gone forever.


50

Figure 38: Administrator Deleted Messages Screen


51

What Has Changed? Users familiar with CollabNet’s existing mailing list and discussion forum tools will find this section to be useful in adapting their work patterns to the new Discussion Service. While we have made every effort to make the DS be a superset of both of these existing tools, there are a few areas where differences exist.

Mailing List Differences • The web interface to mailing lists allows users to manage subscriptions

and to view the message archive, but it does not allow users to post messages. Discussions allow posting access via the web in addition to viewing and subscription management.

• Access to mailing lists is governed by subscriptions, with subscribers receiving email notifications when new postings are received. Access to discussions is governed by user permissions within the CEE project workspace. Users possessing View permission are allowed to view the message archive and also to subscribe for email notifications. We view email subscription as another form of viewing.

• Mailing list users may obtain access to mailing list content via email queries sent to the list. Discussions do not support these queries, requiring users to use the web interface to access mailing list archives. Discussions do support email commands to manage (subscribe, unsubscribe) user subscriptions and to moderate (accept, reject) posting of individual messages.

• Private mailing lists restrict access to their archives to project members; who must be registered users. Access (reading & posting) to private discussions is governed by the Use-private permission which project members obtain via their role(s).

• Guest (unregistered user) access to discussions is governed by the permissions assigned at the host level to the guest user.

• Control over mailing list subscriptions can be exercised by moderators. Since subscription to discussions is governed entirely by permissions, there is no capability to moderate individual subscription requests.

• Mailing list subscribers are only known by the email alias they use to subscribe; there is no other relationship to the CEE project permissions. This has made subscription management by registered users more difficult as there is no way to answer the question “to which lists am I currently subscribed?” Discussions are aware of the CEE identities of their subscribers and provide a page for registered users to manage all of their subscriptions. Discussions also allow anonymous users to subscribe as in the current mailing lists; however, this capability is discouraged and may be disabled at the domain and discussion level by administrators.


52

• Posting access rights to mailing lists are governed by a user’s subscriptions and the type of list. Posting access to discussions is governed by user permissions – not subscriptions – and also by the type of discussion. Users possessing Post permission are allowed to post via email and also via the web interface.

• Mailing lists support explicit lists of allowed posters. Discussions have no similar capability, as posting is controlled entirely by a user’s permissions.

• Mailing lists support explicit ‘black lists’ of disallowed posters. Discussions have no similar capability, as posting is controlled entirely by a user’s permissions.

• The current tool supports three types of lists: o Unmoderated lists correspond to unmoderated discussions. Users

having Post permission may post without moderation. o Moderated lists correspond to moderated discussions. All postings

to moderated discussions are reviewed and approved or rejected by designated moderators. The exception to this rule is that designated moderators may post without moderation.

o Discuss lists correspond closely to trusted discussions but there are differences. Discuss lists rely upon the allowed posters list to determine if a given user may post without moderation. Trusted discussions rely upon users having the Trusted permission. Additionally, individual subscribers to trusted discussions may be designated as being Trusted by discussion administrators. Finally, designated moderators may also post without moderation.

• Mailing lists allow subscribers to receive both message-by-message notification and digest notification. Project discussions allow only one form of subscription at a time, and also introduce a start-page-only subscription type that does not involve email notification at all.

• Mailing lists allow the specification of illegal MIME types on a per-list basis. Discussions support this capability. Individual discussions may be configured to allow all attachments, to allow no attachments or to utilize the domain list of illegal MIME types.

• Mailing lists support two types of attachment handling based upon the MIME type of the attachment:

o Illegal attachments may be deleted without causing the message to be rejected. Discussions support this capability. See Discussion Information Administration

o Illegal attachments may cause the entire message to be rejected. Discussions support this capability. See Discussion Information Administration.


53

• Mailing lists support the ability to remove certain email headers and to add other email headers. Discussions support this capability and allow the same pattern substitutions. See Discussion Information Administration.

• Mailing lists do not support the ability to reject email postings using regular expressions on the header and content fields. Discussions support both capabilities. See Discussion Information Administration.

Discussion Forum Differences Discussion forums are already within the CEE project permission environment and so there are fewer differences.

• Users of discussion forums may only post via the web interface. The new discussion service allows users to post via email as well.

• Forum users may only manage their subscriptions via the web interface. Discussions allow email subscription management as well.

• Forums track which postings have been read by each subscriber and when they were read. The discussion service tracks which messages have not been read subscribers with a start-page-only type of subscription. No dates of message reading by subscribers are recorded.

• Forums have no moderation capability. Discussions have trusted and moderated discussion types.


54

Index Add headers, 47

Allow all, 46

Anonymous Subscribers, 24, 41

Anonymous Users, 41

Attachments, 14

BadUserAlias table, 41

Block all, 46

Block denied MIME types, 46

cacheSize, 40

Default forums, 41

Delete messages and replies, 23

Delete messages only, 23

Description, 29

Digest-format, 8

Email, 9, 11, 13, 15, 19, 29, 30, 45

Email address, 29

Email Moderation, 19

Email Notification, 4

Email posting, 30, 45

Footer, 46

Forum, 4

Forum Subscribers, 24

Group Subscribers, 24

Guest posting, 30, 45

Maximum posting size, 42

Maximum prefix size, 41

Message Quoting, 12

Message-by-message, 8

Messages, 4

MIME types, 47

Moderated, 45

Moderated Forums, 27

Moderators, 16, 27

My start page only, 8

Post permission, 31

Prefix, 45

Private, 45

Private permission, 31

Reject content, 47

Reject headers, 47

Reject MIME types, 47


55

Remove headers, 47

Reply to list, 45

Reply to sender, 45

Reply to X, 45

Send email notification with link only option, 46

Send full text of posted message, 46

Send posting subjects, 42

serverConnections, 40

serverPort, 40

Subscribers, 24

Subscription, 4

system-ext.properties, 40

Threads, 4

Title, 29

Trusted, 45

Trusted permission, 31

Unmoderated Forums, 27

Unsubscribing, 5

User Subscribers, 24

verpLockoutHrs, 41

VerpMessage table, 41

verpTimeoutHrs, 41

View permission, 31

ds external reference specification - collabnet external... · terminology: email may also be used...

Documents