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.

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;
}

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);
ws.AddUserToRole("Manager","",@"us\grant", "","");

Table 1 - SPRights Enumeration

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
 |0x00000001|0x00200000|0x00400000|0x00000200|0x00800000;
ws.UpdatePermission("", "Web","Manager", "role", iMask);

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);

Downloads

[Download Sample]

Conclusion

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