D: Troubleshooting

General Troubleshooting

Scenario 1: Error while adding the app to a site

When adding the app to a site, you may see the following:

This can occasionally occur when this is the first instance of the app being added to the SharePoint farm.  Usually a second attempt (using the “Click to retry” link) will resolve this issue.

However, in rare cases, it has been found that an authentication setting for the server has been installed incorrectly.  In this scenario, looking at the details of the app will provide further information regarding the installation error.

The error displayed may be similar to the following:

The remote event receiver callout failed.

Details: The HTTP request is unauthorized with client authentication scheme 'Anonymous'. The authentication header received from the server was ''

If a second attempt to install still doesn’t succeed, and/or you are receiving a similar error to above, follow these steps.

1. Open IIS Manager and expand the site: Content Manager SharePoint Server.

2. Select EventReceivers, in the right-hand pane, using the Features view, locate and double-click the Authentication icon.

   

3. If  Anonymous Authentication is Disabled, right click and select Enable to enable it.

   The authentication should now be set as follows:

   

4. Confirm that you can browse to the URL: https://YourUrl/EventReceivers/AppEventReceiver.svc.

You should now be able to add the app to the site.

Scenario 2: Viewing the log file

There are two log files containing information, which may help with fault finding an installation.  Log files can be found in the “Logs” sub directory of the installation directory.  By default, this will be:

C:\Program Files\Micro Focus\Content Manager\Content Manager SharePoint Integration\Logs

The log named “Configuration Tool.log” contains logging information created by the configuration tool.

The log named “SharePointIntegration.log” contains logging information created by the rest of the application.

Scenario 3: Turning on additional information

When exceptions occur, in some cases, there is additional information that can be provided to the user.  This is turned off by default as it may contain information that could be used by malicious users.  It is possible to turn this on if required.

1. Navigate to the installation directory and locate the “bin” subdirectory.  Double click the file named:

   EntLibConfig.exe

2. This opens the Microsoft Enterprise Library Configuration Console.

3. From the “File” menu choose “Open” then navigate to the installation directory and find the file named:

   EnterpriseLibrary.config

4. Select and open that file.

5. Expand the “Exception Handling Settings” section:

   

6. For the “HandleDisplayAndLog” handler, expand the “Display Handler” and locate the attribute “ShowAdditionaInformation”.  Set this value to “true”.

   

7. Repeat these steps for the “HandleDisplayOnly” block.

   

8. Once complete, choose “File” then “Save”.

Scenario 4: Turning on success logging

During fault finding, you may be asked to turn on success logging.  This enables verbose logging that will allow the support team to better diagnose where issues may be occurring.

Success logging has a performance impact.  Do not enable it unless absolutely necessary and disable it once fault finding is complete.

1. Navigate to the installation directory and locate the “bin” subdirectory.  Double click the file named:

   EntLibConfig.exe

2. This opens the Microsoft Enterprise Library Configuration Console.

3. From the “File” menu choose “Open” then navigate to the installation directory and find the file named:

   EnterpriseLibrary.config

4. Select and open that file.

5. Expand the “Logging Settings” section followed by the “Success” block:

   

6. Click the “+” button next to the “Listeners” row:

   

7. From the drop down that is added, choose the “Content Manager SharePoint Integration Trace Listener”.

   

8. Once complete, choose “File” then “Save”.

Other logging categories

In 9.1 the following categories were introduced to reduce the amount of verbose logging:

• CoreProcess
• Search
• Security
• ManagementRules
• App
• RemoteEvents
• LifetimeManagement
• Jobs

Turning on the "Search" category will only log messages related to search. This is to make the fault finding process a lot easier. See Turning on success logging.

These logging has a performance impact. Do not enable it unless absolutely necessary and disable it once the fault finding is complete.

Scenario 5: Job process fails to start

If the Content Manager SharePoint Service fails to start, any jobs added to the queue will stay in a pending state, and will not get processed. This is typically because the account details (username and password) were entered incorrectly during installation.

To rectify this, perform the following:

1. Go to Windows Services on the Content Manager Workgroup Server, where you installed the SharePoint integration MSI.

2. Locate the Content Manager SharePoint Service in the list.

3. Double-click the service name to open up the properties dialog, and go to the Log on tab.

4. Browse for the appropriate domain service account, to ensure you are using a valid account in the directory.

5. Re-enter the password, and confirm it, then click Apply.

6. Go back to the General tab, make sure the Startup type is Automatic, and click on Start.

7. If the account details are valid, the service should start, click OK to close the dialog.

Scenario 6: Cannot open the configuration tool due to error

When launching the integration configuration tool to change existing settings, you see the following error:

Make sure that you are launching the configuration tool using ‘Run as Administrator’. If this doesn’t resolve the problem, then continue with fault finding.

The error message does describe some potential causes, and these should be checked, but the most likely issue is that the configuration database is not accessible for some reason. Check to make sure that the SQL Server where the configuration database is hosted is available, and that the configuration database is still listed as an active DB in SQL Server Management Studio.

If for some reason, the database is no longer available, restore from backup and retry the configuration tool.

In the worst case scenario, if the database is irretrievable, use the Configuration Tool to delete the connection string stored for the existing database and creating a new database.

Scenario 7: HTTP Error 503 - the service is unavailable

If when navigating to Content Manager Governance and Compliance app pages, you see the following page:

This means that the application pool for the Content Manager SharePoint Server website has failed to start, most likely due to incorrect account credentials. To rectify this:

1. Open IIS Manager, and in the Connections pane, click on Application Pools. The main window will display a list of all application pools.

2. Locate the Content Manager SharePoint Server application pool in the list.

3. Right-click on the entry and choose Advanced Settings.

4. In the Advanced Settings dialog, locate the Identity row, select it, and then click on the Browse button that appears alongside the account name.

5. In the Application Pool Identity dialog, click on Set.

6. In the Set Credentials dialog, re-enter the correct account credentials, with username in the format domain\username. Click OK.

7. Click OK to close the Application Pool Identity dialog, and then OK to close the Advanced Settings dialog.

8. the Content Manager SharePoint Server application pool in the list, and choose Start.

9. If the account credentials are now valid, the status of the application pool will change to Started.

Scenario 8: Configuration tool takes a long time to load

If the configuration tool takes a long while to start up, this is an indication that caching is incorrectly configured, or not working. To resolve this:

For on premise environments
Refer to the Configuring AppFabric and Troubleshooting AppFabric appendices. Ensure AppFabric is correctly installed and that the cache cluster is running before restarting the configuration tool.

For Windows Azure environments

If using Windows Azure, it is likely that the caching options have not been set in the tool. See General Administration Tasks - Azure Cache for more details.

Scenario 9: Failed to create client context error on pages

If when visiting Content Manager Governance and Compliance app pages, you see a Sorry, something went wrong error:

Message: Failed to create client context for site, http://spi10-spwfem2/sites/Content Manager. This means that the current user does not have the permission on this site or the app configuration settings are invalid.

IntegrationException - Error Number:C1904, Additional Information:, Message:Failed to create client

This is because, in some scenarios, during installation, the Content Manager SharePoint Server inadvertently uses anonymous access in IIS.  To resolve the issue:

1. Open IIS Manager and select the site: Content Manager SharePoint Server.

2. In the right-hand pane using the “Features view” locate and double click the Authentication icon.

3. Authentication will initially show Anonymous Authentication as Enabled and Windows Authentication as Disabled.

4. Right-click on Windows Authentication and choose Enable.

5. Right-click on Anonymous Authentication and choose Disable.

6. Test the app pages again, they should load without any errors.

Troubleshooting Workgroup servers

Scenario 1: Error - Unable to add server – https issue

1. If you have configured the Content Manager farm for SharePoint Online or you are using HTTPS there is a known issue that prevents adding a workgroup server to the list.  The symptoms are:

   • When you try to add a server to the server list, a validation error states “A valid server cannot be reached on this URL”.
   • If you browse to the URL https://YourUrl/SecureServices/DataStoreService.svc you receive an authentication prompt.  Regardless of entering the correct credentials, you are not permitted to view the page.
   • If you have configured HTTPS to be used, you have tested that this is working correctly.

   If you encounter this issue, this will also prevent the publishing of configuration data.  It is likely that you will need to utilize the following workaround on the machine that you are running the configuration tool (and only on that machine):

   • Open IIS Manager and select the site: Content Manager SharePoint Server.

   • Expand the site and select SecureServices.

   • In the right hand pane using the “Features view” locate and double click the Authentication icon.

   • Authentication will initially show Anonymous Authentication as Disabled and Windows Authentication as Enabled.

   • Right click on Anonymous Authentication and select Enable.

   • Right click Windows Authentication and select Disable.

     

2. You will also need to temporarily update the web.config file for the site.

   • Navigate to the installation directory and open the file called “web.config” (notepad is a suitable program for opening this file).

   • Locate all the following nodes:

     <transport clientCredentialType="Windows"/>

   • Modify this node to read:

     <transport clientCredentialType="None"/>

   • Save the web.config file.

   Confirm that you can browse to the URL https://YourUrl/SecureServices/DataStoreService.svc.

   You should now be able to add your workgroup servers to the list.

   Once you have finished publishing, you must change the authentication back to:

   

   You must revert the web.config node that was modified back to read:

   <transport clientCredentialType="Windows"/>

Scenario 2: Error - Unable to add server – code access security issue

If you have configured code access security at machine level, there is a known issue that prevents adding a workgroup server to the list.  The symptoms are:

• When you try to add a server to the server list, a validation error states “A valid server cannot be reached on this URL”
• If you browse to the URL https://YourUrl/SecureServices/DataStoreService.svc you receive an error.  If you turn off custom errors in the web.config file, the error mentions code access security.

If you encounter this issue, this will also prevent the publishing of configuration data and use of the Content Manager Governance and Compliance app.  You will need to make the following changes on all machines in your Content Manager farm.

1. Navigate to the installation directory and open the file called “web.config” (notepad is a suitable program for opening this file).

2. Locate all the following node:

   <system.web>

3. Insert the following node before the closing tag:

   <trust level="Full"/>

   The full node should look similar to this when complete:

   <system.web>
     <customErrors mode="On"/>
  <compilation debug="false" targetFramework="4.5" />
  <httpRuntime requestValidationMode="4.5" executionTimeout="60" />
  <pages controlRenderingCompatibilityVersion="3.5" clientIDMode="AutoID" />
  <identity impersonate="false" />
     <trust level="Full"/>
</system.web>

4. Save the web.config file.

Confirm that you can browse to the URL https://YourUrl/SecureServices/DataStoreService.svc.

You should now be able to add your workgroup servers to the list.

Troubleshooting AppFabric

This section aims to provide solutions to the more common issues found with AppFabric.

Scenario 1: Error - AppFabric install fails with errors

AppFabric can initially be a tricky beast to install and configure.

You can refer to the resources available on the internet to assist with resolving AppFabric issues.

1. Ensure that you have completed all the pre-requisite tasks.

2. If you see the following errors when installing, try the following troubleshooting steps:

   

   Check all of the steps in the following table before retrying the installation:

   AppFabric Installation Troubleshooting Steps

   Check the PSModulePath environment variable: Go to My Computer, right-click Properties On the System' page, click Advanced System Settings on the left-side pane. If you receive a UAC prompt, click on Yes to launch the System Properties dialog box From the Advanced tab, click Environment Variables Within the System Variables section in the lower half, select PSModulePath and click on Edit (or double-click PSModulePath) Check that it includes the v1.0 entry (SQL entry will only be there if SQL Server is installed locally), and remove any extraneous quotation marks “ C:\Windows\system32\WindowsPowerShell\v1.0\Modules\;C:\Program Files (x86)\Microsoft SQL Server\110\Tools\PowerShell\Modules If this fails, delete the PSModulePath variable completely and then retry the installation

   Check that the windows service Remote Registry is running, and set to Automatic

   Enable Windows Update, and ensure that Critical updates are up to date

   Prior to installing AppFabric, the groups AS_Observers and AS_Administrators must not exist. To check if they exist for you and to get rid of them you just go into Administrative Tools à Computer Managementà Local Users and Groups à Groups and if AS_Observers or AS_Administrators exists, delete it as shown here msdn.microsoft.com/en-us/library/ff637696(v=azure.10).aspx

Scenario 2: Error: ‘Failed to access app fabric cache’ errors in the integration log

Follow the steps below to fix any errors related to AppFabric configuration, while publishing settings via the Content Manager SharePoint Configuration tool or when the AppFabric Caching Service (Windows Service) is not running.

Example log Message:

Failed to access app fabric cache. Details are:ErrorCode<ERRCA0017>:SubStatus<ES0006>:There is a temporary failure. Please retry later. (One or more specified cache servers are unavailable, which could be caused by busy network or servers. For on-premises cache clusters, also verify the following conditions. Ensure that security permission has been granted for this client account, and check that the AppFabric Caching Service is allowed through the firewall on all cache hosts. Also the MaxBufferSize on the server must be greater than or equal to the serialized object size sent from the client.)

AppFabric Post-Installation Troubleshooting Steps

Run the Caching Administration PowerShell, right-click and Run as Administrator. From the PowerShell window, execute the following command to restart the cache cluster. restart-cachecluster Ensure the Service Status is UP. If it is in stuck in the STARTING state, restart the server.

Check to make sure that the following domain service accounts are in the local security group Performance Monitor Users: Job Service Account Application Pool Account SQL Server Service Account Go to Administrative Tools > Computer Management > Local Users and Groups > Groups and double-click the Performance Monitor Users group to show the members.

Troubleshooting App Catalog

This section describes some of the issues we have encountered whilst testing and developing the app. These articles are aimed at SharePoint Farm Administrators, and include steps that can have a serious impact on the SharePoint Farm if not carried out correctly. These are suggestions and observations only, and not stipulations on how to configure SharePoint for apps.

Scenario 1: Apps are turned off error

If you receive the following error when trying to add the app to a site, it may be because the Subscription Settings Service Application is not configured:

"Sorry, apps are turned off. If you know who runs the server, tell them to enable apps."

First check in Central Administration to see if there is a provisioned Subscription Settings service application. If not, you can use the example PowerShell script in the Creating a Subscription Settings Service Application appendix below, or you can choose to create one manually.

Once successfully completed, you need to configure app URLS, see the Configuring app URLs – On Premise only section above for details.

Once configured, perform an iisreset from an elevated command prompt, if still getting the same error, a server restart will be required.

Scenario 2: Can’t add this app error

When trying to add the app to a site, you get the following error: You can’t add this app here.

And when you click on the App details link, you see the following message:

The following errors occurs when the User Profile Synchronization service has not started on the SharePoint Server.

As a farm administrator, go to SharePoint Central Administration > Application Management >Manage services on server and check that the service is in a Started state.

If the service is Stopped, and will not start, it will require additional troubleshooting that is outside the scope of this document. Consult Microsoft technical documentation for help with troubleshooting this service.

Scenario 3: Site hasn’t been shared with you error

The following error is a known issue with on premise installations that occurs when you add an app to a site other than the first site:

The solution to this is to add the user attempting to add the app, to the local machine administrators group on all SharePoint machines on the SharePoint farm.

On Sharepoint system, in the Server manager, go to Tools > Computer management > Local users and groups > Groups. Add all the three user types to administrator - SPAdmin1, AppPoolUser1, JobService1. Double click Administrator, click Add and type in the user name and then click Add again.