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

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 :
  1. Start Report (POST /report/{mandant}/{reportname})
  2. Get the report status (GET /jobs/{id}), until either 'FinishedSuccess' or 'FinishedError' is returned
  3. Get the Report result (GET /jobs/{id}/output)
  4. 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
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 :

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"
    }
  ]
}