API for BI systems

[#1]

Endpoints:

File API:

[GET] getFile

The endpoint GET getFile gives tenants data in a zip (with multiple CSVs inside) or a single CSV file to a reference date. Data in CSVs are defined in the HRCB application. Data are stored periodically (once a day at 05:00 AM see also disclaimer), by our scheduler since the first introduction of the referred tenant.

A name of the file is defined as "{date}_{tenantId}_{language}" in zip files (2022-05-13_123456_EN.zip) and as "{date}_{tenantId}_{language}_{groupName}" in CSV files (2022-05-13_123456_EN_Company_basic.csv).

Response content type is based on the type of file:

• zip: application/x-zip-compressed
• CSV: application/octet-stream 

If the file does not exist, it returns 404 (NotFound).

This endpoint has required and optional query parameters. If the required parameter is missing, it returns 400 (BadRequest).

Parameter	Description	Required/ Optional	Example
Language	Defines the language of the file. Supported languages:  EN NL	Required	EN
Group	Defines an exact type of the file and returns a CSV file. The content of a group is defined in HRCB application. When the group parameter is not set, then the endpoint returns a zip file that contains CSV files.	Optional	Company

Examples:

Each request needs to have an "Authorization" value in the headers.

https://api.youserve.nl/yds/file?language=en

https://api.youserve.nl/file?language=en&group=Company

Client Header:

The application needs to be authorized by the corresponding Tenant (HR Core Client) in order to consume the API. This is ensured by a header parameter 'x-raet-tenant-id' and the value is a tenant id that customer requests data for.

Escaping within CSV file

- escape double quote character " to "" (two times double quote)

- enclose the whole field value with double quote character " in these cases:

   -- escaping of double quote occurred

   -- field contains delimiter (character | in our case)

   -- field starts or ends with a whitespace character

   -- field contains newline (any of CR LF characters)

example:

field one|"escaped field due to character "" present"|field three|"field with | pipe character"|"  leading and trailing whitespaces  "|no whitespaces

Time slices or Actual data

With our API for BI business product we have two different content files. Depending on your choice you get one of those types

• Timelines 
  • If history data is necessary you select for the timelines option.
    • History data of max 4 years are made available
    • Start and end date is mentioned for the whole slice of the selected elements 
    • Whenever there is a change in the selected fields a new time slice is created with a start and end date
  • Actual data
    • This file contains only actual data that is active on moment of creation of the file.
    • Selected fields have their own start and end date.

When onboarding on this product and there is a need for more than 4 years of history please be advised to do an service request as this is a paid service of ours.

Disclaimer:

For the time being, due to it is a newly launched product. Endpoint can be accessed throughout the day and triggers the most actual state of configuration and data instead of one file made ready once a day on 5 AM, so that the configuration settings can be tested by our users