Wednesday, June 3, 2015

Toad For Oracle 12.6 and Team Foundation Server 2013: Associating Work Items with Changesets While Performing Check-ins from Toad

 

As stated in the Toad for Oracle 12.1 - Release Notes, this version introduces the following feature “When using Team Foundation Server (TFS) in Toad, you can now check-in TFS Work Items and link one or more TFS work items to the check-in change set.” Additionally, the next version “Toad 12.5 supports Microsoft Team Foundation Server 2013 (TFS), as stated by Toad for Oracle 12.5 – Release Notes.

In other words, it is possible to associate work items with database changes while performing a check-in action from Toad for Oracle 12.6 when connected to a Team Foundation Server 2013 Team Project. This blog describes the main characteristics of this integration feature.

Note: I am using the Visual Studio 2013 Application Lifecycle Management Virtual Machine currently with TFS 2013 Update 3 and Visual Studio Ultimate 2013 with Update 3, where I have additionally installed the Oracle Demo DB locally (Oracle Database 11g Release 2 (11.2.0.1.0) for Microsoft Windows (x64)) and Toad 12.6.0.53 with Team Coding 7.1 – Trial.

Setup Work Item Association

First you need to set up Work Item Association as part of the Team Coding Configuration. Each user needs to perform this step on his own machine, as this is not part of the common connection settings for Team Foundation Server, which are set on the level of each Oracle database.

2 - Associating Work Items with Changesets from Toad For Oracle 12.6 - Toad Set Up

Note: The connection to Team Foundation server is usually set up by the so called Team Coding Administrator (usually named Toad) and can be managed only by users granted the TC_ADMIN_ROLE role.

Depending on the Visual Studio related bits installed on your machine you might need additional installation steps. For installation instructions see my blog post “TIPP: VS Team Explorer 2012 Required for Associating Work Items with Changesets from Toad For Oracle 12.6 to Team Foundation Server 2013”. 

Note: For additional info, check the built in Toad For Oracle Help (F1) under the topic Use Source Control—>Set Up Version Control (VCS)—>Team Foundation Server (TFS)—>TFS Work Items.

Managing Work Items in the Team Coding Check-in Dialog

In the Team Coding Check-in dialog, open the Work Items tab. Here you can manage the list of Work Items available from TFS in the following way:

  1. When you check the “All Team Project Members” check box and select “All Team Projects” in the Team Projects dropdown, the list will initially contain all work items for all TFS team projects in the project collection you are connected to in Toad (which is not optimal due to a possibly large number of work items in multiple team projects). Therefore it is better to filter per team project.

    1 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - CheckIn Dialog With Work Items
  2. When you type a work item ID in the Work Item ID edit box and press enter, this item will be added to the list (which is not the most obvious behavior, but it turns out to be handy).

    2 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - CheckIn Dialog With Work Items - Select by ID
  3. To refresh the list in the Check-in dialog itself, you need to change the filters you are currently using. An explicit action to refresh the selection of work items you are currently previewing does not exist (and it should).
  4. The list can be filtered and sorted using the built-in actions from the container grid control.

Associating Work Items at Check-in

To select the work items you want to associate with the changes to database object, check their corresponding checkbox in the Selected column. If you want to select all work items displayed in the list or the ones you have manually selected (by selecting the whole row in the grid), right click on the header of the Selected column and choose from available actions.

3 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - CheckIn Dialog With Work Items - Select All or Selected

 

Adjust your selection of work items to associate them with changes to database objects you are checking to TFS and click OK.

Toad adds the association to selected work items as the second step in its check-in logic. This can be noticed in the log of actions in the Toad Output dialog and from timestamps in TFS.

Here is an example of checking in 2 database objects and associating 2 work items with this change:

4 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - Checkin With 2 Associated Work Items_1

4 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - Checkin With 2 Associated Work Items_2

For this example you can notice that the log of actions in the Toad Output dialog contains following entries:

11:22:07 Info: Procedure HR.ADD_JOB_HISTORY checked in.
11:22:07 Info: Procedure HR.SECURE_DML checked in.
11:22:10 Info: Changeset 89 linked to Work Item 2.
11:22:10 Info: Changeset 89 linked to Work Item 3.
11:22:10 Info: Checked in revision 89 for $/Default/TOAD/XE/HR/PROCEDURE.

First the 2 changed database objects were checked in as changeset 89 with the comment “Test checkin with 2 associated work items”.
Then the 2 work items were associated (linked) with this changeset 89, whereby the creation of this link did not use the comment from the initial checkin action from Toad. The TFS changed date and the history for both work items shows that the association happened after the check-in itself.
The last comment in the Toad Output window shows that a new revision was created in the Team Coding database as well, what can be seen is in the Controlled objects list.

Remarks:

Adding new objects to a database and to version control:

If you select the option to “Add to Team Coding when loading/creating an object file” (and optionally “Prompt before Adding to Team Coding”) in View—>Toad –>Options—>Source Control, then new object are automatically added to Team Coding VCS and TFS version control respectively. You cannot associate work items during this action (even if you are optionally prompted before adding to Team Coding).

5 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - Toad Source Control Options

5 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - Automatically Adding Objects at Creation

Dropping objects from a database and from version control:

When dropping object from the Toad Schema Explorer, you can be prompted to remove objects from version control as well (this is the default option, check for other options under View—>Toad –>Options—>Source Control). During this action, work items cannot be associated with the resulting changeset. Additionally, this changeset is created with an empty comment (while it should have some generic one).

6 - Toad for Oracle 12.6 and TFS 2013 - Associating Work Items with Changesets - Dropping objects from Taod and Version Control