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, add groups and users as members to groups, and grant permissions to the groups.

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

In this topic

  • Name and Location of Groups Plug-in

  • Defining Groups

  • Defining Members

  • Defining Permissions

  • Groups Element Reference

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 Defining the Tasks to Process a Plug-in.

Back to top

Defining 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>

Back to top

Defining 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>

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>

Back to top

Defining 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>

Back to top

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 Defining 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 ProcessTemplate XML Elements Reference.

group

 
<group name="GroupName" description="GroupDescription">
   <permissions> . . . </permissions>
   <members> . . . </members>
</group>

group is an optional child element of groups and Children.

Defines a group and its permissions. You must specify both the name and description attributes. The name of the group must be 1 to 255 characters long.

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.

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 Configuring Initial Groups, 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.

Back to top

See Also

Concepts

Configuring Initial Groups, Members, and Permissions

Controlling Access to Functional Areas

Configuring Users, Groups, and Permissions

Customizing Functional Areas within a Process Template

Other Resources

Managing Permission to Create or Modify Work Items

Change History

Date

History

Reason

May 2012

Removed EVENT_SUBSCRIPTION as a supported option.

Content bug fix.

April 2011

Added a note about the schema file, and consolidated syntax information into a single element reference.

Information enhancement.