Webservice Interface

This chapter covers the setup, authentication and concrete usage of operations that can be executed via the webservice interface provided by Fabasoft Contracts.

Setup

The WSDL can be reached via this URL:

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

In the data location “Germany“, the variable “<host>“ needs to be replaced with “https://de.cloud.fabasoft.com“ and “<vdir>“ with "folio“:

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

The web service also supports JSON:

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

Authentication

In order to authenticate yourself, you must use your e-mail address as your user name and generate a password for applications. Read the instructions in the chapter ”Access for Applications: new window“ in the document ”User Help Fabasoft Cloud“.

WSImportZIP

WSImportZIP imports a ZIP archive into a contract manager list. The optional parameter name Contains the name of the ZIP archive. If name has no value, a name is automatically generated according to the pattern ”Import <current date>“. The parameter baselist requires the Fabasoft Cloud ID of a contract manager list, otherwise the operation fails. The optional parameter extension Contains the file format. If extension has no value, the operation falls back to the ZIP format.

WSGetExportZIPs

WSGetExportZIPs fetches a list of all keys of ZIP archives contained by contract manager files within contract manager lists. The parameter baselist requires the Fabasoft Cloud ID of contract manager list, otherwise the operation fails. The parameter selector requires an object with an attribute or an attribute definition that contains contract manager files or assignment targets. The return value keys contains a list of all keys to ZIP archives that are to be exported. If the parameter selector has no value, the Fabasoft Cloud ID of the contract manager list is set. If the value of selector is a contract manager file, the keys in the return value are formatted like “COO.a.b.c.d|COO.e.f.g.h“. If the value of selector is an attribute definition (for example the list of expired contracts), the list in keys contains an individual entry for each contract.

WSImportSuppliers

WSImportSuppliers imports a list of suppliers from an XML file in the IDoc format. The optional parameter context contains the Fabasoft Cloud ID of the import context which normally is a contact room. The parameter data requires the XML file, otherwise the operation fails. The optional parameter synchronous determines if the XML is processes (a)synchronously since large amounts of data may cause a timeout.

Note: While the webservice is active, all currently processes data objects are visible in the area “Asynchronous Data Objects” in the Contract Manager Configuration.

WSImportBaseListsAndRoles

WSImportBaseListsAndRoles imports a number of Contract Manger lists from an Excel worksheet. The parameter data requires the worksheet, otherwise the operation fails. The parameter configuration requires the Fabasoft Cloud ID of an App Room (e.g. the Contract Manager Configuration), otherwise the operation fails.

If there are permissions defined in the import Excel worksheet, members and organization units are added to the organization of the current user. After the import, a new Excel worksheet is generated that contains the Fabasoft Cloud IDs of the newly created contract manager lists.

Before executing the operation, do the following steps:

1. In the Cloud Organization, created the desired contract folders, legal areas, assignments and/or file types.
   Note: Contract Manager file types must be the release versions of categories or forms.
2. Create an Excel worksheet.
3. In row 1, write your comments and explanations.
4. In row 2, as of column F, write the names of the newly created contract folders, legal areas, file types and/or assignments.
   Note: Make sure to copy the names of the objects in Fabasoft Contracts into the Excel worksheet verbatim, otherwise the operation fails.
5. In row 3, as of column F, write the e-mail addresses of the primary contacts and/or escalation contacts for the corresponding object in row 2.
6. In row 4, in columns A to E, write the values for the following data points:
   • Surname
   • First name
   • E-Mail address
   • Team prefix
   • Team suffix
     Note:
     • If no team suffix is defined, the team name is identical to the team prefix.
     • If a team suffix is defined, the prefix and suffix are combined into a team name and hyphenated.
7. In row 4, as of column F, write the permissions for members and groups for the corresponding object in row 2:
   • “r“ for “Read Access“
   • “w“ for “Change Access“
   • “x“ for “Full Control“
     Note: “x“ is not applicable in contract manager file types.
   • “r“ for “Restricted Access“
     Note: “r“ is only applicable in contract folders and legal areas.
   • “p“ for “Primary Contact“
     Note: “p“ is only applicable in contract folders and legal areas, in addition to and necessarily subsequent to the permission, e.g. “rp“ or “xp”.
   • “e“ for “Escalation Contact“
     Note: “e“ is only applicable in assignment instances, in addition to and necessarily subsequent to the permission, e.g. “we“.
8. Save and close the Excel worksheet.
9. Store the worksheet in the context from which you execute the web service operations.

WSSearchContracts

WSSearchContracts returns a list of headdata for one or more contracts. The search can be limited to several parameters. The optional parameter context contains the Fabasoft Cloud ID for the context of the search; by default, this is the organization in which the user is located. The optional parameter contractnumber requires a string with the value "<contractlist abbreviation>/<year>/<ordinalnumber>". If filled in, all other parameters will be ignored and a contract is searched for whose identification matches the specified value. The optional parameter contractfolders requires a list of Fabasoft Cloud IDs of the contractlists to which the search should be restricted. The optional parameter signatories requires as value a list of objects with one of the following properties objaddress, objexternalkey, objname, signatoryname, orgsuppliernr, orgcustomernr, orgtradeid, orgvatid, orgdataprocid or orgjurisdiction. The properties should be filled with values that correspond to a signatorypartner. This allows you to search for contracts with these signatorypartners. The optional parameter states requires a list with ContractState`s as a value and filters those contracts whose status corresponds to one of the values. The optional parameter begindatefrom requires a date as a value and restricts the search to contracts whose start date is greater than the specified value. The optional parameter begindateto requires a date as a value and restricts the search to contracts whose start date is less than the specified value. The optional parameter enddatefrom requires a date as a value and restricts the search to contracts whose end date is greater than the specified value. The optional parameter enddateto requires a date as a value and restricts the search to contracts whose end date is less than the specified value. The optional parameter excludepermanent requires a boolean value, if the value is "true" the search is restricted to contracts that do not last indefinitely. The optional parameter contractsigningdatefrom requires a date as the value and restricts the search to contracts whose signing date is greater than the specified value. The optional parameter contractsigningdateto requires a date as the value and restricts the search to contracts whose signing date is less than the specified value. The optional parameter contracttype requires a string with the object name of the contract type to which the search should be filtered. The optional parameter contractlanguage requires the value of a string that corresponds to either the object name, the iso6391, the iso6392B or the iso6392T standard of a language and filters the search for contract languages with the corresponding value. The optional parameter additionalfieldreferences requires the value of a list of strings containing a reference to other metadata fields that the user would also like to have supplied in the headdata. The optional parameters includeemptybegindate, includeemptyenddate and includeemptycontractsigningdate each require a boolean value, if the value is "true" the search includes those contracts that values in the corresponding date properties are empty.

WSSearchLegalFile

WSSearchLegalFile returns a list of headdata for one or more legalfiles. The search can be limited to several parameters. The optional parameter context contains the Fabasoft Cloud ID for the context of the search; by default, this is the organization in which the user is located. The optional parameter legalfilenumber requires a string with the value "<legalarea abbreviation>/<year>/<ordinalnumber>". If filled in, all other parameters will be ignored and a legalfile is searched for whose identification matches the specified value. The optional parameter legalareas requires a list of Fabasoft Cloud IDs of the legalareas to which the search should be restricted. The optional parameter states requires a list with LegalFileState`s as a value and filters those legalfiles whose status corresponds to one of the values. The optional parameter legalfilesigningdatefrom requires a date as the value and restricts the search to legalfiles whose signing date is greater than the specified value. The optional parameter legalfilesigningdateto requires a date as the value and restricts the search to legalfiles whose signing date is less than the specified value. The optional parameter legalfiletype requires a string with the object name of the legalfile type to which the search should be filtered. The optional parameter additionalfieldreferences requires the value of a list of strings containing a reference to other metadata fields that the user would also like to have supplied in the headdata. The optional parameter includeemptylegalfilesigningdate requires a boolean value, if the value is "true" the search includes contracts that do not have a value in the property “Signing Date”.