Don't miss out Virtual Happy Hour this Friday (April 26).

Try our conversational search powered by Generative AI!

AI OnAI Off

EPiServer Connect for Microsoft SharePoint 2007

NOTE! This technical note is for EPiServer Connect for SharePoint version 1.0 only (for EPiServer CMS 5.1 SP1). Technical notes can be found for version 2.0 of EPiServer Connect for SharePoint.

Introduction

This technical note contains functional and technical information for the EPiServer Connect for Microsoft SharePoint 2007 functionality.

Table of Contents

Overview

The EPiServer Connect for Microsoft SharePoint 2007 allows the export of list items and documents from WSS 3.0 or MOSS 2007 (hereby known collectively as SharePoint) to EPiServer CMS. Examples of list items are calendar items, tasks, announcements and custom items. Each item exported from SharePoint to EPiServer CMS becomes a page in EPiServer CMS, documents are imported untouched. Each SharePoint item has fields. These fields are mapped to EPiServer CMS page type properties using the mappings created. See the EPiServer CMS Content Channels section below for details of this.

Components

The EPiServer Connect for Microsoft SharePoint 2007 consists of .NET assemblies, web services, web pages and resource files that get installed on the SharePoint and EPiServer CMS server machines.

EPiServer CMS Components

The EPiServer CMS components consist of a web service and some administrative web pages. The web service is called the EPiServer Content Channel Service (ContentChannelService.asmx). While this is used by the EPiServer Connect for Microsoft SharePoint 2007, it is not restricted to this use.

SharePoint Components

The SharePoint components consists of a .NET assembly DLL, some .aspx pages, some .resx resource files and the relevant feature and element XML files to install them in SharePoint.

Installation

SharePoint

All of the SharePoint components for the connector are packaged in the SharePointConnector.wsp solution file for easy installation. To start using the feature the solution needs to be added and deployed on the SharePoint server. To do this the stsadm.exe tool shipped with SharePoint is used. This command line application can normally be found in the SharePoint BIN folder. SharePoint is normally installed under <drive>\Program Files\Common Files\Microsoft Shared\web server extensions\12. The 12 folder indicates that the installation is WSS 3.0 or MOSS 2007. To deploy the solution in SharePoint:

  • First ensure that the Windows SharePoint Services Timer service is running as the deploysolution command below relies on it. Then use the stsadm tool to do the following:
  • stsadm -o addsolution -filename <path to file>\sharepointconnector.wsp. The <path to file> part should be replaced with the actual path of where the .wsp file is in the file system.
  • stsadm -o deploysolution -name sharepointconnector.wsp -immediate -allowGacDeployment. The deploysolution command is aynchronous which means you need to repeat the following displaysolution command until deploysolution has completed.
  • stsadm -o displaysolution -name sharepointconnector.wsp. This command shows an XML block for the solution. When the deploysolution command has completed the <LastOperationResult> XML element will display either DeploymentSucceeded or DeploymentFailedXXXX where XXXX is the failure reason.
  • stsadm -o copyappbincontent. Do not run this command until displaysolution indicates a successful deployment.

After the solution has been deployed, the features installed need to be activated for the desired SharePoint web sites. To activate the features do as follows:

  • Go to the Site Settings page for the desired SharePoint site. This can normally be accessed from the Site Actions menu.
  • From the Site Settings page access the Site Feature page by clicking the Site Feature link in the Site Administration column.
  • On the Site Feature page there should be two EPiServer SharePoint Connector features listed.
  • Activate the EPiServer CMS 5 SharePoint Connector Administration feature
  • Activate the EPiServer CMS 5 SharePoint Connector Event Listener feature

After activation the EPiServer CMS 5 SharePoint Connector Configuration link should be visible on the Site Settings page under the Site Administration column.

The connector stores information about channels in an XML configuration file. The code automatically creates this file the first time it is needed if it doesn't exist, however 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. The web.config for the SharePoint web application can normally be found at <drive>\inetpub\wwwroot\wss\VirtualDirectories\<port> where <drive> is the drive where IIS is installed and <port> is the port number for the web application to be used (e.g. 80). In the web.config file under the <configuration><appSettings> section, a new entry should be added with a key of 'epiServerConnectorConfigRelativePath' and a value of a file path which is relative to the folder that the web.config file is in. For example, to store the config in a file called 'EPiServerSharePointConnector.config' in the same folder as the web.config file the entry would be:

<?xml version="1.0" encoding="utf-8"?>

<configuration>

  <appSettings>

     <add key="epiServerConnectorConfigRelativePath"

          value="EPiServerSharePointConnector.config" />

  </appSettings>

</configuration>

Updating EPiServer Connect for Microsoft SharePoint 2007 in SharePoint

The stsadm command line tool can be used to do this. Use the following commands:

  • stsadm -o upgradesolution -name sharepointconnector.wsp -filename <path to file>\sharepointconnector.wsp -immediate -allowgacdeployment.The <path to file> part should be replaced with the actual path of where the .wsp file is in the file system. The upgradesolution command is aynchronous which means you need to repeat the following displaysolution command until it has completed.
  • stsadm -o displaysolution -name sharepointconnector.wsp. This command shows an XML block for the solution. When the upgradesolution command has completed the <LastOperationResult> XML element will display either DeploymentSucceeded or DeploymentFailedXXXX where XXXX is the failure reason.
  • stsadm -o copyappbincontent. Do not run this command until displaysolution indicates a successful deployment.

Removing EPiServer Connect for Microsoft SharePoint 2007 from SharePoint

Before removing the connector solution from SharePoint, you need to de-activate it's features in all of the SharePoint sites where it has been activated. This is done on the Site Features page for each site.

The stsadm command line tool can be used to do the rest. Use the following commands:

  • stsadm -o retractsolution -name sharepointconnector.wsp -immediate. The retractsolution command is aynchronous which means you need to repeat the following displaysolution command until retractsolution has completed.
  • stsadm -o displaysolution -name sharepointconnector.wsp. This command shows an XML block for the solution. When the retractsolution command has completed the <LastOperationResult> XML element will display either RetractionSucceeded or RetractionFailedXXXX where XXXX is the failure reason.
  • stsadm -o deletesolution -name sharepointconnector.wsp

 Syntax for all the stsadm commands can be found on Microsoft's TechNet site. 

EPiServer CMS

The connector is reliant on EPiServer CMS 5 Service Pack 1 running in the target site which you install via the EPiServer CMS Manager.

Configuring EPiServer CMS Web Services

Configure EPiServer CMS Web services according to the instructions in the Web Services technical note.

Channels

To make the connection between SharePoint and EPiServer CMS, a channel must be created on both sides. On the SharePoint side this is known as an EPiServer Channel and on the EPiServer side it is known as a Content Channel.

EPiServer CMS Content Channels

Content Channels in EPiServer CMS are administered via the Content Channels link on the Admin tab in Admin mode.  To create a channel the following information is needed:

  • Channel Name - The name of the channel. This is the name that should be entered in the EPiServer Channel Name field when creating a channel in SharePoint.
  • Page Root - The EPiServer CMS page that the imported pages will be created under.
  • Virtual Root for Files - The destination folder that imported files will be copied to.
  • 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 sets of mappings between a page type's properties to alternative names.
  • None mapped page types - Pages types that do not yet have a mapping of its properties to alternative name. See comments below with specific reference to importing SharePoint items.

The fields to be exported for SharePoint items should have their names mapped for 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. Alternatively, this can be handled in the pre event handler available in the EPiServer CMS SharePoint Connector component in SharePoint or in the Content Channel Service on the EPiServer side.

SharePoint Channels

Channels in SharePoint are created and administered via the SharePoint web user interface. Once the necessary components have been installed and activated for a site, then a new link called "EPiServer CMS 5 SharePoint Connector Configuration" should be visible on the Site Settings page for the site. This link leads to a page where channels can be created, edited and deleted. It should be noted that channels are site specific and therefore channels created on one site are not visible from another.

To create a channel the following information is needed:

  • Display Name - The name you wish to assign to this channel.
  • EPiServer Channel Name - The name of the corresponding channel in EPiServer to send content to.
  • EPiServer Url - This is the Url to the EPiServer Content Channel Service. For example http://<hostname>/WebServices/ContentChannelService.asmx. The <hostname> should be replaced by the name of the server hosting EPiServer.
  • EPiServer Username - the username to use to access the EPiServer Content Channel Service.
  • EPiServer Password - the password to use to access the EPiServer Content Channel Service.
  • SharePoint Lists - The types of items that should be exported to EPiServer by this channel.
  • SharePoint Libraries - The document folders that should be exported to EPiServer by this channel.

Permissions for Functions

Because the EPiServer Content Channel Service is a web service, you must give a user the permission to act as a web service user. This is done in EPiServer Admin mode on the Config tab using the Permission for Functions link. It is this user that you enter the details for when creating an EPiServer channel on the SharePoint server.

Extensibility

EPiServer Connect for Microsoft SharePoint 2007 is extensible in code on both the SharePoint and EPiServer side by subscribing to the events published. See below for details:

Extensibility on the SharePoint side

The class EPiServer.SharePointConnector.EventListener.ListItemSender which can be found in the EPiServer.SharePointConnector.dll exposes the following static events:

  • ListItemExporting - Fired before a list item is exported to EPiServer, supports cancelling the action.
  • ListItemDeleteExporting - Fired when a list item has been deleted but before the notification is exported to EPiServer, supports cancelling the action.
  • FileExporting - Fired before a file is exported to EPiServer, supports cancelling the action.
  • FileDeleteExporting - Fired when a file has been deleted but before the notification is exported to EPiServer, supports cancelling the action.
  • FileMetadataUpdateExporting - Fired when a file's metadata has been updated but before the notification has been sent to EPiServer, supports cancelling the action.

Extensibility on the EPiServer CMS side

The class EPiServer.ContentChannels.ContentChannelHandlerBase which can be found in the EPiServer.ContentChannelService.dll exposes the following static events:

  • FileImporting - Fired before a file is imported, supports cancelling the action.
  • PageFileImporting - Fired before a file is imported to the page file folder, supports cancelling the action.
  • FileImported - Fired after a file has been imported.
  • PageImporting - Fired before a page is imported, supports cancelling the action.
  • PageImported - Fired after a page has been imported.
  • FileDeleting - Fired before a file is deleted, supports cancelling the action.
  • FileDeleted - Fired after a file has been deleted.
  • PageDeleting - Fired before a page is deleted, supports cancelling the action.
  • PageDeleted - Fired after a page has been deleted. 
  • FileMetaDataImporting - Fired before a file's metadata has been imported. This event does not support cancelling directly, however the same effect can be achieved by clearing the Metadata dictionary property on the FileMetaDataImportingEventArgs class passed.

Known Limitations

Each item exported from SharePoint will get the same identity (GUID) in EPiServer that it has in SharePoint. A consequence of this is that you can not have a one to many mapping from SharePoint to EPiServer. That is, you cannot map one item from SharePoint to end up as several items in EPiServer (e.g. by configuring a SharePoint item in several Content Channels with different roots on the same EPiServer site).

EPiServer Connect for Microsoft SharePoint 2007 currently has some limitations due to problems with determining the cause of the SharePoint Updating and Updated events. When Metadata is entered or edited for a file, the file contents (as well as the metadata) will be sent to EPiServer. This means that file data will be sent even when the actual file hasn't changed. As a result, the FileMetadataUpdating event will never be fired.

Troubleshooting

Items are created or edited in SharePoint but nothing appears in EPiServer CMS

When items are created, edited or deleted in SharePoint, the connector is notified of these changes via a background event. Any errors that occur sending the changes to EPiServer CMS cannot be reported to the user directly as this component has no way of interacting with the SharePoint GUI. Because of this limitation, all errors are writen to the Windows Event Application Log. The source name to look for is "EPiServer SharePoint Connector".

The most likely errors relating to SharePoint items not appearing in EPiServer CMS are:

  • The EPiServer URL in the channel is not pointing at a EPiServer CMS Content Channel web service. See the section on SharePoint Channels above.
  • The EPiServer Username or Password in the channel are invalid on the EPiServer CMS machine.
  • The EPiServer Username identifies a user on the EPiServer CMS machine that does not have the "Permission to act as a web service user".
  • No SharePoint list items or document libraries have been selected in the channel
  • No page type has been selected in the Content Channel in EPiServer
  • No mapping has been made between a field on the SharePoint list item and the EPiServer PageName property for the seleted page type in the Content Channel in EPiServer

Metadata for a file imported from SharePoint cannot be edited

The user interface in EPiServer CMS for editing file metadata uses the EPiServer X-Forms technology. The root catalogue of the EPiServer CMS web site should contain a file called FileSummary.config. This file contains the mappings between file metadata names and the X-Forms GUI elements in the Metadata editing page. In order to edit metadata for files imported from SharePoint, the FileSummary.config file must be updated with the metadata names that SharePoint generates for files.

Last updated: 2008-05-05