Configuring TFS for Help+Manual

<< Click to Display Table of Contents >>

Navigation:  More Advanced Procedures > Using Version Control Systems > MS Team Foundation Server >

Configuring TFS for Help+Manual

This information is for the administrator of your Team Foundation Server system. If you are a user and you are only now starting to manage your Help+Manual projects with TFS, please pass these instructions on to the administrator so that she or he can get the server set up correctly for you to use it with your Help+Manual projects.

Supported TFS versions

The current version of Help+Manual requires the local versions of Team Foundation Server 2012, 2013 or 2015 (there is no 2014). No earlier versions will be supported. This means you must be using a local installation of TFS 2012 or later to use it with Help+Manual.

Online TFS implementations:

Online TFS implementations like the Microsoft TFS service for Visual Studio are not yet supported. They use unique and highly complex authentication services that still need to be implemented in Help+Manual.

Installing TFS

Installing and configuring Team Foundation Server is a complex job for an experienced Windows Server administrator. We cannot cover this here. Your server administrator needs to consult the Microsoft TFS documentation for instructions.

The items below explain how the TFS server needs to be configured to work smoothly with Help+Manual.

User Permissions

Instructions regarding these issues can also be found in the topic on setting up your projects for TFS.

Permissions for setting up your system for TFS

When you are setting up your system for TFS you will need more permissions than when you are just using TFS with Help+Manual. Specifically, when you are setting up the "server profile" for accessing TFS you will need to be allowed to list all the TFS "collections" (groups of projects) on the server so that you can select the collection where your proejct(s) is/are going to be stored. If you get a message saying that you cannot list the collections in this step you will need to ask your administrator to up your permissions briefly so that you can set up the server profile.

Permissions for creating projects on the TFS server

Help+Manual users who are also going to create TFS projects for storing Help+Manual projects must also have the necessary permissions to be able to do this. Normally, only one user in the team needs to create a TFS project the first time the Help+Manual project is added to TFS. Alternatively, the TFS administrator can do this on the TFS server (see below).

Permissions for working on local working copies of HM projects

All users who are going to work on local working copies of Help+Manual projects linked to TFS must have the necessary permissions to download, upload and synchronize all components of their Help+Manual projects in the TFS projects where their work is stored (check out and check in/commit).

Existing older Help+Manual projects on the TFS server

If you have been managing Help+Manual projects in TFS manually in the past you will most probably need to create new TFS projects for active integration with Help+Manual. This applies in particular if your Help+Manual projects are stored in other common projects along with other material. If that is the case you must create new TFS projects for Help+Manual that conform to the requirements outlined below. Failure to do so can result in serious errors.

You can only continue to use existing TFS projects containing Help+Manual projects if they conform to all the requirements: One and only one Help+Manual project in each TFS project, no other material shared in the same project and the TFS project must be stored in a collection to which all users have the necessary access permissions.

TFS Collections and Projects

A collection is required

Help+Manual requires an existing TFS collection on the server to be able to connect. It cannot create a collection. The TFS administrator must set up one or more collections on the server with the necessary access permissions for all the users who are going to manage their shared projects there.

One TFS project is required for each Help+Manual project

Each TFS project in a collection can store one and only one Help+Manual project. You cannot add Help+Manual projects to other projects, for example existing Visual Studio application development projects, or projects that contain other Help+Manual projects. Each Help+Manual project must be stored in its own separate TFS project. All the additional folders and files stored in the project folder of the local working copy of the Help+Manual project will be added to the TFS project automatically when you synchronize it with the server.

The reason for this is that the current interface of TFS does not allow Help+Manual to protect its files against changes made by other applications and users with access to the project. It is only possible to maintain the integrity of your HM project files if they are stored in their own TFS project.

Empty TFS projects can be pre-created but are not required

Projects do not need to be pre-created for Help+Manual's use. Once it has access to the collection with permissions to create projects it can create its own projects within the collection. If the administrator wishes to pre-create TFS projects with defined names for the Help+Manual projects they can do this. These projects must be empty for Help+Manual to be able to upload existing projects to TFS.

Normally, new projects will be uploaded to TFS by Help+Manual

The normal procedure is for the project team leader to create a Help+Manual project and then use the TFS tools in Help+Manual to upload it to the TFS collection. When doing this, they will either create a new TFS project in the collection or select a pre-created empty project that has been set up by the TFS server administrator. After this, the other team members will connect to this TFS project and download their own working copies.

The administrator can pre-load Help+Manual projects to TFS projects manually

If you wish to handle it this way, it is possible for the TFS administrator to manually pre-load a Help+Manual project into the TFS project that is going to store it. To do this you must import all the contents of the entire Help+Manual project folder to an empty TFS project that does not contain any other projects or data. The Help+Manual users can then download their working copies from this project using the TFS tools in Help+Manual. Normally, however, the team leader would upload the first copy of the project to the TFS collection from within Help+Manual.