Time-off tracking

this guide introduces how to set up time off tracking in your system with marco the two main procedures are data configuration to obtain the necessary data implementation of marco api the guide will walk you through the two procedures, with examples of how you can use marco api data configuration prepare the necessary data so that your system is ready to begin tracking time off records and leave balances with marco api the calculation of the staff's leave balances requires the following data leave item details, such as the annual entitlement employee information time off records to configure the required data, the following tasks should be completed define your company's leave policy add your employees to marco import existing time off records defining company leave policy begin by creating a country specific leave policy for every country you have employees in marco has a global data cloud containing leave type information country specific leave types statutory regulations, such as entitlement and increment rules, carry over, and minimum days you can make use of marco's data cloud to create your company's leave policy based on this policy document, marco will automatically generate the correct leave item data for each staff, including the leave types, effective date, entitlement amount, carry over amount, and more the leave type names used in your company's system should match with marco's multilingual global dictionary of leave types currently, only english and chinese are supported adding employees to start tracking time off records for an employee, the employee must first be added to marco use the create or update user information endpoints to set up the employees in marco there are four identifying parameters involved in adding employees to begin, customer id is your company's unique marco identifier, which is required to match and verify that the api caller is authorized to add employees to your company in addition, the following parameters must be unique for each employee customer system id —the staff's unique identifier in your system (external id) system email —the staff's email account to create an employee, customer system id and system email must not already exist in the system when updating an employee , customer system id and customer system id type will be used to identify the employee other than the four identifying parameters, you can specify as much data when adding an employee the minimum data required to add an employee to marco includes name country job title job start date staff type example minimum data required { "customer id" 11, "customer system id" "3094837", "customer system id type" "ps" "name" "jan howard", "system email" "jan howard\@mail com", "country" "cz", "job title" "engineer", "job start date" "2020 01 31", "staff type" "system", } importing time off records to ensure correct leave balances for the year, existing time off records should be imported into marco the data should be stored in a csv file and sent to marco's technical team for import implementation once the necessary requirements have been configured, you can use marco api to start tracking leave requests and balances for all staff when a staff applies for leave on your system, the following endpoints are involved staff checks their leave balance —use the get leave items endpoints to retrieve the leave balance staff applies for leave for a certain date range —use the calculate total leave days endpoint to check if the staff has sufficient days to apply for leave staff submits the leave request —use the add time off record endpoint to create the time off record in marco with the new time off record, the staff's leave balance will be updated during approval, the following endpoints are involved manager approves the leave request —use the edit time off record to approve or reject the leave request if the request is rejected, the staff's leave balance will update accordingly applying for time off to support systems globally, employees can apply for leave in their preferred language marco api currently supports english and chinese step 1 viewing leave balance use the get leave items endpoints to retrieve the leave balance and other leave item details for example, the endpoints all return the following numbers for display entitlement —the number of leave days granted in the year carried —the number of leave days carried over from previous years balance —the total number of available leave days entitlement can use —the number of available leave days, excluding carried over days carried can use —the number of available leave days that have been carried over taken —the number of used leave days step 2 checking leave request validity when the staff is applying for leave, you can implement additional checks, such as whether the staff has sufficient balance use the calculate total leave days endpoint to get the total number of leave days in the leave request based on the given country, the calculation will automatically account for its weekend days and public holidays the number of leave days can be checked against the staff's leave balance to determine if the staff can apply for time off step 3 submitting leave request use the add time off record endpoint to add the leave request to marco when submitting a leave request, the following fields should be left empty decision once submitted, the requested number of leave days will be automatically deducted from the staff's current leave balance approving leave requests use the edit time off record endpoint to approve or reject leave requests to approve, send "approve" in the decision parameter to reject, send "reject" in the decision parameter, and optionally include the reason for rejection in the reject notes parameter if a leave request has been rejected, the requested number of leave days will be automatically released back to the staff's current leave balance