Connector für Microsoft SharePoint - Appendix

1. Troubleshooting

1.1. Fehlermeldungen

1.1.1. OData-Client

Wenn während eines SharePoint-Requests Fehler auftreten, versucht Intrexx die Fehlermeldungen aus der Antwort des Services zu ermitteln und im Browser anzuzeigen. Dies ist nicht immer in allen Fällen möglich. Für eine detailliertere Fehleranalyse bietet es sich deshalb an, das Request-Tracing im Intrexx-Portal-Sserver zu aktivieren.

1.1.2. Request-Tracing und Fehlerprotokollierung

Bei aktiviertem Request-Tracing werden sowohl die HTTP-Requests als auch Responses im Detail in die Intrexx-Portal-Logdatei geschrieben. Für Requests besteht ein Eintrag aus der HTTP-Aktion, der URL, den Query-Options, den Request-Headern und dem XML-Body. Bei Antworten werden die HTTP-Header und der Response-XML-Body ausgegeben. Aktiviert wird das Tracing wie folgt:

Öffnen Sie die Datei log4.properties im Portalverzeichnis internal/cfg mit einem Texteditor Ihrer Wahl.

Navigieren Sie zum Abschnitt "logging for OData" und ändern Sie den Wert von INFO auf DEBUG:

# logging for OData
log4j.logger.de.uplanet.lucy.server.odata.consumer=DEBUG, File log4j.additivity.de.uplanet.lucy.server.odata.consumer=false

Führen Sie einen Neustart des Portal-Dienstes durch.
Bei jeder OData-Aktion werden nun die Request-Details in der portal.log-Datei protokolliert.

Beispiel für ein Request-/Response-Tracing Eintrag:

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">MyTestAufgaben</title>
	<id>http://SharePoint2013/myTest/_vti_bin/listdata.svc/MyTestAufgaben</id>
	<updated>2014-05-23T07:47:57Z</updated>
	<link href="MyTestAufgaben" rel="self" title="MyTestAufgaben" />
	  <entry m:etag="W/"6"">
	<id>http://SharePoint2013/myTest/_vti_bin/listdata.svc/MyTestAufgaben(2)</id>
	<title type="text">MyTask</title>
	<updated>2014-04-28T14:54:43+02:00</updated>
	<author>
	<name />
	</author>
	<link href="MyTestAufgaben(2)" rel="edit" title="MyTestAufgabenItem" />
	<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">2</d:ID> 
			<d:Vorgangsname>MyTask</d:Vorgangsname>
			<d:Anfangsdatum m:type="Edm.DateTime">2014-04-11T00:00:00</d:Anfangsdatum>
			<d:Fälligkeitsdatum m:type="Edm.DateTime">2014-04-29T00:00:00</d:Fälligkeitsdatum>
			</m:properties>
			</content>
			</entry>
			<entry m:etag="W/"5"">
			<id>http://SharePoint2013/myTest/_vti_bin/listdata.svc/MyTestAufgaben(3)</id>
			<title type="text">PortalVisions 2014 - Infrastruktur</title>
			<updated>2014-04-25T17:29:00+02:00</updated>
			<author>
			<name />
			</author>
			<link href="MyTestAufgaben(3)" rel="edit" title="MyTestAufgabenItem" />
			<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:Vorgangsname>PortalVisions 2014 - Infrastruktur</d:Vorgangsname>
			<d:Anfangsdatum m:type="Edm.DateTime">2014-04-23T00:00:00</d:Anfangsdatum>
			<d:Fälligkeitsdatum m:type="Edm.DateTime">2014-04-28T00:00:00</d:Fälligkeitsdatum>
			</m:properties>
		</content>
	</entry>
</feed>

1.2. SSL-Verbindungen

Für SSL-Verbindungen zwischen dem Intrexx-Portalserver und einem SharePoint-Server muss das Zertifikat der Certificate-Authority, die das Service-Zertifikat ausgestellt hat, dem Zertifikatsspeicher des Intrexx-Portalservers hinzugefügt worden sein. Eine Ausnahme bilden selbstsignierte Zertifikate, die nicht von einer bekannten Certificate-Authority ausgestellt wurden. Um SSL-Verbindungen zu Diensten mit selbstsignierten Zertifikaten zu ermöglichen, muss in diesem Fall im Intrexx-Server die Prüfung der Certificate-Chain deaktiviert werden. Dies ist auf Service-Ebene über eine System-Property möglich. Öffnen Sie die Datei portal.cfg im Portalverzeichnis internal/cfg mit einem Texteditor und fügen Sie dem Abschnitt <environment> einen neuen <systemProperty>-Eintrag hinzu:

<systemProperty name = "de.uplanet.lucy.server.odata.consumer.ssl.allowSelfSignedCerts.<SERVICE_GUID>" value="true"/>

Der Platzhalter <SERVICE_GUID> ist mit der GUID des OData-Services zu ersetzen. Die GUID können Sie der Service-Konfigurationsdatei im Portalverzeichnis internal/cfg/odata entnehmen. Nach dem Speichern der portal.cfg-Datei muss der Intrexx-Portalserver-Dienst neu gestartet werden, damit die Änderungen wirksam werden.

2. Anhang

2.1. Intrexx-Kerberos-Token-Provider

2.1.1. Allgemeines

Der Intrexx-Kerberos-Token-Provider ist ein Webservice, der ein Intrexx-Portal-Server-Kerberos-Token zur Single-Sign-On-Authentifizierung der Portalbenutzer mit externen Systemen anfordern kann. Dieser Dienst wird vor allem dann benötigt, wenn während der Verarbeitung einer Benutzeranfrage im Portal-Server mehrere Zugriffe auf ein externes System benötigt werden, wobei jeder einzelne Zugriff ein Kerberos-Ticket zur Authentifizierung benötigt. Dem Portal-Server selbst steht pro Web-Request nur ein Ticket pro externem System zur Verfügung. Mit diesem kann sich der Portal-Server am Intrexx-Kerberos-Token-Provider im Kontext des Portalbenutzers anmelden und erhält dann für das externe System mehrere Tokens für die Verarbeitung der jeweiligen Requests.

2.1.2. Systemvoraussetzungen

Die Integrierte Windows-Authentifizierung muss für das Intrexx-Portal und den Connector für Microsoft SharePoint aktiviert sein. Außerdem wird Microsoft Windows Server ab Version 2008 unterstützt. Auf dem Intrexx-Portal-Server müssen der Internet Information Server und .Net 4.5 installiert sein.

2.1.3. Installation und Konfiguration

Die Webanwendung für den Kerberos Token Service befindet sich als ZIP-Datei ixkrbtokenservice.zip im Portalverzeichnis adapter/odata/kerberos. Entpacken Sie die Dateien in einem beliebigen Verzeichnis auf dem Server, z.B. in c:/inetpub/wwwroot/ixkrbtokenservice. Erstellen Sie nun eine neue Web-Anwendung im IIS mit folgenden Einstellungen:

Wählen Sie dabei als Anwendungspool einen Pool aus, der die .NET Framework Version 4.0 unterstützt.

Anschließend muss die Ansicht "Authentifizierung" für die Anwendung geöffnet werden. Deaktivieren Sie dort alle Methoden bis auf "Windows-Authentifizierung". Als Provider muss "Negotiate" eingestellt werden und die Kernel-Mode Authentication muss ebenfalls aktiviert sein. Nun kann der Service im Browser getestet werden. Rufen Sie dazu im Browser die URL http://localhost/ixkrbservice/api/Token auf. Zusätzlich kann über den Query-Parameter "spn" direkt der Service-Prinicpal-Name des Microsoft SharePoint-Servers angegeben werden, um die Ticket-Anforderung für diesen zu testen. Es sollte im Browser eine Meldung wie unten erscheinen:

Je nach Browser kann die Darstellung des Ergebnisses als XML- oder JSON-Dokument erfolgen. Die Anzahl der zu erzeugenden Tickets kann in der web.config-Datei im Service-Verzeichnis über den Parameter maxTokenCount eingestellt werden. Standardmäßig werden pro Anfrage 5 Tickets erstellt.

2.2. SharePoint-Abfragen in Groovy-Skripten

Derzeit gibt es noch keine öffentliche Intrexx-Groovy-API für den Zugriff auf Microsoft SharePoint in Groovy-Skripten. Es ist allerdings möglich, die interne Intrexx-SharePoint-API für Groovy freizuschalten. Diese garantiert allerdings nicht Kompatibiltät zu zukünftigen Intrexx-Versionen und sollte daher nur nach Absprache mit Ihrem United Planet Kundenberater verwendet werden. Um den Zugriff auf die internen Klassen zu aktivieren, editieren Sie die Datei scripting.cfg im Portalverzeichnis internal/cfg/scripting und tragen die untenstehende Zeilen ein:

<?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>

Anschließend muss der Portal-Server-Dienst neu gestartet werden. Die Klassen aus den oben aufgeführten Packages können nun in Groovy importiert werden. Im Folgenden wird beispielhaft die Microsoft SharePoint-Volltextsuche aus Groovy ausgeführt. Es ist auch möglich, direkte OData- oder HTTP-Requests zu erzeugen und auszuführen.

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 Konfiguration
def l_cfg = ODataConsumerRegistry.getInstance().getConsumerConfiguration('4F9C5FCE6D0160451C336C4E8FDC9C6E7362B00D') //l_cfgGuid

// SharePoint Service Klasse
def l_sharePointService = SharePointService.getInstance()

// Suche in SharePoint (Ergebnis ist ein JSON String)
def l_result = l_sharePointService.search(l_cfg, 
'86BDB920D3B8A7E8AA20F42F3F3459DE1E0EDCF3', //serviceGuid, 
'7312F993D0DA4CECCA9AE5A9D865BE142DE413EA', //userGuid
'Suchausdruck')

// OData Consumer Client für OData Requests:
def l_strDgGuid = '...' // DG Guid der SharePoint Datengruppe
def l_strUserGuid = '...' // Intrexx User GUID mit statischem SP Login
def l_odataConsumer = l_sharePointService.getConsumer(l_strDgGuid, l_strUserGuid)

//Jersey Client für direkte HTTP Aufrufe im User Kontext
def l_httpClient = ODataConsumerFactory.INSTANCE.createJerseyClient(l_cfg, '86BDB920D3B8A7E8AA20F42F3F3459DE1E0EDCF3', //serviceGuid
'7312F993D0DA4CECCA9AE5A9D865BE142DE413EA') //userGuid

2.3. Dynamischer Zugriff auf mehrere SharePoint-Sites

Üblicherweise werden für jede anzubindende SharePoint-Site eigene Service-URIs in der SharePoint-Dienste-Konfiguration erfasst. Pro Datengruppe kann aber nur auf eine Service-Definition zugegriffen werden. Soll auf Listen/Bibliotheken in unterschiedliche Sites zugegriffen werden, so muss für jede Site/Liste/Bibliothek eine eigene Datengruppe erstellt werden. Dies kann vereinfacht werden, wenn auf die gleichen Listen/Bibliotheken in unterschiedlichen Sites zugegriffen werden soll. Voraussetzung dafür ist, dass die betroffenen Listen und Felder in allen Sites genau die gleichen Bezeichnungen haben. Ist dies der Fall, kann in der Service-URI eine Platzhalter-Variable definiert werden, die zur Laufzeit von Intrexx mit dem Site-Name ersetzt wird. Dabei ist zu beachten, dass pro Intrexx-Session nur eine Site angesprochen werden kann. Eine Service-URI mit Platzhalter kann wie folgt aussehen:

http://sharepoint/{{SITE_NAME}}/_vti_bin/listdata.svc

In diesem Fall wird die Variable SITE_NAME zur Laufzeit nach folgender Reihenfolge gesucht und ersetzt:

Es wird in der Benutzer-Session nach einem Wert mit dem Variablennamen (hier SITE_NAME) gesucht.
Es wird in einem Benutzer-Schema-Attribut mit dem Namen der Variable nach einem Wert gesucht.
Es wird in einem Gruppen-Schema-Attribut mit dem Namen der Variable nach einem Wert gesucht.

2.4. Ressourcen

Weitere Information zu den OData-REST-Services in SharePoint 2010 bzw. SharePoint 2013 sind unter folgenden Links zu finden:

SharePoint 2010

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

SharePoint 2013

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

3. Weitere Informationen

Allgemeines
Systemvoraussetzungen
SharePoint-Daten konsumieren
SharePoint-Daten in Applikationen einbinden
Export / Import