Microsoft SharePoint Portal Server 2001 as a Collaborative Solution Platform
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
Summary: Microsoft SharePoint Portal Server 2001 integrates a flexible Web portal based on Microsoft Digital Dashboard technology, content indexing and search, document management, and a collaborative applications platform. With SharePoint Portal Server, developers with basic or advanced skills can quickly and easily create collaborative solutions. This article looks at the ways you can use Microsoft Web Storage System and the SharePoint Portal Server SDK to extend and enhance SharePoint Portal Server. (52 printed pages)
Introduction: Microsoft SharePoint Portal Server
Concepts and Architecture
Building Collaborative Solutions
Appendix A: Microsoft Web Storage System
Appendix B: SharePoint Portal Server Physical Folder Hierarchy
Appendix C: SharePoint Portal Server Object Model
Appendix D: SharePoint Portal Server Top 10 Programming Tasks
Introduction: Microsoft SharePoint Portal Server 2001
Microsoft® SharePoint™ Portal Server 2001 integrates a flexible Web portal based on Microsoft Digital Dashboard technology, content indexing and search, document management, and a collaborative applications platform. With SharePoint Portal Server, developers with basic or advanced skills can create collaborative solutions.
For Microsoft® Windows® and Microsoft® Office users, SharePoint Portal Server is a portal solution for users to find, share and publish information. SharePoint Portal Server brings together a single solution for corporate portals, document management, and content indexing and searching.
In addition to the benefits of Microsoft Web Storage System as a collaborative solution platform, SharePoint Portal Server has the following benefits for developers:
- Built on the Web Storage System, the Publishing and Knowledge Management Collaboration Data Objects (PKMCDO) object model exposes the unique document management capabilities of SharePoint Portal Server.
- The SharePoint Portal Server dashboard site is Microsoft's first commercial Web Storage System implementation of the Digital Dashboard architecture.
- The SharePoint Portal Server content indexing, search, and retrieval functions are built on top of Microsoft Search technology. These functions are easily accessed through the ADO object model or WebDAV/XMLHTTP search requests.
- SharePoint Portal Server includes a rich set of team collaboration services such as document, folder, and category-based threaded discussions, announcements, and query-based subscriptions and notifications.
- SharePoint Portal Server can be installed in a standalone workgroup or Microsoft Windows NT® or Windows 2000 Active Directory™ domain environment; however, Active Directory is not required since it is with the Microsoft Exchange 2000 Server configuration of the Web Storage System.
SharePoint Portal Server is the solution for developers and end-users that need to deploy the Web Storage System along side Exchange 2000 Server and other messaging and collaboration systems.
Four key principles guided the design and development of the SharePoint Portal Server Web UI, back-end services, and underlying storage architecture.
- Make document management mainstream
- Make it easy-to-use
- Make it easy-to-deploy
- Create a great search experience using the best available technologies
SharePoint Portal Server makes document management accessible and practical for all users by integrating it directly with the user environment.
SharePoint Portal Server achieves ease-of-use through the following:
- Document management features that are directly integrated with Microsoft Windows Explorer and Web Folders using the Client Extensions of SharePoint Portal Server.
- Document management features that are directly integrated with Office through the SharePoint Portal Server COM Add-in and the property promotion features of the Web Storage System
- A Digital dashboard-based Web portal that runs in most popular Web browsers
SharePoint Portal Server is easy to install and requires minimal investment in terms of administration skills and resources because SharePoint Portal Server computers do not have to belong to an Active Directory domain.
To enable the best search experience, SharePoint Portal Server uses the Microsoft Search technology. Microsoft Search makes it easy to index many sources of information: file systems, Web servers, SharePoint Portal Server workspaces, Exchange public folders, Lotus Notes databases, and fax documents in TIFF format. Microsoft Search can be extended to allow developers to include any type of content source or document format for indexing, searching, and retrieval.
Installation of the Windows 2000 Server Service Pack 1 (SP1) is required before beginning to install SharePoint Portal Server. Hardware requirements include a 600MHz+ Intel Pentium III with 256MB RAM and sufficient free disk space to store twice the expected size of the document collection. This allows space for full-text indexes, revisions, and future growth. The indexes and the Web Storage System files consume approximately 95 percent of the required disk space.
From a client perspective, SharePoint Portal Server runs on Windows 2000, Windows NT, and Windows NT 4 using Windows Explorer Web Folder technology. Using the integrated document management features requires Microsoft Office 2000 or later. The SharePoint Portal Server dashboard site performs best using the latest versions of Microsoft Internet Explorer—although it also supports any HTML 3.2 compatible browser. SharePoint Portal Server also includes language support for English (US/UK), French, Spanish, Italian, German, and Japanese.
Concepts and Architecture
The highest-level structure in SharePoint Portal Server is the workspace. A workspace is an organized collection of documents, content sources, management folders, categories, document profiles, subscriptions, and discussions. You can optimize a SharePoint Portal Server computer for three basic types of scenarios:
- Document management
- Searching content
- Indexing content
Document management workspaces are used primarily as repositories for actual content (including Office and other documents, text files, fax images, images, and audio/video). In addition, document management workspaces can also support content indexing, search, and retrieval.
Workspaces dedicated to indexing, called index workspaces, are similar to document management workspaces except that index workspaces do not store any local content. Instead, SharePoint Portal Server builds workspace indexes from content sources that point to external information. External content sources can include the following:
- Other SharePoint Portal Server workspaces
- Intranet or Internet sites
- Exchange 2000 and Exchange 5.5
- Server public folder hierarchies
- Lotus Notes 4.6a+ and R5 databases
- Local file systems
- Networked file servers
Index workspaces typically live on index workspace servers. In this scenario, SharePoint Portal Server crawls content on external content sources and propagates indexes back to one or more document management or dedicated search workspaces. Search workspaces do not store any content locally and are therefore used for searching only. Users can access a workspace through the following methods:
- Microsoft SharePoint Portal Server dashboard site
- Windows Explorer and Web Folders
- Microsoft Office
- Custom-developed solutions
Most users will access SharePoint Portal Server using a Web portal based on the Microsoft Digital Dashboard. Others will use Windows Explorer Web Folders and the client extensions of SharePoint Portal Server. These extensions turn Windows Explorer into a document management client as well as a workspace administration tool. SharePoint Portal Server Web Folders allow users to simply right-click on a document or SharePoint Portal Server workspace folder to access a context-sensitive menu of document management functions. The SharePoint Portal Server COM Add-In for Office provides these same context-sensitive document management functions on the Office File menu. Lastly, custom solutions built using the SharePoint Portal Server object model provide programmatic access to all of the document management, content search, and collaboration functions.
While SharePoint Portal Server can crawl, search, and retrieve content from virtually any content source, the document management functions have been specifically designed and optimized to take advantage of Microsoft Web Storage System.
Microsoft Web Storage System
Microsoft Web Storage System implements a hierarchical folder model for storing any type of unstructured or semi-structured content (e-mail, documents, files, and executables) and then adds support for accessing and updating that content using a rich set of APIs and Internet protocols. The Web Storage System also implements a store-level event model that supports both synchronous and asynchronous processing and a workflow engine.
The Web Storage System is the same server-side storage technology used by Exchange 2000 Server.
A technical description of Microsoft Web Storage System can be found in Appendix A: Microsoft Web Storage System.
Microsoft Web Storage System and SharePoint Portal Server
SharePoint Portal Server also takes advantage of the rich ADO and CDO object models in Web Storage System, as well as its XML, HTTP, and WebDAV Internet protocols and store-level event architecture.
The SharePoint Portal Server dashboard site, document management, content index, search, and collaboration functions can access the Web Storage System using ADO, XML, WebDAV or the MSDAIPP over WebDAV data access methods. MSDAIPP is the Microsoft OLE DB Provider for Internet Publishing. MSDAIPP can use either WebDAV or the FrontPage WEC extensions to access and manipulate remote Web-enabled information sources. Data returned by a WebDAV request can be accessed through the XML Document Object Model (DOM) or as a remote ADO Recordset through the MSDAIPP OLE DB provider.
SharePoint Portal Server Document Management and Microsoft Search processes run on the same server as the underlying Web Storage System.
SharePoint Portal Server implements the document management approval routing and Web folder drag-and-drop functions using Web Storage System store-level events.
SharePoint Portal Server is implemented on top of these core services:
- Web Storage System Information Store process
- Microsoft SharePoint Portal Server Document Management process
- Microsoft Search process
SharePoint Portal Server exposes functionality of the core services through ADO, WebDAV, and the SharePoint Portal Server object model. SharePoint Portal Server also uses secondary services such as the Simple Mail Transport Protocol (SMTP) process.
Microsoft Web Storage System
The Information Store process implements the Web Storage System, which includes an OLE DB provider that allows for data access through either ActiveX Data Objects 2.5 (ADO) or Web Storage System Collaboration Data Objects (CDO).
ADO and CDO are two of the most useful object models for programming SharePoint Portal Server. Generally, you want to use them in read-only mode and use the SharePoint Portal Server object model for tasks that update content or content item properties.
Web Storage System Workflow and SharePoint Portal Server Workspaces
Document management workspaces support a built-in document approval routing and publishing process. As a result, document management workspaces do not support the more general type of workflow that can be implemented using the Workflow Designer for Exchange 2000. However, you can create public folders that live outside of the SharePoint Portal Server workspaces folders. These non-workspace folders can be workflow-enabled using the Workflow Designer in the same way as public folders in Exchange 2000 Server. SharePoint Portal Server workspace folders and non- SharePoint Portal Server public folders are described more fully in Appendix B: SharePoint Portal Server Physical Folder Hierarchy.
The need for Active Directory depends on the requirements of the solution built on top of the Web Storage System. If a workflow solution uses Active Directory directly, or indirectly through the WorkflowSession object ItemReaders and ItemAuthors collections or the GetUserProperty method, Active Directory services are required.
SharePoint Portal Server Document Management
Developers can access SharePoint Portal Server document management functions through the Publishing and Knowledge Management Collaboration Data Objects (PKMCDO). PKMCDO implements and exposes the SharePoint Portal Server object model for developers to program against. PKMCDO extends the functionality in Web Storage System CDO to support SharePoint Portal Server -specific tasks such as document management functions.
The following PKMCDO code samples can be found in Appendix D: SharePoint Portal Server Top 10 Programming Tasks:
- Binding to Items Stored in SharePoint Portal Server Web Storage System
- Creating Enhanced Folders
- Listing Folders and Items
- Reading and Setting Document Properties
- Migrating Content into SharePoint Portal Server
- Publishing and Versioning Documents
A series of code samples for managing schema objects can also be found in Appendix D. The SharePoint Portal Server object model itself is described in Appendix C: SharePoint Portal Server Object Model.
For more information about developing on top of SharePoint Portal Server, see the SharePoint Portal Server SDK.
SharePoint Portal Server uses Microsoft Search technology for crawling, indexing, searching, and retrieving both local content and external content sources.
Microsoft Search was designed without its own object model. Its full-text query capabilities are implemented as extensions to the SQL query language. You can submit these queries through WebDAV using XMLHTTP. In addition, you can execute them against an ADO Connection object connected to a specific Web Storage System folder (or folder hierarchy). The Web Storage System folder can correspond to a SharePoint Portal Server workspace or non-SharePoint Portal Server public folder. Microsoft Search processes these full-text search queries against the appropriate set of workspace full-text and property indexes.
The Microsoft Search service has four main components:
- Index Engine
- Filter Daemon
- Search Engine
The SharePoint Portal Server Gatherer provides a generic mechanism for collecting the contents of a set of Uniform Resource Locators (URLs). The URLs can point to virtually any type of resource on a computer. However, the ability of the Gatherer to process a particular type of content source depends on the presence of a protocol handler that knows how to retrieve the documents or items stored in that content source. SharePoint Portal Server contains protocol handlers for the most common content sources: SharePoint Portal Server workspaces, Web servers, file servers, Exchange 2000 public folders, and Lotus Notes databases.
The contents of the URLs can be gathered as raw text or filtered properties. A simple text document, for instance, is processed as a stream. In contrast, a file system directory has no data, so a stream abstraction is meaningless. A file system directory only has properties, primarily the names of the files in the directory. A filter is used to present those properties to the Gatherer. The Gatherer then treats the file names as links, and gathers the files in the directory. You can implement a filter as part of a protocol handler or as a separate Component Object Model (COM) object. A protocol handler deals with the transport methods of a group of resources (documents). A filter deals with the internal structure of a document. A filter may provide a data stream, metadata, or both. SharePoint Portal Server ships with filters for text files, Office documents, HTML files and TIFF image files. For information about developing your own IFilters for Microsoft Search, see the Platform SDK.
For each URL, the Gatherer makes a series of calls to retrieve data from a particular URL. Next, the Gatherer attempts to instantiate a filter based on the document type. Filters know how to parse a document and extract the metadata and the content data stream.
The Indexer uses a suite of language-dependent word breakers and stemmers to extract words from the content data stream. After filtering out the noise words, the content index is built. Specific linguistic support is available for English (US/UK), French, Spanish, Italian, German, and Japanese. A neutral language word breaker is used to support languages that are not included.
The Search Engine responds to ADO or WebDAV-based SQL search queries and returns the search results as ADO recordsets or WebDAV XML documents, respectively. For both ADO and WebDAV queries, you can use familiar SQL query language syntax. SharePoint Portal Server supports SELECT, LIKE, WHERE, ORDER BY, CONTAINS, FREETEXT, and column aliasing. SharePoint Portal Server does not support JOIN and MAX, MIN, and SUM. In addition, the SCOPE option on the FROM clause can be used to specify whether only the current folder (and no subfolders) should be searched or whether the current folder and all subfolders should be searched. The former is referred to as a SHALLOW search, the latter as DEEP search.
A typical database query follows the following pattern:
SELECT columns FROM table WHERE condition ORDER BY columns
In SharePoint Portal Server the general format is:
SELECT itemproperties FROM folderscope WHERE richtextcondition ORDER BY columns
SELECT "DAV:href" FROM SCOPE ('DEEP TRAVERSAL OF "/mySharePoint Portal Serverworkspace"') WHERE "urn:schemas-microsoft-com:office:office#Author" = 'Stephen King' AND FREETEXT('PennyWise the dancing clown') ORDER BY "urn:schemas.microsoft.com:fulltextqueryinfo:rank"
A developer typically targets three scopes within a workspace: document management workspace folders (and subfolders), external content sources, and the workspace category hierarchy.
Table 1. The three main scope targets
|Target||Example FROM SCOPE Clause|
|Workspace folder (or subfolder)||
|External content source||
|Workspace category hierarchy||
The CONTAINS predicate is part of the WHERE clause, and supports searching for words and phrases from the body text and properties of the indexed documents. The CONTAINS predicate has features for matching the meaning of words, inflectional forms of words, searches using wildcards, proximity searches. You can also apply weights in a CONTAINS predicate, to set the importance of the columns where the search term is found. Examples of the CONTAINS predicate are listed in Table 2.
Table 2. Examples of the CONTAINS predicate
|Word||A single word without spaces or other punctuation. Double-quotes are not necessary.||
|Phrase||Multiple words or including spaces.||
or to use a double quote mark:
|Wildcard||Words or phrases with the asterisk (*) added to the end.||
matches "computer", "computers",
|Boolean||Words, phrases and wildcard strings combined using the Boolean operators AND, OR, and NOT. Enclose the Boolean terms in double quotes.||
|Near||Word, phrase, or wildcard separated by the function NEAR.||
|FormsOf||Matches a word and the inflected versions of that word.||
matches "happy", "happier",
|IsAbout||Combines matching results over multiple word, phrase, or wildcard search terms. Each search term can optionally be given a weight in the range 0.001-1.000. Can optionally specify the rank calculation method, which combines the weights and how many of the items the document matches.||
The FREETEXT predicate is also part of the WHERE clause and supports searching for words and phrases from the body text and properties of the indexed documents. The following example searches for documents containing "computer", "software", "hardware", or combinations of those words:
… WHERE FREETEXT ( 'computer software hardware' )
This example searches for documents containing both the word "computer", and the phrase "software development kit":
… WHERE FREETEXT('computer') AND FREETEXT(' "software development kit" ')
The CONTAINS predicate is more for exact matches than the FREETEXT predicate, which is used more for finding documents containing combinations of search terms spread throughout the document.
The search engine can calculate the rank values, and return them as integers in the range zero to 1000. To make the rank results more meaningful, the query can control how ranks are calculated, and then affect the returned values. Both operations are performed in the RANK BY clause. The RANK BY clause works with either the WEIGHT multiplier clause or the COERCION rank adjustment value. Table 3 provides examples of both.
Table 3. RANK BY using WEIGHT multiplier clause and COERCION rank adjustment values
This example combines both weighting and coercion:
... WHERE( ( CONTAINS(*, '"Index Server" AND "SQL Server"') ) RANK BY ( WEIGHT(0.5), COERCION(MULTIPLY, 0.3) )
Search in the SharePoint Portal Server dashboard site displays three groups of results: Categories, Best Bets, and documents.
For categories, the results match the query by category name or description. Best Bet results are the documents marked manually by a coordinator or author. The rest of the documents are ordered by the ranking calculation.
Additional options allow you to further narrow your search conditions using queries based on specific properties and property values.
The last component of Microsoft Search is its extensible protocol handler architecture. This architecture enables developers to integrate proprietary content information stores into Microsoft Search.
Subscription Management Objects
If you find a document, folder, category, or specific set of search results useful, you can be notified of changes to these items in the future. If the subscriptions feature is enabled in the workspace, you can subscribe to be notified of changes to individual documents, folders, categories, or search results. You can also view notifications on the Subscriptions Summary Web part on the portal home page or on the portal Subscriptions page; you can also choose to be notified by e-mail.
The SharePoint Portal Server Subscription Management object model supports creating, finding, and deleting subscriptions. The SharePoint Portal Server object model for subscription management enables programmatic control over document and folder subscriptions. When the changes occur in subscribed folders or documents, the Persistent Query Service (PQS) sends a notification to the user who subscribed to the changes.
Set oSubMgr = CreateObject("PKM.SubscriptionManager") strSubscriptionUrl = oSubMgr.CreateSubscription( _ strWorkspace, _ ' MyWorkspace strQuery, _ ' CONTAINS(' "monkey" ') 4, _ ' Search 1, _ ' Immediate strEmail, _ ' firstname.lastname@example.org strDescription, _' example 7, _ ' all "" ) ' output parameter ignored
SharePoint Portal Server Discussions and Announcements
In addition to subscriptions, the other categories of collaboration services include support for threaded discussions and announcements.
These are implemented as Web parts in the SharePoint Portal Server dashboard site. Programmatic access to the announcement folders is provided through the standard ADO object model.
Digital Dashboard Services for the SharePoint Portal Server
The SharePoint Portal Server dashboard site uses Microsoft Digital Dashboard technology to create a modular, configurable and extensible user interface for SharePoint Portal Server workspaces. Clients using Web browsers such as Microsoft Internet Explorer can access the document management commands, search, announcements, and other SharePoint Portal Server features using the digital dashboard.
Digital dashboards are applications that run on the Windows 2000 Internet Information Services platform. SharePoint Portal Server digital dashboard Web parts are stored in the Web Storage System as part of the workspace. The coordinator can customize the portal to suit the needs of the business and its users. The coordinator can add custom Web parts into the portal as well as create new workspace dashboards.
Using the Microsoft Digital Dashboard framework and the user interface for portal configuration, programmers or coordinators can modify Web part settings and even add new dashboards and Web parts.
Documentation about Web parts can be found in the SharePoint Portal Server SDK.
SharePoint Portal Server User Experience
A user interacts with a SharePoint Portal Server workspace in three primary ways:
- Through the SharePoint Portal Server dashboard site
- Using the client extensions of SharePoint Portal Server for Windows Explorer and Web folders
- Using the SharePoint Portal Server Office add-in
This section describes some of the user interface elements that are shared across the three primary user interfaces and details each client user interface.
Shared User Interface Elements
There are a number of shared user interface elements common to the three ways users can access the SharePoint Portal Server document library. These include:
- SharePoint Portal Server Document Properties dialog
- SharePoint Portal Server Document Edit Profile dialog
The Document Properties dialog is used to display basic document property, profile information, version history, and security settings as well as the document's category information. The different views of the Document Properties dialog for an AVI stream video are shown in the following figures.
Document profile properties can be saved for any type of digital file.
Figure 1. SharePoint Portal Server Document Properties dialogs (part 1 of 3)
Figure 2. SharePoint Portal Server Document Properties dialogs (part 2 of 3)
Figure 3. SharePoint Portal Server Document Properties dialogs (part 3 of 3)
If the document is an Office document, the Web Storage System automatically promotes the Office document properties to become Web Storage System item properties. Selecting Edit Profile from the context-sensitive document management menus causes the following dialog to be displayed.
Figure 4. Sample SharePoint Portal Server Document Profile Properties
In the Properties dialog for the document profile, the user can update the version comments, select a new profile template as well as provide the values for the template's profile properties. All of these profile properties are stored as item properties in the Web Storage System where they can be searched and accessed with ADO.
SharePoint Portal Server Dashboard Site
The SharePoint Portal Server Web user interface is referred to as the SharePoint Portal Server dashboard site. The SharePoint Portal Server dashboard site is the premier Web Storage System implementation of the Microsoft Digital Dashboard architecture. Each page in the dashboard site is a sub-dashboard composed of one or more Web parts. Each Web part implements a basic workspace function such as running a search query, displaying the search results, browsing the hierarchy of document folders, displaying the list of documents in a folder, and so forth. A Web part either implements the workspace function using the PKMCDO, CDO, or ADO object models or calls a back-end service such as those exposed by the Microsoft Document Management or Microsoft Search processes.
The SharePoint Portal Server dashboard site performs best using the latest versions of Internet Explorer, although it also supports any HTML 3.2-compatible browser.
A user can also access a workspace using Windows Explorer (together with Windows Web Folders and the client extensions of SharePoint Portal Server). Additional administration functions are available through the Windows Explorer Web Folders user interface. Windows Explorer Web Folders provide direct access to the workspace's support and administration folders.
The SharePoint Portal Server COM Add-in for Office integrates the SharePoint Portal Server document management functions as additional menu items in Microsoft Word, Microsoft Excel and Microsoft PowerPoint®.
SharePoint Portal Server supports both the Microsoft FrontPage® WEC Extensions and Office Server Extensions protocols. The Office COM Add-in integration uses the Web Storage System's native WebDAV to support SharePoint Portal Server document management functions from the Office applications.
Security is essential for both document management tasks and the search function. In document management, it is important to restrict access to sensitive information. In document approval scenarios, it is important to restrict the viewing of a document to those who can edit or approve it until it is ready for a larger audience. For search, it is important that SharePoint Portal Server recognize security settings for crawled content so that users viewing the results of searches cannot see documents to which they have no access.
SharePoint Portal Server recognizes any security policies currently assigned to your organization's servers, file shares, and databases. For example, when SharePoint Portal Server crawls documents stored on your organization's servers, the security policy on each document is upheld when SharePoint Portal Server provides search results.
Role-Based Security Architecture
Assigning a role to a user gives that user permission to perform specific tasks. For example, a user assigned to the SharePoint Portal Server author role has permission to add new documents to a folder, edit all documents in the folder, delete any document from the folder, and read all documents in the folder.
SharePoint Portal Server uses a fixed set of three roles to offer a secure method for controlling user access to workspace documents. You cannot modify role permissions. Although roles can be set at the workspace level, they are usually set at the folder level. In addition, you can completely deny a user or users access to a specific document.
The SharePoint Portal Server role-based security architecture includes the following roles:
A reader can search for and read documents but cannot add them to the workspace. All folder users have reader permissions by default. In an enhanced folder, readers can only view folders and published versions of documents. A reader cannot check out, edit, or delete workspace documents and cannot view draft document versions. When the workspace is created, SharePoint Portal Server assigns the Windows 2000 Everyone group to the reader role for all folders in the workspace.
An author can add new documents to a folder, edit all documents in the folder, delete any document from the folder, and read all documents in the folder. In an enhanced folder, authors can also submit a document for publishing. An author can create, rename, and delete folders. When a new folder is created, the roles and folder policies are inherited from the parent folder. However, the author cannot change the roles or the approval policy on folders he or she creates.
A coordinator on the workspace node manages content in the top-level folder and performs a set of workspace administration tasks. These tasks include managing content sources, document profiles, categories, and subscriptions, and customizing the portal. The coordinator creates indexes of updated content when necessary or schedules this to occur automatically. SharePoint Portal Server automatically assigns the administrator who creates the workspace to the coordinator role on the workspace node and on each folder. A coordinator on a specific folder configures user roles for the folder. The coordinator creates subfolders as well as adds, edits, and deletes documents from them. Coordinators can also read and delete a document that has been created but is not yet checked in. For enhanced folders, the coordinator selects the appropriate approval process. In addition, the coordinator can undo the check out of a document or end the publishing process by using the Cancel Publishing or Approve Now actions.
SharePoint Portal Server provides the Deny Access security option on documents only. This setting supersedes all access permissions except those of the local Administrators group. You can deny access to a document for a specific user or group if you do not want that user or group to view that document. Denying access to a document does not affect the local Administrators group's access to that document.
Additionally, SharePoint Portal Server includes a set of folders to support workspace management functions: the Management, Portal, System, Shadow, and Categories folders and their subfolders. A user must be assigned to the coordinator role on the workspace node in order to manage these folders. You cannot directly specify security on these folders, and these folders are generally not exposed to the end-user.
The Windows 2000 local Administrators group has permission to read documents and configure security on any folder or document in a workspace. The ability to configure security provides a way to access every folder in the event that through accident or malicious intent, the folder is made unavailable to those who should have access to it. The local Administrators group can restore permissions for individual folders. Denying access to a document does not affect the local Administrators group's access to that document.
Users Can Have More Than One Role
A user can have different roles for different folders in the same workspace. For example, in one folder a user may have reader permissions only, while in another folder, the same user may have author permissions.
You can give groups of users access to folders in the workspace as though they were a single user by assigning the group to a role, such as reader. If you assign an individual user to more than one role in a folder (as a member of a group and as an individual), the most permissive combination of rights takes precedence. However, you can also deny a user or group access to a specific document, which would supersede all other permissions associated with roles. Because you can deny access to a particular document, a user can have one role on a folder but have no access to a document within the same folder.
If you are an administrator on the SharePoint Portal Server computer, you can assign users to roles on the workspace node by using the SharePoint Portal Server console in Microsoft Management Console (MMC). In addition, SharePoint Portal Server automatically assigns the administrator who creates the workspace to the coordinator role on the workspace node and on each folder.
The Windows 2000 local Administrators group has permission to read documents and configure security on any folder or document in a workspace. Denying access to a document does not affect the local Administrators group's access to that document.
As a SharePoint Portal Server computer administrator, you manage roles on the workspace node by using SharePoint Portal Server console in MMC on the SharePoint Portal Server computer. If you have coordinator permissions on the SharePoint Portal Server workspace node, you can assign users to roles on the workspace node and on any individual workspace folder that inherits its security setting from the node. In addition, a user must be assigned to the coordinator role on the workspace node in order to manage the set of folders that support workspace management functions. The security settings can also be managed in each workspace's Management Web folder.
As a coordinator, you manage roles at the folder and document level by using the folder or document properties pages in the workspace. To do so, you must have the client components of SharePoint Portal Server installed on your computer with Windows 2000. Microsoft Windows NT and Windows NT version 4.0 users cannot manage SharePoint Portal Server roles.
SharePoint Portal Server Security and the Web Storage System Installable File System (IFS) Driver
The SharePoint Portal Server role-based security model is only enforceable when the underlying Web Storage System is accessed through the ADO and CDO object models or through the WebDAV Internet protocol. Accessing the Web Storage System using Installable File System (IFS) bypasses the SharePoint Portal Server role-based security mechanisms. The IFS driver typically presents the hierarchical folder store as a hierarchical file mounted as the M: drive (Note that by default the M: drive mapping is disabled. For information on mapping the M: drive see Appendix A: Microsoft Web Storage System). Therefore, the server must be secured with respect to local physical access as well as network and terminal services access.
The following diagram depicts three ways a user can access and interact with a SharePoint Portal Server workspace (in particular, the enhanced Documents folder): SharePoint Portal Server dashboard site, the client extensions of SharePoint Portal Server for Windows Explorer Web Folders, and through the Office COM Add-in.
Figure 5. The client applications of SharePoint Portal Server
The back-end store-level event sink (PKM Event) that supports SharePoint Portal Server document approval routing as well as the Web Folder drag and drop function is depicted in Figure 6. The Information Store process manages the folder hierarchy and contents (folder items) in the Web Storage System. The SharePoint Portal Server Document Management and Microsoft Search processes provide their respective services to the client components of SharePoint Portal Server.
Figure 6. SharePoint Portal Server architecture: back-end PKM event sink
Building Collaborative Solutions
Collaborative applications can be built three ways using SharePoint Portal Server:
- Within an existing SharePoint Portal Server workspace.
- Within a non-SharePoint Portal Server Public Folder on a SharePoint Portal Server computer. (For example, outside of the SharePoint Portal Server Applications and workspaces folder hierarchies.)
- As a non-SharePoint Portal Server, non-Web Storage System application that needs to programmatically integrate with an existing SharePoint Portal Server or non-SharePoint Portal Server Web Storage System application
Aside from the coordinator's ability to customize the content and layout of the SharePoint Portal Server dashboard site using the digital dashboards and Web parts that accompany SharePoint Portal Server, developers can provide additional customization by developing their own Web parts.
To create a new customized function in SharePoint Portal Server requires consideration of the following:
- What changes, if any, are required to the interface from the perspective of a SharePoint Portal Server dashboard site user to deliver the end-user functionality?
- Which SharePoint Portal Server services can be used to support the new functionality?
- What are the SharePoint Portal Server folder requirements or other information storage requirements needed to deliver the new functionality?
To implement the customized functionality usually requires creating a new Web part that then calls the SharePoint Portal Server back-end services to provide the required results. In addition, a Web part can call any service running on that server, another server, or through custom Microsoft® .NET Web Services running on a Web site across the Internet. Although it is possible to re-use and extend some of the Web parts that accompany SharePoint Portal Server, this must be done carefully.
When the new functionality uses SharePoint Portal Server folders (folders in the SharePoint Portal Server Applications or workspaces folder hierarchies), it is critical that the new functionality not configure any of its own store-level event sinks or Workflow Designer event logic. Solutions that require this type of functionality must implement it outside the SharePoint Portal Server workspace hierarchy.
This also applies to reusing SharePoint Portal Server schema (also known as content classes). It is recommended that the new solutions use their own solution-specific content classes—derived from the underlying Web Storage System or SharePoint Portal Server content classes where possible.
An example of this type of enhanced functionality would be a new version of the Announcement Web part that allows user to submit their own announcements items and to have the submission process be managed by the SharePoint Portal Server document management check in, approval routing, and publish functions. To implement this Web part, a brand-new Web part would be created (Perhaps modeled after the existing Announcement Web part.). The role of the Web part would display only those announcement items that have been approved for publishing. In addition, the Web part could also have a link to a Web Storage System Form that allows users to easily create new or edit announcement items. Alternatively, users could be asked to create their announcements using Word and save them using a custom document profile. The document profile would capture the properties that are important to announcement items. From a storage perspective, these items would have to live in their own enhanced document management subfolder (separate from the default Announcement folder that are created when a user creates a new workspace). Document approval routing would be enabled to insure new announcements were approved before they appeared in the new Web part. The Web part would only display those announcements whose status is published (meaning they had been approved).
Building New Non-SharePoint Portal Server Public Folder Applications
In the same way that collaborative solutions can be built on the Web Storage System used by Exchange 2000 Server, applications can be built using the Web Storage System provided with SharePoint Portal Server.
The Web Storage System includes the forms registry and the forms renderer. The forms renderer creates the user interface. Alternatively, the non-SharePoint Portal Server public folder application could be displayed as a Web part. In this case, the Web part definition lives under the portal subfolder of the workspaces where it is used. The content and event sink registrations reside in a non-SharePoint Portal Server public folder.
A Web part can make use of any database, directory service, or SharePoint Portal Server service. In addition, a Web part can use any other application service running on the SharePoint Portal Server computer or another server within the domain. Web parts can also draw upon any custom .NET Web Service running on a Web site across the Internet.
Integrating SharePoint Portal Server Functionality into External Applications
The last scenario is where a new or existing non-SharePoint Portal Server, non-Web Storage System application wants to use the SharePoint Portal Server document management or index and search functions. This common scenario is easy to design and implement using any of the available object models or Internet protocols: PKMCDO, CDO, ADO, and WebDAV.
PKMCDO reveals virtually all of the SharePoint Portal Server document management functions including the ability to create standard and enhanced folders, check in, check out, and publish documents.
The IFilter object model allows the Indexer to read and parse any document format.
SharePoint Portal Server is a Web portal and new platform for document management and enterprise indexing and search and collaboration. SharePoint Portal Server enables developers, with basic or advanced skills, to create collaborative end-user solutions easily and quickly.
Of particular value to collaborative-solution architects and developers is the Web Storage System upon which SharePoint Portal Server is built. Easy to deploy, a SharePoint Portal Server computer does not need to belong to an Active Directory domain. The Web Storage System provides a flexible platform for building new document-based, workflow-enabled collaborative Web solutions.
This paper would not have been possible without the support of the entire SharePoint Portal Server Product Group and the significant contributions from Brian Murphy, Owen Braun, Tali Weil, Kelly Bowen, Thomas Rizzo, Lyle Curry, Jeff Wierer, Bill Skilton, and the Microsoft EC3 Enterprise Consulting Competency Centers team.
Appendix A: Microsoft Web Storage System
The Web Storage System implements a hierarchical folder model for storing any type of unstructured or semi-structured content (e-mail, documents, files, and executables). It adds support for accessing and updating that content via a rich set of APIs and Internet protocols. The support includes an event model that supports both synchronous and asynchronous processing and a workflow engine.
The Web Storage System is the server-side information store used by Exchange 2000 Server and SharePoint Portal Server.
The Web Storage System supports the following APIs and Internet protocols:
- Client access protocols: HTTP and WebDAV as well as the FrontPage and Office Server Extensions protocols. Exchange 2000 Server adds the following additional client access protocols to the Web Storage System: MAPI, POP3, and IMAP4.
- Data access APIs: ADO 2.5 and Web Storage System CDO. Exchange 2000 Server MAPI support also enables support for CDO 1.2 for backward compatibility.
- Installable file system (IFS) driver allows you to access folders, subfolders and items in the Web Storage System hierarchical folder store as a hierarchical file system mounted as the M: drive. By default the M: mapping is disabled. You can enable the drive mapping for a single session by typing 'subst m: \\.\backofficestorage' at the command line. To permanently enable a drive mapping you will need to make the following change to the registry.
Value: DriveLetter = M
Web Storage System IFS folders can be shared like normal file system folders and accessed using the traditional SMB network file-sharing protocol. Caution should be used when sharing out the m: drive as considerable damage can be done by incorrectly modifying workspace folders.
With this set of APIs and Internet protocols, Exchange 2000 Server, and Microsoft Web Storage System is a powerful collaborative solutions platform for delivering automated business solutions.
Exchange 2000 Server and SharePoint Portal Server System Configurations
Microsoft's newest messaging and collaboration products use a common storage solution: Microsoft Web Storage System. The Web Storage System that accompanies Exchange 2000 Server supports additional messaging protocols (for example, MAPI). It also supports multiple storage groups (maximum of four for Exchange 2000 Server) and multiple databases per storage group (maximum of five per storage group for Exchange 2000 Server). The Web Storage System is extremely scalable with a storage capacity of up to 16 terabytes. It is only limited by the server's virtual memory, physical memory, hard disk storage available on the server, and any product specific configuration parameters. The Web Storage System in an Exchange 2000 Server configuration is depicted in Figure 7.
Figure 7. Web Storage System: Exchange 2000 Server configuration
Microsoft SharePoint Portal Server automatically installs the Web Storage System. SharePoint Portal Server runs equally well in a Windows NT or Active Directory domain environment and as a standalone server.
SharePoint Portal Server does not require Active Directory services. Whether Active Directory is required or not depends on the requirements of the solution built on top of the Web Storage System. If a workflow solution uses Active Directory directly, or indirectly through the WorkflowSession object ItemReaders and ItemAuthors collections or the GetUserProperty method, Active Directory services are obviously required.
Regardless of the configuration, the Web Storage System supports the same ADO and Microsoft Search functionality, store event model, workflow engine, Web Storage System forms model, XML, WebDAV, and HTTP support. The Web Storage System in a SharePoint Portal Server computer configuration is depicted in Figure 8.
The Microsoft Search protocol handler enables full-text indexing, searching, and retrieval of Web Storage System public folder items. The Microsoft Search protocol handler included with Exchange 2000 Server also included with SharePoint Portal Server.
SharePoint Portal Server does not include some of the legacy messaging APIs (MAPI, for example).
Figure 8. Web Storage System: Microsoft SharePoint Portal Server configuration
Hierarchical Object Store
A developer can use a Web Storage System folder as a database table with a dynamically extensible, flexible schema, a hierarchical file system, or a hierarchical object store. The key to understanding these different perspectives is to understand the basics about folders, subfolders, items and properties. For most people, their understanding of the Web Storage System's concepts of a folder and an item are based on the lists and forms that are presented to them by Microsoft Outlook® 2000 or a similar personal information manager. It is important to understand these concepts at a more basic level.
In the Web Storage System, a hierarchy of folders, starting with the hierarchy's top-most folder, is called a Top Level Hierarchy (or TLH). You use a Web Storage System folder to store a collection of items. An item has a list of properties associated with it. A property is a simple name=value pair where the value may be single or multi-valued. The name of the property is qualified by the XML namespace it belongs to (for example, DAV:, or urn:content-classes: ). You can retrieve the list of items and their properties as an ADO Recordset or WebDAV XML document. This is what makes a Web Storage System folder look like a database table.
In addition, each item in a folder is not restricted to having the exact same set of properties as the other items in the folder. It is possible to dynamically add a property to any individual item—independent of the other items in the folder.
Figure 9. Web Storage System: folders, items, and properties
Certain properties have special well-defined meanings and importance. One key property is the Boolean property DAV:isfolder. The isfolder property determines whether an item is a simple item or represents a collection (or subfolder) of additional items. This is how the Web Storage System hierarchical folder store is implemented—that is, some items in a folder have an isfolder property value of True implying the item is a logical subfolder. The ADO GetChildren method can then be called on this item's Record object to return the list of items in the subfolder.
The Web Storage System assigns each item a unique friendly URL. The Web Storage System uses this URL to identify and access the item and its properties. For items in private mailboxes, the format of the URL is:
For items that live under a TLH, the format is:
An item can also be any document including an e-mail message, calendar appointment, contact, any Office document, an HTML page, ASP page, XML document, or audio or video stream, for example. Let us look at some more real-life examples.
The URL for an e-mail message sitting in my personal Inbox might appear as:
The URL for a contact item in a public folder might appear as:
Items and Content Classes as Ready-To-Use Web Storage Objects
Another key item property is DAV:contentclass. Most applications and services including Exchange 2000 Server and SharePoint Portal Server use the contentclass property of an item to determine the type of object that item represents. For example, a contentclass value of urn:content-classes:message implies that the item is an e-mail message. Therefore, its properties are chosen from those appropriate for an e-mail message. Other important contentclasses include urn:content-classes:appointment, urn:content-classes:person and urn:schemas-microsoft-com:exchange:workflowprocessdefinition. Person is the contentclass value used for Contact items. The Web Storage System provides schema and property definitions for more than 30 common object contentclasses. Like property names, contentclass names are also qualified by the XML namespace they belong to. They can belong to either one of the intrinsic Web Storage System namespaces or your own custom application or organization-specific namespace.
MAPI-based applications such as Outlook 2000 maintain a similar item property known as the PR_MESSAGE_CLASS (also known as http://schemas.microsoft.com/exchange/outlookmessageclass). Client applications can use the contentclass property to determine how an item (and its list of properties) should be displayed to the user. If the contentclass is person, then OWA 2000 renders the item as a Contact using HTML, while Outlook 2000 uses a built-in Outlook Contact form to display the item's properties. In the Outlook 2000 example, the equivalent PR_MESSAGE_CLASS value is IPM.Contact. To have OWA 2000 and Outlook 2000 forms behave properly for the same set of contact items, both the contentclass and PR_MESSAGE_CLASS property values have to be set appropriately.
As far as Exchange 2000 Server and the Web Storage System is concerned, the content of a folder is simply a list of items. Each item has its own list of associated properties. In addition, some items may have the isfolder property set to True indicating that they are subfolders of additional items.
To avoid pandemonium, contentclass names are also used to name XML-based schema items called content class definitions. Content class definitions define a list of properties that are expected for a particular class of object in the folder store. The way a client application chooses to display an item is totally up to that application (and normal usage conventions). An item's contentclass property simply provides the name of the item's object class. The properties expected for a particular object are found in its content class definition.
It is also possible to derive new solution-specific contentclass schema from the intrinsic contentclasses or create brand-new contentclasses from scratch. As you have likely guessed, schema and property definitions themselves are simply items that have their own special contentclasses: urn:content-classes:contentclassdef and urn:content-classes:propertydef. Most applications are expected to create their own schema folder that is global only to the instances of that particular solution.
ADO or WebDAV? It's Your Choice
In addition to directly accessing items or objects in the Web Storage System using their URLs, queries can also be executed against the folder store. Regardless of whether you choose to use SQL queries through ADO or WebDAV, the same underlying query processor processes them all. Because the Web Storage System OLE DB provider is not natively remotable, applications that use ADO with the Web Storage System OLE DB provider must run on the same server as the Web Storage System. WebDAV is the recommended protocol from a performance perspective.
For developers familiar with ADO, there is a provider known as the OLE DB Provider for Internet Publishing (MSDAIPP). MSDAIPP runs on top of WebDAV as well as the FrontPage WEC protocols. The FrontPage WEC protocols support remote ADO connections.
WebDAV is a set of extensions to HTTP (which is by definition remotable). With WebDAV, the parameters of the extended requests are formatted as XML documents. The query processor executes the query against the folder store. It then returns the results as an XML document to the requesting application.
For both ADO and WebDAV queries, familiar SQL query language syntax can be used. SELECT *, LIKE, WHERE, ORDER BY, GROUP BY, CONTAINS, FREETEXT, and column aliasing are supported; JOIN and MAX, MIN, and SUM are not. In addition, you can use the SCOPE option on the FROM clause to designate the search level as SHALLOW or DEEP. A SHALLOW search includes only the current folder (and no subfolders) in the search scope. A DEEP search includes the current folder and all subfolders in the search scope. For example:
SELECT Name, WorkPhone, CellPhone FROM SCOPE('DEEP TRAVERSAL OF "<folder URL>"')
Extending Web Storage System Functionality
You can develop many types of solutions using the data access methods described above. However, you may need to extend the functionality of the Web Storage System frequently. You can accomplish this through two mechanisms: a) traditional middle-tier components (referred to here as front-end Web service components), and b) event-driven back-end components.
Front-End Web Service Components
Developers can use middle-tier or front-end Web service components to wrap any of the intrinsic or custom objects in the folder store with additional functionality. In the case of a Web Service, you may use this approach to expose the capabilities of a class or group of classes as a .NET Web Service.
Event-Driven Back-end Components
While you can use middle-tier components to enforce business rules, they only apply to those applications that actually call the middle-tier components. A more effective approach is to use event-driven back-end components.
Any change to an item in the Web Storage System (whether it be to a simple item or a folder) can cause an event to be raised. When a store event is raised, developers can specify whether they would like a custom event sink function to be executed or not. In the Exchange 2000 Server version of the Web Storage System, event sinks are implemented as COM+ or scripted components.
When an event sink is registered for a particular event in a particular folder, the Web Storage System passes an event information structure. The event information structure includes an ADO record for the item that was created, changed, or deleted. In addition, event sink registrations stipulate whether the sink is to be executed synchronously or asynchronously relative to the change being made to the item.
Workflow-Enabling Web Storage Objects
In addition to being able to develop the store-level event sinks mentioned above, the Web Storage System workflow engine and the Workflow Designer for Exchange 2000 Server work together to implement a higher-level set of workflow event services.
The Web Storage System implements the workflow engine as a COM+ component. This provides inherent performance and manageability advantages. In addition to the role-based security model for folder and item security, the Web Storage System takes advantage of the role-based security model of COM+ to determine who is able to workflow-enable the Web Storage System objects in a particular folder.
The workflow engine is invoked when the low-level store events are triggered. The engine is called whenever a change occurs in a workflow-enabled folder. When creating workflows with the Workflow Designer, developers are presented with an easy–to-use workflow action model.
Workflow Designer for Exchange 2000 Server
The Workflow Designer for Exchange 2000 Server is a visual designer for workflow-enabling Web Storage System folders and items. It is included as part Microsoft Office 2000 Developer Edition. You use the design surface for drawing state-transition diagrams representing a business process. The Workflow Designer allows you to use Microsoft Visual Basic® Script to build conditions and action scripts that control how an item can move through a workflow process. You can execute the Visual Basic Script action script to access some external functionality such as sending an e-mail notification or integrating with the capabilities of the Microsoft BizTalk™ Server .NET orchestration process.
Appendix B: SharePoint Portal Server Physical Folder Hierarchy
The Web Storage System installed with SharePoint Portal Server has one storage group containing one database. The single database is used to create one Top-Level Hierarchy called SharePoint Portal Server with a domain name of localhost. The following sections detail the different types of folders that SharePoint Portal Server creates underneath the SharePoint Portal Server top-level hierarchy. This folder can be accessed by a number of different protocols as depicted in Table 4.
SharePoint Portal Server Root Folder
Table 4. M:\localhost\ SharePoint Portal Server Root Folder
|Protocol||Pathname / URL|
|Drive letter and folder pathname||
* Using localhost may require that you configure the host headers for your vroot to accept the name "localhost"
In the Internet Services Manager, two IIS virtual roots called Public and SharePoint Portal Server are mapped to \\.\backofficestorage\localhost\SharePoint Portal Server.
Workspaces Root Folder
The workspaces root folder contains a subfolder for each created workspace. These individual subfolders are called workspace (singular) folders. SharePoint Portal Server names each subfolder using the workspace name entered by the administrator when the workspace was created.
The workspaces root folder is hidden; it cannot be seen in Outlook Web Access or a Web Folder.
One workspace folder exists for each workspace created by a coordinator. The workspace folder name is the same as the workspace name.
In addition, the workspace folder is mapped to an IIS virtual root with the same workspace name. This allows the workspace folder to be accessed as http://servername/workspacename.
A workspace folder contains a number of SharePoint Portal Server-defined subfolders that include Categories, Documents, Portal, SHADOW, system/schema, and System Categories.
Each workspace folder has an item property called urn:schemas-microsoft-com:publishing:applications-root. This item property holds the relative link to the applications folder (such as /SharePoint Portal Server/Applications/EC3).
Workspace Categories Folder
The Categories folder for each workspace implements a hierarchy of Web Storage System search folders. The hierarchy implements the SharePoint Portal Server category browser functionality.
You can create a category hierarchy by navigating to the Categories subfolder. In the Categories subfolder, you can choose to add a main category or move to where the new category is to be added. Right-click in the right pane, point to New and click Category. The Categories folder always presents a hierarchical view of the category hierarchy. A flattened list of all the categories can be found in the workspace System Categories folder.
Workspace Documents Folder
When a new workspace is created, a new default enhanced folder is created in the workspace folder called the Documents folder. Managed documents can be created, checked in, checked out, published and deleted from this folder or from a hierarchy of subfolders created beneath the Documents folder. Subfolders can be designated as enhanced or standard folders. A new subfolder inherits the properties of its parent by default. As long as a folder is empty, you can change its folder properties from enhanced to standard and visa versa.
SharePoint Portal Server automatically includes the contents of the Documents folder and subfolders when crawling and building an index for the workspace.
Workspace Portal Folder
The workspace Portal folder contains all of the Web forms, schema, and form registrations for the portal Web UI based on the Microsoft Digital Dashboard architecture.
Beneath the workspace Portal folder, SharePoint Portal Server creates a subfolder for each digital dashboard in the portal Web UI. These include Categories, Document Library, Management, Search, and Subscriptions by default. SharePoint Portal Server uses the Portal resources subfolder to store the actual Web content for each Web part.
Workspace SHADOW Hidden Folder
The workspace SHADOW folder mirrors the Documents folder for a given workspace. This is where the major and minor versions of a document live. This folder includes working copies, the last approved version, the last unapproved version, and versions that exist during the publishing process. For example:
Newly created document into the workspace Documents folder (for example, abc.doc) has an initial status of Checked-Out:
M:\localhost\SharePoint Portal Server\workspaces\EC3\Documents\abc.doc
When the document is subsequently checked in, a minor version of the document (0.1) appears in the workspace SHADOW folder:
M:\localhost\SharePoint Portal Server\workspaces\EC3\SHADOW\Documents\abc(0.1).doc M:\localhost\SharePoint Portal Server\workspaces\EC3\Documents\abc.doc
When the document is then published, a major version of the document (1.0) appears in the workspace SHADOW folder. The most current version is always available in the Documents folder (or subfolder) for that workspace.
M:\localhost\SharePoint Portal Server\workspaces\EC3\SHADOW\Documents\abc(0.1).doc M:\localhost\SharePoint Portal Server\workspaces\EC3\SHADOW\Documents\abc(1.0).doc M:\localhost\SharePoint Portal Server\workspaces\EC3\Documents\abc.doc
Workspace System/Schema Folder
SharePoint Portal Server uses this hidden folder to store the remaining SharePoint Portal Server-specific schema and forms registrations. The schema and forms registrations found in the workspace System/Schema folder are specific to that workspace. When a workspace is created, it receives its own copy of these items.
Workspace System Categories Folder
The hidden workspace System Categories folder always presents a flattened list of the category names found in the hierarchical workspace Categories folder.
Applications Root Folder
This SharePoint Portal Server-specific folder contains a subfolder named for each SharePoint Portal Server workspace created on the server.
When a workspace folder is created, the new Applications subfolder is automatically added to the list of folders to be searched and indexed for this workspace.
Non-SharePoint Portal Server Public Folders
In addition to the workspaces and Applications folders that live under the SharePoint Portal Server root, developers are free to create their own application folders directly under the SharePoint Portal Server folder. To create a non-SharePoint Portal Server public folder, the user must be a local administrator for the server and then set the appropriate access permissions once the new folder and subfolders have been created.
The folders created under the SharePoint Portal Server root folder do not interfere with the SharePoint Portal Server workspaces and Applications root folders or subfolders. You can register custom store event sinks and Web Storage System forms against the non-SharePoint Portal Server subfolders. In addition, you can use the Workflow Designer for Exchange 2000 to workflow-enable these folders. Custom store events and the Workflow Designer should not be used with the SharePoint Portal Server should not be used within workspaces, but can be used in the Application folder space.
Typical Folder List for a New SharePoint Portal Server Workspace
When a new workspace is created (ec3), a new folder bearing the same name as the workspace is created under the Applications public folder as well as under the workspaces public folder.
M:\localhost M:\localhost\SharePoint Portal Server M:\localhost\SharePoint Portal Server\Applications M:\localhost\SharePoint Portal Server\Applications\ec3 M:\localhost\SharePoint Portal Server\workspaces\ec3 M:\localhost\SharePoint Portal Server\workspaces\ec3\_TEMP_ M:\localhost\SharePoint Portal Server\workspaces\ec3\Categories M:\localhost\SharePoint Portal Server\workspaces\ec3\Categories\Cat 1 M:\localhost\SharePoint Portal Server\workspaces\ec3\Categories\Cat 1\Cat 4 M:\localhost\SharePoint Portal Server\workspaces\ec3\Categories\Cat 1\Cat 5 M:\localhost\SharePoint Portal Server\workspaces\ec3\Categories\Cat 2 M:\localhost\SharePoint Portal Server\workspaces\ec3\Categories\Cat 3 M:\localhost\SharePoint Portal Server\workspaces\ec3\Documents M:\localhost\SharePoint Portal Server\workspaces\ec3\Management M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal Content M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal\Categories M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal\Document Library M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal\Management M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal\resources M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal\Search M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal\Subscriptions M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal Content\Announcements M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal Content\News M:\localhost\SharePoint Portal Server\workspaces\ec3\Portal Content\Quick Links M:\localhost\SharePoint Portal Server\workspaces\ec3\SHADOW M:\localhost\SharePoint Portal Server\workspaces\ec3\SHADOW\Documents M:\localhost\SharePoint Portal Server\workspaces\ec3\system M:\localhost\SharePoint Portal Server\workspaces\ec3\system\Discussions M:\localhost\SharePoint Portal Server\workspaces\ec3\system\Forms M:\localhost\SharePoint Portal Server\workspaces\ec3\system\OBE M:\localhost\SharePoint Portal Server\workspaces\ec3\system\schema M:\localhost\SharePoint Portal Server\workspaces\ec3\system\Subscriptions M:\localhost\SharePoint Portal Server\workspaces\ec3\system\Tour M:\localhost\SharePoint Portal Server\workspaces\ec3\system\Users M:\localhost\SharePoint Portal Server\workspaces\ec3\System Categories M:\localhost\SharePoint Portal Server\workspaces\ec3\System Categories\Cat 1 M:\localhost\SharePoint Portal Server\workspaces\ec3\System Categories\Cat 2 M:\localhost\SharePoint Portal Server\workspaces\ec3\System Categories\Cat 3 M:\localhost\SharePoint Portal Server\workspaces\ec3\System Categories\Cat 4 M:\localhost\SharePoint Portal Server\workspaces\ec3\System Categories\Cat 5 M:\localhost\SharePoint Portal Server\workspaces\PubModels M:\localhost\SharePoint Portal Server\workspaces\PubModels\Auto M:\localhost\SharePoint Portal Server\workspaces\PubModels\Default M:\localhost\SharePoint Portal Server\workspaces\PubModels\Parallel1 M:\localhost\SharePoint Portal Server\workspaces\PubModels\Serial M:\localhost\SharePoint Portal Server\workspaces\selectors M:\localhost\SharePoint Portal Server\workspaces\system M:\localhost\SharePoint Portal Server\workspaces\system\All Discussions M:\localhost\SharePoint Portal Server\workspaces\system\Discussions M:\localhost\SharePoint Portal Server\workspaces\system\schema
Appendix C: SharePoint Portal Server Object Model
For more information about the SharePoint Portal Server object model, download the SharePoint Portal Server SDK.
Table 5. COM Class and Document Management Functions
|COM Class||SharePoint Portal Server Document Management Functions|
|KnowledgeServer||The KnowledgeServer object is the primary mechanism for creating and organizing document workspaces. The KnowledgeServer object provides methods for creating, deleting, and enumerating KnowledgeWorkspaces.|
|KnowledgeWorkspace||The KnowledgeWorkspace object represents a SharePoint Portal Server knowledge workspace. A knowledge workspace contains content-class and property definitions as well as the root categories folder and the root documents folder.|
|KnowledgeFolder||The KnowledgeFolder object represents a SharePoint Portal Server folder. In addition to adding documents, you can add other items to a knowledge folder, including property definitions and dictionaries. A knowledge workspace (KnowledgeWorkspace object) contains the root knowledge folder.|
|KnowledgeCategoryFolder||KnowledgeCategoryFolder objects represent the Category folders in the SharePoint Portal Server folder hierarchy. The KnowledgeCategoryFolder object is a specialization of the KnowledgeFolder object. The KnowledgeFolder object provides a mechanism for the physical organization of content, whereas the KnowledgeCategoryFolder object provides mechanisms for the logical organization of content. KnowledgeFolder objects deal with content storage. KnowledgeCategoryFolder objects deal with organizing and finding content. An individual document can be in only one KnowledgeFolder, but it can appear in many KnowledgeCategoryFolders.|
|KnowledgeDocument||A SharePoint Portal Server document represents the content of a file and other information about the file, also called metadata. Any type of file, containing any type of content, created by any application, can be stored and worked on as a SharePoint Portal Server document. For example, you can store and manage word-processing documents, spreadsheets, presentations, and graphics files as SharePoint Portal Server documents. The properties and methods of the KnowledgeDocument object allow you to work with a SharePoint Portal Server document as a whole. Although this includes access to the file contents of a document, you use applications such as those in Office 2000 to work on the document content. Most of the properties and methods of the KnowledgeDocument object allow you to work with the SharePoint Portal Server metadata that is associated with a document.|
|KnowledgeDictionary||The KnowledgePropertyDef object defines a SharePoint Portal Server property. A dictionary property of a KnowledgePropertyDef can associate it with a KnowledgeDictionary. A dictionary can provide a list of commonly used property values, as guidance to the user. Alternatively, it can define and enforce a limited list of valid property values. The KnowledgeDictionary object is separate from the KnowledgePropertyDef so that multiple KnowledgePropertyDef objects can share a single dictionary object.|
|KnowledgeContentClass||A KnowledgeContentClass object specifies a list of KnowledgePropertyDef objects. Each KnowledgePropertyDef object defines a property (metadata) belonging to the object that is associated with the KnowledgeContentClass object. All SharePoint Portal Server objects have an associated KnowledgeContentClass, but users are only able to create and manipulate KnowledgeContentClasses for document profiles. The document profile does not refer to the file format of the application that created it, but to its purpose or audience.|
|KnowledgePropertyDef||The KnowledgePropertyDef object defines a particular property. Properties are scoped to the Workspace. Multiple KnowledgeContentClasses, displayed in the UI as document profiles, can use a property. A propertydef is different from the attribute value assigned to a specific document; it defines the characteristics of that attribute. For example, a document has a property on the profile page called "Author." A corresponding propertydef defines the characteristics of "Author" (urn:schemas-microsoft-com:office:office#Author). The values are stored in the document object. A KnowledgePropertyDef may have an associated KnowledgeDictionary object that contains a series of possible attribute values. Any number of KnowledgePropertyDefs can link to a KnowledgeDictionary, but a KnowledgePropertyDef can only link to one KnowledgeDictionary.|
|KnowledgeVersion||The KnowledgeVersion provides methods for managing previous versions of documents.|
Appendix D: SharePoint Portal Server Top 10 Programming Tasks
1. Binding to Items Stored in SharePoint Portal Server Web Storage System
Binding to items in the SharePoint Portal Server Web Storage System is nearly identical to binding to items in the Exchange Web Storage System. The first difference is in the pattern of URLs. SharePoint Portal Server URLs reflect the workspace and folder structure. The second difference is in the range of objects offered by SharePoint Portal Server that implement DataSource binding.
The following code example binds KnowledgeWorkspace, KnowledgeFolder, and KnowledgeDocument with URLs in the Web Storage System:
Dim oWS as New PKMCDO.KnowledgeWorkspace Dim oFolder as New PKMCDO.KnowledgeFolder Dim oDocument as New PKMCDO.KnowledgeDocument oWS.DataSource.Open "http://myserver/SharePoint Portal Server/" oFolder.DataSource.Open "http://myserver/SharePoint Portal Server/myfolder" oDocument.DataSource.Open "http://myserver/SharePoint Portal Server/myfolder/mydoc"
And, using Web Storage System CDO:
Dim oItem as New CDO.Item oItem.DataSource.Open "http://myserver/SharePoint Portal Server/myfolder/mydoc"
2. Creating Enhanced Folders
Versioning works on enhanced folders only. The following code changes a standard folder to enhanced. Simply manipulating the underlying ContentClass does this. It is the user's responsibility to set all necessary properties before calling Save. If the parent folder is enhanced, then the SharePoint Portal Server object model copies the publishing and approval settings from the parent folder. In this case, explicit setting is not required.
The following example creates a new enhanced folder:
Dim oF as New PKMCDO.KnowledgeFolder oF.Contentclass = "urn:content-classes:smartfolder" oF.Authors=Array("johndoe") oF.Editors=Array("janedoe") oF.Readers=Array("jackdoe") oF.Approvers=Array("johndoe", "janedoe") oF.Coordinators=Array("jilldoe", "janedoe") oF.Datasource.SaveTo "http://localhost/SharePoint Portal Server/content/enhancedfolder1"
The following example downgrades an enhanced folder to standard:
Dim oF as New PKMCDO.KnowledgeFolder oF.DataSource.Open "http://myserver/SharePoint Portal Server/SmartFolder/SmartSub", 3, -1 oF.Contentclass = "urn:content-classes:knowledgefolder" oF.Save
3. Listing Folders and Items
PKMCDO uses KnowledgeFolder to expose a richer set of functionality than is offered by the CDOEX folder object. The SharePoint Portal Server folder object returns subfolders as an ADO recordset.
This example traverses a folder and lists the absolute URL for each subfolder. It then displays all non-folder items in the subfolder. It is possible to bind to each of these resources with the URLs in the recordsets.
Dim oF as PKMCDO.KnowledgeFolder Dim oRS as ADODB.Recordset Set oF = (some already bound IKNowledgeFolder interface) Set oRS = oF.Subfolders While Not oRS.EOF Debug.Print oRS.Fields("DAV:href") oRS.MoveNext Wend Set oRS = oF.Items While Not oRS.EOF Debug.Print oRS.Fields("DAV:href") oRS.MoveNext Wend
4. Reading and Setting Document Properties
The KnowledgeDocument object makes available properties specific to SharePoint Portal Server metadata. Properties that are related to the urn:content-classes:item "root" contentclass are generally exposed as properties on the IKnowledgeItem interface.
This example displays properties of a document and sets the Categories property:
Dim oDoc as New PKMCDO.KnowledgeDocument oDoc.DataSource.Open sSharePoint Portal ServerDocURL 'bind to the document Debug.Print oDoc.BestBetKeywords Debug.Print oDoc.BestBetCategories Debug.Print oDoc.Categories Debug.Print oDoc.Title Debug.Print oDoc.Description ODoc.Categories = Array("mycategory")
In addition, the SharePoint Portal Server object model offers access to any property supported by the schema. This is equivalent to the last line in the example above.
oDoc.Property("urn:attributes:Categories") = Array("mycategory")
5. Migrating Content into SharePoint Portal Server
The following takes a file from the file system and copies it to a SharePoint Portal Server URL:
const adCreateOverwrite = &h04000000 const adCreateCollection = &h00002000 Dim objDoc Dim objStream Set objDoc=CreateObject("CDO.KnowledgeDocument") objDoc.ContentClass = "urn:content-classes:my-custom-profile" Set objStream = objDoc.OpenStream objStream.Type = adTypeBinary objStream.SetEOS objStream.LoadFromFile "C:\test.txt" objStream.Flush Set objStream = Nothing objDoc.DataSource.SaveTo _ "http://myserver/myworkspace/Documents/myfolder/test.txt", , , _ adCreateOverwrite
6. Publishing and Versioning Documents
For document publishing and versioning, the SharePoint Portal Server object model offers the Version helper object. This allows the user to act on document batches by accepting arrays. Versioning works on enhanced folders only.
The results of publishing methods are returned as recordsets. The VersionHistory method returns a recordset where each entry represents a version. The properties hold all information about each version, such as friendly version number, domain\user name associated with the version, and check in/check out comments.
The version object methods can be passed as a URL, an array of URLs, or a document or folder object (or array of them). In addition, many properties internal to the versioning mechanism are exposed, such as the URL of the version record, the internal version number. In the case of multiple URLs, such as an array of URLs or a folder object, the records reflect all the contained objects, such as items in the folder and its subfolders. It is possible to show the version history of every document in a folder using the recordset returned from one call.
The following example demonstrates document check in and check out:
Dim oVersion as New PKMCDO.KnowledgeVersion Dim sPath as String sPath = "http://mySharePoint Portal Serverserver/SharePoint Portal Server/Content/my.doc" Dim oRS as ADODB.Recordset Set oRS = oVersion.Checkin(sPath) Set oRS = oVersion.Checkout(sPath) Set oRS = oVersion.VersionHistory(sPath)
This example generates a list of URLs of all documents checked out to user "A" in MyEnhancedFolder.
Set oRS = oVersion.VersionHistory("MyEnhancedFolder") While Not oRS.EOF If oRS.Fields("pkm:versioning:user") = "A" And _ oRS.Fields("pkm:versioning:IsCheckedOut") = True Then Debug.Print "oRS.Fields("pkm:versioning:BaseDoc") End If oRS.MoveNext Wend
7. Searching Web Storage System Folders
Searching with ADO
The user can go directly to ADO and use the connection object behind a currently open workspace object to issue a command that is served by the underlying provider—the OLEDB Provider for Internet Publishing (MSDAIPP):
Dim cmd as New ADODB.Command Set cmd.ActiveConnection = oWS.ActiveConnection cmd.CommandText = "Select * FROM Scope('SHALLOW TRAVERSAL OF ""http://myserver/SharePoint Portal Server/""')" Set oRS = cmd.Execute ' and cycle through the items
The user can use ADO directly, binding to MSDAIPP without the services of the OM. This is appropriate if search is the only context, and there is no need to spend overhead on the SharePoint Portal Server objects. In this case, the user specifies the MSDAIPP DSO in the connection string to ADO.
In either case, the items returned have the same underlying fields as if exposed through a document or folder object in the SharePoint Portal Server object model. To regain SharePoint Portal Server-specific functionality, the user can bind a SharePoint Portal Server object using the DAV:href field in the record.
Searching with XMLHTTP
Web applications running on computers separate from the SharePoint Portal Server server, as well as from client applications, can use the Microsoft XMLHTTP component to search SharePoint Portal Server. The XMLHTTP COM component uses HTTP to transmit XML requests. You can use XMLHTTP and the SharePoint Portal Server WebDAV SEARCH implementation to search for documents.
Before sending the request, create a stream object or a string containing the XML request data. You can use the XML DOM to create this if desired. However, complex queries consist of mostly SQL, not XML. The example below assumes the request is stored in the strmXML stream.
' create the XMLHTTP object ' Open a request to the server to perform a search ' Set the header type to send XML ' Now send the stream data to the host Set objXMLHTTP = CreateObject("microsoft.xmlhttp") objXMLHTTP.Open "SEARCH", "http://mySharePoint Portal ServerComputer", false objXMLHTTP.setRequestHeader "Content-Type:" "text/xml" objXMLHTTP.send(strmXML)
After the search completes, objXMLHTTP.responseXML holds the response from the server.
8. Managing Subscriptions
Adding a Subscription
This example demonstrates adding a subscription:
Option Explicit On Error Resume Next Call Main Report "Passed." '======================================================= 'Main Sub Main() On Error Resume Next Dim strWorkspace, NType, strQuery, strOwner, strEmail CheckArgs strWorkspace, NType, strQuery, strOwner, strEmail Dim oSubMgr Set oSubMgr = CreateObject("PKM.SubscriptionManager") ReportError("CreateObject::SubscriptionManager") Dim strSubscriptionUrl strSubscriptionUrl = oSubMgr.CreateSubscription(strWorkspace, _ strQuery, _ NType, _ 1, _ strEmail, _ strQuery, _ 32767, _ "") ReportError("CreateSubscription") Report "Create subscription: '" & strSubscriptionUrl & "'" End Sub Sub Usage() On Error Resume Next Report _ vbCRLF & _ "Usage: AddSub <File | Folder | Search | Category> _ <SubscribeTo> <user or "" for current user> <email addr>" & _ vbCRLF & _ " e.g. AddSub SharePoint Portal Server Search ""CONTAINS('Microsoft')"" johndoe email@example.com" & _ vbCRLF & _ "Use the @ symbol to denote double-quote symbols in the SubscribeTo string" WScript.Quit End Sub '======================================================== 'CheckArgs Sub CheckArgs(ByRef strWorkspace, ByRef NType, ByRef strQuery, ByRef strOwner, ByRef strEmail) On Error Resume Next Dim strType If WScript.Arguments.Count <> 5 Then Usage End If strWorkspace = WScript.Arguments(0) strType = WScript.Arguments(1) strQuery = WScript.Arguments(2) strOwner = WScript.Arguments(3)lisag strEmail = WScript.Arguments(4) ' Replace the @ symbol with a " symbol in strQuery strQuery = Replace(strQuery, "@", """") if (strType = "Category") Then NType = 1 if (strType = "File") Then NType = 2 if (strType = "Folder") Then NType = 3 if (strType = "Search") Then NType = 4 End Sub '======================================================== 'Report Sub Report(strMessage) WScript.Echo strMessage End Sub '======================================================== 'ReportError 'Sub ReportError(strMsg) If Err.Number <> 0 Then Report vbCRLF & "ERROR: " & strMsg & _ vbCRLF & "ErrNo: " & Hex(Err.Number) & _ vbCRLF & "Desc: " & Err.Description & _ vbCRLF & "Source: " & Err.Source & _ vbCRLF & "File: " & Err.Helpfile & _ vbCRLF & "Context:" & Err.HelpContext WScript.Quit End If End Sub '========================================================= ' RaiseError Sub RaiseError(ErrNo, strMsg) On Error Resume Next Err.Raise ErrNo ReportError(strMsg) End Sub
All subscriptions in a workspace are stored in the same system folder. This example demonstrates searching for a subscription by the owner name.
SELECT * FROM SCOPE('SHALLOW TRAVERSAL OF "http://mySharePoint Portal ServerServer/SharePoint Portal Server/system/subscriptions"') WHERE "urn:attributes:SubscriptionOwner" = 'domain_name\user_name'
Reading Subscription Properties
This example lists several properties of a subscription. The ID is a text representation of the SubscriptionID number.
Option Explicit On Error Resume Next Call Main Report "Passed." '======================================================== ' Main Sub Main() On Error Resume Next Dim strSubscription CheckArgs strSubscription Dim oSub Set oSub = CreateObject("CDO.KnowledgeDocument") ReportError("CreateObject::KnowledgeDocument") Report "Created document object, binding to subscription row " & _ strSubscription Call oSub.DataSource.Open(strSubscription) ReportError("DataSource::Open subscription") Report "Bound to subscription " & strSubscription Report "SubscriptionId: " & _ cstr(oSub.Property("urn:attributes:SubscriptionId")) ReportError("oSub.Property(SubscriptionId)") after beta 2 Report "Id: " & oSub.Property("DAV:displayname") ReportError("oSub.Property(Id)") Report "Query: " & oSub.Property("urn:attributes:Query") ReportError("oSub.Property(Query)") Report "Owner: " & oSub.Property("urn:attributes:SubscriptionOwner") ReportError("oSub.Property(Owner)") Report "Email: " & oSub.Property("urn:schemas:mailheader:to") ReportError("oSub.Property(Email)") End Sub '======================================================== ' CheckArgs Sub CheckArgs(ByRef strSubscription) On Error Resume Next If WScript.Arguments.Count <> 1 Then Report _ vbCRLF & _ "Usage: ViewSub <subscription url>" & _ vbCRLF & _ " e.g. ViewSub http://myServer/SharePoint Portal Server/system/subscriptions/1" ReportError("Invalid number of args") WScript.Quit End If strSubscription = WScript.Arguments(0) End Sub '======================================================== ' Report Sub Report(strMessage) WScript.Echo strMessage End Sub '======================================================== ' ReportError Sub ReportError(strMsg) If Err.Number <> 0 Then Report vbCRLF & "ERROR: " & strMsg & _ vbCRLF & "ErrNo: " & Hex(Err.Number) & _ vbCRLF & "Desc: " & Err.Description & _ vbCRLF & "Source: " & Err.Source & _ vbCRLF & "File: " & Err.Helpfile & _ vbCRLF & "Context:" & Err.HelpContext WScript.Quit End If End Sub '======================================================== ' RaiseError Sub RaiseError(ErrNo, strMsg) On Error Resume Next Err.Raise ErrNo ReportError(strMsg) End Sub
Deleting a Subscription
This example deletes the Subscription identified by the Workspace URL and the SubscriptionID number. See Viewing Subscription Properties for an example of obtaining the ID.
Option Explicit On Error Resume Next Call Main Report "Passed." '======================================================== ' Main Sub Main() On Error Resume Next Dim strWorkspace, nId CheckArgs strWorkspace, nId Dim oSubMgr Set oSubMgr = CreateObject("PKM.SubscriptionManager") ReportError("CreateObject::SubscriptionManager") oSubMgr.DeleteSubscription strWorkspace, nId ' strWorkspace is the URL of the Workspace ' that contains the subscription. ' nID is the SubscriptionID, note this in an integer, not a string. ReportError("DeleteSubscription") End Sub '======================================================== ' CheckArgs Sub CheckArgs(ByRef strWorkspace, ByRef nId) On Error Resume Next If WScript.Arguments.Count <> 2 Then Report _ vbCRLF & _ "Usage: DelSub2 <Workspace Name> <Subscription Id>" & _ vbCRLF & _ " e.g. DelSub2 SharePoint Portal Server 414" ReportError("Invalid number of args") WScript.Quit End If strWorkspace = WScript.Arguments(0) nId = WScript.Arguments(1) End Sub '======================================================== ' Report Sub Report(strMessage) WScript.Echo strMessage End Sub '======================================================== ' ReportError Sub ReportError(strMsg) If Err.Number <> 0 Then Report vbCRLF & "ERROR: " & strMsg & _ vbCRLF & "ErrNo: " & Hex(Err.Number) & _ vbCRLF & "Desc: " & Err.Description & _ vbCRLF & "Source: " & Err.Source & _ vbCRLF & "File: " & Err.Helpfile & _ vbCRLF & "Context:" & Err.HelpContext WScript.Quit End If End Sub '======================================================== ' RaiseError Sub RaiseError(ErrNo, strMsg) On Error Resume Next Err.Raise ErrNo ReportError(strMsg) End Sub
9. Managing User Roles
This example adds a Reader to a folder, and then recursively adds the Reader to all of the subfolders of the folder. It takes two arguments: the topmost folder object to be modified, and the User to be added as a Reader. It can be modified to change any role property.
The Reader property, like all the role properties, is a Variant array of Variants. A Variant array of Variants has to be declared differently in Visual Basic Script than it is in Visual Basic. First, declare it as a Variant, then assign a Variant array Property to it. VBS will "do the right thing," silently converting the Variant to an array of Variants. Then it can be redimensioned to the proper size. If you initially declare it as an array, the assignment of the property works in Visual Basic, but not in VBS.
Option Explicit On Error Resume Next Call Main Report "Success." '======================================================= ' Main Sub Main On Error Resume Next Dim kfFolder Set kfFolder = WScript.CreateObject("CDO.KnowledgeFolder") ReportError "Create KnowledgeFolder" kfFolder.DataSource.Open( WScript.Arguments(0) ) ReportError "Open Folder " & WScript.Arguments(0) AddReader kfFolder, WScript.Arguments(1) End Sub '======================================================== ' AddReader Sub AddReader(kfFolder, strUser) On Error Resume Next Dim i Dim nReaders nReaders = -1 Dim arReaders 'a Variant destined to become an array of Variants. nReaders = UBound(kfFolder.Readers) arReaders = kfFolder.Readers 'VBS silently converts the Variant to an array of Variants ReportError "Setting arReaders" ReDim Preserve arReaders( nReaders + 1) 'make room for the new Reader arReaders( nReaders + 1) = strUser 'add the reader to the end of the array kfFolder.Readers = arReaders 'assign the array back to the Readers property of the folder 'SharePoint Portal Server will automatically remove any duplicate entries ReportError "Setting kf.Readers" kfFolder.DataSource.Save 'save the folder object to the store ReportError "Updating Folder" WScript.Echo "Updated " & kfFolder.DisplayName & " to " & _ CStr(nReaders +1) & " Readers" If kfFolder.HasSubs Then Dim rsSubFolders Set rsSubFolders = kfFolder.Subfolders rsSubFolders.MoveFirst Dim kfSubFolder Set kfSubFolder = WScript.CreateObject("CDO.KnowledgeFolder") ReportError "Creating KnowledgeFolder in AddReader" Do Until rsSubFolders.EOF kfSubFolder.DataSource.Open( _ rsSubFolders.Fields("RESOURCE_ABSOLUTEPARSENAME") ) ReportError("Open Folder " & _ rsSubFolders.Fields("RESOURCE_ABSOLUTEPARSENAME") ) AddReader kfSubFolder, strUser ' recursive, call AddReader with the current subfolder. rsSubFolders.MoveNext Loop End If End Sub '======================================================== ' Display Sub Display(strRole, objRole) Dim i For Each i in objRole WScript.Echo i Next Err.Clear WScript.Echo "" End Sub '======================================================== ' Report Sub Report(strMessage) WScript.Echo strMessage End Sub '======================================================== ' ReportError Sub ReportError(strMsg) If Err.Number <> 0 Then Report vbCRLF & "ERROR: " & strMsg & _ vbCRLF & "ErrNo: " & Hex(Err.Number) & _ vbCRLF & "Desc: " & Err.Description & _ vbCRLF & "Source: " & Err.Source & _ vbCRLF & "File: " & Err.Helpfile & _ vbCRLF & "Context:" & Err.HelpContext Err.Clear WScript.Quit End If End Sub '======================================================== ' RaiseError Sub RaiseError(ErrNo, strMsg) On Error Resume Next Err.Raise ErrNo ReportError(strMsg) End Sub
10. Managing Schema Objects
Schema objects define the structures of a SharePoint Portal Server installation. They are stored in the Web Storage System and their scope is the workspace in which they are defined. Schema objects are accessible the GetObject method on the KnowledgeWorkspace object.
The object model facilitates schema manipulation by defining the properties on the schema object definitions as COM properties on the corresponding objects, KnowledgeContentClass, KnowledgePropertyDef and KnowledgeDictionary.
For example, each SharePoint Portal Server contentclass is associated with a list of properties, but also inherits the properties of the contentclasses it "extends." A property on the contentclass object, FullPropertyList, shows all the properties available on an instance of a contentclass, both "local" and inherited.
Property Enumeration Examples
This example displays the address (URL) of the row storing the definition of a property in SharePoint Portal Server:
Dim oPD as PKMCDO.KnowledgePropertyDef Set oPD = oWS.GetObject("urn:content-classes:propertydef") Debug.Print oPD.Href
http://myserver/SharePoint Portal Server/system/schema/propertydef_cc.xml.
This example loops through all of the properties on a workspace and retrieves the corresponding PropertyDef objects.
For Each s in oWS.Properties Set oPD = oWS.GetObject(s) 'do work here Next s
The next example displays the list of properties in a ContentClass, then binds to each property definition, and displays its user-friendly name.
'oCC is a previously bound Contentclass object Dim oPD As New PKMCDO.KnowledgePropertyDef For Each i In oCC.FullPropertyList Set oPD = oWS.GetObject(i) MsgBox oPD.Title Next I
The FullPropertyList is a SafeArray. Note how safe arrays returned from PKMCDO are accessible for "For Each… Next" enumeration in Visual Basic.
To get the "local" list of properties, that is, those that are not inherited, use the Element property. It returns an array of URLs of properties or property overrides.
For Each i In oCC.Element Set oPD = oWS.GetObject(i) MsgBox oPD.Title Next I
Property Override Examples
Property overrides allow the user to override the attributes of a property within the context of a contentclass. For example, the property Advanced Degree may be required in all cases, except when it is associated with the contentclass Coach.
There is no Property Override object. An override exists as a record on the ContentClass. The following example creates such a record for the contentclass Core Document and propertydef Relation:
Set p = CreateObject("PKMCDO.KnowledgePropertyDef") p.Name = p.GenerateOverrideUri ("urn:content-classes:document/progid/SharePoint Portal Server/coredocument", "urn:attributes:Relation") p.Isrequired = true p.DataSource.saveto _ "http://localhost/SharePoint Portal Server/system/schema/coredoc_relation_ovr"
Once an override record is present, access is transparent and uses the PropertyDef object. In the code above, the IsRequired attribute's default value was overridden. To access the value of this attribute, the user binds to the PropertyDef from the ContentClass. The value of IsRequired now automatically reflects whatever attributes are overridden for this contentclass /property combination. The user is not required to look up an override record explicitly to find if an attribute is overridden. Explicit manipulation of overrides is needed only for creation and deletion. Deletion is done using the Delete() method.
Creating and removing property/contentclass associations is done using the two helper functions: AddPropertyDef and RemovePropertyDef. Listing members of the Elements property, which is a SafeArray of string-type variants, enumerates propertydefs per contentclass.
This example adds a property to a contentclass:
Dim oCC as New PKMCDO.KnowledgeContentclass … (bind to existing Contentclass)… oCC.AddPropertyDef("urn:attributes:pdefuri") oCC.DataSource.Save
This creates an error if the propertydef is already in the elements array. Call RemovePropertyDef to remove a PropertyDef from a contentclass, by URI.
The following example creates a new dictionary in the system schema.
Dim oDict As New PKMCDO.KnowledgeDictionary Dim vValue Dim sAR(2) sAR(0) = "hello" sAR(1) = "there" sAR(2) = "!" oDict.DictionaryValues = sAR oDict.Name = "urn:dictionary:mydict" oDict.DataSource.SaveTo "http://localhost/SharePoint Portal Server/System/schema/mydict.xml"
A property definition can be tied to a dictionary. This example displays all objects in the schema folder, binds to each dictionary, and lists the dictionary values for each:
Dim oWS as new PKMCDO.KnowledgeWorkspace Dim oF as New PKMCDO.KnowledgeFolder Dim oRS as New ADODB.Recordset Dim oDict as New PKMCDO.KnowledgeDictionary Dim sValue as String oWS.DataSource.Open ("http://localhost/SharePoint Portal Server") oF.DataSource.Open ("http://localhost/SharePoint Portal Server/System/schema") Set oRS = oF.Items oRS.MoveFirst While Not oRS.EOF If oRS.Fields(PKMCDO.cdostrURI_ContentClass) = _ "urn:content-classes:dictionary" Then Debug.Print "This is a dictionary: " & _ oRS.Fields(PKMCDO.cdostrURI_HREF) oDict.DataSource.Open oRS.Fields(PKMCDO.cdostrURI_HREF) For Each sValue In oDict.DictionaryValues Debug.Print sValue Next End If oRS.MoveNext Wend