Here is a description of the Payroll API.
End users or people who just want to use ERP5 Payroll should first have a look at HowToCreatePaySheet and HowToMyCountryPaySheet. This document is nothing else than a technical note to help developer creating calculation scripts or localize erp5_payroll Business Template.
Table of Contents
How to create a Calculation Script¶
When the end user click on 'Calculation of the Pay Sheet Transaction' action menu (from PaySheetTransaction_view), Pay Sheet Lines will be created with values from a calculation method that will be applied on each model line.
For each line, if there is a calculation script defined on the Pay Sheet Model Line, this script is used, otherwise we look for a calculation script on the Pay Sheet Model, then fallback on the default PaySheetTransaction_defaultCalculationScript from 'erp5_payroll' skin folder, if no script is defined on the model.
If you want to make a particular calculation for a certain tax, you can write a new script and put it in your project or localized skin folder. The script will be called by PaySheetTransaction class method with the following parameters:
- base_amount_dict : this is a dict which have base_amount category as key and the corresponding amount that has been calculated so far as value. On each model line (=contribution), the amount in this dict is increased with the amount corresponding to this contribution, that's why you have to specify calculation order on model lines carefully.
- cell : the concerned model line cell
The script must return a dictionary with the keys 'quantity' and 'price'. Quantity will be the Base for this new Pay Sheet movement, and Price will be the Tax Rate.
A very simple example could be the following :
##parameters=base_amount_dict, cell
result={}
result['quantity'] = 1000
result['price'] = 0.05
return result
If we assign this script on a model line, when it will be calculated, a Pay Sheet Transaction Line will be created with a cell with a quantity=1000 and a price=5% so, the total_price=50 (the amount paied for this contribution)
A more real example of such script can be this:
##parameters=base_amount_dict, cell
# get the value returned by the default script (this is not mandatory)
result = context.PaySheetTransaction_defaultCalculationScript(base_amount_dict, cell)
# get some constants
salaire_charniere = context.getRatioQuantityFromReference('salaire_charniere')
plafond_ss = context.getRatioQuantityFromReference('plafond_ss')
# do the particular calcul
if salaire_charniere and plafond_ss:
result['quantity']=salaire_charniere-plafond_ss
return result
After write your script, your can assign it to a model line by putting the script name in the Model Line Calculation Script StringField of the concerned model line : 
view larger image
How to get information from a Calculation Script¶
Inside the script, you may need to retrieve certain information. Here is a list and the way to get it:
From the script parameters¶
From methods called on Pay Sheet Transaction Object¶
- you can obtain the concerned cell category ('tax_category/employee_share', 'tax_category/employee_share', 'salary_range/france/tranche_a'... ) on the model cell, like this :
cell.getVariationCategoryList(base_category_list=base_category)
- ratio : a ratio is a constant defined by the 'Add Pay Sheet Model Ratio Line' action menu. You can get a ratio value using the methods 'getRatioQuantityFromReference(ratio_reference)' or 'getRatioQuantityList(ratio_reference_list)' on a PaySheetTransaction document.
'getRatioQuantityFromReference' return the value corresponding to the ratio_reference parameter whereas 'getRatioQuantityList' return the list of values corresponding to ratio_reference_list parameters (in the same order than ratio_reference_list).
- Social Insurance Annotation Line is the annotation line created if you filled the field 'Social Service Provider' of the model or pay sheet. In France, this Organisation is called 'URSSAF' and it's mandatory to display the URSSAF address on the printed pay sheet. You can get this organisation value by calling getSocialInsuranceAnnotationLineValue().getSourceValue() on a PaySheetTransaction document.
- Work Time Annotation Line is the annotation line created if you filled the field 'Work Duration Value' of the model/pay sheet. It contains the quantity of worked time, with a quantity unit. You can get it using the method getWorkTimeAnnotationLineQuantity() on a PaySheetTransaction document.
- Overtime Annotation Line is the annotation line created if you filled the field 'Overtime Duration Value' of the model/pay sheet. You can get it using the method getOvertimeAnnotationLineQuantity() on a PaySheetTransaction object.
- Default Payment Condition is the Payment Condition created if you filled the field 'Absolute Payment Date' of the model/pay sheet. You can get the default payment date using the method getPaymentConditionPaymentDate() and the default payment condition using getDefaultPaymentConditionValue() on a PaySheetTransaction object.
Some other usefull method¶
Currently, there are some script who return a year to date amount for the curent user:
- PaySheetTransaction_getYearToDateBaseSalary
- PaySheetTransaction_getYearToDateGrossSalary
- PaySheetTransaction_getYearToDateNetPay
- PaySheetTransaction_getYearToDateOvertimeAmount
- PaySheetTransaction_getYearToDateOvertimeHours
- PaySheetTransaction_getYearToDateTaxableNetPay
- PaySheetTransaction_getYearToDateWorkTimeSalary
How to write similar scripts¶
This is PaySheetTransaction_getYearToDateGrossSalary script:
## Script (Python) "PaySheetTransaction_getYearToDateGrossSalary"
##parameters=paysheet=None
portal_simulation = context.getPortalObject().portal_simulation
params = {
'section_uid' : paysheet.getDestinationSectionUid(),
'mirror_section_uid' : paysheet.getSourceSectionUid(),
'tax_category_uid' : context.portal_categories.tax_category.employee_share.getUid(),
'to_date' : paysheet.getStartDate(),
'from_date' : DateTime(paysheet.getStartDate().year(), 1, 1),
'simulation_state' : ['confirmed', 'stopped', 'delivered'],
'precision' : paysheet.getPriceCurrencyValue().getQuantityPrecision(),
'resource_category' : context.portal_categories.base_amount.gross_salary.getUid()
}
return portal_simulation.getInventoryAssetPrice(**params)
Here getInventoryAssetPrice() method is called with current paysheet parameters, but you can use the parameter you want to get the amount payed by a precise person to a precise organism at a precise periode, ...
Related Articles¶