EPiServer Connect for SharePoint
Installation Instructions

Introduction

This document describes the installation procedure for EPiServer Connect for Microsoft SharePoint 2.1 module on a EPiServer CMS 5 R2 SP1 Web site.

Installation of the EPiServer Connect for SharePoint 2.1 module is performed by carrying out several steps; including installation of the EPiServer Connect for SharePoint 2.1 module on the EPiServer CMS application and also deployment and configuration on the Microsoft SharePoint application.

Contents

• Prerequisites
• Components
• SharePoint Module Installation on EPiServer CMS
• VPP Installation, Configuration and Verification
• SharePoint Solution Deployment
• Web Parts Configuration
• Content Channel Configuration
• Web Services Authentification Configuration
• SharePoint Web site Configuration
• Uninstalling the SharePoint Solution
• Module Installation Restriction

Prerequisites

Listed below are the prerequisites that must be fulfilled before installing the EPiServer Connect for SharePoint module:
• Installation of the EPiServer CMS 5 R2 SP1 assemblies and its prerequisites.
• EPiServer CMS 5 R2 SP1 Web site creation and its prerequisites.
• Microsoft Office SharePoint Server 2007 or Windows SharePoint Service 3.0 must be installed (and the corresponding prerequisites).

Components

wsp file

This EPiServer Connect for Microsoft SharePoint 2.1 wsp file (SharepointConnector.wsp) is an Windows SharePoint Services Solution Framework File,  this file is used to deploy the EPiServer Connect for Microsoft SharePoint 2.1 solution onto Microsoft SharePoint Services. Information about using the this file (Windows SharePoint Services Solution Framework File) can be found  in the SharePoint Solution Deployment section in this document.

msi file

The Microsoft installation file installs the module

EPiServer.SharePointWebParts.zip 

Source code for Web Parts - used by the wsp file.

SharePoint Module Installation on EPiServer CMS

1. Run the EPiServer Connect for Microsoft SharePoint 2.1.msi installation package on the computer where you want to install the module. Wait until the installation process is complete.
2. Run the EPiServer Deployment Manager.
3. Select the Install EPiServer Connect for Microsoft SharePoint item in the tree list and press the Run button.
   
4. In the following dialog box select the EPiServer CMS Web site where you want to install the module and press the Next button.
   
5. The following dialog that will appear is used to configure the settings for the EPiServer Connect for Microsoft SharePoint module. Here you can enter three groups of module parameters, which are described below. Add the relevant information in the dialog and press the Next button.
   
   If this attempt is not successful insert the correct settings and press the Next button.
   
   
   The following is a short description of the parameters that can be enterred in this dialog:
   a) The Virtual Path parameters:
   • The Virtual root path is the path of the virtual path provider for Microsoft SharePoint.
   • Select the Allow to open any file from this virtual path check box if you want to enable access to the files of any type using this virtual path provider.
     
   b) The SharePoint configuration:
   • By selecting one of the SharePoint environment radio buttons you indicate whether the WSS or MOSS environment is used by this module. This option is important for Search operations in the virtual path provider for SharePoint.
   • Site URL is the URL to the SharePoint site for connection.
   • Domain is the domain name connection to SharePoint. This is an optional parameter.
   • User login is the user name for connection to SharePoint.
   • Password is the password for connection to SharePoint.
   • Target library or folder on SharePoint which will be used as the root directory for the virtual path provider. If this parameter is not filled in then all directories will be accessible through the virtual path provider.
   • The Test connection button is used to test if your connection settings are accessible.
   • Select Use impersonation mechanism if you want to use an impersonation authorization mechanism based on Kerberos protocol. See the Security and Delegation tech-note (EPiServer Connect for Microsoft SharePoint 2.1) for information regarding this.
   
   c) Caching configuration:
   • Select the Enable cache checkbox if you want the metadata and file content from SharePoint to be cached on the EPiServer CMS R2 SP1 Web site machine.
   • Cache expiration time is the time span in seconds to store values in the cache.
   • The ASP.NET application must have read/write access to the files in the temporary files folder.
   • The Temporary files folder is the folder on the file system which will be used to store temporary cached file content. Click on the button to the right of this field in order to choose this directory through the open folder dialog. If this field is not filled in then a temporary system folder will be used.
   
   
6. In the next step you can provide a full path for the EPiServer Connect for SharePoint license file. You may leave the path empty if you already have copied the license file into the Web application folder or shall do so after installation of the module. Press the Install button and wait until installation is complete.
   

VPP Installation, Configuration and Verification

• Open your EPiServer CMS 5 R2 SP1 Web site.
• Login with a user account with sufficient rights  to enter Edit mode.
• Go to the Edit mode.
• Open file manager.
• Find ”SharePoint” below ”Starting points” section.
• Try to list the SharePoint libraries and folder, open files and edit file Meta data.

SharePoint Solution Deployment

1. Download the SharepointConnector.wsp file and save it in a location available to Windows SharePoint Services or the Microsoft Office SharePoint Server.
2. Make sure that the Windows SharePoint Services Timer service is running. (The service can be found here: Start - Control Panel - Administrative Tools - Services)
3. Open Microsoft Windows Command Prompt (Start – Programs – Accessories - Command Prompt).
4. From the command prompt run the following commands in the order that they are described below:
   a) cd <system drive>:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN - this command changes the current directory to the directory that contains stsadm.exe tool (administrative tool for SharePoint). The parameter <system drive> must be replaced with the actual system drive on the computer that runs SharePoint.
   
   b) stsadm -o addsolution -filename <path to file>\SharepointConnector.wsp – this command adds the EPiServer Connect for SharePoint 2.1 solution to the Microsoft SharePoint application.
   
   c) stsadm -o deploysolution -name SharepointConnector.wsp –immediate –allowGacDeployment –url <application url> - this command deploys the solution onto the Microsoft SharePoint Web site. The <application url> parameters must be replaced with the actual URL of the Microsoft SharePoint Web site. Please note! As this command runs asynchronously, you are required to enter the command described below in d) until checking of the deployment status is complete.
   
   d) stsadm -o displaysolution -name SharepointConnector.wsp – this command shows the status of the deploying process, when the command described in c) is complete you should be able to find the result under the <LastOperationResult> section (only for Windows SharePoint Services). "DeploymentSucceeded" will appear when deployment is successful or “DeploymentFailedXXXX” will be displayed when deployment was not sucessful (XXXX will denote the error code).
   
   e) stsadm -o copyappbincontent – this command copies content to SharePoint. Do not run this command until the command descibed under d) is complete and deployment has been successful.
   
   
5. After installation has been completed Web Parts should then be added to the Web site Web Parts gallery. This can be carried out in the following way:
   a) Go to:  Site Actions – Site settings –Galleries – Web Parts – New, and select EPiServer.SharePointWebParts.PageListWebPart and EPiServer.SharePointWebParts.PageViewWebPart and click on the Populate Gallery button.
   
   b) Locate and select the following two new Web Parts in the gallery:
   
   c) Click on the Edit document properties button and fill in the Title, Description and Group fields and press the OK button.
   
   
   

Web Parts Configuration

After adding Web parts on the page you need to configure it to establish a connection to the EPiServer CMS R2 SP1 Web site. Click Edit\Modify Shared Web Part.

            
 Web Parts consist of the following connection parameters:

• Web service URL – is the address of the EPiServer PageStore Web service (for example: http://website.com/WebServices/PageStoreService.asmx);
• User name – EPiServer user name;
• User password – EPiServer user password. Click the Change password button if you want to change the existing password. The field to enter the mew password will then appear.
• Root Page Id (only for PageListWebPart) – is the id of the EPiServer page that will be used as the root of the page tree.
• Page id (only for PageViewWebPart) – is the id of the EPiServer page to display.
• EPiServePageProperties (only for PageViewWebPart ) – allows you to choose which properties will be displayed. Note that the list of available properties appears only when the connection parameters properly configured and Page Id points to existing EPiServer page. PageListWebPart and PageViewWebPart can be connected to each other. If connection between these parts is established then the PageViewWebPart displays the content of the page selected in PageListWebPart. Both Web Parts should have correctly configured connection parameters.

Content Channel Configuration

1. The connector stores information about channels in an XML configuration file. The application automatically creates this file the first time it is required if it does not already exist. The path to where this file should be stored needs to be entered into the web.config file for the SharePoint Web application hosting the connector. See below for the configuration which needs to be added to the web.config file:
   
   a) Locate the webconfig file for the SharePoint Web application. It can normally be found at <drive>\inetpub\wwwroot\wss\VirtualDirectories\<port>. <drive> is the drive where IIS is installed and <port> is the port number for the web application to be used (e.g. 80).
   
   b) Add the next line to <configuration> - <appSettings> section (If this section does not exist you need to also add to this):
   <add key="EPiServerConnectorConfigRelativePath" value="EPiServerSharePointConnector.config" />
   
   c) You can modify or add the value above if you choose to place the configuration file in another location.
   
   d) Make sure that SharePoint application pool process has read and write access rights for the directory where specified EPiServerSharePointConnector.config file is going to be located.
   
   
2. You also need to create or make sure that the Content Channel exists and is correctly configured on the EPiServer CMS Web site:
   
   a) Log on to the EPiServer CMS Web site with an account that has Administrator rights for the Web site. 
   b) Switch to Admin mode.
   c) Select Content Channels on the Admin tab.
   
   d) Click Add if you need to add a Content Channel, or click the Edit button to change the parameters of an existing Content Channel.
   
   
   The following is a description of the Content Channel configuration parameters:
   Channel name – name of content channel. This name will be used then you set up connection parameters on the SharePoint Web site
   Page root – the EPiServer CMS page that the imported pages will be created under.
   Default Page Type – the default page type to use if one is not specified when creating imported pages.
   Save Action – the save action to use when creating imported pages.
   Mapped page types – one or more set(s) of mappings between a page type's properties to alternative names.
   Unmapped page types – pages  types that do not yet have a mapping of its properties to alternative name. See the text Importing SharePoint Items Issues below about issues when importing SharePoint items.
   
   e) Click on the Save button to apply the changes.
   
   Importing SharePoint Items Issues
   The fields to be exported for SharePoint items should have their names mapped to the desired page types for each EPiServer CMS Content Channel to be used. If no mappings are created then EPiServer will only import properties whose names match that of the properties of the page type being used. Note that you must create a mapping in the EPiServer Content Channel from a field on the SharePoint item to the EPiServer PageName property. If no mappings are created then EPiServer will only import properties whose names match that of the properties of the page type being used. 

Web Services Authentification Configuration

The following changes need to be applied in the configuration of the EPiServer CMS Web site:

1. Open the web.config file for the EPiServer CMS Web site.
2. Find the section <configuration> – <system.web> - <httpModules>. Uncomment or if not present add the EPiServer CMS Basic Authentication Module below configuration, see below:
   <add name="BasicAuthentication" type="EPiServer.Security.BasicAuthentication, EPiServer" />
3. Find the section <configuration> - <location path=”WebServices”>. Ensure that EPiServer Basic authentication is switched on in this location. Check the next line or add it if it does not already exist:
   <EPiServer.basicAuthentication sendBasicChallenge="true" basicRealm="" />
4. Find the section <configuration> - <location path=”WebServices”> - <system.web> - <authorization>. Check that the User you chose to connect from SharePoint is allowed to enter this location (or group which contains that particular user).

The following changes need to be applied to the Authentication mode for the Web site on the Internet Information Services:

1. Open the IIS Manager (Start – Settings – Control Panel – Administrative Tools – Internet Information Services (IIS) Manager).
2. In the IIS Manager open EPiServer CMS Web site properties.
3. Select the Directory Security settings tab.
4. Click on the Edit button under “Authentication and access control”.
5. Select the Basic authentication (password is sent in clear text check box. Ensure that the other check boxes are not selected.
   
6. Click the OK button.
7. Restart the Web site or apply the IIS reset to approve changes.

Ensure that the user has the appropriate permissions and can act as a Web service user on the EPiServer CMS Web site, see below :

1. Log on to the EPiServer CMS Web site with an account that can provide administration access for the Web site.
2. Switch to Admin mode.
3. Select Permissions for Functions on the Config tab.
4. Click on the Edit button for the Allow the user to act as a web service user function.
5. Ensure that the user has permission to use this function (or the group that the user belongs).
   

SharePoint Web site Configuration

The following is a description of how to configure the SharePoint Web site:

1. a) Go to: Site Actions – Site settings –Site Administration – Site features
   b) Click on the Activate button adjacent to the EPiServer CMS 5 SharePoint Connector Administration item.
   c) Click on the Activate button adjacent to the EPiServer CMS 5 SharePoint Connector Event Listener item.
   d) Verify that they are activated.
    
2. On this page you can manage the content channels that are used for the connection to the EPiServer CMS system. If you do not have any configured content channels or want to create a new one  see below:
   a) Go to: Site Actions – Site settings –Site Administration – EPiServer Connect for SharePoint page.
   b) Click the Add new button. Here you are also able to edit any existing content channel to work with your EPiServer CMS Web site.
   
   c) Click on the Test connection button to verify the properties.

The EPiServer CMS Content Channel configuration consists of the following parameters:

• Name – name of the content channel to display on the  EPiServer CMS Channel page.
• EPiServer Channel – name of the existing content channel on the EPiServer CMS Web site (you may have created it in the previous stage - 2b).
• EPiServer Content Channel Service – the connection settings to the EPiServer CMS. 
  EPiServer Web Service URL – a valid URL to the EPiServer CMS Content Channel web service (for example http:///WebServices/ContentChannelService.asmx)
  EPiServer Username – name of the user that will be used to connect to EPiServer CMS. 
  EPiServer Password – the password to connect to EPiServer CMS. If you are editing an existing content channel, you will see the Change password button instead of an input field. Click the Change password button if you want to change the password for the connection.
• SharePoint Content – the content that will be accessed through the channel.
  SharePoint Lists - The types of items that should be exported to EPiServer by the channel. 
  SharePoint Libraries - The document folders that should be exported to EPiServer by the channel.

Uninstalling the SharePoint Solution

Please note that if you installed the connector with a custom name forgot its name then you can use the STSADM to view a list of solutions deployed to the server using the enumsolutions operation (stsadm.exe -o enumsolutions).

1. Ensure that the “Windows SharePoint Services Timer” service is running. (Verify this by opening Services: Start - Control Panel - Administrative Tools - Services).
2. Open the Microsoft Windows Command Prompt (Start – Programs – Accessories - Command Prompt).
3. Run the following commands from the command prompt:
   • stsadm -o retractsolution -name SharepointConnector.wsp –immediate –url <application url> - this command retracts the solution from the SharePoint Web site. The <application url> parameters must be replaced with the actual URL of the Microsoft SharePoint Web site. This command runs asynchronously, so you are required to enter the next command until it finishes checking the status of deploying solution.
   • stsadm -o displaysolution -name SharepointConnector.wsp – this command shows the status of the deploying process, when the previous command is completed, you can find the result under the <LastOperationResult> section (for Windows SharePoint Services only). It could be “RetractionSucceded” in case of fine deployment or “RetractionFailedXXXX” in case of any error either (XXXX would show the error code).
   • stsadm -o deletesolution -name SharepointConnector.wsp – this command removes the solution from SharePoint. Do not run this command until the previous command shows “RetractionSucceded”.
   
   

Module Installation Restriction

There are restrictions regarding the installation of EPiServer modules after installation of the EPiServer Connect for SharePoint module.  This issue occurs due to a conflict between SharePoint virtual path provider and the installer initialization procedure. To avoid this error it is possible to turn off the SharePoint virtual path provider for the time of installation. Follow the instructions below if you have already installed the EPiServer Connect for SharePoint and wish to install another EPiServer module, for example EPiBooking:

1. Open the web.config file of your web site (in any text editor).
2. Locate  the“configuration – episerver – virtualPath – providers” section.
3. Comment out all lines which store settings for SharePoint virual path provider (those are lines
   there the “type” attribute is equal to “EPiServer.VirtualPathWssProvider.VirtualPathWssProvider,EPiServer.VirtualPathWssProvider”). (To comment out the lines paste “<!--“ before it and “-->” after the text.)
4. Save and close the web.config file.
5. Install the desired module with the EPiServer Installation Manager.
6. Open the web.config once again.
7. Uncomment the SharePoint virtual path provider lines and save the  web.config file.
8. The module should have been installed succesfully on the EPiServer CMS R2 SP1 Web site.