SharePoint Connector 2.0

This documentation covers the Day JCR Connector for Microsoft SharePoint 2007, version 2.0.

The Day JCR Connector for Microsoft SharePoint 2007, also called SharePoint connector, belongs to Day's CRX connectors family. CRX is Day's Content Repository Extreme, fully implementing the Content Repository API for Java Technology (JCR).

The SharePoint connector supports the following base functionalities:

1. Reading content and metadata from SharePoint
2. Writing files and folders to the SharePoint document libraries
   
3. Executing queries on the SharePoint system
4. Respecting SharePoint security settings for accessed content via leveraging native SharePoint authentication and authorization
5. Observing content changes that occurred in the SharePoint system

All functionalities are implemented using the native SharePoint web services as interface to SharePoint content and services.

To get started with the connector:

1. Make sure you have at least Java 5 installed.
   
2. Download the connector Quickstart distribution .jar file.
   
3. Copy a valid license.properties file in the same directory as the .jar file.
4. Double-click the file or start it from the command line (for example: java -jar crx2sharepoint-2.0.0.20090924.jar).
5. When the connector is up and running, your browser shows the connector welcome screen after a short while.

Your connector is up and running.

The SharePoint connector JCR-enables and Java-enables MS SharePoint repositories by implementing a part of JCR interface (Level 1 and parts of Level 2 and optional JCR feature), using the native SharePoint web services to map to JCR API the content, metadata, and content services provided by SharePoint repositories. It supports reading, writing, searching and observing changes in the Microsoft SharePoint repository through the standard JCR API.

The SharePoint connector is delivered deployed and preconfigured in the CRX framework to simplify installation, configuration, integration and administration of the connector and applications using it. The following diagram provides an architectural overview of the connector:

The connector is a part of Day JCR infrastructure and operates in the following content application infrastructure layers:

• JCR Application layer. The JCR applications, operating on top of the connector and JCR infrastructure layer, access the content and content services mapped from the Sharepoint repository to the standard JCR API by the connector JCR repository implementation.
• JCR Infrastructure layer. The connector provides an implementation of the JCR repository, using SharePoint server as provider for native SharePoint content and metadata storage/retrieval services, as well as content services like search, security and observation. The connector acts as a client application, accessing SharePoint via SOAP Web Services API over the HTTP protocol. The connector can also be deployed into CRX Framework, which provides additional services to the JCR applications. These include  content integration and federation via Virtual Repository, configuration and management tools, Apache Sling content delivery and application development platform, etc.
• SharePoint Infrastructure layer. Includes the network infrastructure and native SharePoint server deployment. The SharePoint server is accessed through its native SOAP web services installed in Windows Server operating system, and operating in the context of the MS Internet Information Server (IIS). The core SharePoint server implements content persistence and retrieval (using MS SQL database by default) and other content services (like indexing, search, application-level services).

The connector is designed to map content managed in SharePoint servers (sites, lists, list items, metadata, documents, etc) and content services delivered by SharePoint (like search, security, change notification). The mapping covers the content and content services, which are relevant to the JCR standard. That means, that SharePoint graphical user interface (GUI) and the application-level functionalities not covered by the JCR standard will not be mapped by the connector.

As an example, while the connector does not map the GUI application logic of the SharePoint server (not covered by JCR), it will provide GUI-relevant metadata, so that JCR or Java applications can restore some of the GUI logic if that is the goal of the application (e.g., for SharePoint lists, the connector gives access to Views and their metadata as used by SharePoint GUI). In most use cases it is the content itself that is important for integration and reuse.

The general high-level flow of requests from the applications using the connector (read or write SharePoint content, search for documents, log in) works as follows:

1. An application executes a JCR call on the connector repository. 
2. The connector translates the call to a native call (or set of calls) to the SharePoint web services.
3. The web service calls are executed by the SharePoint server and the results are returned.
4. The results are received by the connector and translated back to JCR space.
5. The JCR call returns the results.

Apart from caching, the connector does not persist any data by itself.

This section explains how to install the SharePoint connector. The connector is a jar file package based on the Day's Quickstart technology and allows for easy installation: double-click the jar file and then set the URL of the SharePoint server. The SharePoint content is available in the CRX repository.

If needed, the installation can be customized to meet specific needs as running on a different port, running on a different CRX instance, or upgrading from a previous version of the connector.

The connector requires the following:

• Java Runtime Environment 1.5 or later
• SharePoint Web Services available via network
• A URL to a SharePoint server
  
• User credentials and permissions for CRX and SharePoint repositories
• Supported platforms

The connector has the following platform requirements:

• Generally the supported platforms are identical to those supported by the CRX 1.4.2 release. Please see the corresponding section in the CRX documentation.
• The following Microsoft SharePoint versions are supported:
• Microsoft Office SharePoint Server (MOSS) 2007
• Microsoft Windows SharePoint Services (WSS) version 3
• If you need support for customized deployments of the connector (OEM, special requirements, customized authentication methods) please contact the Day Software office for your region.
• The connector only supports the standard IIS Windows authentication method. For more information, please refer to the authentication method called Windows in the table listing the supported authentication methods at http://technet.microsoft.com/en-us/library/cc262350.aspx#section2.
  The other authentication methods can be supported through the extensibility mechanism described in the section Supporting different authentication methods of the SharePoint server.
  

You can install the connector by using a Quickstart package, which is a self-running jar file. It consists of CRX 1.4.2.PS1 Quickstart, a connector-specific content package and the default configuration for JAAS authentication.

The first time you start the jar file, it creates three JCR-compliant repositories (a standard CRX repository, a connector specific repository, and a virtual repository federating access to both), a web framework for developing web applications on Java (Apache Sling), a web application to browse through the repository (CRX Explorer) and mounts the SharePoint repository to the CRX workspace by using the CRX virtual repository feature.

To install the connector, proceed as follows:

1. Copy the connector .jar file to the desired directory on the host file system.
2. Copy a valid license.properties file into the same directory as the .jar file.
   Note: If when starting the application, you do not provide the license.properties file, CRX asks you for a valid license key. You can request a valid license key from Day at this time.
3. Start the connector Quickstart by doing one of the following:
   - If using a GUI file-system explorer, double-click the .jar file. This installs and automatically starts the connector.
   - If using the command line, for example, type java -jar crx2sharepoint-2.0.0.20090924.jar
   
4. The Welcome window opens in your browser. Below Sharepoint Connector, click Configure to access the Configuring window of the CRX Connector for Sharepoint.
5. Enter the URL to your SharePoint server and click OK.
   Note 1: the host, which this URL resolves to, needs full name resolution in order for the connector to work properly. In addition it might be necessary to configure SharePoint's Alternate Access Mappings accordingly. See http://technet.microsoft.com/en-us/library/cc288609.aspx.
   Note 2: in order to access content through the connector, a user needs to have the appropriate rights. Being a Site Owner or a Site Member gives enough rights to access the SharePoint content.
   Note 3: special authentication needs to be configured so that the connector can access the SharePoint Web Services.
   
6. Restart the CRX instance.
7. In the Welcome window, in the Manage box, click Manage Repository to open the Main Console of CRX.
8. Login as a valid SharePoint user.
9. Open the Content Explorer.
10. Navigate to the nodes under /mnt/sharepoint to view the SharePoint content mapped by the connector.

As the connector is based on the Quickstart technology, starting or stopping the connector is similar to starting or stopping a CRX Quickstart file:

• To start the connector, double-click the connector Quickstart jar file or start the connector from the command line with the java command or with a custom script. Follow the steps described in the corresponding section of the CRX Quickstart documentation.
  
• To stop the connector, follow the steps described in the corresponding section of the CRX Quickstart documentation.
  

To verify that the connector instance works (that is, that the SharePoint server runs and its web services are accessible to the connector instance, the SharePoint user credentials are valid and the user has necessary SharePoint permissions, the connector is installed and configured properly), execute the following steps:

1. Open the CRX console (http://localhost:7402/crx by default), log in using user credentials recognized by the connector (SharePoint server). Alternatively, log into your custom JCR application running on top of the connector.
   
2. Open the Content Explorer.
3. Verify that you can see SharePoint nodes mapped into JCR. If you are using Content Explorer in the default setup, you should see a connector node hierarchy under the /mnt/sharepoint node, starting with the sp:Site node representing the SharePoint site.

You should see the following node hierarchy in the Content Explorer.

The default port for the connector is 7402. To change it, refer to the corresponding section in the CRX Quickstart documentation.

To upgrade from a previous version of the connector, uninstall the former connector, install the Day JCR Connector for Microsoft SharePoint 2007 and apply the former configurations to the connector.

Because the connector does not persist any content (apart from potential caches, which will be recreated), you don't have to upgrade or migrate any content.

It is possible to install the SharePoint connector within an existing CRX or CQ5 instance, enabling for example an existing application to access a SharePoint repository.

The initial release of SharePoint connector v. 2 was released before CRX 2.1 and CQ 5.3 were released. To provide compatiblitiy with the new major 2.x releases of the repository (implementing JCR 2), patch releases of the SharePoint connector are provided (2.0.1, 2.0.2) enabling installation of the connector into CRX 2.x repositories. Note that the connector core has not been updated, and it still implements a part of JCR 1 standard.

The connector patch releases for CQ 5.3 (2.0.1) and CRX 2.1 (2.0.2) are provided as content packages, available through the new distribution channel, Day Package Share. The connector original runnable Quickstart jar distribution (2.0.0) is not needed to install the connector into these products.

The table below presents an overview of connector versions to be used for specific versions of target systems (CRX, CQ5). Click the link in the Target System column to navigate to detailed installation instructions for CRX or CQ5 version you use.

The SharePoint content mapped by the connector can be integrated into CRX 2.1 applications. CRX version 2.1 requires a connector package supporting the new JCR 2.0 standard (released as version 2.0.2 of the core connector package). This package contains the same connector core (connector functionality) as in version 2.0.0, repackaged so that it works when deployed in CRX 2.1.

To enable integration of SharePoint content into CRX 2.1, you need to install the crx2sharepoint-initial-content-2.0.1.zip content package. Please follow these steps:

1. In the CRX instance open Package Share.
2. Login to Package Share.
3. Go to Public » Day » Connector » SharePoint Connector 2.0.2 or search for the package and select its parent folder.
4. Click Download to download the crx2sharepoint-crx21-2.0.2.zip package.
5. When the package is downloaded, go back to the Package Manager of the CRX instance: click the Downloaded button of the selected package in Package Share.
6. Install the package in the CRX instance: click Install in the page describing the package. In the Install Package dialog, click Install.
   Note: make sure that you are logged-in as administrator.
7. Go to the welcome screen by clicking the Day logo.
8. Click the new option SharePoint Connector.
9. Configure the connector. For more details refer to the Configuring section.
10. Stop CRX.
11. Connector does not work with the new default, token-based authentication mode introduced in CRX 2.1. You need to disable the token-based authentication mode as follows:
    
    • Edit the repository.xml file in <crx-install-dir>/crx-quickstart/repository and add the following line between the <LoginModule> and </LoginModule> tags:
      <param name="disableTokenAuth" value="true"/>
12. Start CRX.
    

You can now proceed with configuring and using the connector.

Configuration of authentication. The connector instance does not have JAAS configured by default. You need to create CRX user(s) corresponding to SharePoint users (user name and password need to match) in order to be able to see SharePoint content mapped to the connector instance.

Alternatively, refer to Configuring Authentication for informaiton on how to configure the CRX & connector instance for, e.g., authentication against an Active Directory server used by SharePoint.

The SharePoint content mapped by the connector can be integrated into CQ5 applications. Version CQ 5.3 requires a connector package supporting the new JCR 2.0 standard (released as version 2.0.1 of the core connector package). This package contains the same connector core (connector functionality) as in version 2.0.0, repackaged so that it works when deployed in CQ 5.3.

To enable integration of SharePoint content into CQ 5.3, you need to install the crx2sharepoint-initial-content-2.0.1.zip content package. For evaluation pupropses, it is recommended to start with example packages for CQ 5.3 (see below). To install the connector into CQ 5.3, please follow these steps:

1. In the CQ 5.3 instance open Packages, then Package Share.
2. Login to Package Share.
3. Go to Public » Day » Connector » SharePoint Connector 2.0.1 or search for the package and select its parent folder.
4. Click Download to download the crx2sharepoint-initial-content-2.0.1.zip package.
5. Go back to the Package Manager of the CQ instance: click the Downloaded button of the selected package in Package Share.
6. Install the package in the CQ instance: click Install in the page describing the package. In the Install Package dialog, click Install. When the package is installed, click Close.

You can now proceed with configuration and usage of the connector. The steps above only install a connector instance into your CQ 5.3 - you need to configure Virtual Repository to mount the connector content into your CQ 5.3 and make it available for further integration. See example packages below for sample configurations.

Example packages for CQ 5.3. Example packages demonstrating some of the possibilities of integrating SharePoint content into CQ5 are provided in Package Share, in Public » Day » CQ 5.3.0 » example » connector folder. They extend Geometrixx example website with SharePoint integration. The following examples are available:

• cq53wcm-sharepoint-example-1.x.zip: Integration using a custom Content Finder tab ("Connectors"), allowing for browsing and searching for documents stored in SharePoint, and dragging and dropping them on WCM pages. Also contains sample scripts for rendering metadata-based SharePoint content (Announcements in this case).
• cq53dam-sharepoint-example-1.x.zip: Integration using CQ5 DAM workflows to synchronize documents stored in SharePoint into CQ5 DAM assets.

Example packages are fully self-contained, and include the SharePoint connector, configuration of Virtual Repository, and example integration code.

To use the examples, go to Package Share to the location specified above, download the package to your local CQ 5.3 instance, and install it. Then follow the package description to access the information about the example at hand, and a step-by-step description of how to use it (this information is available via "WCM+SharePoint Info" or "DAM+SharePoint Info" links on the CQ5 welcome screen).

The SharePoint content mapped by the connector can be integrated into CQ 5.2.1 applications.

To enable it, the JCR Connector Integration content package delivered with CQ 5.2.1 should be installed into the CQ instance. Generally, it can be found in your CQ5 installation, in the <cq-install-dir>/crx-quickstart/opt/connector/ folder.

The content package contains a sample configuration for a Virtual Repository that mounts JCR Connectors available from Day. Please note that the various mount configurations are initially disabled.

To integrate the SharePoint content into CQ 5.2.1 applications:

1. Upload and install the cq-connector-content-5.2.jar file located at <cq-install-dir>/crx-quickstart/opt/connector/ by using the CRX Package Manager.
2. Adapt and enable the mount configurations under /etc/virtual-repositories/virtual-crx as needed.
3. Go to the Felix Management Console at http://localhost:4502/system/console and change the repository name for the factory configuration CRX Sling Client Repository from crx to virtual-crx.
4. Restart the CQ5 server.

Required CQ 5.2.1 Updates

You might need to use and install one of the Apache Jackrabbit libraries in your CQ 5.2.1 installation (jackrabbit-core-1.4.9.jar) to at least version jackrabbit-core-1.4.11.jar for the SharePoint connector integration. It prevents CQ5 link checker problems when there is a user with CQ5 administrative credentials defined in the SharePoint server.

Please proceed as follows:

1. Download the Apache Jackrabbit library jackrabbit-core-1.4.11.jar from Jackrabbit release archive.
   
2. Stop the CQ 5.2.1 instance.
3. Go to the <cq-install-dir>/crx-quickstart/server/runtime/0/_crx/WEB-INF/lib folder.
4. Rename the jackrabbit-core-1.4.9.jar file to jackrabbit-core-1.4.9.jar.NOT.
5. Copy the jackrabbit-core-1.4.11.jar file in this folder.
6. Re-start the CQ5 instance.
   

Installing the connector in a CRX 1.4.2 PS1 instance consists in extracting the relevant files from the SharePoint connector package and installing them into the existing CRX instance, configuring the connector, and configuring Sling, CRX Explorer and JAAS. Proceed as follows:

1. Unpack the connector jar file: start the jar file from the command line with the option -unpack; for example: java -jar crx2sharepoint-2.0.0.20090924.jar -unpack
   
2. Acquire the two following content packages located on your file system at <connector-install-dir>/crx-quickstart/repository/install: crx2sharepoint-initial-content-2.0.0.jar and crx-sharepoint-2.0.0.jar.
   
3. Install the crx-sharepoint-2.0.0 content package on the existing CRX server by using the CRX Package Manager.
   
4. Set the URL to the SharePoint server.
   
5. Set the Sling Client repository to point to the virtual repository: in the OSGI console, select the CRX Sling Client Repository bundle and as Repository Name set: virtual-crx.
6. Stop the CRX instance.
   
7. Make the content under the node /mnt available in CRX Explorer: edit the web.xml file of the existing CRX server which is located on the file system at <connector-install-dir>/crx-quickstart/server/runtime/0/_crx/WEB-INF and edit the code within the JCR EXPLORER SERVLET section to match as follows:   
   <init-param>
         <param-name>repository-name</param-name>
         <param-value>virtual-crx</param-value>
         <description>Repository Name that is used to retrieve it via JNDI</description>
    </init-param>
   Note: make sure to apply this configuration only in the JCR EXPLORER SERVLET section.
   
8. Install the connector authentication module into the CRX server: copy the file <connector-install-dir>/crx-quickstart/server/lib/container/crx2sharepoint-auth-2.0.0.jar into the same directory of the existing CRX server.
   
9. Configure JAAS on the existing CRX server: copy/paste following code into the jaas.config file located on the file system at <connector-install-dir>/crx-quickstart/server/etc:
   com.day.crx {
      com.day.crx.security.authentication.CRXLoginModule sufficient;
      com.day.crx.spi.sharepoint.security.SharepointLoginModule required
           callback.enabled="true"
           java.naming.factory.initial="com.day.util.jndi.provider.MemoryInitialContextFactory"
           java.naming.provider.url="http://jcr.day.com";
   };
   Note: This is the default configuration of the connector Quickstart.
   
10. Restart the CRX server.

Because the connector installs only into a directory, there is no need for an uninstall utility. Uninstalling is as simple as deleting the entire installation directory.

This section describes how to configure the SharePoint connector and its interfaces with both the application and the SharePoint layers.

The following diagram depicts the detailed deployment architecture of the SharePoint connector:

The only required configuration to make your SharePoint repository JCR compliant is to set the URL of the SharePoint server. You can set further parameters to configure the connection with the SharePoint server.

The virtual repository, which is accessed by content applications through either Apache Sling or the JCR API, and the actual mount point where the SharePoint repository is mounted, are pre-configured in the connector Quickstart package: their configuration can be changed to adapt to specific needs.

The content applications running on the connector need to be configured to access the mounted SharePoint repository.

Finally, authentication needs to be configured with the SharePoint connector.

The only required configuration to make your SharePoint repository JCR compliant is to set the URL of the SharePoint server. All the other configuration parameters are optional and have default values that can be configured afterwards.

To set the URL of the SharePoint server and set advanced options:

1. Navigate to the Launchpad: http://localhost:7402/content/crx.html
2. In the SharePoint Connector frame, click Configure.
3. Set the SharePoint Server URL.
4. Beside Advanced options, click [+] to set advanced configuration options.

The parameters can also be set through:

• the CRX Explorer: /apps/crx2sharepoint/config/com.day.crx.spi.sharepoint.osgi.impl.SharepointRepositoryImpl
• the OSGI Management Console (http://localhost:7402/system/console/configMgr): bundle "Day JCR Connector for Microsoft Sharepoint 2007"
  Warning: this method is not recommended as the values are not replicated into the content, and might be overriden by connector upgrades. You can use this method to verify connector configuration settings in case of problems.

'Workspaces' and 'Default Workspace Name' parameters:

By default the connector exposes a single JCR workspace. The SharePoint server which is exposed by this workspace is set through the 'Sharepoint Server URL' configuration parameter.

The connector can also be configured for multiple workspaces. In this case each workspace is associated with the URL of the respective SharePoint server which is exposed through that workspace. To add a workspace, add a workspace definition to the 'Workspaces' configuration parameter. A workspace definition has the form <name>=<url> where <name> is the name of the JCR workspace and <url> is the URL of the SharePoint server for that workspace.

More insight into search-related parameters:

Please refer to the Search section to get more insight into following search-related parameters: 'Query Maximal Result Count', 'Query Ignore Noise', 'Query Trim Duplicates', 'Query Include Non Full Text Items' and 'SharePoint Server Search Service'.

More insight into observation-related parameters:

Please refer to the Observation section to get more insight into following observation-related parameters: 'Observable paths' and 'Observation polling interval'.

When you install the connector, the three following JCR-compliant repositories are created and registered with JNDI:

• a native CRX repository with a primary workspace bound to the JNDI name 'crx'
  
• a virtual repository bound to the JNDI name 'virtual-crx'
• a connector-specific repository bound to the JNDI name 'crx2sharepoing.repository'

The SharePoint repository is mounted into the native CRX repository by leveraging the CRX virtual repository. The idea of mounting JCR workspaces under mount points in the primary workspace is similar to the way operating systems allow you to mount external or network file systems under directories in the local file system.

Content applications can access content stored in all these repositories via the standard JCR API of the Virtual Repository.

Thus the connector provides content applications with virtualized view on the primary workspace and the SharePoint workspace mounted into it.

The virtual repository, which is accessed by content applications through either Apache Sling or the JCR API, and the actual mount point where the SharePoint repository is mounted, are pre-configured in the connector Quickstart package:

• the virtual repository JNDI object is configured in the repository by the node /etc/virtual-repositories/virtual-crx/mnt/sharepoint
• the SharePoint repository is mounted into the native repository at the node /mnt/sharepoint

It is possible to change this configuration: please refer to Configuring the Virtual Repository in the CRX documentation.

Applications running on top of the connector like CQ or other Sling-based and JCR-enabled applications need to be configured as follows to access the SharePoint content:

• To be able to access the content virtualized through the virtual repository mount, the application needs to use the virtual repository object instead of the "normal" CRX repository object.
  This configuration needs to be done at the application level: refer to the related CRX documentation.
  
• To be able to browse the virtual repository, including the SharePoint mounted workspace, the JCRExplorerServlet in CRX web application's web.xml needs to be switched to use virtual-crx as JNDI repository object.
  It is already pre-configured in the connector Quickstart package.
  
• To allow content application based on Apache Sling and running within the CRX Launchpad module to access the virtual repository content, the CRX Sling Client Repository bundle needs to be configured to use virtual-crx as repository name.
  This setting is pre-configured in the connector Quickstart package.

The typical connector and connector integration deployments use the JAAS-based authentication, supported by the CRX framework, which is the JCR repository infrastructure powering both the SharePoint connector default installation, as well as other Day CQ applications.

There are several possibilities to configure authentication with the SharePoint connector:

• you can use the pre-configured JAAS authentication of the connector Quickstart package. Only a SharePoint authenticated user can access the SharePoint content through the connector. Warning: anonymous has all the rights on CRX. Day recommends this configuration for evaluation, prototype and development.
• you can disable the JAAS authentication. In this case, only a user who is authenticated on both CRX and SharePoint can access the SharePoint content through the connector. Day recommends this configuration if you don't use an external authentication for SharePoint like Active Directory or if the number of users to be managed is relatively small.
• you can configure the authentication for Active Directory by leveraging the CRX LDAP Login Module. This way, the connector authenticates against the central Active Directory server that authenticates the SharePoint users. This configuration should be used whenever external authentication is needed.

When you use the pre-configured authentication of the connector Quickstart package, only a SharePoint authenticated user can access the SharePoint content through the connector.

The connector uses JAAS authentication and is configured to manage the users in the SharePoint repository by setting the value "required" to the SharePoint Login Module.

The jaas.config file which is located in the file system at <connector install dir>/crx-quickstart/server/etc looks as follows:

For supported options see the JavaDoc of SharepointLoginModule which is located on the file system at <connector install dir>/crx-quickstart/docs/crx2sharepoint-auth-2.0.0-javadoc.jar.

The following diagram provides two detailed authentication scenarios: one with a CRX-only user, the other one with a SharePoint-only user.

In scenario 1, a user is present only in CRX (depicted with a circle on the diagram). When the user logs into the connector with credentials that are valid for CRX but not for SharePoint, he cannot access the SharePoint content mapped by the connector (under /mnt/sharepoint). The process goes as follows:

1. The user logs into the JCR application with his credentials.
2. The CRX Native JCR Repository authenticates the credentials and passes them to the CRX Login Module.
3. Based on the JAAS config, the first condition "CRX Login Module is sufficient" is true: the CRX Login Module authenticates the credentials and passes them to the Virtual Repository.
4. The Virtual Repository authenticates the credentials and passes them to the Connector.
5. The Connector authenticates the credentials and passes them to the SharePoint server.
6. The SharePoint server does not authenticate the credentials. The SharePoint server passes the failure back to the Connector.
7. The Connector does not authenticate the credentials and passes the failure to the Virtual Repository.
8. The Virtual Repository does not authenticate the credentials
9. The SharePoint content is not mapped to the node, the mount point stays empty.

In scenario 2, a user is present only in SharePoint (depicted with a square on the diagram). When the user logs into the connector with credentials that are valid for SharePoint but not for CRX (native repository), he can access the SharePoint content mapped by the connector (under /mnt/sharepoint). The process goes as follows:

1. The user logs into the JCR application with his credentials.
   
2. The CRX Native JCR Repository authenticates the credentials and passes them to the CRX Login Module.
3. Based on the JAAS config, the first condition "CRX Login Module is sufficient" is false as the credentials are not valid for CRX: authentication with the CRX Login Module fails and the credentials are passed to the SharePoint Login Module.
   
4. Based on the JAAS config, the second condition "SharePoint Login Module is required" is true: the credentials are authenticated and passed to the SharePoint Repository.
5. The SharePoint Repository authenticates the credentials and passes them to the Virtual Repository.
6. The Virtual Repository authenticates the credentials and passes them to the SharePoint Connector.
   
7. The SharePoint Connector authenticates the credentials and passes them to the SharePoint Repository.
8. The SharePoint Repository authenticates the credentials and passes them to the SharePoint Connector.
   
9. The SharePoint Connector authenticates the credentials and passes them to the Virtual Repository.
   
10. The Virtual Repository authenticates the credentials and sends the SharePoint mapped content to the user.
    
11. The user is able to browse the mounted SharePoint node.

 The scenario, where a user exists in both systems (with exactly the same credentials) has not been described as it is relatively straightforward. Such a user after successful login would have access to both CRX and SharePoint content (subject to respective permissions for that user in both systems).

When the JAAS authentication is disabled, only a user who is authenticated on both CRX and SharePoint can access the SharePoint content through the connector.

You can also use the connector extension for authentication to create a custom authentication module, which, e.g., maps access by CQ5 or CRX users to specific SharePoint users. The Authenticaion code example in Developing section below provides an example of how to achieve this.

To disable JAAS authentication, delete the JAAS configuration file jaas.config at <connector-install-dir>/server/etc/.

To configure authentication for Active Directory, you leverage the CRX LDAP Login Module so that the connector authenticates against the central Active Directory server that authenticates the SharePoint users. Follow the steps:

1. Set the LDAP Login Module in the JAAS configuration: edit the jaas.config file located on the file system at <connector-install-dir>/crx-quickstart/server/etc and replace the line:
   com.day.crx.spi.sharepoint.security.SharepointLoginModule required
   with following line:
   com.day.crx.security.ldap.LDAPLoginModule required
2. Set the other specific parameters of the Active Directory: refer to the the LDAP configuration in the CRX documentation.
   

The following diagram provides a detailed authentication scenario for an Active Directory based setup, where both CRX and SharePoint are configured to use the same Active Directory server and delegate authentication and user information retrieval to this server. Users are then managed in one place, which is a usual practice in enterprise deployments.

In Scenario 3, a user is managed centrally in an Active Directory server (depicted with a triangle on the diagram), and both CRX and SharePoint are configured to use the Active Directory server for user authentication. When the user logs into the connector with credentials that are valid on an Active Directory server that is used by both CRX and SharePoint, they can access the SharePoint content mapped by the connector (under /mnt/sharepoint). The process goes as follows:

1. The user logs into the JCR application with his credentials.
2. The CRX Native JCR Repository authenticates the credentials and passes them to the CRX Login Module.
3. Based on the JAAS config, the first condition "CRX Login Module is sufficient" is true: the CRX Login Module authenticates the credentials and passes them to the LDAP Login Module.
4. The LDAP Login Module authenticates the credentials and passes them to the Active Directory server.
5. The Active Directory server authenticates the credentials and passes them to the Virtual Repository.
6. The Virtual Repository authenticates the credentials and passes them to the SharePoint Connector.
7. The SharePoint Connector authenticates the credentials and passes them to the SharePoint Repository.
8. The SharePoint Repository authenticates the credentials and passes them to the Active Directory Server.
9. The Active Directory Server authenticates the credentials and passes them to the SharePoint Repository.
10. The SharePoint Repository authenticates the credentials and passes them to the SharePoint Connector.
11. The SharePoint Connector authenticates the credentials and passes them to the Virtual Repository.
12. The Virtual Repository authenticates the credentials and sends the SharePoint mapped content to the user.
13. The user is able to browse the mounted SharePoint node.

As a result the Active Directory managed user:

• Can access CRX content (subject to CRX permissions on „mirrored“ user / groups)
• Can access mounted SharePoint content (subject to SharePoint permissions on „mirrored“ user / groups)

In its standard version the connector supports the standard IIS Windows authentication method. The other authentication methods can be supported through the extensibility mechanism.

The following steps give some guidelines how to extend the standard authentication to support different authentication methods of the SharePoint server:

A sample implementation is available in the Authentication section for developers.

You can export the configuration by creating a content package:

1. Disable the mnt point to be within the package: set the param/etc/virtual-repositories/virtual-crx/mnt/sharepoint/.params/./enabled to false.
   Note: if it is not disabled, the Sharepoint content will also get exported (which is not wanted).
   
2. Include the node '/apps/crx2sharepoint/config' for the connector configuration in the content package.
   
3. Include /etc/virtual-repositories/virtual-crx/mnt for the virtual repository configuration in the content package.
   
4. Include the node /mnt/sharepoint in the content package.

Note: you can also recreate the packages included in the connector Quickstart package.

This section describes how various SharePoint features are mapped to the JCR 1.0 API. Content exposure, search and change observation are covered here. Note that the full JCR 1.0 functionality is not always available since SharePoint might not support it over its remote APIs.

The SharePoint connector exposes content from a Microsoft SharePoint server in a hierarchical way which is similar to the way by which the content is exposed by the native web interface.

To ease integration with existing CRX applications, the items of the hierarchy have a primary type of either nt:folder, nt:file or a specialization of these. Additional SharePoint specific characteristics are in some instances added by means of mixins (i.e. sp:Folder, sp:File, etc.). The SharePoint specific name space 'http://www.day.com/crx/sharepoint/1.0' (usually called sp when used as a prefix) is used for items controlled by the SharePoint server. Items controlled by the user - webs, documents, list items and the like - are in the default name space.

The connector allows write access to SharePoint document libraries. That is, it allows folders and files to be created within document libraries in correspondence with creating folders or uploading files to the native SharePoint web interface.

Limitation: Retrieving items by UUID only works for items which are cached locally. This is due to SharePoint's remote APIs not supporting the retrieval of items by their unique identifier.

The SharePoint connector supports queries using the JCR 1.0 XPath and SQL syntax. The behavior is however specific to SharePoint in several ways. The connector translates JCR 1.0 queries to SharePoint queries. These queries are executed on the SharePoint server, the result is then sent back to the connector which translates it to a JCR QueryResult. The two major consequences of this process are: features present in JCR 1.0 but not available in SharePoint queries are usually ignored, and items which are not indexed by the SharePoint server are not returned in the query result even though they match the query criteria. For example SharePoint servers, by default, do not index PDF documents so that full text search is not available for them. See http://support.microsoft.com/kb/927675/en-us for further details. If a full text search does not return the expected result, check whether the document is correctly indexed by SharePoint and whether the search terms are not excluded from indexing (i.e. noise words).

The SharePoint connector supports the following relational operators for comparison: =, >=, >, <=, <, LIKE, <>, IS NULL, IS NOT NULL. Predicates, descendants and self operators (//) are supported on the last location step. The following properties are supported for comparison: Size, Author, Modified, Url, Title, IsDocument, ContentClass, SiteName, Description, FileName, jcr:data, jcr:mimeType, jcr:created, jcr:lastModified.

Examples

The following configuration settings are available to fine tune the search behavior:

• 'Query Maximal Result Count': The maximum number of results to return from search. Corresponds to the count element in SharePoint's QueryPacket. See http://msdn.microsoft.com/en-us/library/ms409102.aspx.
  
• 'Query Ignore Noise': Specifies whether noise words in the search results should be ignored. Corresponds to the IgnoreAllNoiseQuery element in Sharepoint's QueryPacket. See http://msdn.microsoft.com/en-us/library/ms455211.aspx for details.
• 'Query Trim Duplicates': Enables collapsing of duplicate results in search results. Corresponds to the TrimDuplicates element in Sharepoint's QueryPacket. See http://msdn.microsoft.com/en-us/library/ms457559.aspx for details.
• 'Query Include Non Full Text Items': Items whose content is not full text indexed by the SharePoint server are not included in the search result by default. For such items it is in general not possible to reliably determine their NodeId. Including these items in the search result might lead to unexpected behavior.
• 'SharePoint Server Search Service': Determines the SharePoint search web service against which to execute queries. For 'auto detect' it is detected automatically by querying the server for the available services.

The connector supports JCR 1.0 compliant change observation for items inside document libraries. Observation must be enabled on a by path basis. Use the 'Observable paths' setting to add paths for which observation should be enabled. Enabling observation for a path results in observation events being generated for all items of document libraries on that path and its sub paths. Note that observation must maintain some meta data in memory, as the information returned from web services would not allow for JCR 1.0 compatible observation implementation. This results in growing memory requirements if many paths are configured for observation.

Observation regularly polls the SharePoint server for latest changes. The polling interval can be set by changing the value of the 'Observation polling interval' configuration setting.

Limitation: Observation events are generated as they are reported by the corresponding SharePoint server web service. This web service has in particular no support for the isLocal parameter of ObservationManager#addEventListener. Furthermore changes which cancel each other (like adding and removing an item immediately after) might not be reported by the web service.

This section covers performance optimization of the connector deployments.

When working on system perfomance optimization, consider that the connector deployment is just a part of a bigger system that delivers certain functionalities to users (usually related to content integration or federation).  Performance optimization should always be considered in the context of the whole system and the specific use cases and performance benchmarks that are valid and relevant for the end user. Performance of the connector itself might be irrelevant or negligible in this context.

The following parts of the overall connector deployment architecture need to be considered:

• Application layer performance (outside of the scope of this document)
  
• Connector instance performance (covered)
  
• Network infrastructure performance (partially covered)
• SharePoint infrastructure performance (outside of the scope of this document)
• Servers and storage performance (outside of the scope of this document)

The following sections give guidance on what aspects of the connector instance and network infrastructure could be used to optimize performance of deployments using the connector.

The connector uses a built-in JCR item cache to optimize access to nodes and properties by JCR sessions. You might use the Item Cache Size configuration parameter of the connector to fine-tune the cache size to give your system a better overall performance. The default setting should work reasonably well for most of the cases, but fine-tuning might help achieve better performance for specific use cases and system characteristics.

Having a performant and properly configured network infrastructure (between the connector instance and the SharePoint server) is the key aspect of achieving the good performance of the connector deployment (measured from the JCR API level to the SharePoint server). This part of the infrastructure should be set up, configured and managed by IT Operations, and optimized for the use of SOAP-based web services used by the connector as a client access protocol to the SharePoint server.

One of the important aspects of the proper network setup in case of performance concerns identified in this infrastructure layer is fine-tuning of the delay or timeout for the so-called TIME_WAIT state in the TCP/IP protocol on the server, where the connector instance is running. This parameter (called TCPTimedWaitDelay, timeout_timewait,  TCP_TIMEWAIT, or TCP_TIME_WAIT_INTERVAL depending on the operating system) determines the time that must elapse before TCP/IP can release a closed connection and reuse its resources. This interval between closure and release is known as the TIME_WAIT state or twice the maximum segment lifetime (2MSL) state. During this time, reopening the connection to the client and server costs less than establishing a new connection. By reducing the value of this entry, TCP/IP can release closed connections faster and provide more resources for new connections. Adjust this parameter if the running application requires rapid release, the creation of new connections, or an adjustment because of a low throughput caused by multiple connections in the TIME_WAIT state.  

The subsections below provide a high-level descriptions of how this parameter can be fine-tuned in popular server operating systems. Please refer to your operating system's documentation to make sure what is the supported way of setting this parameter.

This section describes how to tune Windows 2000, Windows XP, and Windows 2003 operating systems to optimize the performance of SharePoint connector.
When you have a performance concern, check the operating system settings to determine if they are appropriate for your application.

Configure the following settings or variables according to your specific tuning needs:

TCPTimedWaitDelay

To view or set TCPTimedWaitDelay:

1. Use the regedit command, access the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Services\TCPIP\Parameters registry subkey, and create a new REG_DWORD value named TcpTimedWaitDelay.
2. The default value is 0xF0, which sets the wait time to 240 seconds (4 minutes). It is recommended to set the value to a minimum value of 0x1E, which sets the wait time to 30 seconds.
   
3. Stop and restart the system.

MaxUserPort

MaxUserPort determines the highest port number that TCP/IP can assign when an application requests an available user port from the system.    

To view or set MaxUserPort:

1. Use the regedit command, access the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Services\TCPIP\Parameters registry subkey, and create a new REG_DWORD value named MaxUserPort.
2. It is recommended to set this value to at least decimal 32768. Note: it does not have a default value.
3. Stop and restart the system.

This section describes how to tune the Linux operating system to optimize the performance of the connector.    
Configure the following settings and variables according to your tuning needs.    

timeout_timewait

To view or  set the timeout_timewait parameter to 30 seconds, issue the following command in the terminal:

This section describes how to tune the AIX operating system to optimize the performance of the connector.    
Change the following configuration settings or variables according to your needs.

TCP_TIMEWAIT

To view or set TCP_TIMEWAIT state to 15 seconds, issue the following command in the terminal:

The following tuning parameter is specific to the Solaris operating system.    
Configure the following setting according to your tuning needs.

Solaris TCP_TIME_WAIT_INTERVAL

The default time wait interval for a Solaris operating system is 240000 milliseconds, which is equal to 4 minutes. It is recommended to set the value to 60000 milliseconds.

Use the get command to determine the current interval and the set command to specify an interval of 60 seconds. For example:

This section describes a few examples how to extend the out of the box functionalities of the connector.

This example application demonstrates how the CRX2Sharepoint connector can be used by scripts. After installing this package point your browser to http://localhost:7402/apps/sharepoint/explorer.html

Simple authentication example which maps all non anonymous users to admin/admin. Usage: Install the OSGi bundle and set Sharepoint Connection Factory to com.day.crx.spi.sharepoint.auth.CustomConnectionFactory on the configuration screen, restart CRX.

This example registers a resource provider which maps the CRX2Sharepoint content to the URL space. Usage: Install the OSGi bundle and optionally set configuration parameters for it (CRX2Sharepoint Resource Provider Example Application). Sharepoint content is by default mapped to the root URL /crx2sharepoint (for example http://localhost:7402/crx2sharepoint/sp:Site.2.json).

This example shows how to use JCR observation with CRX2Sharepoint. Observation must be properly configured (Observable Paths) in the CRX2Sharepoint configuration in order for this example to work.

This section lists all licenses, copyright notices and disclaimers which must be explicitly stated in connection with the Day JCR Connector for SharePoint.

The connector for SharePoint is covered by the following license.

Third-Party License Agreements