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:
-
Open the file log4.properties from the portal directory /internal/cfg with the text editor of your choice.
-
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
- Restart the portal service.
- 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:
- A value will be searched for in the user session with the variable's name (here: SITE_NAME).
- A value will be searched for in a user schema attribute with the variable's name.
- 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