Contents
Client Requirements
Mylyn is a client based on a full offline architecture that eagerly or passively synchronizes with one or more task repositories.
- Query tasks by attributes (retrieve either ID/URL, or attributes, or contents)
- Query tasks by date range
- Retrieve task contents (either via query, or by task ID/URL)
- Retrieve repository configuration (schema of all task attributes)
Tasks are uniquely identified by:
- A repository URL (e.g., https://bugs.eclipse.org/bugs). Can change when a repository moves servers/domains. Any valid URL, including protocol segment.
- A per-repository task ID (e.g. 123456). Unique for the lifecycle of the task. Any String.
- A task key (optional, e.g., JDB-123). Convenience version of the ID, can change during lifecycle of task.
Scenarios
- Setup task repository [1.0] service discovery
- Enter repository information: url, username, password
- Enter network parameters: http authentication, proxy information
- Specify repository specific configuration parameters
- Search for tasks in repository [requires repository schema]
- Repository configuration is retrieved [2.0] shapes
- Enter search criteria [1.0] query
- This can include free text, attribute selections from lists, String-formatted stack traces or frames, date ranges etc.
- Results are retrieve from repository [1.0] query
- Results may not include all details for a task (e.g. no attachment information)
- This should be a fast operation, balancing returned detail and overhead
- Monitor tasks in repository (new query) [requires repository schema] [2.0] shapes
- Follow steps for Search for tasks in repository [1.0] query
- Results are refreshed periodically [1.0] query (or TRS)
- This is a frequent operation, the cost should be minimal
- Full task details are retrieved for changed tasks [1.0]
- Notifications are displayed for changed tasks [1.0]
- Continue with Results are refreshed periodically [1.0]
- Retrieve task by id
- Enter task id/key [1.0]
- Full task details are retrieved and displayed [1.0]
- Display task details (open task editor) [2.0]
- Full task details are retrieved
- If the task was cached only a check is needed if the cached copy is up-to-date. This should be a fast operation with minimal cost
- Task attributes, attachments, comments are displayed
- Edit task (submit) [requires repository schema] [2.0] shapes
- Follow steps for Display task details
- Change task attributes (optional)
- Enter comment (optional)
- Select a work-flow operation [3.0]
- Submit changes to task
- Either submit delta of changed attributes or full details
- Detect concurrent modification of task in the repository
- Refreshed details for the task are retrieved
- Manage the state of the Task on the TaskList
- Resolve [READY_FOR_TEST, FIXED, STALE/EXPIRED]
- Reject [INVALID, WORKS_FOR_ME, WONT_FIX, INCOMPLETE/NEED_MORE_INFO]
- Close
- Verifiy
- Reopen
- Duplicate [URI of resource that this is a duplicate of]
Attachment Scenarios
- User wishes to attach documents or screenshots or some other form of supporting informatino in blob form to the ChangeRequest. The information is deemed to be in support of a particular ChangeRequest and is not expected to referended by any other ChangeRequest [3.0]
- A specific ChangeRequest is chosen by the user
- User selects a file for attaching to the ChangeRequest
- File is submitted (in some cases Files are attached along with a supporting Comment)
- Attached file may be large, the repository should support streaming of data
- Refreshed details for the ChangeRequest are retrieved (including metadata for new attachment such as id, (url), name, size)
- Users collaborating on a ChangeRequest with others will want to be able to retrive attachments posted by others [3.0]
- User having viewed the presence of an attachment on a ChangeRequest, selects that the attachment be downloaded
- The attachment is retrieved (downloaded) by the client either immediately viewed if content type support or optionally saved to disk
- Attached file may be large, the repository should support streaming of data
- User wishes to update an existing attachment. (Not implemented by all repositories)
- User is able to post a new attachment, identifying the existing attachment that should be replaced.
- Metadata about attachment (who attached, size, content type) updated based on new submit
- Potentially a new comment also added as part of update
[1.0] - indicates the capability exists in 1.0 specification
[2.0] - indicates missing capability in 1.0 specification, added in 2.0
[3.0] - indicates missing capability in 1.0 & 2.0 specification, targeting 3.0
API Requirements
Authentication
All repository that we currently support use either form/cookie or HTTP BASIC authentication mechanisms.
Data Structures
Task Schema / Repository Configuration
A task schema specifies the structure of a task or search query. Some repositories may use specific schemas on a per task basis or use a single schema (repository configuration) for all tasks. The repository configuration may depend on user permissions, e.g. a user may not have permission to see all available projects.
Task schemas contain the following data:
- URI/Version: A task schema should have a unique location to allow caching
- List of fields: Available fields
Field
Fields specify information how to interpret and present a task attribute. Each field has specifies at least the following details:
- ID: Unique identifier
- Label: User-visible string, e.g. Project, Summary, Component
- Visible: Set to false for internal attributes, e.g. ids
- Type: String, Integer, Comment, Custom type etc.
- Multi-Value: Set to true for attributes that allow selection of multiple values
- Options: List of legal values for an attribute
- Relational dependencies on other fields, e.g. a component may only be a valid choice if a another field has a certain value or state.
A list of common ids and types needs to be specified to support a generic implementation that is able to (partially) interpret task schemas.
Operation
An operation can be performed on a task:
- ID: Unique identifier
- Label: User-visible string, e.g. Reassign, Close
- List of fields: List of fields that can be modified when this operation is performed
Search Specification
A generic language is needed for specifying search queries against a repository. Date range-based searches must be supported for incremental synchronization; alternately, a feed of changed tasks can be provided.
Search Result
A task received as result of a search. The schema should be similar to Task with less details to allow fast execution of searches.
Task
A task. Each task has a schema that may depend on the state of the task, e.g. whether it’s a bug or feature request, the current workflow state or permissions of the authenticated user.
Accessors on ITask / ITaskMapping define the core schema for a task:
- ID (reqd): Unique, static identifer, usually an integer. Combined with repository url to form unique handle.
- Task Key: User facing identifer that can change during the lifetime of the task
- Summary (reqd): One line description of the task
- Description: Multiline description of the task
- Creation Date
- Completion Date
- Task Kind: User recognized kind of task used in UI (i.e. Bug, Task, Enhancement). Often used by connectors to preform kind specific functions.
- Task Url: Url for html representation of the task
- Owner: Person who owns / is assigned to or otherwise responsible for completion of the task (usually email address)
- Reporter: User who orignially submitted the task (does not chage)
- Cc: List of user’s Cc’d on task
- Status: Current state of the task usually within a multstate workflow
- Resolution: In what capacity this task was completed (fixed, duplicate, invalid etc) *
- Priority: Indicator of urgency. Connectors encouraged to map to Mylyn’s PriorityLevel ( P1 - P5) states
- String getPriority()
- PriorityLevel getPriorityLevel() - opportunity to override and perform alternate mapping
- PriorityLevel is an enum with values P1, P2, P3, P4, P5
- Severity: Degree of the importance of the task
- Modification Date: Timestamp when task was last modified (if no explicit version attribute exists, this is used to detect a change)
- Date getModificationDate()
- Due Date: Date the task is expected to be completed by
- Product: Name of entity with which this task corresponds to or intended to affect
- Component: Sub section of Product this task is concerned with
- Keywords:list of strings to help identify the task, usually searchable
- Attachments: Similar to list of attributes, except that the value of an attachment has to be retrieved separately
- Operations: Legal operations that can be taken on the task in its current state
- Attributes: This api doesn’t cover all possible ways that a task can be described. Connectors can add additional attributes that can later be displayed to the user or hidden. Each attribute corresponds to a field in the task schema and has one or multiple values. Attributes can be nested within parent attributes. Attributes can be declared to be of one of the following types:
- Boolean
- Date
- Date Time
- Integer
- Long
- Short Text
- Long Rich Text
- Long Text
- Single Select
- Multi Select
- Person
- Task Dependency
- Url
- Comment (See Task Comments below)
- Attachment (See Task Attachment below)
- Operation (used by Operations mentioned above)
Task Comments (ITaskComment) - Implemented as attributes on task data of type TaskAttribute.TYPE_COMMENT with ID = TaskAttribute.PREFIX_COMMENT + COMMENT_NUMBER. Attribute ids identified by TaskAttribute.COMMENT_XXXX
- Author
- IRepositoryPerson getAuthor()
- Creation Date
- Comment Number
- Comment Text
Task Attachment s (ITaskAttachment) - Implemented as attributes on task data of type TaskAttribute.TYPE_ATTACHMENT with id prefix TaskAttribute.PREFIX_ATTACHMENT + ATTACHMENT_NUMBER. Child attributes below are identified by TaskAttribute.ATTACHMENT_XXXX.
- File Name (String)
- Author (IRepositoryPerson)
- Description (String)
- Comment (String)
- Content Type (String)
- Content Length (long)
- Url (String)
- isDeprecated (boolean)
- isPatch (boolean)
Repository Person
- Name - String
- Person ID - String (email address / unique id)
Integration Levels
The two most significant levels of Mylyn integration are distinguished by the ability to view/edit the change reqest (task) offline and in an Eclipse native rich editor.
Integration Level 1 - Task List Support
The first level of integration with a repository give support for presenting tasks within the task list that represent the server side change request. Query support is also expected to be implemented for this level. This level does not include any rich editing. Opening of the change request itself is delegated to the repository’s web UI. For this level of integration to work, very few fields are required. Suggested minimum fields include:
- Task Id
- Summary
- Modification Date
- Completion Date (not completely necessary but desirable)
Integration Level 2 - Rich offline editing
In order to support rich offline task editing, connectors need to retrieve the change requests raw data and populate Mylyn’s TaskData structure. Additionally, a mapping is required from Mylyn attributes to the equivalent field in the retrieved TaskData. The required attributes depend on how complete support you desire for the repository in question. For example, Attachments is not required to have the rich offline editing support. This can initially be delegated to the web ui. Comments however (Task Comments above) woudl be required to make any real use of the editor.
Remote Interface
It is key that all operations that return data support checking if a repository artifact has changed before transferring large amounts of data. Polling for updates is a frequent operation of rich task repository clients and the API needs provisions to ensure scalability.
Updated with feedback from 2009-02-04 call.
– MikKersten - 18 Feb 2009
I definitely concur with what is said in the Remote Interface n support checking if a repository has changed before transferring large amounts of data.
– PeterThung - 24 Mar 2009
It would be useful that this protocol be sensitive to web based clients or the creation of web based clients for users that do not want or need a full blown Eclipse IDE to manage tasks, but would benefit from managing issues from different repositories such as Mantis, Razor etc… Also, it would be useful (at least to me), although this may be more on an aggregator client side than server side of being able to detect duplicates within a single repository and also related issues between repositories and tag them as related. In talking with MikKersten, I see the value of having fields created within each repository maybe holding the value of the unique key of the other repositories that they may be related to, but that assumes that you actually have write permissions to affect individual reports in someone elses repository and have the ability to add columns. - If possible, I think the scenario of you only have read only privileges of people’s or organizations Issue tracking repository and can only be guaranteed updates from them should be included. I’m thinking right now that the design constraint would make perhaps the one repository you do have access to the “master” repository” and have entries/copies from other peoples repositories. As they do updates to their own repositories it would update your repository. Then in your repository if you support relatinships between issues you tag issues as related locally and then your client to your own repository would have the ability to filter issues and hide related issues from table viewing purposes, but allow drill down into the relationships where they exist.
– PeterThung - 24 Mar 2009
Category:Supporting Documents
