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”.

WSSearchCondition

WSSearchCondtition returns a list of data for one or more text modules. 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 condition requires a string as value. As a result, the search filters either the text module that matches the COO-address or the text modules that contain the search string in the name or the externalkey. If the string is a COO-address, all other filter options are ignored. The optional parameter folders requires a string array as value. The strings in the array could contain the COO-addresses, names or external keys of text module folders. The search filters the text modules located in the specified text module folders as results. The optional parameter categories requires a string array as value. The strings in the array could contain the COO-addresses, names or external keys of document categories. The search filters the results to those text modules that use one of the specified document categories as a category. The optional parameter releasedversions requires a boolean value. If this is set to "true", the published versions of the text modules are used as the result. If the value is "false" or not set, the draft versions are used in the result. The optional parameter modifieddatefrom requires a date in the format "YYYY-MM-DD" as value and filters the result for text modules for which the "Last modified on" date is greater than or equal to the specified value. The optional parameter modifieddateend requires a date in the format "YYYY-MM-DD" as value and filters the result for text modules for which the "Last modified on" date is less than the specified value. The optional parameter modifiedby requires a string as value. The search filters the result to those text modules for which the "Last modified by" user matches either the specified COO-address or the e-mail address. The optional parameter createddatefrom requires a date in the format "YYYY-MM-DD" as value and filters the result for text modules for which the "Created on/at" date is greater than or equal to the specified value. The optional parameter createddateend requires a date in the format "YYYY-MM-DD" as value and filters the result for text modules for which the "Created on/at" date is less than the specified value. The optional parameter createdby requires a string as value. The search filters the result to those text modules for which the "Created by" user matches either the specified COO address or the e-mail address. 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 return data.

WSUpdateBaseFiles

The WSUpdateBaseFiles interface allows users to create or update contracts and legal files, as well as to create, update, or delete documents related to these contracts and legal files. To call the interface, a parameter must be passed, namely the parameter data, which contains the data of the contract or legal record to be created or updated.
The interface returns two values: result and basefiles.
The result value provides an overview of the entire interface call outcome:

• statuscode: contains either OK for successful execution or NOK for failed execution.
• details: contains the list of all contract or legal areas in which the contracts or legal records were created or updated.
• updatedbasefiles: contains the number of successfully updated contracts or legal records.
• createdbasefiles: contains the number of successfully created contracts or legal records.
• updateddocs: contains the number of successfully updated documents.
• createddocs: contains the number of successfully created documents.
• deleteddocs: contains the number of successfully deleted documents.
• faileddocs: contains the number of documents that were not successfully created or updated.
• failedbasefiles: contains the list of all contracts or legal records that were not successfully created or updated. This list consists of two values:
  • entrykey: contains the cloud address of the contract or legal record.
  • entryvalue: contains the error message that helps the user quickly identify the error in the request.

The basefiles value is a list of information about all created or updated contracts or legal records. Each entry in this list contains:

• bfevent: the event ("Created", "Updated") that occurred on this contract or legal record
• bfbasefile: the cloud ID and name of the contract or legal record.
• bfdocumentsresult: a list of information about the documents of each created or updated contract or legal record. This information includes:
  • docstatuscode: contains either OK for successful execution or NOK for failed execution.
  • docdetails: contains the cloud ID of the contract or legal record in which the document was created or updated.
  • updateddocuments: contains the number of documents updated in this record.
  • createddocuments: contains the number of documents created in this record.
  • deleteddocuments: contains the number of documents deleted from this record.
  • numfaileddocuments: contains the number of documents not successfully created or updated.
  • changeddocs: contains a list of information about all created or updated documents. Each entry in this list contains:
    • bfevent: the event ("Created", "Updated", "Deleted") that occurred on this document.
    • document: the cloud ID and name of the document.