Connector for Microsoft SharePoint - Appendix

Connectors SharePoint

1. Troubleshooting

1.1. Error messages

1.1.1. 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.

1.1.2. 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>

1.2. 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 "portal.cfg" in the portal directory /internal/cfg/ 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.

2. Appendix

2.1. Intrexx Kerberos Token Provider

2.1.1. 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 multiple tokens for processing each request for the external system.

2.1.2. System requirements

The Integrated Windows Authentication must be activated for the Intrexx portal and the Connector for SharePoint, 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.

2.1.3. Installation and configuration

The Web application for the Kerberos Token Service is located as a ZIP file "ixkrbtokenservice.zip " in the portal 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 also needs to 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.

2.2. 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 scripting.cfg in the portal directory internal/cfg/scripting 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

2.3. 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 run time 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.

2.4. Resources

Further information relating to the OData REST service in SharePoint 2010 or 2013 can be found at the following links:

SharePoint 2010

https://msdn.microsoft.com/en-us/library/ff798339.aspx
http://blogs.msdn.com/b/odatateam/archive/2009/10/21/using-data-services-over-sharepoint-2010-part-1-getting-started.aspx
https://msdn.microsoft.com/en-us/library/office/ff521587%28v=office.14%29.aspx

SharePoint 2013

https://msdn.microsoft.com/en-us/library/office/fp142380.aspx
https://msdn.microsoft.com/en-us/library/office/jj860569.aspx

3. More information

General
System requirements
Consume SharePoint data
Integrate SharePoint data into applications
Export / Import