25. (Server89092)
For Developers
Entry "User Roles"
This release introduces the concept of "entry user roles," which are chiefly used to offer stereotyped API methods to answer questions of the form, "which users fill a particular role or have a particular relationship to this entry?"
com.traction.sdk.Entry contains a new interface and two new enums that implement it:
/**
* Represents a role that one or more Users can have with
* respect to an, and provides a mapping from an Entry to a
* UserSet.
*
* @author Dave Shepperton
*/
public static interface UserRole {
/**
* Returns a Function that provides a mapping from an
* Entry to a UserSet reflecting the
* Users who have this role for the Entry.
*/
public Function<Entry,UserSet> entryToUsers();
}
public static enum StandardIntrinsicUserRole implements UserRole {
/**
* The contributors to an Entry.
*/
CONTRIBUTORS,
/**
* The users mentioned in an Entry's content.
*/
MENTIONED;
}
public static enum StandardAuthoredUserRole implements UserRole {
/**
* Users who are considered the assignees for an entry that
* represents a task.
*/
ASSIGNEES,
/**
* Users who are considered the invitees for an entry that
* represents an event.
*/
INVITEES,
/**
* Users who are considered members for an entry that supports
* some sort of membership, such as projects.
*/
MEMBERS,
/**
* Users who are considered owners for an entry that supports
* some sort of ownership, such as projects.
*/
OWNERS,
/**
* Users who have been subscribed to instant notifications of
* activity by an entry author or editor.
*/
SUBSCRIBERS;
}
The mappings for all the StandardAuthoredUserRoles are handled by these new EntryClass methods:
public Set<User> getUsers(Entry entry, Entry.StandardAuthoredUserRole role);
public Set<User> getUsersAssigned(Entry entry);
public Set<User> getUsersInvited(Entry entry);
public Set<User> getUsersMembers(Entry entry);
public Set<User> getUsersOwners(Entry entry);
public Set<User> getUsersSubscribed(Entry entry);
The following methods have been added to Entry to provide direct access to those Users in the form of a com.traction.sdk.UserSet:
public UserSet getAssignees();
public UserSet getInvitees();
public UserSet getMembers();
public UserSet getOwners();
// This will likely be changed to "getSubscribers"
public UserSet getAutomaticSubscribers();
The main visible change related to these API changes are related to TeamPage's "notifier" event listener, which produces TeamPage's instant notifications (sent via email or other transports). In determining which users should receive a notification for a particular event (e.g., a newly created entry, a tag change, or a newly uploaded file), TeamPage treats the users in all of the standard "authored" roles -- assignees, invitees, subscribers (i.e., the "Notify" list), owners and members -- as candidates for notification regardless of whether any subscriptions they've created for themselves cover the event. For example, users whose name appears in a task's "Assigned to" or "Notify" field will generally automatically receive notifications of activity on that task (as long as they weren't the user who performed the operation that triggered the event).
Previously, the definitions of these roles were all based upon hard-coded references to entry properties, but they're now driven by these newly added APIs. This means that it's easy for plug-in authors to customize the definitions of these user roles simply by creating custom EntryClasses that override one or more of those newly added methods with an alternative implementation of their choosing. For example, a custom task EntryClass could extend com.traction.sdk.TaskEntryClass (see below), and could override the getUsersAssigned method to pull in users from other entry properties to have those users treated as assignees for the purposes of receiving instant notifications. (Server89038)
com.traction.sdk.EntryClass Changes
Users' Permission to "Use" an EntryClass
EntryClass's long-deprecated checkCanAuthorOrEditQ method has been removed, as has the rarely used checkCanAuthorByEmailQ method. There are now four separate methods that can be used to find out whether an EntryClass can be used by a particular user:
canAuthor(com.traction.sdk.Context)canComment(com.traction.sdk.Context)canEdit(com.traction.sdk.Context)canAuthorByEmail(com.traction.sdk.Context)
In the built-in com.traction.sdk.view.ViewActionDisplay classes, wherever checkCanAuthorOrEditQ was previously used, the applicable one of these newly added methods is now used so that the links or buttons for adding or editing entries belonging to various EntryClasses continue to be included or omitted as appropriate for the viewing user and the context.
These methods are also used in the SDK implementation layer alongside the standard appropriate security checks to determine whether the user is allowed to perform an entry creation or edit operation, making them more than advisory/informational. This allows plug-in authors to create properly tailored custom rules for different sorts of entry creation or edit operations, and to have them enforced on top of TeamPage's built-in permissions model. (Server89066)
Class Hierarchy Reorganization
PM EntryClasses
The EntryClasses representing entry types in TeamPage's PM module have been moved around and reorganized.
PMEntryClass and TaskEntryClass have been moved to com.traction.sdk, making them part of the public SDK API.com.traction.sdk.GoalEntryClass and MilestoneEntryClass, extending PMEntryClass, have been added to represent separate types for project and milestone entries, respectively.com.traction.sdk.EventEntryClass, extending EntryClass, has been added to represent a separate type for event entries.- The "task", "goal", "milestone" and "event" configurations at config/entry/classes have been updated accordingly.
These changes make it easy to override the "entry user role" API methods with definitions for those roles specific to each of these PM entry types.
"Microblog" EntryClasses
There have been a few changes to the com.traction.sdk.EntryClass classes representing "microblog" entry types:
- The
StatusEntryClass class, which is associated with status update entries, has been moved to the com.traction.sdk, making it part of the public SDK API.
- There is a deprecated
LiveblogEntryClass, also in com.traction.sdk, which is associated with still supported but not currently used "liveblog" entry type.
- The "status" and "liveblog" configurations at config/entry/classes have been updated accordingly.
- Both of these classes inherit from the new
com.traction.sdk.AbstractMicroblogEntryClass.
These changes clarify the definitions of these EntryClasses, and the relationships among them. (Server88772)
Article: Customer5083 (
permalink)
Categories: :Doc:r62, :Doc:changelog
Date: May 28, 2018; 9:28:54 PM Eastern Daylight Time
Author Name: Dave Shepperton
Author ID: shep
