Its been a little longer than I wanted it to be since I've blogged.  Over the past few weeks, I've been trying my best to answer many of your questions related to installing the Connector while also fixing any issues that many of you have reported.  By the way, thanks to all who reported issues -- these will only help to improve the experience for everyone that uses the Connector.  In an effort to proactively answer several of the questions you may have when installing and configuring the Connector, I've put together the most frequently asked questions.  As soon as the codeplex site is updated, I'll include the link to them (as well as answers to them ) here.

So, now that the Connector has been released and more than a few of you have it up and running, you may be asking:

• What's a typical "day in the life" when using the Connector? 
• How do I use the Connector Administrative UI?
• What's really happening underneath the covers?  How is information passed back and forth? 

Over the next few blogs, I will begin to scratch the surface of the Connector and try to explain what it does and how it works.  Eventually, I will dive into its depths and walk you through how you can extend and customize the Connector to serve your company's specific needs. For now, let's start at the basics.

After you have successfully installed the Connector, one of the first things you will probably notice is the Connector's Administrative web site.  The Home page for the Connector Site shows the projects that have currently been associated such that synchronization can take place.  Initially, this should be empty and appear like this:

However, if you see a screen that looks similar to this:

then something is wrong with the way the Connector has been configured.  Check the Application Event Log and search for the handlingInstanceId displayed in the error message.  This should give you a decent indication of what went wrong.  Check out the FAQs mentioned earlier in this blog to see if any of those resolve your issues.  More often than not, it is an authorization issue connecting to Project Server. 

If you can see the home page as displayed in the first figure, then the next action you'll want to take is to associate a Project Server project and a Team Foundation Server project together.  These projects must already exists; that is, the Connector will not create the projects for you.  It would not be difficult to extend the Connector so that it could create Project Server projects; however, there is a bit of 'black magic' needed to automatically create TFS projects.  Still, if this is a feature that is greatly desired, please let me know -- we could probably get it on the list for the next major release of the Connector.

To create an association between a Project Server project and a TFS project, click the "Create new project association" button.  That will take you to a page that looks like this:

The first drop-down box on this page lists all the published projects within Project Server that have not already been associated with a TFS team project.  The second drop-down box lists all TFS team projects that have not already been associated with a Project Server project.  The check boxes allow different methods for creating the initial associations between the assignments within the Project Server project and the WorkItems within the TFS project.  Here is a brief description of each:

Selecting either of the first two options and clicking the Save button will redirect the user back to the home page.  The project association should now appear on the page and it will usually be locked so that no modifications can be made to it while it is creating the new assignments/WorkItems and corresponding associations.  The following figure shows the home page with a few projects that have been associated and one that is currently in the 'locked' state.

Eventually, the project association should come out of the locked state.  The home page is set to automatically refresh every so often to show its state as well as any new WorkItems that may be pending approval (more on that in the next blog).  You can change how many seconds the page waits before refreshing by modifying the ProjectListRefreshInterval setting within the Connector Web Site's web.config file:

 <setting name="ProjectListRefreshInterval" serializeAs="String">
      <value>30</value>
 </setting>

Every once in a while, the project association might get 'stuck' in a locked state due to some error that has occurred.  I am currently working on a more elegant solution to resolve this; however, for now you can unlock a project association a few different ways.  First, check the Application Event Log to ensure that it is truly stuck due to some error.  If you see that an error has occurred, you can either unlock it by going to the ProjectsAssociation table in the PS2007ProviderDb database and changing the value for the IsLocked field to false or by finding the ID for the ProjectAssociation (in this same table) and calling the LockProjectAssociation web method in the PS2007ProviderAdministration web service (shown below) with the enableLock parameter set to false.  The latter is preferred as any future modifications I make to this process will go through this service.  But for now, they just do pretty much the same thing.

Assuming everything works okay and the project association becomes unlocked, you'll see several different options available to you for each project association.  You can view any WorkItem changes that are pending approval in order to be sent to Project Server (more on this in the next blog), view the current associations between assignments and WorkItems, delete the project association, or see a hierarchical view of the assignments in Project Server including information about their corresponding Workitems.  Let's dive into viewing the assignment associations now.  To do this, click the "Details..." link for a project association. It should take you to a page that looks like this:

This page shows you the assignments and WorkItems that are currently associated and affords you the ability to delete this association should you wish.  Any changes made to any of these assignments in Project Server (aside from changing the value for 'AutoSync to External System' to No) will automatically be propagated to its corresponding WorkItem in TFS.  By default, any changes made to one of this WorkItems in TFS will be marked as pending approval by the Connector Administrator before it is sent to Project Server.  You can configure the Connector Web Service to have WorkItems automatically sent to Project Server; i.e., not require approval by the Connector Administrator, by setting approvalNeeded to false in the service's web.config file:

...

    <SynchronizationManagerProviders>
      <add approvalNeeded="false" workItemWinsConflict="false" tfsServerUri="http://vstsr-epm-tfs:8080"
       resourceGroupName="Contributors" pendingQueueDb="ConnectorDb"
    ...

Clicking the "Create new assignment association" button will take you to a page that allows you to select any WorkItems that are not closed or resolved and are not already associated with an assignment and associate them with any published, unassociated assignment.  There are two ways to choose the assignment and WorkItem you want to associate; by WorkItem or by Assignment.  When the page is first displayed, it provides the option of having WorkItems drive the process. 

The reason that there are two ways to drive how to create an assignment association is that the items that appear in the second drop-down list are filtered according to the WorkItem type for the item selected in the first drop-down list.  For example, in the figure above, a WorkItem of type Task is selected in the WorkItem drop-down list.  Therefore, the Task drop-down is filtered to only show assignments that equate to having a WorkItem of type Task.  Now, you may be wondering, "Project Server does not have the concept of WorkItem Types for assignments; how can the Connector do this?"  This is where the Project Server assignment custom fields comes into play -- specifically the Enterprise WorkItem Type custom field.  When the Project Server part of the Connector was installed, this custom field was created.  If the Enterprise WorkItem type is not set for an assignment, it will default to Task.  However, this can be changed by modifying the value just as you would any other custom field within Project.  The figure below shows the Task Usage View within MS Project; this view allows for changes at both the Task level as well as the Assignment level.  In the figure below there are thirteen assignments -- eight are tasks, two are requirements, and three are bugs:

The mappings between the Enteprise WorkItem Types within Project Server and the TFS WorkItem Types is maintained within the configuration for the Connector Web Service.  The snippet below shows the mappings for Bug to Bug, Quality of Service Requirement to Quality of Service Requirement, Requirement to Scenario, and Task to Task for the out of the box MSF Agile process template.

<workItemMappings>
   <add processTemplate="MSF for Agile Software Development - v4.0" name="MSF for Agile Software Development - v4.0 Mapping">
     <workItemTypeMappings>
       <add partnerWorkItemType="Bug" tfsWorkItemType="Bug" name="Bug Mapping">
         <fieldMappings>...

         </fieldMappings>
       </add>
       <add partnerWorkItemType="Quality Of Service Requirement" tfsWorkItemType="Quality Of Service Requirement" name="QOS Requirement Mapping">
         <fieldMappings>...
         </fieldMappings>
       </add>
       <add partnerWorkItemType="Requirement" tfsWorkItemType="Scenario" name="Scenario Mapping">
         <fieldMappings>...
          </fieldMappings>
       </add>
       <add partnerWorkItemType="Task" tfsWorkItemType="Task" name="Task Mapping">
         <fieldMappings>...

Alternatively, because the engine for the Connector Service just leverages a new application block named the TFS Connector Application Block, this configuration could also be viewed and modified using the Enterprise Library Configuration Tool. 

After adding the associations and submitting them, the Connector will redirect to the home page again.  From there, you can also view the hierarchy information and respond to WorkItems that are pending approval.  And that's where I'll pick up in my next blog...

HTH,

Lenny