Connector for Microsoft SharePoint - Troubleshooting

Error messages

OData client

If errors occur during a SharePoint request, Intrexx will attempt to ascertain the error message from the service's response and then display it in the browser. This is not possible in every single case. You can therefore activate request tracing in the Intrexx portal server for a detailed error analysis.

Request tracing and error logging

When request tracing is activated, both the HTTP requests and the responses will be written in detail in the Intrexx portal log file. For requests, the entry consists of the HTTP action, the URL, the query options, the request headers and the XML body. For responses, the HTTP header and the response XML will be delivered.

Tracing is activated as follows:
  1. Open the file log4.properties from the portal directory /internal/cfg with the text editor of your choice.
  2. Navigate to the section logging for OData and change the value INFO to DEBUG:
    # logging for OData
    log4j.logger.de.uplanet.lucy.server.odata.consumer=DEBUG, File log4j.additivity.de.uplanet.lucy.server.odata.consumer=false
  3. Restart the portal service.
  4. With every OData action, the request details will now be logged in the file portal.log.
An example for such a request/response tracing entry:
DEBUG 2014-05-23 09:47:57,384
OData response: 
Status: 200
DataServiceVersion: 1.0;
Content-Length: 5074
Server: Microsoft-IIS/8.0
Date: Fri, 23 May 2014 07:47:57 GMT
Content-Type: application/atom+xml;charset=utf-8

<feed xml:base="http://sharepoint2013/myTest/_vti_bin/listdata.svc/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">  
	<title type="text">MyTestTasks</title>
	<id>http://sharepoint2013/myTest/_vti_bin/listdata.svc/MyTestTasks</id>  
	<updated>2014-05-23T07:47:57Z</updated>  
	<link href="MyTestTasks" rel="self" title="MyTestTasks" />  
	<entry m:etag="W/"6"">    
		<id>http://sharepoint2013/myTest/_vti_bin/listdata.svc/MyTestTasks(2)</id>    
		<title type="text">MyTask</title>    
		<updated>2014-04-28T14:54:43+02:00</updated>    
		<author>      
		<name />    
		</author>    
		<link href="MyTestTasks(2)" rel="edit" title="MyTestTasksItem" />    
		<category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" term="Microsoft.SharePoint.DataService.MyTestTasksItem" />    
		<content type="application/xml">      
			<m:properties>        
			<d:ID m:type="Edm.Int32">2</d:ID>        
			<d:ProcedureName>MyTask</d:ProcedureName>        
			<d:StartDate m:type="Edm.DateTime">2014-04-11T00:00:00</d:StartDate>        
			<d:DueDate m:type="Edm.DateTime">2014-04-29T00:00:00</d:DueDate>      
			</m:properties>    
		</content>  
	</entry>  
	<entry m:etag="W/"5"">    
		<id>http://sharepoint2013/myTest/_vti_bin/listdata.svc/MyTestTasks(3)</id>    
		<title type="text">PortalVisions 2014 - Infrastructure</title>    
		<updated>2014-04-25T17:29:00+02:00</updated>    
		<author>      
		<name />    
		</author>    
		<link href="MyTestTasks(3)" rel="edit" title="MyTestTasksItem" />    
		<category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" term="Microsoft.SharePoint.DataService.MyTestAufgabenItem" />    
		<content type="application/xml">      
			<m:properties>        
			<d:ID m:type="Edm.Int32">3</d:ID>        
			<d:ProcedureName>PortalVisions 2014 - Infrastructure</d:ProcedureName>        
			<d:StartDate m:type="Edm.DateTime">2014-04-23T00:00:00</d:StartDate>        
			<d:DueDate m:type="Edm.DateTime">2014-04-28T00:00:00</d:DueDate>      
			</m:properties>    
		</content>  
	</entry>
</feed>

SSL connections

For SSL connections between the Intrexx portal server and a SharePoint server, the certificate from the certificate authority, that issued the service certificate, must be added to the Certificate Store of the Intrexx portal server.

Self-signed certificates, which weren't issued by a known certificate authority, are an exception. To enable SSL connections to services with self-signed certificates, the examining of the Certificate Chain needs to be deactivated in the Intrexx server in this case. This is possible on the service level by using a system property.

Open the file /internal/cfg/portal.cfg in the portal directory with a text editor and add a new <systemProperty> entry to the section <environment>:
<systemProperty name = "de.uplanet.lucy.server.odata.consumer.ssl.allowSelfSignedCerts.<SERVICE_GUID>" value="true"/>
The placeholder <SERVICE_GUID> needs to be replaced by the GUID of the OData service. The GUID can be retrieved from the service configuration file in the portal directory internal/cfg/odata.

After saving the portal.cfg file, the Intrexx portal service must be restarted so that the changes take effect.

Appendix

Intrexx Kerberos Token Provider

General

The Intrexx Kerberos Token Provider is a Web service which an Intrexx Portal server can use to request Kerberos tokens for Single Sign On authentication for portal users with external systems. This service is especially needed if it is necessary to access an external system multiple times while a user enquiry is being processed; every access, however, requires a Kerberos ticket for authentication. Per Web request, only one ticket for each external system is available to the portal server. The portal server can use this to log in to the Intrexx Kerberos Token Provider in the context of a portal user and will then receive, for the external system, multiple tokens for processing multiple requests.

System requirements

The Windows integrated authentication must be activated for the Intrexx portal and the SharePoint adapter, as is described in capital 2.1.4.

This feature is supported by Windows Server version 2008 and upwards. The Internet Information Server and .NET 4.5 must be installed on the Intrexx server.

Installation and configuration

The Web application for the Kerberos Token Service is located as a ZIP file ixkrbtokenservice.zip in the portal server directory /adapter/odata/kerberos. Unpack the files to a folder of your choice on the server e.g. C:\inetpub\wwwroot\ixkrbtokenservice. Now create a new Web application in IIS with the following settings:



Select an application pool which supports .NET Framework Version 4.0.



Subsequently, you need to open the Authentication overview for the application. Deactivate all methods apart from Windows Authentication. Negotiate must be set as the Provider and Kernel-mode authentication must also be activated.



The service can now be tested in the browser. To achieve this, open the URL http://localhost/ixkrbservice/api/Token in the browser. Additionally, the query parameter spn can be used to directly provide the Service Principal Name of the SharePoint server to test the ticket request. A message like the one below should appear in the browser:



Depending on the browser, the result can either appear as an XML or JSON document. The number of tickets to be created can be setup in the web.config file in the service directory with the parameter maxTokenCount. As a default, 5 tickets are generated per request.

SharePoint requests in Groovy scripts

Currently, there is not a published Intrexx Groovy API for accessing SharePoint in Groovy scripts. It is however possible to enable the internal Intrexx SharePoint API for Groovy. Be that as it may, it is not guaranteed that this will be compatible with future versions of Intrexx and should therefore only be implemented after discussing it with your United Planet customer consultant.

To activate access to the internal classes, edit the file

<INTREXX_HOME>\org\<PORTAL>\internal\cfg\scripting\scripting.cfg

and add the following lines:
<?xml version="1.0" encoding="UTF-8"?>
<scripting xmlns="urn:schemas-unitedplanet-de:lucy:server:scripting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<scriptable name="de.uplanet.lucy.server.odata.consumer.cfg" type="package" />
	<scriptable name="de.uplanet.lucy.server.odata.consumer.jersey" type="package" />
	<scriptable name="de.uplanet.lucy.server.odata.consumer.sharepoint" type="package" />
	<scriptable name="org.odata4j.core" type="package" />
</scripting>
The portal service needs to be restarted afterwards. The classes from the packages executed above can now be imported into Groovy. As an example, the SharePoint full-text search will be performed using Groovy below. It is also possible to generate and perform OData or HTTP requests directly.
import de.uplanet.lucy.server.odata.consumer.cfg.ODataConsumerRegistry
import de.uplanet.lucy.server.odata.consumer.jersey.*
import de.uplanet.lucy.server.odata.consumer.sharepoint
import org.odata4j.core.*

// SharePoint configuration
def l_cfg = ODataConsumerRegistry.getInstance().getConsumerConfiguration('4F9C5FCE6D0160451C336C4E8FDC9C6E7362B00D') //l_cfgGuid

// SharePoint service class
def l_sharePointService = SharePointService.getInstance()

// Search in SharePoint (Result is a JSON String)
def l_result = l_sharePointService.search(l_cfg, 
'86BDB920D3B8A7E8AA20F42F3F3459DE1E0EDCF3', //serviceGuid, 
'7312F993D0DA4CECCA9AE5A9D865BE142DE413EA', //userGuid
'Suchausdruck')

// OData Consumer Client for OData Requests:
def l_strDgGuid = '...' // DG GUID of the SharePoint data group
def l_strUserGuid = '...' // Intrexx User GUID with static SP login
def l_odataConsumer = l_sharePointService.getConsumer(l_strDgGuid, l_strUserGuid)

//Jersey Client for direct HTTP requests within the user context
def l_httpClient = ODataConsumerFactory.INSTANCE.createJerseyClient(l_cfg, '86BDB920D3B8A7E8AA20F42F3F3459DE1E0EDCF3', //serviceGuid
'7312F993D0DA4CECCA9AE5A9D865BE142DE413EA') //userGuid

Dynamic access to multiple SharePoint sites

Usually, individual service URIs are specified in the SharePoint service configuration for each SharePoint site that is connected to. Only one service definition can be accessed per data group. If it is required that lists/libraries are accessed in different sites, then an individual data group needs to be created for each site/list/library. This can simplified if the same lists/libraries can be accessed in different sites. This is under the condition that the lists and fields involved have the exact same labels in every site. If this is the case, a placeholder variable can be defined in the service URI, this is replaced with the site name by Intrexx in runtime. It should be noted however that only one site can be addressed per Intrexx session.

A service URI with a placeholder could look something like this:

http://sharepoint/%7b%7bSITE_NAME%7d%7d/_vti_bin/listdata.svc

In this case, the variable SITE_NAME will be searched for and replaced in runtime according to the following sequence:
  1. A value will be searched for in the user session with the variable's name (here: SITE_NAME).
  2. A value will be searched for in a user schema attribute with the variable's name.
  3. A value will be searched for in a group schema attribute with the variable's name.

Resources

More information about the OData REST service in SharePoint 2010/2013 is available at the following links:

SharePoint 2010

https://docs.microsoft.com/en-us/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service

SharePoint 2013

https://docs.microsoft.com/en-us/dotnet/api/system.net.webproxy.bypassproxyonlocal?view=netframework-4.8