The Problem

In a somewhat boneheaded move I was trying to use a local directory the destination to back up my SharePoint 2013 Lab farm:

PS C:\Users\alexsmith.SPSEARCHDEMO> Backup-SPFarm -Directory D:\SPFarm-backup\ -BackupMethod Full –Verbose

This resulting in plenty of errors and warnings in the backup log:

[2/6/2014 4:54:51 PM] Finished with 54 warnings.
[2/6/2014 4:54:51 PM] Finished with 9 errors.
[2/6/2014 4:54:51 PM] FatalError: Backup failed for Object User Profile Service Application_SocialDB_bfef37f1886f4d0f847d518ad8320c49 failed in event OnBackup. For more information, see the spbackup.log or sprestore.log file located in the backup directory.
[2/6/2014 4:54:51 PM] -------------------------------------------------

Further investigation of the log file (D:\SPFarm-backup\spbr0000\spbackup.log) showed:

[2/6/2014 4:53:26 PM] FatalError: Object User Profile Service Application_SocialDB_bfef37f1886f4d0f847d518ad8320c49 failed in event OnBackup. For more information, see the spbackup.log or sprestore.log file located in the backup directory.
     SqlException: Cannot open backup device 'D:\SPFarm-backup\spbr0000\00000081.bak'. Operating system error 3(The system cannot find the path specified.).

First I checked the permissions on the destination directory, and made sure that my admin account had db_owner permissions on the databases, etc.  Then I remembered this bit of information from the TechNet doc for the Backup-SPFarm cmdlet:

“…if SQL Server 2008 and SharePoint 2010 Products are installed on multiple computers or if you have multiple servers running SharePoint 2010 Products, you must use Universal Naming Convention (UNC) share paths so that the SQL Server database and search components are written to the same location; for example, \\computer_name\volume\Backup).”

My lab farm has separate SQL and SharePoint servers, and so the SQL server was trying to write to it’s local D: drive where that directory didn’t exist!

The Solution

The fix was to create a network share accessible to the SharePoint and SQL servers. You shouldn't use the administrative shares e.g. \\servername\d$, because the permissions won't be correct.
Permissions on the share and the underlying directory should include “Full Control” for the account you run the backup from, plus the SQL service account. I’m using a Managed Service Account for SQL, but it worked the same as a normal user account.

Once my share was set up, I adjusted my the cmdlet to use the UNC path for the share, and the backup completed successfully:

PS C:\Users\alexsmith.SPSEARCHDEMO> Backup-SPFarm -Directory "\\spsearchwfe01\SPFarm-backup" -BackupMethod Full –Verbose

...

Finished with 0 warnings.
Finished with 0 errors.
Backup completed successfully.
-------------------------------------------------

Happy backups!

PS C:\> Add-PSSnapin Microsoft.SharePoint.PowerShell
The local farm is not accessible. Cmdlets with FeatureDependencyId are not registered.

PS C:\> Get-SPEnterpriseSearchServiceApplication
Get-SPEnterpriseSearchServiceApplication : Microsoft SharePoint is not supported with version 4.0.30319.1008 of the Microsoft .Net Runtime.

Although this is not a supported configuration, there is a workaround to force PowerShell 2.0 documented in KB 2796733 - SharePoint 2010 Management Shell does not load with Windows PowerShell 3.0 

What isn't mentioned in the KB article is a different combination when this issue can occur, even if WMF 4.0 isn't installed. If your PowerShell version is 2.0 but configured to run with .NET 4.x CLR, you will still see the errors.

The $PSVersionTable will show the version of PowerShell and .NET that is being used.  If it shows a CLRVersion of 4.x, you will probably still have problems running SharePoint 2010 cmdlets:

PS C:\> $PSVersionTable

Name   Value
----   -----
PSVersion  2.0
CLRVersion  4.0.30319.1008

You can override the .NET CLR version with these steps:

1. Create or edit a file at $pshome\powershell.exe.config
   1. If you use the ISE, also do the same for powershell_ise.exe.config
      
2. Insert or edit the contents so that the line for the v2.x supportedRuntime is listed before the v4.x line.

   <?xml version="1.0"?>
   <configuration>
      <startup useLegacyV2RuntimeActivationPolicy="true">
        <supportedRuntime version="v2.0.50727"/>
        <supportedRuntime version="v4.0.30319"/>
    </startup>
   </configuration>

3. Save the file and reopen any previous PowerShell sessions

4. Test by adding the SharePoint snap-in, and running some SharePoint cmdlets, e.g.
   
   Add-PSSnapin Microsoft.SharePoint.PowerShell

This is similar to the procedure described in this post, but with forcing .NET version 2.x instead of version 4.x.

If this helps you, or if you still encounter these issues when running SharePoint 2010 PowerShell cmdlets, please post a comment or send me an e-mail.

This post continues a series on the SharePoint 2013 Documentum Connector.  The previous post covered the prerequisites and installation of the connector.  This post focuses on the configuration of the connector and Documentum content sources in SharePoint.

Registering the Documentum Connector

After setting up the prerequisites and installing the connector, you need to register the connector with SharePoint so it will appear in the Content Sources as an option for Custom Repository.

Multiple Crawl Components: If you have more than one SharePoint Crawl Component server, you only need to register the connector once.

Steps: Register the Indexing Connector for Documentum to the Search service application

Make sure you are using a PowerShell windows opened AFTER you installed the Documentum connector, or else the cmdlets added by the connector will missing.

If you prefer, you can pass an actual SSA object instead of specifying it by name (String):

$ssa = Get-SPEnterpriseSearchServiceApplication "Search Service Application"
New-SPEnterpriseSearchCrawlCustomConnector -SearchApplication $ssa …etc

Example:

 PS C:\>New-SPEnterpriseSearchCrawlCustomConnector -SearchApplication $ssa -Protocol "dctm" -ModelFilePath  "C:\Program Files\Common Files\Microsoft shared\Web Server Extensions\15\CONFIG\SearchConnectors\Documentum\MODEL.XML" -Name "Microsoft SharePoint 2013 Indexing Connector for Documentum"

Output:

Protocol   DisplayName                              ModelFileLocation

--------   -----------                              -----------------

dctm       Microsoft SharePoint 2013 Indexing C...  C:\Program Files\Com... 

Configuring the Documentation Connector

At this point, the connector is installed and registered with SharePoint.  The next step is to configure it for your environment.  The location for the Documentum config file is:

%CommonProgramFiles%\Microsoft Shared\Web Server Extensions\15\CONFIG\SearchConnectors\Documentum\DCTMConfig.XML

The DCTMConfig.xml  file can be generated using the cmdlet Set-SPEnterpriseSearchDCTMConnectorConfig. A sample config is also available at:

%CommonProgramFiles%\Microsoft shared\Web Server Extensions\15\CONFIG\SearchConnectors\Documentum\DCTMConfigSample.XML

Multiple Crawl Components: If you have more than one SharePoint application server running crawl components, you only need to generate the DCTMConfig.xml once.  Then you can copy it to the same location on the other servers.  Do this before configuring a content source in central administration.

Before you configure the connector, you should decide which of the four security modes to use.  They are listed in the table at this link: http://technet.microsoft.com/en-us/library/ff721975(v=office.15).aspx#DCTM_Overview

Your decision will determine which option to choose for the ACLTranslation parameter of the configuration cmdlet, which determines how the connector handles user permissions for documentum objects. If you are not interesting in maintaining Documentum security for testing, you can choose the NoSecurity option:
-ACLTranslation NoSecurity

Using the DisplayURL options isn't required, but you should think about what happens when a user clicks a documentum result link (display URL). The actual crawling uses DFS URIs which won’t work in a browser.  The connector allows you to substitute a webtop URL or other link for Documentum cabinets, folders and documents.

Example: Setting Shared Parameters

PS C:\> Set-SPEnterpriseSearchDCTMConnectorConfig -Shared -ACLTranslation NoSecurity -DisplayURLPatternForDocument "http://mywebtopserver:8080/webtop/component/drl?objectId={ObjectId}&RepositoryName={RepositoryName}" -DisplayURLPatternForContainer "http://mywebtopserver:8080/webtop/component/drl?objectId={ObjectId}&format={Format}&RepositoryName={RepositoryName}"

Configuration information is saved suceessfully into C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\Config\SearchConnectors\Documentum\DCTMConfig.xml.

Once the Shared connector settings are configured, you can configure the DFS Web Service location for each of your Documentum Repositories.  The Documentum Connector uses the DFS client libraries to connect to a DFS Web Service, which gives access to objects on the content server.  You can confirm that this service is running by accessing the host and port with this URL, and it should return a list of the available services:

http://myDFSserver:9080/services/core/ObjectService

Example: Adding Repositories

Set-SPEnterpriseSearchDCTMConnectorConfig -Repository -RepositoryName "dmRepo1" -DFSWebServiceURL "http://myDFSserver:9080/services"
Set-SPEnterpriseSearchDCTMConnectorConfig -Repository -RepositoryName "dmRepo2" -DFSWebServiceURL "http://myDFSserver:9080/services" 

Create a new Crawl Rule

Before creating Content Sources, you should create Crawl Rules for your Documentum Start Addresses.  This allows you to specify which Documentum credentials the crawler should use for each source.  At least one "Include" crawl rule is required to allow authentication for the content access account in the Documentum repository you are crawling. Additional exclude rules are optional.

First, you should determine which Documentum user to use as the SharePoint Content Access Account.  This should be a Documentum user that has read permission for all containers and objects that you wish to crawl.  Then, follow these steps to set up your Include rule:

1. In SharePoint Central Admin, open the Search Service Application where the Documentum connector is registered
2. Navigate to the Crawl Rules section
3. Input a Path using wildcards that match the Documentum URIs that you plan to crawl with one Documentum user.
1. To set the Path for all  DCTM URIs, use "dctm://*"
4. For Crawl Configuration, choose "Include all items in this path", and select only the "Crawl Complex URLs" checkbox
5. Under Specify Authentication, choose "Specify a different content access account".  Input the username and password for your Documentum content access account.  The Documentum connector only supports basic authentication.
6. Make sure "Do not allow Basic Authentication" option is unchecked.

 Creating a Crawl Rule for the Documentum Source

Configure a Content Source

In your SSA administration page, create a new Content Source.  Give it a name that is descriptive.  For Content Source Type choose Custom Repository, and then select "Microsoft SharePoint 2013 Indexing Connector for Documentum". If that option is not available, then your Documentum Connector has not been properly registered.

For the Start Addresses, you will need to provide DCTM URIs that target the Documentum containers and objects you want to crawl.  By default it will crawl the root repository. This should be the actual Documentum URI that will be passed as a request to the DFS web service. Do not include a port number in the Documentum URIs, as the port is determined by the connector configuration.

To determine the Documentum path to crawl, see Syntax to refer to a Documentum object

Once the Content Source is created, start a full crawl and watch the crawl log to monitor the status.

Final Word

At this stage you should now have Documentum content in your SharePoint Index.  If not, there could be something wrong with your installation, configuration or your environment.  In my next post I plan to cover troubleshooting for the SharePoint 2013 Documentum Connector.

Please share your feedback in a comment.

So you have downloaded the SharePoint 2013 Documentum Connector, and you can't wait to zip through the install wizard and get to crawling your Documentum repositories. Hang on one minute. There are some important prerequisites you should be aware of. The TechNet article describes the requirements in the "Before you begin" section of the document.

Your Documentum Environment

Unless you are a Documentum expert, it may not be clear how the SharePoint connector retrieves the content in a Documentum repository for indexing.

The Documentum Content Server manages the repository, which can contain objects like cabinets, folders, and documents. The repository can only be accessed through the Content Server.

The Documentum Foundations Service (DFS) is a web service that provides access to the Content Server to external clients like the SharePoint connector. Client DLLs are provided by EMC for a variety of frameworks, including .NET. Typically, the DFS server will be separate from the content server, but they can run on the same host in small environments.

EMC DFS Productivity Layer DLLs

There are four DLLs from EMC DFS SDK that the DCTM connector uses to connect to the remote DFS service. These need to be loaded into the .NET Global Assembly Cache on all the servers where the connector is installed, which should be all SharePoint farm application servers running a Crawl Component.

Previous versions of the connector used DLLs from DFS Productivity Layer v6.5 with SP2 and DFS hotfix 1049 (6.5.0.231). However, the May 2013 release of the SP2013 DCTM connector has been updated to use DFS Productivity Layer 6.7 SP2 (6.7.2000.36). This version is more readily available from EMC and enables forward compatibility with Documentum 7.x.

You can download the emc-dfs-sdk-6.7 zip package and extract the DLLs from:

.\emc-dfs-sdk-6.7\emc-dfs-sdk-6.7\lib\dotnet

Emc.Documentum.FS.DataModel.Core.dll
Emc.Documentum.FS.DataModel.Shared.dll
Emc.Documentum.FS.Runtime.dll
Emc.Documentum.FS.Services.Core.dll

In Windows Server 2012, I had trouble dragging-and-dropping the DLLs into the GAC while UAC was enabled. Instead of turning off UAC, I used the 'gacutil.exe' tool which is available as part of a .NET SDK:    

C:\EMC_DFS_6.7SP2_DLLs> gacutil.exe /i .\Emc.Documentum.FS.DataModel.Core.dll

Microsoft (R) .NET Global Assembly Cache Utility. Version 3.5.30729.1
Copyright (c) Microsoft Corporation. All rights reserved.
Assembly successfully added to the cache    

When it's done, you should see all four global assemblies in C:\Windows\assembly:

Editing the machine.config

The TechNet guide provides an XML snippet that needs to be pasted into the .NET v4 machine.config. The guide is not totally clear on where to put it in the file. In my testing, it worked when I put the snippet immediately after the only instance of the tag " <system.serviceModel>" near the end of the file, like this:

  </system.data>
  <system.serviceModel>
    <!-- Paste the XML snippet here -->
    <extensions>
      <behaviorExtensions>

If needed, changes can be made to these parameters for the DfsDefaultService binding, including:

1. maxBufferSize
2. maxBufferPoolSize
3. maxReceivedMessageSize
4. Transport elements - to enable an SSL connection to the DFS web service

I also had a customer report mysteriously losing the changes in their machine.config after applying patches, so double-check this if you are having issues crawling Documentum content.

Connector Installation

If the prerequisite steps have been completed, then the actual connector install wizard should be straight-forward. The default installation directory is:

C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\CONFIG\SearchConnectors\Documentum

If you encounter an error that says "The signature or catalog could not be verified or is not valid," then you have issues with the strong-named assemblies and you probably have an older version of the connector installer.

Then follow the instructions to register the indexing connector with your Search Service Application.

Final Word

Hopefully this information helped you get through the prerequisites and installation of the SP2013 Documentum Indexing Connector. I plan to cover connector configuration in a follow-up post. Please share your feedback in a comment, and feel free to post corrections to what I have said.

TechNet- Configure and use the Documentum connector in SharePoint Server 2013
Download- Microsoft SharePoint 2013 Indexing Connector for Documentum

This feature was previously available for SharePoint 2010 and FAST Search for SharePoint with the Microsoft SharePoint 2010 Indexing Connector for Documentum.

The SP2013 Documentum connector was first released to the public in March 2013 but it was taken down to fix some minor issues and to add support for newer versions of EMC's Documentum Foundation Services (DFS).  The connector was re-released on May 14, 2013 at the links above.

I plan on posting a series of blog posts covering the installation, configuration, troubleshooting, and security features of the SharePoint 2013 Documentum Indexing Connector.  This information is intended to compliment and not replace the official documentation on TechNet.

I have a degree in Information Technology from Rochester Institute of Technology. My career in IT has spanned a variety of software and service organizations in the fields of e-Commerce, healthcare IT, digital TV streaming, and enterprise search. I joined Microsoft as part of the 2008 acquisition of FAST Search and Transfer, where I had worked since 2006. In my five years at Microsoft, I have worked on many fun and exciting projects. I hope that this blog will allow me to share useful information with customers, colleagues, and anyone interested in search.    

The best way to contact me regarding specific blog posts will be in the comments, where I plan to monitor and reply. If you are a Microsoft Premier Support customer and need assistance with your search application, you can work with your account team to find the right resource in your region.