Abacus AbaReport REST-API

The Abacus AbaReport REST-API provides functionality for exporting AbaReports via a REST-API WebService. The AbaReports accessed by the AbaReport-API WebService must first be configured on the Abacus Server.

The following criteria for the reports should be observed :

The AbaReports must be saved on the Abacus Server in the in the "x:\abac\kd\abav\web" folder (or a sub-folder beneath this folder), in order to be access the Reports via WebService
The Service-User must be configured with the Interface Option "AbaReport" in the Abacus User Managament (Q981)
The Service-User must have the Application access rights for "AbaR" in the Abacus User Managament (Q981)

Attention : The AbaReport server path "kd\abav\web" is Scope dependent. If Scopes are being used then the Server reference folder is defined within the Scope e.g. "x:\abac\scopes\<Scope-Name>\kd\abav\web" where <Scope-Name> is the name of the Scope.

If the AbaReport file is in a sub folder beneath the main "x:\abac\kd\abav\web" folder, then the relative path must be specified with forward slash "/" as URL compatible (i.e. with "%2F"). Only the report name part with the relative path should be URL encoded. (On some servers where "URL-Sanitizing" is active, and an encoding of the forward slash "/" with "%2F" is not possible, a backslash "\" encoding using "%5C" may be possible)

Server Report Path	URL Encoded	Request URL
x:\abac\kd\abav\web\data\abareport_test.avx	data%2Fabareport_test.avx	/api/abareport/v1/report/7777/data%2Fabareport_test.avx

Note : The default file extension for Reports is "*.avw". The file extension ".avw" will be appended to the report file name, if not explicitly defined when requesting the report. The file extension for "*.avx" reports can be explicitly defined when using "*.avx" reports. Report file names may only contain the characters A-Z, a-z, 0-9, underline "_" and space. Due to security reasons, other characters, including European characters (e.g. ä, ö, ü, à, é, è, Ä, Ö, Ü, À, É, È, etc.), are not permitted in the report file name.

Setup of the Service User in Abacus UI (Q981)

The AbaReport REST-API is designed for access using an Abacus Service-User, that can be configured in the Abacus User Management (Q981). The specified Service-User can only access Abacus via the available interfaces (access to the Abacus UI is not possible). The Service-Users are identified with a Client-ID and Client-Secret (ClientSchlüssel), that can be copied from the Abacus User Management when the user is created. Please refer to the general documentation for authenticating a REST-API Service-Users with Abacus (see: Abacus REST_API ).

After obtaining the access-token via the OAuth-Endpoint, the AbaReport REST-API interface can be accessed by including the Authorization header with the specific request. Further information regarding the Abacus AbaReport REST-API's can be located directly in the Abacus Server with the Swagger URL http://localhost:40000/swagger-ui/index.html. By default is the Swagger-UI URL accessible via "localhost". It can be configured to access the Swagger documentation externally, but it is generally not required.

Report Request Procedure

The following steps are necessary to export the Report data :

Start Report (POST /report/{mandant}/{reportname})
Get the report status (GET /jobs/{id}), until either 'FinishedSuccess' or 'FinishedError' is returned
Get the Report result (GET /jobs/{id}/output)
Close the Report-Session (DELETE /jobs/{id})

Note : If the report response returns with 'Running', the report status must be further polled until the state 'FinishedSuccess' or 'FinishedError' is returned. The client side polling of the report status should include a short time interval between the requests. A recommended starting interval is 250 milliseconds, Depending on the duration of report preparation, this value could be increased.

Output Report Types

The following output report types are available

Output Report Type	Description
"txt"	Report returned as text comma separated values (CSV) (Detail Component-Elements only)
"txt_all"	Report returned as text (All Report Component-Elements)
"txt_cstr"	Report returned as text coded as C/Java String format (Detail Component-Elements only)
"txt_allcstr"	Report returned as text coded as C/Java String format (All Report Component-Elements)
"xml_query"	Report rows returned as xml format with field name and value
"xml"	Report returned as XML defined in Report output
"json"	Report rows returned as json format with field name and value
"json_compact"	Report rows returned as json format with field name and value (with no line-feed/whitespace formatting)
"json_userdef"	Report returned as JSON defined in Report output
"json_userdef_compact"	Report returned as JSON defined in Report output (with no line-feed/whitespace formatting)

Note : The Output Types "json_userdef" and "xml" can only be used in conjunction with Reports that output JSON and XML, respectively.

Example Report Request (POST /report/{mandant}/{reportname})
The Mandant number and report name are definied via the Request-URL. In the POST body, the following parameters are defined :

"outputType" : the report output type (possible options "txt", "xml_query", "json", "json_userdef" and "xml")
"paging" : The maximum number of rows returned in report result
"parameters" : List of input report parameters as name/value variables

Note : The "paging" size should be realistically specified to limit the maximum size of the page blocks that need to be retrieved via the HTTP connection. The minimum "paging" size is defined as 10. If a "paging" value less than 10 is specified, the default is set to 10000 data rows. No maximum value is defined, but large report results should be realistically split into blocks to avoid problems with memory and resources, both on the server and the client.

Example of Report Request Procedure

The following shows a sequence of example request procedures to retrieve a basic report. Please note that the requests and responses shown below have been formatted with line breaks and indenting for easier reading.

1. Request : Start Report

POST /api/abareport/v1/report/7777/abareport_test.avx HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:40000
Connection: keep-alive
Content-Length: 89

{
  "outputType":"txt",
  "paging":200,
  "parameters": 
  {
    "param1" : "value1",
    "param2" : "value2"
  }
}

Response : State Running

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json
Content-Length: 166

{
  "id":"58621b44-45c7-bd55-ce3c-543462505db6",
  "state":"Running",
  "message":"",
  "submittedAt":"2021-05-03T16:21:45.188+02:00",
  "startedAt":"2021-05-03T16:21:45.198+02:00"
}

2. Request : Get Report Status (depending on the report preparation time this request may be repeated)

GET /api/abareport/v1/jobs/58621b44-45c7-bd55-ce3c-543462505db6 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:40000
Connection: keep-alive

Response : State Running

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json
Content-Length: 166

{
  "id":"58621b44-45c7-bd55-ce3c-543462505db6",
  "state":"Running",
  "message":"",
  "submittedAt":"2021-05-03T16:21:45.188+02:00",
  "startedAt":"2021-05-03T16:21:45.198+02:00"
}

2a. Request (repeated) : Get Report Status

GET /api/abareport/v1/jobs/58621b44-45c7-bd55-ce3c-543462505db6 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:40000
Connection: keep-alive

Response : State FinishedSuccess

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json
Content-Length: 245

{
  "id":"58621b44-45c7-bd55-ce3c-543462505db6",
  "state":"FinishedSuccess",
  "message":"rows\u003d213;pages\u003d1",
  "submittedAt":"2021-05-03T16:21:45.188+02:00",
  "startedAt":"2021-05-03T16:21:45.198+02:00",
  "finishedAt":"2021-05-03T16:21:45.365+02:00"
}

The report preparation is finished when "state":"FinishedSuccess" is returned. The report result can then be obtained by requesting the results via the return Job "id".

3. GET Report Result first output page Request and Response (.../output/1)

GET /api/abareport/v1/jobs/58621b44-45c7-bd55-ce3c-543462505db6/output/1 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:40000
Connection: keep-alive

Response : Report results returned

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: text/plain
Content-Length: 17319

ADR_INR,ADR_KURZNA,ADR_NAME,ADR_VORNAME,ADR_LAND,ADR_PLZ,ADR_ORT,ADR_MUTDATUM
106,"SWISS LIFE","Swiss Life AG","","CH","8022","Zürich",05.03.2021 09:41:57.408
109,"MOBILIAR","Mobiliar","","CH","9001","St. Gallen",05.03.2021 09:42:54.891
1,"ABACUS DEMO AG","Abacus Demo AG","","CH","9300","Wittenbach",04.02.2019 13:46:19.756
2,"MATTER & SCHLATT","Matter & Schlatter","","CH","4500","Solothurn",24.01.2020 13:37:16.693
3,"RILLING AG","Rilling AG","","CH","9200","Gossau SG",24.01.2020 13:37:22.060
4,"SWISSCOM AG","Swisscom AG","","CH","9001","St. Gallen",30.01.2020 18:04:46.382
5,"LAGRO GMBH","Lagro GmbH","","DE","80000","München",30.01.2020 18:05:24.977
6,"ROCKWELL INC","Rockwell Inc.","","US","WA98130","Seattle",21.11.2013 15:17:02.789
7,"DOLBI LTD","Dolbi Ltd","","US","90000","San Francisco",24.01.2020 13:37:37.359
8,"BOSSHARD AG","Bosshard AG","","CH","3003","Bern",24.01.2020 13:37:42.686
....
....
212,"BRAENDLE SANDRA","Brändle","Sandra","CH","9230","Flawil",27.01.2015 16:39:37.411
213,"DE COSTA SILVIA","De Costa","Silvia","CH","9204","Andwil SG",27.01.2015 16:40:10.833
214,"SCHMIDLIN GABRIE","Schmidlin","Gabriela","CH","9403","Goldach",27.01.2015 16:40:38.068
215,"MEIERHANS JULIAN","Meierhans","Julian","CH","9240","Uzwil",27.01.2015 16:41:08.225
216,"GIGANDET FRANC","Gigandet","François","CH","2513","Twann",26.02.2015 16:57:47.933
217,"ABACUS DEMO SA","ABACUS Demo SA","","CH","2501","Biel/Bienne",27.01.2015 16:42:49.008
218,"ROSSIER CHLOE","Rossier","Chloé","CH","2000","Neuchâtel",27.01.2015 16:43:34.665
219,"KLAUSER CYNTHIA","Klauser","Cynthia","CH","9443","Widnau",27.01.2015 16:43:55.791
220,"MALDINI FRANCO","Maldini","Franco","CH","9212","Arnegg",27.01.2015 16:44:17.776

3a. GET Report Result next output page Request and Response (.../output/2)

GET /api/abareport/v1/jobs/58621b44-45c7-bd55-ce3c-543462505db6/output/2 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:40000
Connection: keep-alive

Response : Report results returned

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: text/plain
Content-Length: 1074

ADR_INR,ADR_KURZNA,ADR_NAME,ADR_VORNAME,ADR_LAND,ADR_PLZ,ADR_ORT,ADR_MUTDATUM
221,"MUELLER LARS","Müller","Lars","CH","9450","Altstätten SG",27.01.2015 16:44:44.448
222,"TANNER MARCO","Tanner","Marco","CH","9500","Wil SG",27.01.2015 16:45:07.245
223,"DICKEL NORBERT","Dickel","Norbert","CH","9240","Uzwil",27.01.2015 16:46:26.747
224,"GUENTENSPERGER P","Güntensperger","Philipp","CH","9500","Wil SG",27.01.2015 16:46:44.825
225,"LUECHINGER THOMA","Lüchinger","Thomas","CH","9200","Gossau SG",27.01.2015 16:47:06.419
226,"KUNZ NILS","Kunz","Nils","CH","9200","Gossau SG",27.01.2015 16:47:20.795
227,"MC ALLISTER STAC","Mc Allister","Stacey","CH","8001","Zürich",27.01.2015 17:11:10.291
228,"BROWN JORDAN","Brown","Jordan","CH","8001","Zürich",02.03.2015 08:48:17.466
229,"AMINA AG LIE","Amina AG","","CH","3000","Bern",30.03.2016 11:15:22.908
230,"AMINA AG FAK","Amina AG","","CH","3000","Bern",30.03.2016 11:16:21.972
231,"KUSTER PETER","Kuster","Peter","","","",30.03.2016 11:19:27.976
232,"SUTER HANS","Suter","Hans","","","",30.03.2016 11:19:50.476

3b. GET Report Result last query Request and Response (.../output/3)
If no more Report data is available for a requested page, then the response with return "404 Not Found"

GET /api/abareport/v1/jobs/58621b44-45c7-bd55-ce3c-543462505db6/output/3 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:40000
Connection: keep-alive

Response : No more report results available

HTTP/1.1 404 Not Found
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Length: 0

4. Resquest : Close Report Session

DELETE /api/abareport/v1/jobs/58621b44-45c7-bd55-ce3c-543462505db6 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1Qi ..... lSke0ScsAlc77Ye8d4E8aNXELHEdN5try_b5fwoZUL92oNYIVog
User-Agent: Java/1.8.0_251
Host: localhost:8888
Connection: keep-alive

Response : Report session closed

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:21:45 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Length: 0

Example Report Response with "outputType" : "xml_query"

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Mon, 03 May 2021 14:41:54 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: text/xml
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <row>
    <field name="ADR_INR">106</field>
    <field name="ADR_KURZNA">SWISS LIFE</field>
    <field name="ADR_NAME">Swiss Life AG</field>
    <field name="ADR_VORNAME"></field>
    <field name="ADR_LAND">CH</field>
    <field name="ADR_PLZ">8022</field>
    <field name="ADR_ORT">Zürich</field>
    <field name="ADR_MUTDATUM">05.03.2021 09:41:57.408</field>
  </row>
  <row>
    <field name="ADR_INR">109</field>
    <field name="ADR_KURZNA">MOBILIAR</field>
    <field name="ADR_NAME">Mobiliar</field>
    <field name="ADR_VORNAME"></field>
    <field name="ADR_LAND">CH</field>
    <field name="ADR_PLZ">9001</field>
    <field name="ADR_ORT">St. Gallen</field>
    <field name="ADR_MUTDATUM">05.03.2021 09:42:54.891</field>
  </row>
    ....
    ....
  <row>
    <field name="ADR_INR">220</field>
    <field name="ADR_KURZNA">MALDINI FRANCO</field>
    <field name="ADR_NAME">Maldini</field>
    <field name="ADR_VORNAME">Franco</field>
    <field name="ADR_LAND">CH</field>
    <field name="ADR_PLZ">9212</field>
    <field name="ADR_ORT">Arnegg</field>
    <field name="ADR_MUTDATUM">27.01.2015 16:44:17.776</field>
  </row>
</result>

Example Report Response with "outputType" : "json"

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; fullscreen *
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self)
Server: Jetty(9.4.40.v20210413)
Date: Tue, 04 May 2021 05:11:07 GMT
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json
Transfer-Encoding: chunked

{
  "data" : [
    {
     "ADR_INR": 106,
     "ADR_KURZNA": "SWISS LIFE",
     "ADR_NAME": "Swiss Life AG",
     "ADR_VORNAME": "",
     "ADR_LAND": "CH",
     "ADR_PLZ": "8022",
     "ADR_ORT": "Zürich",
     "ADR_MUTDATUM": "2021-03-05T09:41:57.408+01:00"
    },
    {
     "ADR_INR": 109,
     "ADR_KURZNA": "MOBILIAR",
     "ADR_NAME": "Mobiliar",
     "ADR_VORNAME": "",
     "ADR_LAND": "CH",
     "ADR_PLZ": "9001",
     "ADR_ORT": "St. Gallen",
     "ADR_MUTDATUM": "2021-03-05T09:42:54.891+01:00"
    },
    ....
    ....
    {
     "ADR_INR": 220,
     "ADR_KURZNA": "MALDINI FRANCO",
     "ADR_NAME": "Maldini",
     "ADR_VORNAME": "Franco",
     "ADR_LAND": "CH",
     "ADR_PLZ": "9212",
     "ADR_ORT": "Arnegg",
     "ADR_MUTDATUM": "2015-01-27T16:44:17.776+01:00"
    }
  ]
}

Error Messages

Some of the following error messages may occur if the Report Access is not permitted due to the Service-User configuration in Q981.

The following error message can be returned when the Report is started (POST /report/{mandant}/{reportname})

If the following error occurs, check the Service-User Application access rights in Q981 User management that the "AbaR" is selected

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 13 Dec 2024 10:14:31 GMT
Content-Type: application/json
Content-Length: 332
Connection: keep-alive
Cache-Control: no-store
Access-Control-Allow-Origin: *

{
  "id":"f2cbe459-5315-60d3-874a-92205dd3d736",
  "state":"FinishedError",
  "message":"Zugriffsrecht verweigert.\n- Kein gültiger ABEA-Beleg-Report. Sie benötigten eine AbaReport-Lizenz.\n",
  "submittedAt":"2024-12-13T11:14:31.581+01:00",
  "startedAt":"2024-12-13T11:14:31.583+01:00",
  "finishedAt":"2024-12-13T11:14:31.619+01:00",
  "result":[]
}

If the following error occurs, check the Service-User Access in Q981 User management is configured with the interface access option "AbaReport"

HTTP/1.1 403 Forbidden
Server: nginx
Date: Fri, 13 Dec 2024 09:58:56 GMT
Content-Type: application/problem+json;charset=iso-8859-1
Content-Length: 208
Connection: keep-alive
Cache-Control: no-store
Access-Control-Allow-Origin: *
AbacusServletExceptionMessage: User has no access to service : AbaEngine

{
  "status":403,
  "title":"User has no access to service",
  "type":"https://docs.api.abacus.ch/erp/authorization/user-service-access-forbidden",
  "instance":"User: Abacus API - Abacus_API_V2025",
  "detail":"AbaEngine"
}