Knowledge base YouServe API's

  The csv files which are retrieved with the API for BI systems can be configured easily with our API configuration application. The application is available in the YouServe Portal and via direct web address:  https://apiconfiguration.youserve.nl/ How to use the configurator is described in this article Overview   Create a new file (1) To create a new file in the API for BI systems, use the green button on the right bottom. 1a) The entity number will always be added to the file. Example: CompanyData becomes CompanyData_17.csv   Continue to add elements (columns in the csv-file):   The number of columns in the file is limited. Please check the maximum numbers of columns in the table below: Level/ Data entity Max number of columns/ elements 90014669 (90014669) 5 Assignment 5 Child(7262) 5 Client(15) 10 ClientCla(191) 5 Company (17) 20 CompanyCar 20 CompanyCla(193) 10 ConnectionLeavePayroll 5 ContactPerson(7580) 15 contract (49) 200 Education(7170) 10 Employee(21) 140 Establishment (7449) 30 Establishment_824 5 Evaluation 5 Experience(7157) 5 FormationPlace 5 Function(97) 5 FunctionInformation 5 Gatekeeper 10 GatekeeperAction 5 IncomeRelationship 25 IndividualLeaveRights(7701) 10 Knowledge 5 LeaveBalance 5 LeaveRequest 10 LeaveRequestDetails 5 MaternityLeave(7593) 10 MedicalLeaveManagement(7471) 20 OrganizationalUnit(6000) 15 OrgUnitWorkLocation 5 Person (821) 10 ProcessingUnit 5 ReductionLeaveRights 5 RoleAssignment 5 TemporaryWorker 5 TradeMagazine 5 Trainee 15   A newly created file will be available in the next creation of the csv files. This is done once a day between 00:00 and 5:00 in the morning.   Change/Copy a file (3) You can change the columns of the csv-files. If elements/columns are added, they will always be added to the end of the columns in the csv -file.   The copy (clone) function will allow you to make changes without immediate effect on your process after you have downloaded the files. For instance: you want to add some fields and want to test first. Take the next steps: Copy the current file with the name CompanyData_17, give a new name. For instance:  CompanyDataV2_17 Open the configuration of CompanyDataV2_17 and apply the changes. The next day, the API for BI systems delivers both files: CompanyData_17 and CompanyDataV2_17 Now you can use the new file to test the process. If you are ready to start using the new file, change the current filename and rename the new file to the old filename: CompanyData_17 rename to CompanyDataV1_17 CompanyDataV2_17 rename to CompanyData_17 Once you have your process complete, you can delete the CompanyDataV1_17  file.   Changing/ copying a file will take affect in the next creation of the csv-files. This is done once a day between 00:00 and 5:00 in the morning.            

API for BI systems is already stated an API within the process to retrieve the CSV files. It is an File transfer API. This article is gonna explain from a functional perspective regards the files themselves.   Content: Within HR Core Business application the consultant on request can configure your specific needs, so that the files transported contains all relevant data based on entity level.    Time slices With our API for BI business product we support timelines.  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 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   ParentID and ID collumns These files contain 2 major components, that is the ID and ParentID collumn.    See the attachment in the model of all keyellements page there you can find the key elements (Entities) with their respective ParentID. This knowledge is necessary for knowing the relations between the key elements (Entities).   Filenames The name of the files regardless of which language you select in the API retrieval it will use the name of which is configurated.        

Within API for BI systems there are CSV files. These files contain 2 major components, that is the ID and ParentID collumn.    In the attachment you can see the key elements (Entities) with their respective ParentID. This knowledge is necessary for knowing the relations between the key elements (Entities).   Attachment is stored as txt file, but it can be downloaded and converted to .json.

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