Work items are a representation of any Team Productivity Center artifact that a person can perform work on. Typical examples include program defect records, requirement database entries, test cases, project tasks, and use cases, but work items are not limited to these. Any Team Productivity Center artifact can be represented and displayed if a suitable connector exists.
This chapter includes the following sections:
The Oracle Team Productivity Center Work Items accordion contains nodes that connect teams to their information repositories, such as bug tracking databases, systems that log feature requests, project tracking information, and many other types of shared technologies that are used to track major projects.
Work items are the mechanism that Team Productivity Center uses to represent individual elements of the information repository. For example, the work items in a bug-tracking database would be individual bug reports; a feature repository's work items would be the individual feature requests tracked in that repository.
Work item nodes typically include such product development tools as:
Feature request tracking repositories, such as Atlassian's JIRA.
Bug tracking databases, such as Bugzilla.
Project tracking software, such as Microsoft Project Server.
HPALM to support quality assurance tests.
Oracle Team Productivity Center's own Task Repository, for tracking the status, priority, and ownership of projects within Team Productivity Center.
Through Oracle Team Productivity Center, you can save context, make an active item and add details of source-control system checkins. You can create queries against these repositories and then build upon this information by creating relationships and assigning tags to the various work item elements that are important to the current part of the development process.
In addition, each work item has its own set of relationships, which it maintains to other work items both in its own repository (that is, of its own type) and, optionally, with work items of other types. For example, a bug database entry might be linked to the requirements tracking system; a feature enhancement request might link to a team milestone chart. These relationships will vary depending on the nature of the work and of the specific repositories you use with Team Productivity Center.
Here are the requirements for a particular information repository to become available as a work item node:
An administrator needs to add the Team Productivity Center connector to the server.
The end user needs to install and add the same Team Productivity Center connector as an extension to their copy of JDeveloper.
Access to the repository has been set up for your team.
The repository must be on line.
If you have not previously done so, depending on the repository's login requirements, you will need to log into the repository through the Oracle Team Productivity Center Manage Accounts dialog. For more information on connecting to a repository, see Section 3.3, "Making Repositories Available in Oracle Team Productivity Center."
Work items can be thought of as records, fields, or simply items of information returned from repositories in response to Oracle Team Productivity Center queries.
Typically, work items returned by a query are presented in a selectable, tabular format, as determined by the Oracle Team Productivity Center Connector.
The range of what you can do with information returned from the underlying repository is determined by the design of each repository's connector. In a typical use case, you can double-click to edit a work item, and then interact with the work item in ways defined by the connector author. It is recommended that connector developers duplicate the functionality and user interface of the repository as far as possible when developing a connector for use inside JDeveloper, providing the team with a consistent user experience and the functionality within the repository that the team desires. For more information on developing connectors, see Chapter 4, "Working with Oracle Team Productivity Center Connectors."
In addition, Team Productivity Center users will need to make sure they have downloaded the connectors for the repositories your team uses. You can download these from Help > Check for Updates.
The Team Administrator can add repositories, based on the installed connectors. You may find it useful to add a different server that points to the same repository, a common situation if your team is distributed throughout the world. Adding a local server for different branches of your organization can improve performance and efficiency for your organization.
To select repositories for team use:
Team Navigator > Team Administration > Teams > Team Repositories
Most administrative tasks involving repositories begin from the Team Administration dialog. You access this dialog by selecting Team Navigator > Team Administration > Repositories. The Team Administration dialog lets you add, remove, and modify repositories.
Work items are elements of a data repository that encapsulate the data you are tracking in that repository (such as a bug report, which encapsulates the bug description, version numbers, and other information important to your product lifecycle management methodology).
Another way of looking at work items is to consider them the result of a query you have made to a data repository. Once Team Productivity Center returns the work item, you can interact with it in a number of ways.
Note that your team may have one or more repository servers for the same Repository, with different values in the parameters. For example, there may be two mirror sites for the repository, based on geographical preference. In addition, after a corporate merger, the two companies might use the same repository and different configurations. Users can choose which server to connect to through the Manage Accounts dialog when they log in, but still maintain access to the same data repository.
You typically connect to a repository by double-clicking
Double-click the repository in the Work Items accordion. If your repository login credentials are correct, JDeveloper connects you automatically.
If your repository login credentials are not correct, JDeveloper will notify you that it cannot access the repository and will then prompt you to go the Account Manager to correct the problem. From the Account Manager you can update your login credentials.
To update your repository login credentials:
Select one of the repositories under the Accounts column.
From the Repository Server drop-down, select the preferred server for the repository you selected in the preceding step.
Enter the login credentials (user name and password) for the server associated with this repository, and then click OK.
You can also check the connection to the repository by clicking Test Connection. This will allow you to verify the connection data and make changes if required.
Team Productivity Center uses queries to access work items in the selected repository. Queries allow you to specify elements of the work item (for example, the bug status or range of ID numbers in a bug database repository) to return just the work item or range of work items you are interested in.
A team query is a query which has been set up by your administrator to be available to all members of your team. In addition to team queries, Team Productivity Center also lets you create user queries. For more information, see Section 2.6, "Working with Queries."
Once you are logged in, you use these queries to access individual work items from the available repositories. When you first begin working in Team Productivity Center, you will most likely not yet have created any user queries, but you might have team queries available. The following procedure assumes that your team administrator has saved a number of team queries for one or more of your repositories.
Before you can use a particular Work Item node, you need to log into the repository through the Manage Accounts dialog. If you have not logged into the repository, Team Productivity Center will instruct you to go to the Manage Accounts dialog if you try to access a work item before being logged in. Once you are logged in to a repository, JDeveloper displays a small yellow in the upper right-hand corner of the repository icon.
To access Work Items through a team query:
Click on the + next to the repository's name to expand its listing in the Work Items accordion
Click on the + next to Team Queries to expand the listing.
Double-click on one of the team queries. JDeveloper displays the result of this query in the central pane.
Depending on the structure of the query, you may see a large number of work items displayed in the central pane. Scroll up and down to see the range of work items returned by the query you selected. Later, if you have team query privileges, you can refine the results of this query to restrict (or expand) the number of work items returned. If you do not have team query privileges, you can create user queries of your own to help you focus on the specific kinds of work items that reflect your part of the project team.
You can also choose from a list of available operations on a query on the work item by right-clicking on the work item. JDeveloper displays a menu of operations specific to that query.
You can create a new work item in either of two ways:
by selecting New from the repository context menu.
by creating a work item from a template.
To create a new work item from the menu:
Click the right mouse button on the repository in which you wish to create the work item, then select New repository name.
Enter the information for the work item. This will vary depending on the connector and the repository in which you are creating the work item.
When you are finished, click Submit.
To create a new work item from a template:
Click the right mouse button on the repository in which you wish to create the work item, then select New repository name from User Template. This displays a pop-up menu of all the available templates for that repository.
Select the desired template from the menu.
Modify the preset data to fit the specific work item you wish to create. The fields and options in the work item will vary depending on the connector and the repository in which you are creating the work item.
When you are finished, click Submit.
Before accessing work items, you need to log into the associated repository, through the Manage Accounts dialog. Once in the repository, you can run a query to return specific records from that repository. If you double-click on an individual record, JDeveloper opens that record as a work item. For more information, see Section 2.6.2, "How to Run a Query."
After selecting a work item from the repository, you can perform the following operations on those work items that are part of the tasks you are performing:
Link a change list to a work item when you check a file in to the version control system your team uses. This way, other team members who access the same work item will be able to refer to the change list, with changes and comments you have made. For more information, see Section 2.2.5, "How to Use Work Items with the Change List."
Save the work item as your Active Work Item. This makes it easy to access the same work item (for example, a bug you are currently working to resolve) after you exit JDeveloper and re-enter later. For more information, see Section 2.2.6, "How to Set and Display the Active Work Item."
Save the context (all open files, etc.) for this work item. This stores the application, files, and other hierarchical elements associated with the work item you are working on.
You can save and restore context from any work item, not just the active work item. If you were last working on your active work item and closed JDeveloper, then on restart all your editors will open as they were when you closed. If you want to go to another work item (or if the last thing you did before closing JDeveloper was something other than working on your active work item), you can restore the context and quickly get back to where JDeveloper was when you last worked on that work item
Choose Restore Context for a specific work item (either the active work item or any other for which you have saved context) to easily repopulate JDeveloper with the elements associated with the project you are working on through the work item you created. For more information, see Section 2.2.8, "How to Work with Context."
Add a work item to a tag list. For more information, see Section 2.7, "Working with Tags."
Create a relationship to another work item. Section 2.8, "Working with Relationships."
Create a code review. See Section 2.3, "Working with Code Reviews."
When you commit files to your version control system, you can choose to associate them back to your version repository by linking the file to one or more work items. The Changes tab on each work item lists the file (or files) associated with that work item.
When you open a work item, it may have checkin information stored with it. This allows you to see a listing of all the checkins done against that item (there may be multiple checkins over time), the details of each file included in the checkin, and any checkin comments.
To add files to a work item as a change list:
In the Change List tab, select a list of files to be checked in and open the checkin dialog for your selected version control system.
Select the work item to associate these files with.
Check in these files to your selected version control system.
The files will be listed on the Change List tab of the selected work item in Oracle Team Productivity Center.
JDeveloper stores the list of files with their checkin version ID, checkin date and any checkin comments written by the developer against each of the selected work items in the appropriate repository
The active work item in JDeveloper is a work item that you wish to make available for easy access, and which will persist when you shut down and restart JDeveloper. You can make any work item as active at any time; only one work item can be active for a given team at a time, so making a new work item active replaces any previously selected active work item for that team.
Click Make Active in the work item's tool bar.
You can also right-click on a selected work item in a list of work items returned by a query, then select Make Active.
The Work Items accordion includes a link to the work item you have marked as an active work item, above the list of repositories. The selected work item is persistent for each team you are part of. If you shut down and restart JDeveloper, the active work item link will appear above the Work Items accordion when you restart the IDE later. This gives you an easy way, much like a bookmark, of returning to an item that you expect to be working on as a high priority.
To display the Active Work Item in JDeveloper:
Choose the link on the top portion of the work item accordion to open the active work item. To select an entry in the query result list, click the right mouse button and then choose Make Active to mark a work item as active.
JDeveloper retrieves the work item from the appropriate repository and displays the work item that you had previously set to be the active work item.
You can associate work items with the files you are working on in a project when you commit the files in your selected version control system. When Oracle Team Productivity Center is active, the Commit dialog (or in some systems, the checkin dialog) contains an additional field from which you can specify work items to associate with the file when you commit your changes.
When using Oracle Team Productivity Center, the Commit dialog for your selected version control system will include additional options designed to support Oracle Team Productivity Center's work items. For help at any time on your software's Commit dialog, click Help or press F1.
To associate work items with project files:
Commit your changes from the project file(s) you are working on, in the selected source control management system.
Select Associate with work items from the Commit dialog.
To associate an Oracle Team Productivity Center work item with the file or files being committed, click on the green + sign above the Associate with Workitems panel of the commit dialog. This lets you choose a work item from the Select Work Item dialog.
The Associate with Workitems panel of the commit or checkin dialog displays four columns of information about each work item you add:
Table 2-1 Information for associating work items with files being committed
| Column | Description |
|---|---|
|
Repository |
The repository in which the work item is stored. You must have that repository's connector installed in order to access the work item. |
|
Type |
The type of work item. This is dependent on the repository in which the work item is stored. For example, work items in the Task repository are of type Task; other repositories may have additional types. See the documentation on the specific repository or connector for more information. |
|
ID |
The work item's ID—for example, a bug number or feature request ID. |
|
Subject |
The subject of the work item, imported from the repository in which the work item is stored. |
If you associate more than one work item with the file or files being committed, you can move selected work items up and down in the list by selecting the work item and then clicking the Move Up icon (double upward arrows).
When you are finished, click on Commit.
Note that the Commit dialog may have different options, depending on the source control management software your team uses. For help at any time on your software's Commit dialog, click Help or press F1.
From time to time, you may find it necessary to remove a work item's association from the project file. For example, if you restructure your project so that the work item actually refers to content in another file (such as moving a JavaScript function from an HTML file to a.JS library), you can remove the obsolete association from the HTML file so that it is no longer connected to the work item.
To remove a work item's association from a file:
Commit your changes from the project file(s) you are working on, in the selected source control management system. For example: Team > Subversion > Commit.
Select the work item from the list, and then click on the red X.
The work item is deleted from the commit menu immediately. If you delete a work item in error, add it back.
When you are finished, click on Commit.
Sometimes, the process of development involves having a number of files and windows open in JDeveloper—for example, while developing Java classes and visualizing those classes in a diagram. The challenge can be to remember which files and windows are open for any given task, especially if it becomes necessary to close JDeveloper, or to switch to another project with its own set of files.
Team Productivity Center addresses this issue through the ability to save and restore context for work items. If you are logged into Team Productivity Center and are tracking the task through a Work Item, Team Productivity Center lets you save the context of those files and IDE layout against that work item, using Save Context. Finally, you can delete a saved context when that phase of the project is done.
Later, you can return to that set of files and layout (for example, if you are working on multiple tasks concurrently) using Restore Context.
Saving work item context lets you easily associate the state of JDeveloper, including open files, windows and accordion panes, so that you can easily resume editing for a particular work item at a later date.
To save context for a work item:
Open a work item.
Select the Save Context icon. This saves the state of JDeveloper against the specific Work Item you are editing.
If you have previously saved the context of a work item, you can restore it at a later date. Restoring the context of a work item opens windows, files, and accordion panes, making it easy to resume work if it becomes necessary to close and re-open JDeveloper.
To restore a previously saved context:
Open a work item.
Select the Restore Context icon. This returns the IDE to the saved state for that work item.
In addition, you can click the right mouse button on an entry in the query result list and then choose Restore Context.
As useful as saving and restoring context can be, it may be necessary to delete a previously saved context, especially if the context for a work item changes (for example, if additional file libraries become involved in the resolution of a work item). To simplify, you can delete a saved context. (You can then save the context again, taking the new files, windows, or panes into account.)
Open a work item.
Select the Delete Context icon. This removes any saved context from the work item.
The Changes tab of the work item view lets you view the details of changes to a work item over time. You can select individual revisions, then look at the details of included files and related builds.
Click the Changes tab of the work item you have selected. This displays a table showing the revisions associated with this work item, along the date each revision was committed, the name of the team member who committed it, and any comments made during the commit.
Double-click one of the revisions. This loads the details for the selected revision into the Included Files table, which lists the path to the file and the specific version associated with this revision in the work item history. Additionally, if available, the related build information is displayed.
Code reviews are integrated into many components of Oracle Team Productivity Center, and there are many ways to access them. They are associated with the files waiting to be checked in to your version control system. This portion of the guide will take you through the tasks that make up a typical work flow:
Creating a new code review
Adding reviewers to a code review
Searching available code reviews
Browsing and selecting an individual code review
Commenting on a code review
Adding content (such as a link, a code snippet, or a file) to a code review.
Each of these tasks is discussed individually.
You can create a code review in a number of ways, in the following elements of the JDeveloper IDE:
The New Review menu item from the drop-down menu at the right of the Code Reviews panel.
The Reviews tab of a work item: Click on the green plus sign.
You can also create a code review from the changeset of your selected version control system.
To create a code review from the changeset:
Make sure that the Pending Changes window is displayed for your selected version control system. If it is not visible, select Team > Subversion > Pending Changes (or select the version control system your team is using).
Select the file in the Pending Changes window, then click the Create Code Review button.
Oracle Team Productivity Center creates a code review associated with the selected file.
Any team member can add other team members to a code review.
Once you have created a code review, you can add reviewers from your team.
To add reviewers to a Code Review:
Click the Add Reviewer icon (the silhouette with the green plus sign) in the upper-right corner of the list of reviewers.
The team members you add will now be able to access the review, make comments, and follow other reviewers' comments.
Other reviewers can also add reviewers in the same way.
Communication between reviewers and developers is the key to successfully developing in teams. Whether you are reading others' reviews of code you are responsible for, or reviewing a team member's code, you can communicate directly with other team members through the Code Review feature. You can do this either through chat or email.
To contact a reviewer about a code review:
Click the Reviewers tab of the Code Reviews window, right-click the name of the reviewer and then select Chat or Send Email.
If you are not connected to your chat server, JDeveloper displays the Connect to Chat Server dialog. See the section Section 1.3.2, "How to Use Team Productivity Center Chat".
You can search the code reviews for specific information.
This window lets you search by characteristics of the review (for example, by review name, by date created, etc.), and allows multiple search criteria. The following table lists the criteria you can use for your search:
| Element | Description |
|---|---|
|
Search for reviews by the date they were created. Criteria for comparison: Equals - return reviews created on a specific date. Not equal - return reviews created on any date except that entered Greater than - return reviews created after a specific date Less than - return reviews created before a specific date Greater than or equal - return reviews created on OR after a specific date Less than or equal - return reviews created on OR before a specific date Use the calendar icon to the right of the search box to browse for a date and enter it in the correct format (YYYY-MM-DD). |
|
|
Review name |
Search for reviews by the name of the review, as entered in the search field. Criteria for comparison: Like - return reviews that are similar (that is, have some of the words in the search field) in their name. For example, to find all reviews with the word “bug” in their name, select Like, then type “bug” in the search field. Note that search is case-sensitive, so searching for “bug” will not find reviews with “Bug” in the name. Equals - return reviews with the exact name entered in the search field. Not equal - return all reviews that do not have the exact name entered in the search field. |
|
Review status |
Search for reviews by their status (Under Review, or Closed). Criteria for comparison: Equals - return reviews that match the selected status. Not equal - return reviews that do not match the selected status. |
|
Submitter Name |
Search for reviews by a specific submitter, by name. Criteria for comparison: Like - look for strings similar to the submitter name you entered. |
|
Submitter ID |
Search for reviews by a specific submitter. Criteria for comparison: Like - look for strings similar to the submitter name you entered. Equals - return reviews that match a specific submitter. Not equal - return all reviews that do not match the name of the submitter. |
To search by more than one characteristic, click the green + sign and specify the criteria for comparison. For example, you can search all reviews after January 1, 2012 that are still open and that have the word “Bug” in their name by adding three search criteria fields: one that searches for reviews on or after 2012-01-01, one that searches for status of Open, and one that searches for reviews with a name like “Bug”.
You can further refine the search by selecting one of the radio buttons below the search fields:
Match All: return only reviews which match all the criteria entered in the search fields. The fields will be evaluated in the order they appear on the screen (that is, criteria are evaluated as a logical “AND”). If you only specify one search field, Match All is selected as the default.
Match Any: At present, Match Any is not supported. It is greyed out.
Selecting Match Any or Match All can have a large impact on the number of reviews returned. For example, if you are searching for all reviews during the month of March that have the word “Bug” in their title, selecting Match All will restrict the returned reviews to those which have both. Selecting Match Any will return all reviews during the month of March as well as all reviews with the word “Bug” in the title.
To conduct the search, click Search. JDeveloper returns all reviews that match the combination of criteria you have entered.
Once JDeveloper returns a list of reviews based on your search criteria, you can further filter the results by typing in the Filter field. This limits the displayed reviews to those which contain the string in the Filter field.
To select a review from the list, double-click the review. This places the selected review in the Code Reviews pane, listing all files included in that review. To view the review's details, double-click on one of the files. This opens the file in a review window.
To modify an existing search, add a new search field by clicking the green + sign, or remove an existing search field by clicking the red X. This lets you add or remove individual search criteria to refine your search.
To conduct a completely new search, click Clear. This clears all returned reviews, and also clears any search criteria fields you have entered.
Once you have searched for and displayed the code reviews that match your search criteria, you can browse the returned reviews as follows:
Sort the reviews by the contents of each column: Click on the column heading to sort by the values in that field. For example, to display reviews sorted by name in alphabetical order, click on the Review Name field. To reverse the sort, click Review Name again.
Control which fields are displayed in the return list: Click on the drop-down list box at the right edge of the heading field to display the list of column names (Review Name, Submitter, Review Status, Created Date). A checkmark beside each column name includes that column in the display; to remove that column from the display, click the check mark to remove it. Note that the Review Name column cannot be removed.
Open a review: Double-click on the review name, or click the right mouse button and select Open Review.
This loads into the Code Review tab. The drop-down list box in the Code Review tab displays three folders:
Reviews You Created: this lists reviews for which you were the submitter.
Reviews Assigned to You: this lists reviews that you have been assigned as a reviewer.
Recently Viewed Reviews: this lists reviews that you have already opened and viewed. You can clear this by clicking the drop-down list box to the right and selecting Refresh Review List.
Once you have selected one of these folders, JDeveloper displays the reviews contained in that folder.
Scroll to the review you wish to open.
Double-click on the review name.
This places the code review in your Code Reviews window. Once it is there, you can scroll through the individual files displayed in the Code Review tab.
Once you have selected a code review and can see its files displayed in the Comments tab of the Code Reviews window, you can select a specific file containing review comments.
To select a specific file to review:
Double-click the name of the file you wish to review.
There are two kinds of comment you can make to a code review:
General comments. These are meant to apply to the entire code review, and are displayed in the Comments tab, at the top of the list of review comments.
Code review comments. These are typically meant to apply to a specific change in one of the files in the changeset, and are displayed under the general comments, grouped by the file to which the code review comments were made.
You can add these kinds of comment as follows.
General comments are intended to provide information about the entire code review, for example linking the review to a release, to a feature, or to some other part of the project which includes more than one file or more than one change to files in the changeset.
To add a general comment to a code review:
Click the Add New General Comment icon (beside the Publish drop-down list) above the list of review comments.
When you have finished typing your general comment, press Enter. The general comment will not be visible to other team members until you click on the Publish drop-down and select Publish Comments.
Code review comments are more focused in nature than general comments. Code review comments pertain to a specific change in one of the files in the changeset, and are meant to provide information about the change, or to ask for clarification or otherwise engage the team in specific conversation about the file on the change set.
To add comments to a code review:
In the file you are reviewing, scroll to the line about which you wish to add a comment and select a section of code.
Click the right mouse button, then select Add Review Comment.
Type your comment, then press the Enter key.
The comment will be visible to other team members when you click on the Publish drop-down and select Publish Comments.
In addition to making comments, you can add specific content types to a code review: attachments, links, and code snippets. You can attach files to a review at the top level; you can also attach files, add links, and include code snippets to individual comments.
You can attach files to a code review, at the top level of the review (rather than to a specific comment inside the review).
To add an attachment to a code review:
Select a review, then select the Attachments tab.
Click the Add Files button (the green plus sign).
Browse to the file you wish to add, then select Save.
You can also attach files, links, and snippets (short sections of code meant to exemplify a technique or methodology) to a specific comment inside a code review.
Note that to add a snippet of code, you will need to select the snippet from another file (either in JDeveloper or in any text editor) and save it by typing Ctrl+C.
Similarly, you will need to prepare a link by placing the cursor over the URL in your Web browser and copying the link as required by the browser of choice. For example, in Firefox, roll over the link, click the right mouse button, and select Copy Link Location.
To add content to a code review:
Select or create a review comment.
Click the Add Content button (the green plus sign).
Select the type of content you wish to add by selecting the appropriate menu item: Add Links, Add Snippets, or Add Files.
For links or snippets, type Ctrl+V to paste the previously saved snippet or link into the field.
For files, browse to the location of the file you wish to add, select the file, and click Save.
The Oracle Team Productivity Center Task repository contains work items intended as a shared “to do” list for your Oracle Team Productivity Center team. To access the Task Repository, you must install the Task connector, then use the Manage Accounts dialog to access the Task repository for the first time. Access to the Task Repository does not require a user ID and password.
When Team Productivity Center shows a list of Task work items, the display contains the following columns:
Table 2-2 Task work item fields
| Column Header | Description |
|---|---|
|
Task ID |
A unique identifier for this work item in the Task Repository |
|
Task Name * |
The name given to this task. Mandatory field. |
|
Created By |
The user who created this task. This field is read-only. |
|
Team * |
The name of the team to which this task is assigned. Mandatory field. |
|
Assigned To |
The owner of this task |
|
Priority |
The relative importance assigned to this task. Values can be High, Medium, Low or None |
|
Status |
The current status of this task. Values can be Assigned, Blocked, Done, or In Progress |
|
Start Date |
The date on which this task began. |
|
End Date |
The date on which this task is to end. |
|
Description |
Enter any descriptive comments which will be of use in defining or completing the task. |
You specify or change the values that appear in each column when you create or edit a Task work item. See Section 2.4.2, "How to Create a Task Work Item."
As with other work item repositories, you query the Task Repository to return one or more work items that match your query terms.
Select Task > My Queries (or Task > Team Queries).
Double-click the query you wish to run.
Oracle Team Productivity Center displays the work items which match the query you entered. For example, to display a list of all Task work items in the repository, create a query that returns Task work items with a Task ID greater than or equal to 1.
For more information about creating and working with queries, see Section 2.6, "Working with Queries."
You create a Task work item from the Work Items accordion.
In the Work Items accordion, right-click Task, and then select New Task. This opens the Task work item editor.
Enter the information for the task in the fields. For more information about any of the fields in the Task work item, press F1 at any time.
When you are finished, click Submit.
The next time you view all available Task work items, the newly created Task will be visible in the Work Item pane. For more information, see Section 2.2, "Working with Work Items."
You can edit any Task work item visible in the Work Item pane, after running a query to return the Task work items of interest to you. For example, if you have recently completed work on a Task work item, you can change the Status field to Done.
In the Work Item pane, locate the Task work item you wish to edit.
Double-click the selected work item. This opens the Task work item editor.
Enter the information for the task in the fields. For more information about any of the fields in the Task work item, press F1 at any time or click the Help icon.
When you are finished, click Submit.
The next time you view all available Task work items, the updated Task will be visible in the Work Item pane. For more information, see Section 2.2, "Working with Work Items."
Team Productivity Center lets you add attachments to work items, as long as the work item's connector supports it. For example, if you build a jar file on your local system as part of testing a bug fix, you can attach the local jar to the bug report. Your QA staff can then download the attachment and test your fixes. Your user-experience team can attach graphics showing their design for the layout of an application's screens and dialogs, making it simpler to design the interface in JDeveloper. And because these attachments are available to any kind of work item, you can tag the work items or define relationships to make it easier to keep track of your work.
Some repository connectors support attaching any type of document (such as test cases, snippets of code, screenshots, specifications) or Web link to a work item. It is up to the connector writer to indicate whether attachments are supported and if so, to store the documents in a document repository and return them to Team Productivity Center. For more information, see Chapter 4, "Working with Oracle Team Productivity Center Connectors."
If attachments are supported by a work item repository, the work item displays an Attachments tab. Clicking on that tab displays all attachments that have been attached to the work item already. Double-clicking on an attachment either launches the default application associated with it, or saves the file locally. Users also have the ability to add new attachments to the work item by selecting a local file on the system to upload. Depending on the document store's permission settings and the privileges set for your role, you may also be able to delete documents attached to work items. Because these documents are attached to the work item, this means that all Team Productivity Center users who access the work item can view the attachments.
Attachments can be files from your local file system or your local network, in which case the file contents are uploaded to a document repository specified by the connector author. Because these references are attached to the work item, this means that all Team Productivity Center users accessing the work item can view and download the attachments. The details of uploading and downloading depend on how the connector has been defined; connector authors are encouraged to use the standard file browser interface for uploading and downloading attachments.
In addition, work item attachments can be links to content on the Web. Adding an attachment of this type adds the URL to the work item; to view the destination of the URL in a work item you are viewing, click on Download Attachment.
Adding attachments to a selected work item lets you share additional information (such as a customer email, a UI mock-up, a bug report, or any other file attachment) with your colleagues. This can help ensure that all team members are working from the same source material or background information while resolving their individual areas as represented by the work item.
To add an attachment to a work item
Select Work Item view > Attachments tab > Add Attachment icon
This opens the Add Attachment dialog, with which you can save a file or link to the work item.Attachments can be one of the following:
Select the file icon to open a file system browser. Browse to the desired file, then select Save.
Attach a URL to this work item. Enter the following information for the URL you wish to save as an attachment:
Name: The name that you wish to appear in the Team Productivity Center work item.
Link: The URL you wish to associate with this name.
When you have specified the file or URL to use as the attachment to this work item, select Add.
You can download attachments from a work item in Team Productivity Center to your local workstation. You can then save it or open it with the associated program (for example, a text editor or PDF viewer).
Select Work Item view > Attachments tab > Download Attachment icon.
This opens the Download Attachments dialog, from which you can make the attachment available for viewing or editing locally. Select one of the options from the dialog:
Opens the attachment in the appropriate editor or application. For example, if you download a text file, JDeveloper opens the current default text editor (for example, WordPad).
Copies the attachment to your local file system. Select this option, then select the file icon to browse to the location in your local file system where you wish to save the attachment.
You can update an existing attachment when there is new content available to share with the team.
To update an attachment with new content:
Select Work Item view > Attachments tab > Update Attachment icon.
This opens the Update Attachment dialog, which you can use when the content of the attachment has changed since the last time you accessed it. For example, if the attachment is a text file containing minutes of a meeting on the issue, use Update Attachment to copy the newest minutes to the work item.
When you select Update Attachment, JDeveloper opens a file browser dialog from which you can select the file to update. Browse to the file, then select Save.
Note:
You can only update a file with the same name. For example, if the minutes of your design meeting are dated with the month and date (such as minutes_jan_15.txt), you will not be able to update the attachment with the minutes from the following week (in this example, minutes_jan_22.txt).
You can rename an attachment that has already been uploaded.
Select Work Item view > Attachments tab > Rename Attachment icon.
This opens the Rename Attachment dialog, from which you can change the name of the attachment associated with the work item.
This dialog contains the following fields:
Table 2-3 Fields in Rename Attachment dialog
| Field | Description |
|---|---|
|
Type |
The type of attachment (File or URL) represented by the selected attachment. |
|
Old Name |
The existing name of the selected attachment. |
|
New Name |
The name to which you wish to change the attachment. |
When you are finished, click OK.
Queries are the way Team Productivity Center retrieves work items, based on the search criteria, from the repositories to which you are connected. As you work with Team Productivity Center, you will have the opportunity to work with team queries that your administrator (or another team member) has created to cover common situations. For example, your entire team would benefit from a team query that searches a bug database and returns all open items assigned to the project or product the team is working on.
In addition, you can create custom queries that apply specifically to your work. For example, a query that searches the same bug database and returns all open items assigned to you could help you manage your workload effectively.
In either event, the result of the queries in these examples will be a list of records extracted from the bug database, presented in Team Productivity Center as a list of work items. Other queries from different repositories might return records from a feature tracking list, from a schedule management program, or from any other repository you and your team use. Once the query returns these work items, you can then interact with them in the various ways that Team Productivity Center offers.
Oracle Team Productivity Center lets you create two types of query: user queries and team queries. User queries are those you create to solve a specific problem that you are facing—for example, to find bugs in a specific date range, or filed by an individual team member if you are taking over another member's tasks. You can easily create specific user queries to solve these and other immediate needs.
If you find that you are regularly searching for the same kind of work item, you can save your user query rather than modifying an existing one. For example, if you are tracking bugs on different branches of the same product, you can save user queries for each branch individually and retrieve work items that match each query as needed.
Additionally, some queries may be general enough that they can be used by multiple team members. For example, the entire team might want to view bugs filed as a result of a usability session or beta program. Queries with a wide application such as these, which apply to more than one user, are saved and accessed as team queries. Depending on the Team Productivity Center administrative rights you have, you may be able to save team queries.
Select a repository and create a query for it, returning fields and information of interest to you.
Review the results of that query, editing the settings as required.
Save the query for later use. When you use the query again, it will return the same fields from the repository but with updated information.
If you have administrative privilege and the query is general enough to be of use to the entire team, save it as a Team Query.
Running a query from Team Productivity Center gives you access, within JDeveloper, to the resource for which the query returns results. In a bug database, for example, running an Oracle Team Productivity Center query can return all bugs matching the criteria of the query you run. This simplifies tracking bugs, fixes, and features compared to using separate applications in multiple windows.
Double-click on the Work Item Node that contains the query you want to run. (Alternatively, click on the + to the left of the node.)
Open either Team Queries or My Queries (if a "+" doesn't appear adjacent to the Queries icon, it means no queries are available).
Double-click on an available query (such as Open Bugs). (Alternatively, right-click on the Query and choose Run.) The query results should appear in a tabbed panel named for the query.
Note:
For any returned results, you can double click on the returned row to view details and make modifications and add comments to the extent supported by the Oracle Team Productivity Center Connector for the particular repository you are accessing.
In Oracle Team Productivity Center, queries are easy to customize, even if you start with a pre-existing team query. The key to this customization potential is that data fields that are made available from the underlying repository can be used in two ways:
To apply additional fields to the underlying information.
To tailor the resulting on-screen report.
For example, a team query might provide the following fields:
Product
Type
Status
As the development process draws to a close, you may find it useful to add Priority as a filtering element.
Here is a simple example of how an existing query can be enhanced by adding an additional query field filter. In this example, we're creating a query on a defect repository, specifically a query that returns defects that do not have the priority of "Blocker."
To add an additional query field filter:
Click the green + icon to add a new criteria line.
With the Query Results tab open, click any dropdown on the far left of the query to see a list of available fields.
Note:
You can choose a field element that is already in use. For example, you could add a second Project field element to get a report on two projects.
In the leftmost field dropdown, select Priority.
Change the Not Equals dropdown to Equals.
Choose Blocker from the rightmost dropdown.
Click Search.
To clear the field option selections you have made before saving the query, select Clear from the More Actions dropdown menu. To clear all the entries, select Restore.
The query returns the results that match the criteria you entered.
Tip:
You can sort the results by any column simply by clicking on the column name. In addition, the widths of the columns and the currently sorted columns will be saved when you save the query
Once you have created a custom query, you can save it.
Just as a project matures and develops over time, you may need to change the ways that you interact with it. You may wish to change the name of a query to reflect other modifications or customization you have made to it, as well as to reflect changes in the project itself.
Click the right mouse button on the query and select Rename.
Enter the new name for the query in the Name field.
Click OK.
The query will now be available with the name you entered.
Often, an existing query may contain slightly different criteria than what your present needs require. For example, if you have a query which has all the right criteria for a regular search, you might wish to modify the query, for example by changing the date to return the latest work items. You can then save this modified query so that you can use it again in the future without having to re-modify the original query.
To save the new or changed query:
Click the More Actions button on the right side of the screen report.
Select Save As.
Pick a name for your query, such a Open Blocker Bugs.
If you have team administration privileges, you will have a choice of creating a Team Query or a User Query. If not, you will only be allowed to create a User Query. In either case, for this example, choose User Query and click OK.
If you have team administration privileges and the query you are saving would be useful to all the members of your team, you can also save it as a Team Query.
Note that all queries are saved against the current team. Even if you have access to this repository from multiple teams, queries are saved in the scope of the current team.
If you have team administration privileges, you will likely want to create team queries based on the projects your team is working on and the status of the projects. For example, towards the end of a project, creating a query around Priority 1 bugs with a description that includes the phrase "stop ship" might be a useful addition to the set of queries available to the team.
The option to save a team query only appears if you have team privileges. If you find that you are frequently creating queries that other members of your team would find useful, ask your Team Productivity Center administrator to grant you team privileges. For more information, see Chapter 3, "Working with Oracle Team Productivity Center Administration."
Click the More Actions button on the right side of the screen report.
Select Save As.
Pick a name for your query, such a Open Blocker Bugs.
If you have team administration privileges, choose Team Query and click OK.
Only users with a role that allows them to modify team queries can delete team queries. In the default roles used by Team Productivity Center, this includes users with roles of Team Administrator and Group Administrator.
To delete a query you created:
In the Oracle Team Productivity Center panel right-click on the query you want to delete.
Select the Delete option, then answer Yes to the verification dialog.
In addition to querying individual work item repositories, Oracle Team Productivity Center provides a tagging mechanism that allows you to tag work items from multiple repositories for additional integration. You can then view items from across your repositories by querying for tags you have set on work items; Team Productivity Center will display work items with those tags, regardless of which repository contains them.
A key distinction between tagged work items and work items returned by a query is that the query searches through the entire repository, finding and returning items that match the query terms (for example, a range of bug IDs or the owner of a feature enhancement request). Tagged work items, on the other hand, are work items you have already identified and specifically tagged for a particular purpose.
Team Productivity Center uses two kinds of tags:
Team tags, set up by your team or group administrator, are available for use by all members of the team. Each team's tags are unique to that team, not shared among other teams. If you work on more than one team, the administrators of the various teams may use different tags (though they may also choose to use the same tags, particularly if your organization uses company-wide tags for bug tracking, feature requests, etc.)
Private tags, which you define on your own, help you find, sort, and group work items by project, by urgency, or by a specific section of the code. For example, you might choose to set up a tag for use in a bug database for bugs where you have fixed the code and checked it in, but not yet verified the fix in a product build. You can tag the appropriate work items—entries in a bug-tracking database, in this example—with this private tag each time you've checked in the fixes for that work item's issue.
Once you tag a number of work items, you can return a list of work items that you have identified with a specific tag. Creating a tag, as described here, for items you've fixed but not verified could greatly simplify verification of your assigned bugs once the next build of the product is available, because you can query the work item repository for all items that use this tag.
You create tags by using the Manage Tags dialog. If you are a team administrator, you have the choice of creating team or user tags; if you do not have administrative privileges, you can only create user tags. Administrators and non-administrators alike can apply tags to work items.
Creating a tag gives you an easy way to label work items across repositories, allowing you to take a quick look at previously tagged work items that all apply to a common issue.
Select the tag icon from the Work Item accordion toolbar in the Team Navigator.
Select Manage Tags.
In the Manage Tags dialog, click the green plus button.
Enter a name and description for the tag. The name should be short and easily distinguished; the description can include more detail.
If you are a Team or Group Administrator, select the visibility for this tag:
Team: all members of the team can view and query by this tag. (Option available to administrators, or to users with Manage Tag privileges.)
User: only you can view and query by this tag.
Click OK.
As your project evolves, you may need to modify an existing tag to more accurately reflect the tag's current usage, role, or importance. For example, if you have been using a tag to identify a series of related bugs which later testing determines to have a greater severity than initially detected, you can change the name of the tag applied to these bugs to reflect the increased importance.
You can modify any tag to which you have access, changing its name, description, and (if you have sufficient privileges) scope of visibility.
Locate the Work Items accordion in Team Productivity Center.
Click the Tag icon, selecting Manage Tags.
In the Manage Tags dialog, select the tag you want to change.
Double-click the field you wish to modify and make the necessary changes.
Click OK.
During the project lifecycle, you occasionally reach a point where you need to remove some of the “clutter” around your working environment. Deleting unused or obsolete tags is one way of cleaning up your JDeveloper environment, making the tags you are still using more effective because there is less distraction.
Locate the Work Items accordion in Team Productivity Center.
Click the Tag icon, selecting Manage Tags.
In the Manage Tags dialog, select the tag you want to delete.
Click the red X to delete the selected tag.
Click Yes to confirm the deletion.
Work items artifacts can be tagged with existing keywords. For example, bugs in a product under development may be tagged by a project manager as Hot, Warm, EOD (end-of-day), or Deferrable.
Note:
These tag names are just examples. You and your team can devise a tag naming scheme that best matches your tasks and work style.
In addition, artifacts in other work items can also be tagged with the same terms. For example, a JIRA feature could be tagged Hot. In such a case both the bugs and the feature request would show up if you look at the list of work items tagged as Hot.
You use tags by applying them to work items.
You can apply a tag, or multiple tags, to work items in any of your existing work item repositories. This lets you group similar work items by whatever characteristic you are using the tags to sort or group your work items.
To apply a tag to a work item:
Open the repository containing the work item you wish to tag—for example, a bug database.
Double-click the work item to be tagged, and then select the Tags tab.
Click the green + icon to add a tag. This opens the Apply Tags dialog.
Select the tag or tags you wish to apply to this work item, and then click OK.
Once you have applied tags to work items, you can view work items by the tags you have applied to them.
If the tag you want to apply does not already exist in the Apply Tags dialog, click on Manage Tags to open the Manage Tags dialog and create a new tag. See Section 2.7.1, "How to Create, Modify, and Delete Tags."
You can easily check your work items to see those that you have already tagged. This can be a quick and effective way to view a number of work items, in multiple repositories, which you (or your team) have tagged as being related in some way.
To view work items associated with a particular tag:
Select the tag icon from the Work Item accordion toolbar in the Team Navigator.
Select Query by My Tag to select a private tag, or select Query by Team Tags to select a team tag.
Select a tag name from the dropdown list.
A JDeveloper window will open, showing the items whose tags match the name you selected. This window shows the results of a cross-repository search for tagged work items, essentially returning all work items to which you or another team member (in the case of team tags) has assigned the tag on which you are querying. To get a list of tagged items for just one repository, right-click on the repository and select Query By My Tag or Query By Team Tag.
When you search across repositories, JDeveloper only displays the Repository, ID, Type and Subject (generally the common fields). When you search within a repository, additional fields may be displayed.
You can remove a work item from a Tag Result by selecting the item and clicking the Delete icon.
While one of the most useful aspects of tagging work items is the ability to show the contents of multiple repositories, you may occasionally find it necessary to search a specific repository for a tag. For example, if a colleague mentions a specific bug report that you think may have an impact on your work, you can search just the bug database for work items with this tag, and see if any of them relate to your portion of the project.
To search for tagged work items in a specific repository:
Click the right mouse button on the repository you wish to search. This brings up a context menu with the following options.
Table 2-4 Options while searching for tagged work items
| Option | Description |
|---|---|
|
Query by My Tag |
Displays a list of your tags, from which you can select the tag you wish to use for the query. |
|
Query by Team Tag |
Displays a list of team tags from which you can select the tag you wish to sue for the query. |
|
Query by ID |
Look through this repository and return the work item with the single ID you are looking for. The query will return the specified work item; to view tags associated with that work item, click the Tags tab of the work item display. |
|
New Query |
Opens the New Query pane in JDeveloper. See Section 2.6.1, "How to Create Queries." |
|
New <work item> |
Opens a pane in JDeveloper from which you can create a new work item of the type associated with the selected repository. For example, in the Task repository, this menu selection will say New Task. To obtain more information about the specific repository, click inside one of the fields in the New Workitem pane and press F1. |
|
Refresh |
Updates the display of the selected repository in the Work Items accordion. |
Note that only the top two menu items deal with tags; the other items on the menu provide additional functionality in working with work items and queries.
A relationship is an association between work items, which can either be in the same repository or in different repositories. It provides a way to relate two work items together. You can navigate to what is related to the current work item, and to the work item from the elements related to it.
Because relationships cross repositories, you can establish a relationship between, for example, a defect-tracking system and a customer request database; the relationship means that the work items in the two repositories will refer to each other, so that team members who view the defect-tracking entry will be able to track down the customer request as well.
Relationships cross the entire team. For example, you could create a relationship between a bug and an item in the Atlassian JIRA feature request tracking repository. Once you create the relationship, anyone from any team who opens that bug will see the relationship with the JIRA work item. However, team members who don't have that JIRA repository in their connectors will not be able to open the work item.
You add a relationship to a work item through the Add Work Item Relationship dialog. This dialog displays a list of work items from which you can select the ones for which you wish to create a relationship with the work item you have selected.
To add a relationship to a work item:
Select the work item to which you wish to add a relationship, then select the Relationships tab.
Click on the Add drop-down (the green +). This displays the work item relationship context menu, which lets you determine how to sort and display the available work items for the relationship you are adding. See Section 2.8.3, "How to Associate a Relationship with a Work Item."
Select an option from the context menu. The Add Work Item Relationship dialog is displayed.
Click on the work item (or work items) for which you wish to create a relationship with the item you selected, and then click OK.
You delete a relationship from a work item with the Delete button (the red X) from the work item tool bar.
To delete a relationship from a work item:
Select the work item from its repository.
Click on the Relationship tab.
Select the relationship that you wish to delete, and then click Delete (the red X).
When the Delete Tag from Work Item dialog asks you to confirm, click Yes.
The relationship is deleted.
Note that the work item referred to by the relationship is unchanged. You can add other relationships using that work item as required.
When you add a relationship to a work item, the Create button (the green +) displays a context menu that lets you select how to sort, display and select other work items for the relationship. This context menu contains the following selections:
Table 2-5 Associate Relationships with a Work Item
| Selection | Description |
|---|---|
|
By My Tags |
Displays a list of your user tags. When you select a tag from the list, the Add Work Item Relationship displays all work items that have been tagged with the selected user tag. To select one of these tagged work items for the relationship, click on the work item from the Add Work Item Relationship, and then click OK. To select more than one tagged work item, hold down the Control key and click any additional work items (Ctrl+Click). |
|
By Team Tags |
Displays a list of your available team tags. When you select a tag from the list, the Add Work Item Relationship displays all work items that have been tagged with the selected team tag. To select one of these tagged work items for the relationship, click on the work item from the Add Work Item Relationship, and then click OK. To select more than one tagged work item, hold down the Control key and click any additional work items (Ctrl+Click). |
|
By Opened Work Items |
Displays a list of all the work items you currently have open in JDeveloper. To select one of these open work items to use in the relationship, click on the work item from the Add Work Item Relationship, and then click OK. To select more than one open work item, hold down the Control key and click any additional work items (Ctrl+Click). |
|
By Active Work Item |
Creates a relationship between the selected work item and the active work item. See Section 2.2.6, "How to Set and Display the Active Work Item." If the work item you have selected is the active work item, this menu option will not be available. |
Oracle Team Productivity Center includes a News panel, in which you can select from available RSS feeds to have news of interest to you displayed in JDeveloper. The News panel is adjacent to the Messages and Chat panels in the main JDeveloper pane.
The News panel gives you a number of controls over what appears in JDeveloper:
Important items. Important items are identified by the sender, at the RSS feed. You can choose to display only Important items, or to display all items.
Quick sorting of news items by column. To change how news items are displayed, click the heading of each column (title, date, categories). Clicking toggles the display; for example, clicking once on the date column displays news items oldest first, while clicking again displays news items newest first.
Select Tools > Preferences > News. This opens the News dialog.
Click the green + sign to add a news feed.
Enter the news feed URL, then click Test to verify the connection.
Additionally you can also configure other user preferences here, such as the frequency for refreshing news items.
Once you have set up the News feed, select Team > News to open the news window. By default, the news window is docked in the bottom pane (shared with the Log window and Pending Changes windows, if open.)