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:

1. 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.
2. Erzeugen Sie eine Excel-Arbeitsmappe.
3. Schreiben Sie In Zeile 1 Kommentare und Erläuterungen.
4. 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.
5. 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.
6. 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.
7. 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“.
8. Speichern Sie die Excel-Arbeitsmappe ab.
9. 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.

WSSearchCondition

WSSearchCondition liefert eine Reihe von Daten eines oder mehrerer Textbausteine. 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 condition verlangt als Wert einen String. Die Suche filtert als Ergebnis entweder jenen Textbaustein der mit der COO-Adresse übereinstimmt oder die Textbausteine die den Suchstring im Namen oder in der Importkennung enthalten. Ist der String eine COO-Addresse, werden alle anderen Filtermöglichkeiten ignoriert. Der optionale Parameter folders verlangt als Wert einen String Array. Dieser kann die COO-Adressen, Namen oder Externalkey von Textbausteinordnern beinhalten. Die Suche filtert als Ergebnisse jene Textbausteine, die sich in den angegebenen Textbausteinordnern befinden. Der optionale Parameter categories verlangt als Wert einen String Array. Dieser kann die COO-Adressen, Namen oder Externalkey von Dokumentkategorien beinhalten. Die Suche filtert als Ergebnisse jene Textbausteine, die als Kategorie eine der angegebenen Dokumentkategorien verwendet. Der optionale Parameter releasedversions verlangt als Wert einen Wahrheitswert. Wird dieser auf „true“ gesetzt werden die Veröffentlichten Versionen der Textbausteine als Ergebnis verwendet. Ist der Wert „false“ oder nicht gesetzt, werden im Ergebnis die Entwurfsversionen verwendet. Der optionale Parameter modifieddatefrom verlangt als Wert ein Datum im Format „JJJJ-MM-TT“ und filtert das Ergebnis auf Textbausteine, bei denen das „Zuletzt geändert am“-Datum größer gleich dem angegeben Wert ist. Der optionale Parameter modifieddateend verlangt als Wert ein Datum im Format „JJJJ-MM-TT“ und filtert das Ergebnis auf Textbausteine, bei denen das „Zuletzt geändert am“-Datum kleiner dem angegeben Wert ist. Der optionale Parameter modifiedby verlangt als Wert einen String. Die Suche filtert als Ergebnis auf jene Textbausteine, bei denen der „Zuletzt geändert von“-User entweder mit der angegebenen COO-Adresse oder der E-Mail-Adresse übereinstimmt. Der optionale Parameter createddatefrom verlangt als Wert ein Datum im Format „JJJJ-MM-TT“ und filtert das Ergebnis auf Textbausteine, bei denen das „Erstellt am/um“-Datum größer gleich dem angegeben Wert ist. Der optionale Parameter createddateend verlangt als Wert ein Datum im Format „JJJJ-MM-TT“ und filtert das Ergebnis auf Textbausteine, bei denen das „Erzeugt am/um“-Datum kleiner dem angegeben Wert ist. Der optionale Parameter createdby verlangt als Wert einen String. Die Suche filtert als Ergebnis auf jene Textbausteine, bei denen der „Erzeugt von“-User entweder mit der angegebenen COO-Adresse oder der E-Mail-Adresse übereinstimmt. 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.

WSUpdateBaseFiles

Über die Schnittstelle WSUpdateBaseFiles kann der Benutzer Verträge, Rechtsakten und Anfragen erzeugen bzw. aktualisieren, sowie Dokumente zu diesen Verträgen, Rechtsakten und Anfragen erzeugen, aktualisieren oder löschen. Um die Schnittstelle aufzurufen, muss der Parameter data übergeben werden, welcher die Daten des zu erzeugenden oder zu aktualisierenden Vertrags, der zu erzeugenden oder zu aktualisierenden Rechtsakte, der zu erzeugenden oder zu aktualisierenden Anfrage enthält.
Die Schnittstelle liefert zwei Werte zurück: den Wert result und den Wert basefiles. Der Wert result gibt einen Überblick über das gesamte Ergebnis des Schnittstellenaufrufs:

• statuscode: enthält OK bei einer erfolgreichen Ausführung und NOK bei einer gescheiterten Ausführung.
• details: enthält die Liste aller Vertragslisten bzw. Rechtsbereiche, in denen die Verträge, Rechtsakten oder Anfragen erzeugt oder aktualisiert wurden.
• updatedbasefiles: enthält die Anzahl aller erfolgreich aktualisierten Verträge, Rechtsakten oder Anfragen.
• createdbasefiles: enthält die Anzahl aller erfolgreich erzeugten Verträge, Rechtsakten oder Anfragen.
• updateddocs: enthält die Anzahl aller erfolgreich aktualisierten Dokumente.
• createddocs: enthält die Anzahl aller erfolgreich erzeugten Dokumente.
• deleteddocs: enthält die Anzahl aller erfolgreich gelöschten Dokumente.
• faileddocs: enthält die Anzahl aller nicht erfolgreich erzeugten oder aktualisierten Dokumente.
• failedbasefiles: enthält die Liste aller Verträge, Rechtsakten oder Anfragen, die nicht erfolgreich erzeugt bzw. aktualisiert wurden. Diese Liste besteht aus zwei Werten:
• entrykey: enthält die Cloud-Adresse des Vertrags, der Rechtsakte oder der Anfrage.
• entryvalue: enthält die Fehlermeldung, die dem Benutzer hilft, den Grund zu finden, weshalb die Fehler aufgetreten ist.

Der Wert basefiles ist eine Liste von Informationen aller erzeugten bzw. aktualisierten Verträge, Rechtsakten oder Anfragen. Jeder Eintrag dieser Liste enthält:

• bfevent: das Ereignis („Created“, „Updated“), das auf diesem Vertrag, auf dieser Rechtsakte oder auf dieser Anfrage aufgetreten ist.
• bfbasefile: die Cloud-ID und den Namen des Vertrags, der Rechtsakte oder der Anfrage.
• bfdocumentsresult: eine Liste von Informationen zu den Dokumenten jedes erzeugten oder aktualisierten Vertrags, jeder erzeugten oder aktualisierten Rechtsakte oder jeder erzeugten oder aktualisierten Anfrage. Die Informationen sind:
  • docstatuscode: enthält OK bei einer erfolgreichen Ausführung und NOK bei einer gescheiterten Ausführung.
  • docdetails: enthält die Cloud-ID des Vertrags, der Rechtsakte oder der Anfrage, in dem/der das Dokument erzeugt bzw. aktualisiert wurde.
  • updateddocuments: enthält die Anzahl aller in dieser Akte aktualisierten Dokumente.
  • createddocuments: enthält die Anzahl aller in dieser Akte erzeugten Dokumente.
  • deleteddocuments: enthält die Anzahl aller aus dieser Akte gelöschten Dokumente.
  • numfaileddocuments: enthält die Anzahl aller nicht erfolgreich erzeugten oder aktualisierten Dokumente.
  • changeddocs: enthält eine Liste von Informationen aller erzeugten bzw. aktualisierten Dokumente. Jeder Eintrag dieser Liste enthält:
    • bfevent: das Ereignis („Created“, „Updated“, „Deleted“), das auf diesem Dokument aufgetreten ist.
    • document: die Cloud-ID und den Namen des Dokuments.