Webservice-Schnittstelle

Fabasoft Contracts stellt eine Webservice-Schnittstelle zur Verfügung. In diesem Kapitel wird die Einrichtung, die Authentisierung sowie die konkrete Verwendung der einzelnen Operationen erläutert.

Einrichtung

Die WSDL ist unter folgender URL erreichbar:

https://<host>/<vdir>/fscdav/wsdl?WEBSVC=IDANGLCONTRACTS_111_100_WebService

„<host>“ ist in der Lokation Deutschland durch „https://de.cloud.fabasoft.com“ zu ersetzen und „<vdir>“ durch „folio“:

https://de.cloud.fabasoft.com/folio/fscdav/wsdl?WEBSVC=IDANGLCONTRACTS_111_100_WebService

Das Webservice unterstützt auch das JSON-Format:

https://<host>/<vdir>/wsjson/IDANGLCONTRACTS_111_100_WebService/<operation>

Authentisierung

Zur Authentisierung müssen Sie als Benutzernamen Ihre E-Mail-Adresse verwenden und ein Passwort für Anwendungen für „Vertragsmanager“ generieren. Um ein Passwort für Anwendungen zu generieren, gehen Sie folgendermaßen vor:
https://help.cloud.fabasoft.com/index.php?topic=doc/Benutzerhilfe-Fabasoft-Cloud-ger/kontoeinstellungen.htm#zugriff-fuer-anwendungen: neues Fenster

WSImportZIP

WSImportZIP importiert ein ZIP-Archiv in eine Vertragsmanagerliste. Der optionale Parameter name erhält den Namen des ZIP-Archivs; wenn der Paramater leer ist, wird automatisch ein Name für die Datei nach dem Muster „Import <aktuelles Datum>“ generiert. Der Parameter baselist verlangt als Wert die Fabasoft Cloud ID einer Vertragsmanagerliste, ansonsten schlägt die Operation fehl. Der optionale Parameter extension erhält als Wert das Dateiformat; wird kein Wert vergeben, setzt die Operation standardmäßig das ZIP-Format. Der Parameter data verlangt als Wert die zu übertragende Datei, andernfalls schlägt die Operation fehl.

WSGetExportZIPs

WSGetExportZIPs ruft eine Liste aller Schlüssel von ZIP-Archiven ab, die Vertragsmanagerakten in einer Vertragsmanagerliste enthalten. Der Parameter baselist verlangt als Wert die Fabasoft Cloud ID einer Vertragsmanagerliste, ansonsten schlägt die Operation fehl. Der Parameter selector verlangt als Wert ein Objekt mit einem Attribut bzw. eine Attributsdefinition, in dem Vertragsmanagerakten bzw. Zuordnungsziele enthalten sind. Der Rückgabewert keys enthält eine Liste aller Schlüssel zu ZIP- Archiven, die exportiert werden sollen.

Wenn der Parameter selector keinen Wert enthält, wird standardmäßig die Fabasoft Cloud ID der Vertragsmanagerliste gesetzt.

Wenn als selector eine Vertragsmanagerakte definiert wird, werden die Schlüssel im Rückgabewert nach dem Muster „COO.a.b.c.d|COO.e.f.g.h“ ausgegeben.

Wenn als selector eine Attributsdefinition (z. B. die Liste der abgelaufenen Verträge) definiert wird, enthält die Liste in keys für jeden Vertrag einen eigenen Eintrag.

WSImportSuppliers

WSImportSuppliers importiert eine Liste von Lieferanten aus einer XML-Datei im IDoc-Format. Der optionale Parameter context enthält die Fabasoft Cloud ID für den Kontext des Imports; standardmäßig ist dieser ein Kontaktraum. Der Parameter data verlangt die XML-Datei, ansonsten schlägt die Operation fehl. Der optionale Parameter synchronous legt fest, ob die Verarbeitung der XML-Datei synchron oder asynchron durchzuführen ist, da große Datenmengen gegebenenfalls ein Timeout bewirken können.

Hinweis: Wenn das Webservice asynchron aufgerufen wird, sind die aktuell in Verarbeitung befindlichen Datenobjekte in der Vertragsmanager-Konfiguration im Bereich „Asynchrone Datenobjekte“ sichtbar.

WSImportBaseListsAndRoles

WSImportBaseListsAndRoles importiert eine Reihe von Vertragsmanagerlisten aus einer Excel-Arbeitsmappe. Der Parameter data verlangt als Wert ein Excel-Arbeitsblatt, ansonsten schlägt die Operation fehl. Der Parameter configuration verlangt als Wert die Fabasoft Cloud ID eines App-Rooms (z. B. die ID der Vertragsmanager-Konfiguration), ansonsten schlägt die Operation fehl.

Wenn in der importierten Excel-Arbeitsmappe Berechtigungen definiert sind, werden die Benutzer und Organisationseinheiten der Organisation des aktuellen Benutzers hinzugefügt.
Nach dem Import wird eine neue Excel-Arbeitsmappe erzeugt, die die Fabasoft Cloud IDs der erzeugten Vertragsmanagerlisten enthält.

Führen Sie vor dem Aufruf der Operation die folgenden Schritte aus:

Legen Sie in der Cloud-Organisation die gewünschten Vertragslisten, Rechtsbereiche Vertragsmanageraktenarten und/oder Zuordnungen an.
Hinweis: Vertragsmanageraktenarten müssen veröffentlichte Kategorien oder Formulare sein.
Erzeugen Sie eine Excel-Arbeitsmappe.
Schreiben Sie In Zeile 1 Kommentare und Erläuterungen.
Schreiben Sie In Zeile 2 ab Spalte „F" die Namen der zuvor erzeugten Vertragslisten, Rechtsbereiche, Vertragsmanageraktenarten bzw. Zuordnungen.
Hinweis: Stellen Sie sicher, dass die Namen der erzeugten Objekte in Fabasoft Contracts korrekt in die Excel-Arbeitsmappe übernommen werden, andernfalls schlägt die Operation fehl.
Schreiben Sie in Zeile 3 ab Spalte „F" die E-Mail-Adressen der primären Ansprechpartner bzw. der Eskalationskontakte für das jeweilige Objekt in Zeile 2.
Schreiben Sie ab Zeile 4 in die Spalten „A“ bis „E“ jeweils die Werte für die folgenden Daten:
- Nachname
- Vorname
- E-Mail-Adresse
- Team-Präfix
- Team-Suffix
  Hinweis:
  - Wenn kein Team-Suffix angegeben wird, entspricht der Teamname dem Team-Präfix.
  - Wenn ein Team-Suffix angegeben wird, werden Team-Präfix und Team-Suffix mit „ - “ zu einem Teamnamen verbunden.
Schreiben Sie ab Zeile 4 und ab Spalte "F" die Berechtigungen für Benutzer und Gruppen für das jeweilige Element in Zeile 2:
- „r“ für „Leseberechtigt“
- „w“ für „Änderungsberechtigt“
- „x“ für „Alle Rechte“
  Hinweis: „x“ ist nicht in Vertragsmanageraktenarten anwendbar.
- „r“ für „Eingeschränkte Rechte“
  Hinweis: „r“ ist nur in Vertragslisten und Rechtsbereiche anwendbar.
- „p“ für „Primärer Ansprechpartner“
  Hinweis: „p“ ist nur in Vertragslisten und Rechtsbereichen anwendbar, zusätzlich zur Berechtigung und ihr zwingend nachfolgend, z. B. „rp“.
- „e“ für „Eskalationskontakt“
  Hinweis: „e“ ist nur in Zuordnungen anwendbar, zusätzlich zur Berechtigung und ihr zwingend nachfolgend, z. B. „we“.
Speichern Sie die Excel-Arbeitsmappe ab.
Legen Sie die Arbeitsmappe in dem Kontext ab, von dem aus Sie das Webservice ansteuern.

WSSearchContracts

WSSearchContracts liefert eine Reihe von Kopfdaten eines oder mehrerer Verträge. Die Suche kann dabei auf mehrere Parameter beschränkt werden. Der optionale Parameter context enthält die Fabasoft Cloud ID für den Kontext der Suche; standardmäßig ist dies die Organisation, in der sich der Benutzende befindet. Der optionale Parameter contractnumber verlangt als Wert einen String nach dem Muster „<Kürzel Vertragsliste>/<Jahr>/<Ordnungszahl>“. Ausgefüllt werden alle weiteren Parameter ignoriert und nach einem Vertrag gesucht, dessen Identifikation mit dem angegebenen Wert übereinstimmt. Der optionale Parameter contractfolders verlangt als Wert eine Liste der Fabasoft Cloud-IDs der Vertragslisten, auf die die Suche beschränkt werden sollte. Der optionale Parameter signatories verlangt als Wert eine Liste mit Objekten mit einem der folgenden Eigenschaften objaddress, objexternalkey, objname, signatoryname, orgsuppliernr, orgcustomernr, orgtradeid, orgvatid, orgdataprocid oder orgjurisdiction. Die Eigenschaften sollten mit Werten befüllt sein, die einem Vertragspartner entsprechen. Somit kann nach Verträgen mit diesen Vertragspartnern gesucht werden. Der optionale Parameter states verlangt als Wert eine Liste mit ContractState`s und filtert jene Verträge dessen Status einer der Werte entspricht. Der optionale Parameter begindatefrom verlangt als Wert ein Datum und beschränkt die Suche auf Verträge dessen Startdatum größer dem angegeben Wert sind. Der optionale Parameter begindateto verlangt als Wert ein Datum und beschränkt die Suche auf Verträge dessen Startdatum kleiner dem angegebenen Wert sind. Der optionale Parameter enddatefrom verlangt als Wert ein Datum und beschränkt die Suche auf Verträge dessen Enddatum größer dem angegeben Wert sind. Der optionale Parameter enddateto verlangt als Wert ein Datum und beschränkt die Suche auf Verträge dessen Enddatum kleiner dem angegebenen Wert sind. Der optionale Parameter excludepermanent verlangt einen Wahrheitswert und beschränkt beim Wert „true“ die Suche auf Verträge die nicht auf unbestimmte Zeit dauern. Der optionale Parameter contractsigningdatefrom verlangt als Wert ein Datum und beschränkt die Suche auf Verträge dessen Unterschriftsdatum größer dem angegeben Wert sind. Der optionale Parameter contractsigningdateto verlangt als Wert ein Datum und beschränkt die Suche auf Verträge dessen Unterschriftsdatum kleiner dem angegebenen Wert sind. Der optionale Parameter contracttype verlangt als Wert einen String mit dem Objektname der Vertragsart, auf die die Suche gefiltert werden sollte. Der optionale Parameter contractlanguage verlangt als Wert einen String der entweder dem Objektnamen, dem iso6391, dem iso6392B oder dem iso6392T Standard einer Sprache entspricht und filtert die Suche nach Vertragssprachen mit dem entsprechen Wert. Der optionale Parameter additionalfieldreferences verlangt als Wert eine Liste von Strings, die eine Referenz weiterer Metadatenfeldern enthalten, welche der Benutzende in den Kopfdaten zusätzlich mitgeliefert haben möchte. Die optionalen Parameter includeemptybegindate, includeemptyenddate und includeemptycontractsigningdate verlangen jeweils einen Wahrheitswert und beziehen bei dem Wert „true“, Verträge mit ein, die bei den dazugehörigen Datumsfeldern keinen Wert besitzen.

WSSearchLegalFile

WSSearchLegalFile liefert eine Reihe von Kopfdaten eines oder mehrerer Rechtsakten. Die Suche kann dabei auf mehrere Parameter beschränkt werden. Der optionale Parameter context enthält die Fabasoft Cloud ID für den Kontext der Suche; standardmäßig ist dies die Organisation, in der sich der Benutzende befindet. Der optionale Parameter legalfilenumber verlangt als Wert einen String nach dem Muster „<Kürzel Rechtsbereich>/<Jahr>/<Ordnungszahl>“. Ausgefüllt werden alle weiteren Parameter ignoriert und nach einem Rechtsakte gesucht, dessen Identifikation mit dem angegebenen Wert übereinstimmt. Der optionale Parameter legalareas verlangt als Wert eine Liste der Fabasoft Cloud-IDs der Rechtsbereiche, auf die die Suche beschränkt werden sollte. Der optionale Parameter states verlangt als Wert eine Liste mit LegalFileState`s und filtert jene Rechtsakten dessen Status einer der Werte entspricht. Der optionale Parameter legalfilesigningdatefrom verlangt als Wert ein Datum und beschränkt die Suche auf Rechtsakten dessen Unterschriftsdatum größer dem angegeben Wert sind. Der optionale Parameter legalfilesigningdateto verlangt als Wert ein Datum und beschränkt die Suche auf Rechtsakten dessen Unterschriftsdatum kleiner dem angegebenen Wert sind. Der optionale Parameter legalfiletype verlangt als Wert einen String mit dem Objektname der Vertragsart, auf die die Suche gefiltert werden sollte. Der optionale Parameter additionalfieldreferences verlangt als Wert eine Liste von Strings, die eine Referenz weiterer Metadatenfeldern enthalten, welche der Benutzende in den Kopfdaten zusätzlich mitgeliefert haben möchte. Der optionale Parameter includeemptylegalfilesigningdate verlangt einen Wahrheitswert und bezieht beim Wert „true“ jene Rechtsakten mit ein, welche beim Feld „Unterschriftsdatum“ keinen Wert besitzen.