SharePoint Online DMS Schnittstelle

Die SharePoint Online DMS Extension erlaubt die Integration mit SharePoint Online.

• Vertec-generierte Legacy Office-Berichte und Office-Berichte können ihre Ausgabe direkt in Sharepoint speichern. Das Ergebnis wird in Office Online angezeigt und kann direkt weiterverarbeitet werden.
• Dokumente und E-Mails können mittels Vertec Explorer Addin sowie der Outlook App via Vertec direkt in SharePoint gespeichert werden. Dabei werden die Dokumentenpfade in Vertec berücksichtigt, wie weiter unten erläutert.
• Dokumente können aus Vertec heraus in Microsoft 365 Online geöffnet und bearbeitet werden.

Folgende Vorgänge sind nicht möglich:

• Speichern von Office-generierten Legacy Berichten in SharePoint
• Verwenden von Berichtsvorlagen aus SharePoint

Zur Inbetriebnahme der Schnittstelle sind folgende Schritte nötig:

Voraussetzungen

Für den Betrieb der Schnittstelle wird ein SharePoint Online benötigt. Darin muss mindestens ein Hauptuser / Administrator mit Login vorhanden sein. Hier in den Beispielen verwenden wir ein Microsoft Office 365 mit Sharepoint Online.

Es können mehrere Dokumentbibliotheken via Sharepoint-Schnittstelle angebunden werden. Die maximale Anzahl liegt in Vertec Versionen vor 6.4.0.21 bei 200 Sites.

Die Vertec Systemeinstellung Allgemein > Existenz von Dokumentfiles überprüfen arbeitet nicht mit der SharePoint Online DMS Schnittstelle zusammen und sollte deaktiviert werden, um ungültige Aktivitäten zu vermeiden. Ab Vertec 6.3.0.15 ist diese Systemeinstellung in Vertec nicht mehr vorhanden.

Schnittstelle in Vertec installieren

Um die Schnittstelle zu installieren, öffnen Sie im Ordner Einstellungen > Extensions die SharePoint Online DMS Extension und klicken auf Installieren.

Die Schnittstelle legt folgende Systemeinstellungen CRM/Aktivitäten an:

Nach Änderung der Werte in den Systemeinstellungen muss Vertec neu gestartet oder bei der SharePoint Online DMS Extension auf den Button Reload geklickt werden.

Dokumentenpfad

Der Basispfad – Systemeinstellungen Allgemein > Dokumentenpfad – wird mit SharePoint: gefolgt vom Verzeichnis, in welches im SharePoint die Vertec Dokumente gespeichert werden sollen, angegeben, z.B. SharePoint:\mydir.

Die Dokumente, die aus Vertec heraus generiert oder via Addin ins Vertec gespeichert werden, werden so direkt in SharePoint Online gespeichert.

Das Vertec Pfad-System wurde so erweitert, dass mit dem SharePoint: Präfix (anstelle von z.B. C:) ein Sharepoint Pfad angegeben werden kann. Es ist also auch möglich, nur bestimmte Dokumente in Sharepoint zu speichern, ohne den generellen Dokumentpfad auf Sharepoint umzustellen.

Benutzer-Authentisierung

Die SharePoint Online DMS Schnittstelle stellt zwei verschiedene Betriebsmodi der Benutzer-Authentisierung zur Verfügung:

Modus "Als Vertec App"

Hier lädt Vertec die Dokumente für alle Benutzer immer unter dem gleichen Benutzeraccount, bzw. dem in der App Registierung konfigurierten Namen, als "Vertec App". Mittels Berechtigungen kann nicht unterschieden werden, wer das Dokument hochgeladen hat.

Modus "Individueller Benutzer"

Ab Version 6.5.0.1. Damit die Systemeinstellung sichtbar wird, muss eine bereits installierte SharePoint Online DMS Schnittstelle deinstalliert und neu installiert werden.

Voraussetzung: Die erstmalige Aktivierung der Benutzerlogins kann nur mit der Cloud- oder Web App sowie via Webaccess erfolgen. Danach kann mit allen Vertec Apps gearbeitet werden.

Hier meldet sich Vertec bei SharePoint zwar auch als "Vertec App" an, die Dateien werden aber mit dem SharePoint-Account des entsprechenden Benutzers abgelegt. Damit dies funktioniert, muss sich jeder Benutzer einmal über einen Browser anmelden. Die Anmeldedaten werden zurück an Vertec geschickt und die Dokumente unter diesem Benutzeraccount hochgeladen. Dadurch wird ersichtlich, welcher Benutzer die Dokumente hochgeladen hat.

Zur Aktivierung der individuellen Authentisierung, muss die Checkbox DMS SharePoint OAuth individuelle Anmeldung verwenden unter Systemeinstellungen > CRM / Aktivitäten aktiviert werden. Zudem muss im Microsoft 365 Admin Center unter App Registrations > Vertec (Name Ihrer registrierten Vertec App) die Webaccess URL mit /callback am Ende eingetragen (bspw. https://demo.vertec-cloud.com/callback) sowie die Berechtigungen eingestellt werden, siehe weiter unten.

Mehrere Dokumentbibliotheken via Sharepoint-Schnittstelle anbinden

Ab Vertec 6.3.0.18 können mehrere verschiedene Dokumentbibliotheken (Libraries) angesprochen werden. Die verschiedenen Libraries werden dabei mit dem Pfad unterschieden.

Dabei ist es möglich, dass die Library URL in Vertec nur teilweise angegeben wird, und zwar so, dass alle zu verwendenden Library URLs durch Vervollständigung dieses Pfades erzeugbar sind.

Vertec prüft zunächst die im System hinterlegte Library URL auf ihre Vollständigkeit. Ist sie das, wird dieses Verzeichnis verwendet. Findet Vertec mit diesem Schritt noch keine Library, wird nun sukzessive jeweils das vorderste Verzeichnis aus dem Vertec Dokumentenpfad an die Library URL angehängt, bis eine Library gefunden wird. Der Rest des Dokumentenpfads wird dazu verwendet, um innerhalb der Library den Pfad der Datei festzulegen.

Möchte man mehrere Dokument-Libraries nutzen und Dokumente pro Klasse speichern, muss man folgendes beachten:

• Unter Systemeinstellungen Allgemein > Dokumentenpfad muss der Root-DMS-Pfad hinterlegt werden, z.B. Sharepoint:\MultiSite2\Shared Documents. Dies ist der Standard-Pfad und wird für alle Objekte verwendet, die nicht einen anderen Pfad hinterlegt haben (siehe nächster Punkt). Der Standard-Pfad muss als eigenständiger Pfad gültig sein.
• Im Ordner Einstellungen > Klasseneinstellungen muss für alle Klassen, die vom Standard-Verzeichnis abweichen, ein absoluter Sharepoint-Pfad eingetragen werden, bei Adressen zum Beispiel Sharepoint:\MultiSite1\Shared Documents\Kontakte\%if oclistypeof(Kontakt) then oclastype(Kontakt).firma.name else name endif%.

Vertec Applikation in Office 365 registrieren

Dieser Vorgang muss einmal pro Firma durchgeführt werden.

• https://portal.azure.com/ öffnen und auf Azure Active Directory verwalten klicken
• Links auf App-Registrierungen klicken

Applikation erstellen

1. Auf + Neue Registrierung klicken
2. Namen eingeben, z.B. Vertec
3. Auf den Button Registrieren klicken
4. Danach sollte Home > Kunde AG | App-Registrierung > Vertec offen sein, mit Vertec = Name der soeben erstellen App
5. Die Anwendungs-ID (Client) (nicht die Object ID) in den Vertec Systemeinstellungen unter DMS SharePoint Application ID eintragen (siehe Schnittstelle in Vertec installieren).

Berechtigungen festlegen und erteilen

1. Auf API-Berechtigungen > Berechtigung hinzufügen klicken
2. In der Liste Microsoft Graph auswählen
3. Berechtigungen festlegen:
   
   - Für den Modus Modus "Als Vertec App" alle Berechtigung vom Typ Anwendung hinzufügen:

   API/Berechtigungsname	Beschreibung
   Files.ReadWrite.All	Read and write files in all site collections
   Sites.FullControl.All	Have full control of all site collections
   Sites.Manage.All	Create, edit, and delete items and lists in all site collections
   Sites.ReadWrite.All	Read and write items in all site collections

   
   - Für den Modus "Individueller Benutzer" alle Berechtigungen vom Typ Delegiert hinzufügen:

4. API/Berechtigungsname	Beschreibung
   Sites.FullControl.All	Verfügt über Vollzugriff auf alle Sitesammlungen
   Sites.Manage.All	Elemente und Listen in allen Websitesammlungen erstellen, bearbeiten und löschen
   Sites.ReadWrite.All	Elemente in allen Websitesammlungen bearbeiten oder löschen
   User.Read	Anmelden und Benutzerprofil lesen

4. Jeweils auf Berechtigung hinzufügen klicken. Dieser Schritt aktiviert die soeben ausgewählten Rechte, Administratorberechtigungen sind erforderlich. Dieser Schritt muss erfolgreich sein, sonst funktioniert die Anbindung später nicht. Bei Problemen meldet Azure einen Fehler.

Schlüssel erstellen

1. Links auf Zertifikate und Geheimnisse klicken
2. Unter Geheime Clientschlüssel auf Neuer geheimer Clientschlüssel klicken
3. Im Feld Beschreibung einen Namen für den Schlüssel eingeben, z.B. VertecSchlüssel
4. Gültigkeitsdauer des Schlüssels wählen (das Maximum beträgt 24 Monate) und den entsprechenden Ablauftermin merken, um vor Ablauf einen neuen Schlüssel zu erstellen und durch den Alten zu ersetzen.
5. Auf Hinzufügen klicken
6. Der Schlüssel, der in der Spalte Wert erscheint, muss in den Vertec Systemeinstellungen unter DMS SharePoint Application Secret eingegeben werden (siehe Schnittstelle in Vertec installieren). Der Schlüssel ist später nicht mehr abrufbar.
7. Client schliessen oder Sharepoint Schnittstelle neu laden

Sharepoint Site anlegen oder bestimmen

Dieser Vorgang muss einmal pro Firma durchgeführt werden.

An dieser Stelle gibt es 3 Fälle:

1. Es wird eine neue SharePoint Site angelegt (bitte entsprechende Anleitung von Microsoft befolgen) oder eine bestehende SharePoint Site verwendet.
   • Diese Site im Browser öffnen
2. Es wird ein neues Team mit TeamSite angelegt (bitte entsprechende Anleitung von Microsoft befolgen) oder eine bestehende TeamSite verwendet, in welcher die Dokumente ablegt werden sollen.
   • Microsoft Teams Webapp öffnen
   • Zum entsprechenden Team navigieren bzw. entsprechendes Team öffnen
   • Files anzeigen
   • In Sharepoint öffnen anwählen
3. Es wird eine neue Office365 Group mit Group Site angelegt (bitte entsprechende Anleitung von Microsoft befolgen) oder eine bestehende Office365 Gruppe mit Group Site verwendet.
   • Die Site der Office 365 Gruppe im Browser öffnen

Alle 3 Fälle führen zum gleichen Ergebnis: Es gibt nun eine SharePoint Site und diese ist im Browser geöffnet.

Nun im Menü Einstellungen den Menüpunkt Websiteinhalte anklicken:

Es erscheint eine Liste, welche die Dokumentbibliotheken der Site enthält. Im Aktionsmenü der entsprechenden Dokumentbibliothek auf Einstellungen klicken:

Unter Webadresse sollte nun ein Link in der Form https://kundenoffice365.sharepoint.com/sites/KundenTeam/Freigegebene Dokumente/Forms/AllItems.aspx? sichtbar sein.

Kopieren Sie den ersten Teil des Links, ohne /Forms/AllItems.aspx etc. (also https://kundenoffice365.sharepoint.com/sites/KundenTeam/Freigegebene Dokumente) und tragen Sie ihn in den Vertec Systemeinstellungen unter DMS SharePoint Document Library URL ein (siehe Schnittstelle in Vertec installieren).

Ab Vertec 6.4.0.10 wird mit der StoreDocument Methode die Aktivität als Objekt übergeben. Die Standard-Schnittstelle funktioniert weiter wie bisher, Metadaten werden nur geschrieben, wenn dies entsprechend eingerichtet wird.

Damit Metadaten geschrieben werden, muss die verwendete DMS-Schnittstelle wie folgt überschrieben bzw. ergänzt werden. Das Beispiel bezieht sich auf die Standard Vertec Sharepoint DMS Schnittstelle.

Es wird ein Script erstellt mit folgendem Text:

#
import DmsSharePoint

class MyDmsSharePointExtension(DmsSharePoint.DmsSharePointExtension):
    __doc__ = "Erweiterung DMS-Extension mit Metadaten"
#    pass

    # Override this method in a subclass to be able to define meta data during document upload.
    # This method is called by Vertec for each document that is uploaded. If the returned
    # dictionary contains entries, Vertec interprets the keys as site column name and the values
    # as site column value and writes meta data accordingly during document upload.
    def getMetaDataDict(self, vertecFilePath, content, aktivitaet):
        self.Log("getMetaDataDict(...)" + (" with aktivitaet" if aktivitaet else " without aktivitaet"))
               
        # override the extension and uncomment this line to activate the meta data example
        return self.getExampleMetaDataDict(vertecFilePath, content, aktivitaet)

        # empty dict => Vertec does not try to write meta data to SharePoint
        return dict()

Damit wird die Methode getExampleMetaDataDict aktiviert, die sich in der Standardschnittstelle befindet und Beispiel-Metadaten zurückgibt. Den entsprechenden Code finden Sie in der Standardschnittstelle:

Die übergebenen Felder müssen zum Metadaten-Schema Ihres Sharepoint passen. Diese Methode wird deshalb im oben erzeugten Script ebenfalls überschieben:

def getExampleMetaDataDict(vertecFilePath, content, aktivitaet):

oder statt der folgenden Zeile

return self.getExampleMetaDataDict(vertecFilePath, content, aktivitaet)

direkt die entsprechenden Werte zurückgegeben.

Dann wird ein Extension-Eintrag erzeugt mit <Name des Scripts>.<Name der Methode> (wie man eine Extension kundenspezifisch anpasst, ist im Artikel Arbeiten mit Schnittstellen (Extensions) beschrieben).

Die Standard Sharepoint Online DMS Schnittstelle wird daraufhin deaktiviert und die hier neu erzeugte installiert.