API for the business intelligence module
Product line
Standard
|Expert
Operating mode
CLOUD ABO
|ON-PREMISES
Modules
Services & CRM
Budget & Phases
Purchases
Resource Planning
Business Intelligence
As of Vertec 6.4.0.14 there is an API (Application Programming Interface) for querying BI data from external applications. The call is made via <ServerURL>/api/bi
.
In the configuration file Vertec.ini there is the parameter BI API :
[CloudServer] BI API=True
Standard is True
. This means that the BI API will run even if the parameter is not specified.
The BI API can only be used if the business intelligence module is licensed.
The Bi user rights are applied.
Here you will find a detailed Bi api – sample application with postman/excel .
Authentication to the BI API is done via Api token
. This must be passed as a Bearer
token in a Authorization
header:
import requests url = 'http://localhost:8081/api/bi/measures' api_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.MGVhZmUzMzYtNmVhMi00MDdhLTgxNjQtZDYxZmI0NzU2MWZi._r16YlvWmZCMJ3qdDX3bK5_DJHwcczTYaWoKUYUNZuk' headers = {'Authorization': 'Bearer %s' % api_token} r = requests.get(url, headers=headers) measures = r.text
Note: In Vertec versions before 6.6, authentication was done via HTTP Basic Auth with username and password. You can find the corresponding handling in the article at the bottom .
Under /api/bi
the following GET endpoints are available:
The Bi data
is processed via endpoint /getdata
queried. It accepts the following parameters via query string:
measures | Mandatory. Comma-separated list of internal metric names (e.g. |
Dimension | Mandatory, case-insensitive. List of dimensions by which the result is grouped (e.g. As a pseudo-dimension, If different roles exist for the dimension, it can be accessed via a suffix [index 0-4].
Example when querying the measure FeesExt (external fee): dimension0 = Projekt dimension1 = Projektbearbeiter_1 dimension2 = Projektbearbeiter_2 dimension3 = ProjektPhase dimension4 = Taetigkeit dimension5 = Month If several measures with different “dimension structure” are requested and the requested dimensions cannot be supplied across all measures, a corresponding error message appears. In such a scenario, the measures with the same dimension structure must be bundled in one query and several of these queries must be performed in order to extract all the data. |
_variable and OCL expression | Optional. As of Vertec 6.5.0.11 you can specify alias parameters with an OCL expression as a value for each dimension parameter (dimension0=project, dimension1=project editor, etc.), e.g. This causes a new field to be added in the answer Any number of alias parameters can be specified per dimension. If the parameter used corresponds to a name that is already in use (as measure names, class names or their translations, or alias of another dimension), an error is reported. |
startDate | Optional. Start date in ISO 8601 format (2020-01-01) |
endDate | Optional. End date in ISO 8601 format (2020-12-31) |
selectExpression | Optional. OCL expression for Selection . |
useDescriptions | Optional, True or False. Default: False. Determines whether the column designations are delivered in plain text and translated or as internal technical designations that are language-independent. |
f | Optional. Specifies the format in which the result is output:
The parameter can be specified as an Accept Header instead of a query string. If both are present, the query string is used. |
The endpoint returns results in the following format:
Header (column names) | Name of the requested measure (internal name). If the parameter |
Data row |
|
api/bi/getdata?measures=fte&dimension0=Projektbearbeiter&useDescriptions=true&dimension1=month&startDate=2023-01-01&endDate=2023-03-31
Returns:
"Bearbeiter","Bearbeiter_Id","Monat","Vollzeitstellen" "Christoph Keller",676,"2023-01-01",0.8 "Christoph Keller",676,"2023-02-01",0.8 "Christoph Keller",676,"2023-03-01",0.8 "Judith Feller",682,"2023-01-01",1 "Judith Feller",682,"2023-02-01",1 ...
The GET endpoint /measures
returns all available measures.
The optional f
parameter can be specified (see above).
The return contains the following fields:
The return values are translated in the language that the user has set in the web app.
With Vertec version 6.6, Api tokens were introduced to increase the login security of Web API accesses. HTTP Basic Authentication with username and password is therefore no longer supported from Vertec version 6.7.
XML Session Timeout = 5
(the BI API and the Xml server
share the session timeout setting).If both API Token and Username/Password are specified in a request, only the API Token will be considered. If it is invalid, a login attempt with Username/Password will not be made automatically.