Define groups, teams, and permissions using the Groups and Permissions Plug-in

  • Article

You can define security groups to control access to functional areas within a team project. In addition to the default security groups in Visual Studio Team Foundation Server, you can configure a team project's initial groups, group members, and security permissions by customizing the Groups and Permissions plug-in. With this plug-in, you can define groups, teams, add groups and users as members to groups, and grant permissions to the groups.

This topic describes the syntax structure of the groups, iterationPath, members, permissions, and teamsettings elements that are used in the file for the Groups and Permissions plug-in. For more information about how to use these elements, see Configure initial groups, teams, members, and permissions.

Name and location of Groups plug-in

The Groups and Permission plug-in is defined by the GroupsandPermissions.xml plug-in file, which must conform to the schema definition that is defined in the Gss.xsd file. You can download the schema files for process templates from the following page on the Microsoft website: Process Template and Work Item Schemas for Visual Studio Team Foundation.

The following table summarizes the names of the file, the folder, and the plug-in for the process templates for Microsoft Solutions Framework (MSF).

File name:

GroupsandPermissions.xml

Folder name:

Groups and Permissions

Plug-in name:

Microsoft.ProjectCreationWizard.Groups

Note

You can change the names of the XML file and the folder but not the plug-in. Visual Studio Team Foundation Server does not include a mechanism for the deployment of client-side plug-ins, policies, or other modifications. If you want to deploy this kind of functionality, you must use your own distribution and installation program.

In the Groups and Permissions plug-in, you specify one or more tasks and their dependencies within the taskXml element. Generally, you specify one task per security group to create for your process. For more information about how to specify tasks, see Define the tasks to process a plug-in.

Define groups

You use the group element to specify a new security group in Team Foundation Server.

<group name="GroupName" description="GroupDescription"></group>

The following example shows how to create a group that is named Reader:

<task id="GroupCreation1" 
      name="Create Groups and Permissions" 
      plugin="Microsoft.ProjectCreationWizard.Groups" 
      completionMessage="Groups and Permissions created.">
   <taskXml>
      <groups>
         <group name="Readers"
                description="A group for users who have read access across the project">
            <permissions>
               <!-- permissions -->
            </permissions>
         </group>
      </groups>
   </taskXml>
</task>

Define members

You use the member element to assign a group as a member of a security group in Team Foundation Server.

<member name="MemberName" ></member>

Note

A group that is a team (isTeam="true") cannot be a member of a group.

The following example shows how to add TestGroup1 as a member of TestGroup2.

<task id="GroupCreation1" 
    <taskXml>
      <groups>
        <group name="TestGroup1" description="Test group 1.  Contains no members out of the box.">
          <permissions>
            <permission name="GENERIC_READ" class="PROJECT" allow="true" />
          </permissions>
        </group>
        <group name="TestGroup2" description="Test group 2.  Contains TestGroup1 and Project Administrators.">
          <permissions>
            <permission name="GENERIC_READ" class="PROJECT" allow="true" />
          </permissions>
          <members>
            <member name="TestGroup1" />
            <member name="$$PROJECTADMINGROUP$$" />
          </members>
        </group>
      </groups>
    </taskXml>
</task>

Define teams and team settings

Within the default Groups and Permissions plug-in file, the @defaultTeam macro creates the default team at the root area path. You can change this structure by including additional area paths within the Classification plug-in file. By using the teamsettings element, you can pre-configure the iterations assigned to a team. The plug-in uses the following code snippet. In this example, three iterations are defined for the default team.

Important

You must assign iteration paths that correspond to paths defined in the Classification plug-in file. See Define the initial areas and iterations in the classification plug-in.

<group name="@defaultTeam">
   <permissions>
      <permission name="GENERIC_READ" class="PROJECT" allow="true" />
   </permissions>
   <members>
      <member name="@creator"/>
   </members>
   <teamSettings areaPath="Area">
      <iterationPaths backlogPath="Iteration">
         <iterationPath path="Iteration 1" />
         <iterationPath path="Iteration 2" />
         <iterationPath path="Iteration 3" />
      </iterationPaths>
   </teamSettings>
</group>

You can also define additional teams within a team project. You do this by defining a group and assigning the isTeam attribute to true. The following example shows how to define a team and its permissions, members, and initial sprint assignments. Specify the default team settings for a team project.

<group name="Dream Team" isTeam="true" description="Next generation work">
   <permissions>
      <permission name="GENERIC_READ" class="PROJECT" allow="true" />
   </permissions>
   <members>
      <member name="@creator"/>
   </members>
   <teamSettings areaPath="Area">
      <iterationPaths backlogPath="Iteration">
         <iterationPath path="Iteration 1" />
         <iterationPath path="Iteration 2" />
         <iterationPath path="Iteration 3" />
      </iterationPaths>
   </teamSettings>
</group>

Define permissions

You must specify permissions for each group that you create. You use the permission element for this purpose.

<permission name="PermissionName" class="ClassName" allow="true | false"/>

The following example shows how to grant permissions to the Reader security group so that members can view information about a team project, but they cannot modify that information.

<group name="Readers" description="A group for users who have read access across the project">
   <permissions>
     <permission name="GENERIC_READ" class="PROJECT" allow="true" />
     <permission name="GENERIC_READ" class="CSS_NODE" allow="true" />
     <permission name="WORK_ITEM_READ" class="CSS_NODE" allow="true" />
   </permissions>
</group>

Groups element reference

The following table describes the elements that you use to define the initial groups and permissions for a team project. You specify these elements within a taskXml container element in the Groups and Permissions plug-in file. For information about this element, see Define the tasks to process a plug-in.

Warning

The Gss.xsd schema file does not define the property or properties elements. When you upload the process template, the Process Template Manager validates these elements before storing them in Team Foundation Server.

The groups and group (Groups and Permission) elements are distinct from the groups and group (Process Template) elements. For information on the latter pair of elements, see Process template XML elements reference.

group

 
<group name="GroupName" isTeam="true | false" description="GroupDescription">
   <permissions> . . . </permissions>
   <members> . . . </members>
</group>

The following definitions apply for each attribute:

  • name: Required. Specifies the name of the group. The name of the group must be 1 to 255 characters long.

  • isTeam: Optional. Identifies the group as a team, which supports small groups to organize their work within a team project.

  • description: Required when the group is not a team. Specifies a description of the group. The description is displayed within the security pages of Team Web Access.

group is an optional child element of groups and Children.

Defines a group or a team and its permissions and members.

groups

 
<groups>
   <group> . . . </group>
</groups>

groups is a required child element of taskXml for the Groups and Permissions plug-in.

Contains the group and permission definitions.

iterationPath

 
<iterationPath path="IterationName" />

iterationPath is a required child element of iterationPaths.

Specifies a team milestone.

iterationPaths

 

<iterationPaths backlogPath="BacklogPathName">
. . .      </iterationPaths>

iterationPaths is an optional child element of teamsettings.

Specifies team milestones.

member

 
<member name="MemberName" ></member>

For information about how to specify default groups, see Group Macros and Default Groups Defined in Team Foundation Server.

member is a required child element of members.

Specifies the name of a group that you are adding as a member of another group. You can create groups and automatically populate them with default groups in Team Foundation Server, previously defined project groups, and groups and users in Active Directory.

members

 
<members>
   <member> . . . </member>
</members>

members is an optional child element of group.

Specifies the collection of members to add to the group.

permission

 
<permission name="PermissionName" class="ClassName" allow="true | false" />

Where the following definitions apply for each attribute:

  • name: Required. Specifies the name of the permission. For more information, see the table in Configure initial groups, teams, members, and permissions that describes each class and name combination you can specify as a permission.

  • class: Required. Identifies the class, or area, where the group permission is granted. The following values are valid: NAMESPACE (collection-level), PROJECT (project-level), CSS_NODE (area node) and ITERATION_NODE (iteration node).

  • allow: Optional. Specifies a true or false value that indicates whether you are allowing the permission.

permission is a required child element of permissions.

Specifies the permission to apply to the group.

permissions

 
<permissions >
   <permission> . . . </permissions>
</permissions >

permissions is a required child element of group.

Specifies the collection of permissions to apply to the group.

teamsettings

 
<teamSettings areaPath="Area">
. . .
</teamSettings>

teamsettings is an optional child element of group.

Configures the team project as the default team, and optionally specifies team milestones with the iterationPath element.

See Also

Concepts

Configure initial groups, teams, members, and permissions

Control access to functional areas

Manage users or groups in TFS

Customize a process template

Other Resources

Apply a rule to a work item field