A SharePoint site and its contents can not only be created and updated manually, but also programmatically. Microsoft has provided SharePoint class libraries and web services for this purpose. I was involved in programmatically creating SharePoint sites, adding and updating web parts, setting permissions, changing lists etc., basically working with every aspect of SharePoint sub sites. I found generally if anything can be done manually, it can also be done programmatically. In this article, I’d like to introduce how to use SharePoint web services to loop through all the sub sites to add roles, add users to site roles, and update role permissions on site and list levels.

In the attached example program, I’ll accomplish the following tasks:

·         Work with many sub sites under a top level site;

·         Add a Manager role and add a user “us\grant” to this role in every sub site;

·         Customize the permissions of the Manager role in every sub site;

·         Customize the permissions of the Manager role to the “Shared Document” library for every sub site.

The sample program will work only if you update the web services with the valid URL and change the network credentials to the correct user name and password.

System Requirements

The server has to be Microsoft Office SharePoint Portal Server 2003. The development system can be any Windows system with Microsoft Visual Studio .NET 2003 installed. When calling the web services, the network credential passed in must have the corresponding permissions on the site.

Working with a Collection of Sub Sites

Microsoft has provided SharePoint Web services to work with sites and sub sites. The URL for this site is: http://Server_Name/[sites/][Site_Name/]_vti_bin/Webs.asmx.

It provides five methods. The GetAllSubWebCollection method returns the titles and URLs of all sites within the current site collection. Here we use GetWebCollection() to get the titles and URLs of all sites directly beneath the current site. Listing 1 shows the code to return all the sub sites one level down.

Listing 1 – Get all the sub sites directly beneath the current site

ws_webs.Webs ws = new ws_webs.Webs();
ws.Url = sSPSServer + @"/" +sSecondLevelSite + "/_vti_bin/Webs.asmx";
ws.Credentials =System.Net.CredentialCache.DefaultCredentials;
System.Xml.XmlNode nd = ws.GetWebCollection();
XmlNodeList ndlist = nd.ChildNodes;
foreach (XmlNode xGet in ndlist)
  string sWebTitle = xGet.Attributes["Title"].Value;
  string sOneSubSite =xGet.Attributes["Url"].Value;
Add Role and Add User to This Role

SharePoint has built-in groups Guest, Reader, Contributor, Web Designer, and Administrator with default site permissions, but you can add your own groups with customized permissions on the site and on specific lists.

The Users and Groups service of SharePoint provides methods for working with users, site groups, and cross-site groups. The Web Reference is: http://Server_Name/[sites/][Site_Name/]_vti_bin/UserGroup.asmx.

The Users and Groups service has over thirty methods. It contains all the web methods to work with groups, roles, and users. The AddUserToRole method is used to add a user to a specific role and AddRole web method is what we need here to add the manager role to each subsite, Listing 2 shows the code for adding the manager role.

The AddRole web method has three input parameters. The first two parameters are straightforward. The third parameter is defined on the Microsoft web site as shown in Table 1.

·         roleName   A string that contains the name of the site group.

·         description   A string that contains the description for the site group.

·         permissionMask   A 32-bit integer in 0x00000000 format that represents a Microsoft.SharePoint .SPRights value and specifies permissions for the new site group. Use the pipe symbol (“|”) in C# or Or in Visual Basic .NET to delimit values when creating a custom permission mask that combines permissions.

Listing 2 – Add manager role and add a user to Manager role

ws_usergroup.UserGroup ws = newws_usergroup.UserGroup();
ws.Url = sOneSubSite +"/_vti_bin/usergroup.asmx";
NetworkCredential nc = newNetworkCredential(sUserName, sPassword, sDomain);
ws.Credentials = nc;
ws.AddRole("Manager""Managerrole.", 0x00000400|0x00000800);

Table 1 – SPRights Enumeration






Add, change, or delete ASPX pages, HTML pages, or Web Part Pages, and edit the Web site using a Windows SharePoint Services-compatible editor.



Add or remove Web Parts on a personalized Web Part Page.



Add items to lists, add documents to document libraries, and add Web discussion comments.



Apply a style sheet (.CSS file) to the Web site.



Apply a theme or borders to the entire Web site.



Browse directories in a Web site.



View information about users. This right is not available through the user interface.



Check in a document without saving the current changes.



Create, change, and delete site groups, including adding users to the site groups and specifying which rights are assigned to a site group.



Create a Web site using Self-Service Site Creation.



Delete items from a list, documents from a document library, and Web discussion comments in documents.



Edit items in lists, edit documents in document libraries, edit Web discussion comments in documents, and customize Web Part Pages in document libraries.



Has no permissions on the Web site. Not available through the user interface.



Has all permissions on the Web site. Not available through the user interface.



Grant, deny, or change user permissions to a list.



Approve content in lists, add or remove columns in a list, and add or remove public views of a list.



Create, change, and delete personal views of lists.



Create, change, and delete site groups, including adding users to the site groups and specifying which rights are assigned to a site group.



Manage or create sub sites.



Manage a site, including the ability to perform all administration tasks for the site and manage contents and permissions



Open the SharePoint Web site and get metadata related to the site, as well as see the underlying navigation structure (not exposed in the user interface).



Update Web Parts to display personalized information.



View items in lists, documents in document libraries, view Web discussion comments, and set up e-mail alerts for lists.



View pages in a Web site.



View reports on Web site usage.


Update Role Permissions at Site Level

You can set permissions when you add roles. So updating role permissions at site level is not necessary for the tasks here. But sometimes developers need to change permission after a SharePoint site goes live and roles have been created, so I added this method here for illustration purposes.

The permissions for SharePoint sub sites can be set at two levels: site level and list level. The Permissions service provides methods for working with the permissions for a site or list. The URL for this web service is http://Server_Name/[sites/][Site_Name/]_vti_bin/Permissions.asmx. For example, if the sub site URL is http://testserver/sites/granttest/GRANTTEST2/default.aspx, then the web service URL is http://testserver/sites/granttest/GRANTTEST2/ vti_bin/Permissions.asmx. No matter at which level the sub site resides, this service is always available. This is different than some of the services that are only available to the top level site.

The UpdatePermission method of the Permissions service modifies site-level permissions for the specified site group, or modifies permissions to the list for the specified user, site group, or cross-site group. Its input parameters are defined as follows:

·         objectName   A string that contains the name of the list or site. It can be an empty string if it is a site.

·         objectType   A string that specifies either List or Web.

·         permissionIdentifier   A string that contains the name of the site group, the name of the cross-site group, or the user name (DOMAIN\User_Alias) of the user to whom the permission applies.

·         permissionType   A string that specifies user, group (cross-site group), or role (site group). The user or cross-site group has to be valid, and the site group has to already exist on the site.

·         permissionMask   A 32-bit integer that specifies the new permission mask (See table 1).

Listing 3 – Update permissions at site level

ws_Permissions.Permissions ws = newws_Permissions.Permissions();
NetworkCredential nc = newNetworkCredential(sUserName, sPassword, sDomain);
ws.Credentials = nc;
ws.Url = sOneSubSite +@"/_vti_bin/permissions.asmx";
int iMask = 0x00000400|0x00000800|0x00000100|0x00000002|0x00000004|0x00000008
ws.UpdatePermission("""Web","Manager""role", iMask);
Add, Update Permissions at List Level

In SharePoint, if you don’t define the permissions of a user, a role or a group on a specific list, the permissions that are defined at site level will be inherited. But you can define a unique permission collection for a user, a role, or a group on a specific list. In our example, the manager role has all the list permissions including Manage Lists, Cancel Check-Out, Add Items, Edit Items, Delete Items, and View Items on all the lists, except only Add Items, Edit Items, Delete Items, and View Items on Shared Documents.

We use the same web method to update list permission as we did to update site permissions. Listing 4 shows the code to do that. UpdatePermission is not required and can be combined into AddPermission, but for illustrate purpose, I list them separately.

Listing 4 – Updating role permission on a list

ws_Permissions.Permissions ws = newws_Permissions.Permissions();
NetworkCredential nc = newNetworkCredential(sUserName, sPassword, sDomain);
ws.Credentials = nc;
ws.Url = sOneSubSite +@"/_vti_bin/permissions.asmx";
int iMask = 0x00000001;
ws.AddPermission("Shared Documents","List""Manager""role", iMask);
int iMask2 =0x00000001|0x00000002|0x00000004|0x00000008;
ws.UpdatePermission("Shared Documents","List""Manager""role", iMask2);


[Download Sample]


The SharePoint web services that Microsoft has provided are very powerful. Developers can programmatically do everything with SharePoint sites.