Versions Compared

Old Version 1

changes.mady.by.user John Jellema

Saved on

compared with

New Version Current

changes.mady.by.user ubisebastian

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

...

Create new OAuth2 client application as instructed in Management UI Applications or alternatively use the Management API. Allow Accounting Users to access the newly created application and enable for example password.1 method or your preferred method for the application.

Tip

The following OAuth2 client metadata describes a simple OAuth2 client that can request an access token using OAuth2 Resource Owner Password Credentials Grant

Code Block
languagetext
{
  "client_id": "... redacted ...",
  "client_secret": "..redacted...",
  "allowed_methods": [
    "password"
  ]
}


...

Add a user to Accounting Users group e.g. with the Management UI. You can choose from the following options:

...

Any of these actions can also be performed using the Management API.

Using Accounting API

Locate API scope

In order to access the Accounting API you need its client ID for the scope parameter of the OAuth2 Token Request. This client ID is visible in System → Accounting → Applications → Accounting as depicted here

Image Modified

Get the access token

Get the access token e.g. with OAuth2 Password grant. You may use the --insecure flag in case self-signed certificates are used:

Code Block
languagetext
$ curl \
  --request POST 'https://<sso-base-url>/uas/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'scope=openid <accounting-client-id>' \
  --data-urlencode 'client_id=<oauth2-client-id>' \
  --data-urlencode 'client_secret=<oauth2-client-secret>' \
  --data-urlencode 'username=<accounting-api-user>' \
  --data-urlencode 'password=<accounting-api-password>'

Where:

ParameterDescription
accounting-client-id
The client_id of the Accounting OAuth2 application retrieved in Locate API scope section
oauth2-client-id
The client_id of your OAuth2 client application you created in Creating a new OAuth2 application section
oauth2-client-secret
The client_secret of your OAuth2 client application you created in Creating a new OAuth2 application section
accounting-api-user
The username of the user you created in Define API user section
accounting-api-user-password
The password of the user you created in Define API user section

Using Accounting API

The Accounting API is documented using Swagger. You can access Swagger UI in https://<accounting-base-url>/swagger-ui/ by providing Accounting user credentials. Swagger documentation defines the endpoints, payloads, and responses. Note that the Swagger UI Try it out feature is not supported.

...

Request URL parameters

Path parameters

Parameter nameDescription
period

The period of the time from which to return the events: MINUTE, HOUR, DAY, WEEK (7 days), MONTH - case insensitive.

NOTE that you should choose such a period that produces a reasonable amount of events in the response so that you don't overuse resources. In typical installations, a period longer than a DAY is not recommended. It is better to make consecutive calls with a shorter period. See also spring.mvc.async.request-timeout property in Accounting Service additional configuration.

datetime

Optional date/timestamp for the earliest events to include with ascending order or latest events to include with descending order. The required precision for the parameter depends on the given period. If not given, derived from the current time and given period.

  • MINUTE 2021-03-19T08:23
  • HOUR 2021-03-19T08
  • DAY 2021-03-19
  • WEEK 2021-03-19 - meaning 7 days starting from /ending by the given day
  • MONTH 2021-03

The times are handled in UTC time zone so if you specify e.g. day/2021-03-31 with ascending order, then the events from 2021-03-31T00:00Z for 24 hours shall be included.

Query parameters

Parameter nameDescription
sortSort direction, provide '-' for descending order by timestamp, otherwise ascending order by timestamp is used.

Headers

Header nameDescription

Authorization

Mandatory bearer token e.g. 'Authorization: Bearer eyJjdHkiOiJKV1Q...' (token truncated)
Accept

Optional case insensitive media type for the response. If not provided or allows all media types, application/json media type is returned.

If CSV output is desired, media type text/csv needs to be specified. Note that due error handling in case of CSV it is recommended to add also application/json media type to the header with lower precedence as an error response is always JSON. You can use either the order or q-value to specify the precedence.

Examples:

'Accept: text/csv, application/json' - CSV is returned
'Accept: application/json;q=0.9, text/csv' - CSV is returned
'Accept: */*' - JSON is returned


Curl example

You may use the --insecure flag in case self-signed certificates are used. Add Accept header with value 'Accept: text/csv, application/json' for CSV output.

...

Response Document

JSON output

An EventDetailsResponse object with NavigationLinks and list of EventDetails matching request parameters is returned (see Swagger API models for additional information)

...

When accepting JSON media type and an error happens an ErrorResponse object is returned (see Swagger API models)

...

With JSON, if the streaming has already started with status code 200 and an error happens during processing, an error element may be included to the EventDetailsResponse.

With CSV, an error after streaming has started causes just end of streaming.

...