[14.0] [IMP] payroll: Add new "payslips" object methods

[nimarosa]

Hello, this PR is intended to add new functionalities to the "payslips" object.

By default, "payslips" object have the "sum" method, which you need to pass a code and a date (and optionally a to_date) and the function will sum all rules with that code and return the summed value. This is useful if you need the ytd, mtd or just the sum of some rule to calculate a salary rules. Following this approach, the new functionalities introduced in this PR are:

• The "payslips" object methods requiere dates as a param, so it's useful to add "datetime" object to the tools dict. This will make things like this possible:

# Inside salary rule code
from_date = tools.datetime(2022, 01, 01) # from_date is a datetime object that can be easily passed as param

# PRO Tip: 
# You can also get payslip dates that are useful to use as params using: 
payslip_start_date = payslip.date_from # "datetime" object
payslip_stop_date = payslip.date_to  # "datetime" object

• Add "sum_category" method. This method allows the user to get the sum of rules that have the passed category between a time frame. Usage is as following example, inside salary rule code:

# Get the average gross between a time period, date_from and current date
date_from = tools.datetime(2022, 1, 1)
gross_category_sum = payslips.sum_category("GROSS", date_from, payslip.date_to) 
result = gross_category_sum / 12 

# There are a lot of usages of this, this example is used to get the average GROSS category sum salary between two dates. 
# The method also consider hierarchical structure of rules, so if you have rules that have the GROSS category as
# parent_rule_id, they will be also summed to get the correct value. 

• Add "max_category" and "max_rule" method. This methods return the max value of a category (or rule if using max_rule) between a time period:

# Get the max "GROSS" category amount from payslips between start of the year and current date.
date_from = tools.datetime(2022, 1, 1)
result = payslips.max_category("GROSS", date_from) # "result" will contain the max value of the category in the selected time frame payslips

# Get the max "BASIC" rule amount from payslips
result = payslips.max_rule("BASIC", date_from) # "result" will contain the max value of the rule in the selected time frame payslips

• Add "min_category" and "min_rule" method. As "max_category" and "min_rule" methods, this one returns the min value of the selected category/payslips depending of the function used. Example are the same as the last ones, but using the "min_***" methods.

• Add "average_category" and "average_rule" methods. This methods, will calculate the average value of a category (or a rule if you are using the rule method) between a given time period. An example of it could be:

# Get the average "GROSS" category amount from payslips between start of the year and current date.
date_from = tools.datetime(2022, 1, 1)
result = payslips.average_category("GROSS", date_from) # "result" will contain the average value of the category in the selected time frame payslips

# Get the average "BASIC" rule amount from payslips
result = payslips.average_rule("BASIC", date_from) # "result" will contain the average value of the rule in the selected time frame payslips

• Add "average_xxx_monthly", "max_xxx_monthly" and "min_xxx_monthly" methods. This methods have the same params and syntax that previous ones, with the difference that they return average/max/min on monthly basis. Meaning that function first sums monthly payslips and then applies functions to get max/min/average. This functions are useful for cases when the employee has more than one payslip per month, and you need to get monthly variables.

---

This changes also are motivated by the need to reduce the "env" object usage. If some user need to get maximum or sum values, he will use the "env" object to execute a query. As discussed in #94 the usage of "env" is not the best for security, so writing more methods that execute common queries will reduce the use of that object. If we continue doing useful functions for the Browsable Objects, we can think in removing env access in the future.

Regards.

[OCA-git-bot]

Hi @appstogrow,
some modules you are maintaining are being modified, check this out!

[norlinhenrik]

Maybe it would be good to rename sum() to sum_rule(), and create a sum() method that will call sum_rule().

I need to print year-to-date totals on the payslip lines. So I have added a new field l10n_no_total_ytd. (Later I will rewrite the code and use the sum() method.) Do you also need a year-to-date field?

[nimarosa]

Maybe it would be good to rename sum() to sum_rule(), and create a sum() method that will call sum_rule().

Yes I thought about that, but wanted to mantain compatibily for rules using sum() but I can change the name and call sum_rule from sum() and display a deprecation warning in log. So we remove it in future versions and keep sum_rule.

I need to print year-to-date totals on the payslip lines. So I have added a new field l10n_no_total_ytd. (Later I will rewrite the code and use the sum() method.) Do you also need a year-to-date field?

Yes I also need ytd of some categories, averages and max values. In my country we have rules that are based in previous payslips so it's a common variable to use. This functions make easy to operate with previous payslips inside rules.

If you need to print ytd in payslips, you can calculate it in a salary rule and then just filter the payslip lines to find the rule you need. That way you will not need a field.

[nimarosa]

@norlinhenrik @mtelahun This is ready for review if you want to do it.

I added more methods (they are all explained in the main comment) and also a minor tweak in views to allow inherit "controls" group and add fields on the right of the boolean fields.

[nimarosa]

Merging since no reviews.
The new methods don't affect main functionality and are available to use if needed.

/ocabot merge minor

[OCA-git-bot]

On my way to merge this fine PR!
Prepared branch 14.0-ocabot-merge-pr-109-by-nimarosa-bump-minor, awaiting test results.

[OCA-git-bot]

Congratulations, your PR was merged at 5cea404. Thanks a lot for contributing to OCA. ❤️