Configuring Settlement Definitions
Configuring Daily Allowances and Settlement Definitions
This guide describes the complete configuration of daily allowances in the dialog tm_editAllowanceCalcDef.act. Technically, the dialog edits a TmAllowanceCalcDefCtx: a context with time-limited calculation versions and separate assignments. The regional base amounts for per diem and overnight allowance are not maintained here, but in the regional per diem definitions.
Scope: This article covers daily allowances. Overnight allowance, regional base rates, trip types and validation scripts are dependent configurations and are linked at the appropriate places.
Configuration map
| Level | What is configured? | Effect at runtime |
|---|---|---|
| 1. Context | Name, client, definition type and optionally a default definition | Determines which type of calculation is available in principle. |
| 2. Calculation version | Validity period, algorithm, domestic region, wage types and thresholds | For the travel date, exactly the matching historical version is chosen. |
| 3. Factors | Hour/day ranges, factors or classifiers for domestic and international | Payable daily portions result from travel time and regions. |
| 4. Reductions | Meal deductions, long-term and multi-trip deductions | Reduce the daily allowance according to business rules. |
| 5. Assignment | Trip type as well as client, group, role or person with validity | Determines which person receives this context for which trip type. |
| 6. Acceptance | Trip with time, legs, regions, meals and repeat trips | Verifies amount, tax-free portion, comment and reduction reason. |
Prerequisites
- The regions and their VAT/legal assignments are maintained.
- The regional base amounts for daily allowance and, if applicable, overnight allowance exist for domestic and international.
- The required trip types, clients, groups, roles and persons have been created.
- The business rule has answered the following in advance: 24-hour or calendar day logic, domestic and international treatment, deductions, tax-free portion and historical validity start.
- For payroll exports, the wage type and tax-free wage type are agreed with the target system.
1. Create the context
| Field | Meaning and rule |
|---|---|
| Name | Unique, business-friendly name for the entire set of rules, for example for a travel expense policy. The name is used in administration and assignments. |
| Description | Administrative explanation; limited to 255 characters in the form. Document the legal basis, business ownership and validity concept here. |
| Client | Restricts the context organizationally. The business selection for travelers is made additionally via the assignments. |
| Default settlement definition | Fallback if no specific assignment applies. A default definition must have no assignments; the form validates this combination. |
| Definition type | Determines the data model and thus the visible inputs. Do not change it after productive use; for a model change, create a new context. |
| Show history | Shows expired calculation versions. It serves traceability and should be enabled before making changes to historical trips. |
2. Choose the definition type
| Type | Use | Algorithm and option fields |
|---|---|---|
| LEGACY | Existing older configurations in which payout and tax exemption are calculated together. | One Implementation field with the older implementations. Factors contain payout and tax-free side by side. Continue maintaining only for existing legacy rules. |
| Payout view (company) | Only the amount that the company pays out. | One calculator bean and one set of calculator options. Tax-free reductions can be configured. |
| Tax view (tax-free) | Only the tax-free portion. | One calculator bean and one set of calculator options. Certain company options, such as the reduction to the payout amount, are hidden. |
| Composite | Payout and tax exemption are maintained as two views in one calculation version. | One calculator bean each and a separate set of options for the company view and the tax exemption view. |
For modern views, the dialog offers the currently registered AllowanceCalculator beans. In the standard installation, TmAllowanceCalculator24HourImpl and TmAllowanceCalculatorCalDayImpl are particularly relevant. Do not enter a bean name as free text or assume an implementation that is not offered.
3. Historize calculation versions
A context contains one or more settlement definitions with Valid from and Valid to. At least one version is mandatory. The dialog prevents overlapping periods within this context. New statutory or company rules are created as a new version from a cutoff date; an old version is not overwritten.
| Field | Configuration |
|---|---|
| Description | Designates the specific historical version, for example "AT 2026 from 01/01". |
| Valid from / Valid to | Required fields. Periods must not overlap. The selection uses the travel date, so test cutoff dates with a trip before and after the change. |
| Domestic region | Required field. It defines which region counts as domestic and which trip segments are processed as international. |
| Wage type / Wage type tax-free | Export information for downstream payroll accounting. Use only values agreed in the target system. |
| Pre-calculation script | Expert function. The script runs before the calculation and can work with the trip and calculator or replace the calculator. Use only versioned, tested scripts; do not hide core business logic in it without test cases. |
4. Algorithm and calculator options
The selected calculator determines which options are offered in the form. Options are stored per modern view: once for payout view or tax-free view, and separately for both views in composite definitions.
How to read the examples: The euro amounts always result from the regional per diem definition. The examples therefore use factors: 1 means the full daily amount defined in the region, 2/3 two thirds. The factor limits given are deliberately only example values. Before going live, your own factor table must be verified with a test trip.
| Option | When visible | Business effect with concrete example |
|---|---|---|
| Settle remaining international hours as domestic | 24-hour and calendar day | Effect: The calculator first evaluates the entire business travel time with the domestic factors and then subtracts the international factors already determined. The time that is not compensated as international per diem within a 24-hour window thus receives a domestic valuation. Example: A 24-hour trip comprises 08:00 to 16:00 in Germany and otherwise Austria. For the whole trip, the domestic table would yield factor 1, for Germany factor 1/3. With the option active, factor 2/3 remains as the domestic portion, in addition to the German portion. Without the option, only the actual domestic intervals are valued individually according to their respective duration. With graduated factor limits, this can lead to a different result. Test case: Calculate the same trip with the option enabled and disabled and compare domestic and international factors in the comment. |
| No international amount? Re-evaluate hours with domestic factors | 24-hour and calendar day | Effect: This fallback rule applies only if the entire international calculation has not yielded a single international factor, for example because every international leg is below the configured minimum duration. The travel time is then valued according to the domestic factors. Example: A purely business meeting in Germany lasts 4 hours. The international configuration requires more than 5 hours and therefore yields factor 0. If the option is active and the domestic factor table contains factor 1/3 for 4 hours, factor 1/3 is paid at the domestic rate. If even a single international leg achieves an international factor, this fallback rule does not apply. Test case: Record one trip just below and one just above the international minimum duration; only the first may fall back to domestic. |
| Merge legs of the same region before the day/hour calculation | 24-hour and calendar day | Effect: Business segments of the same region are considered together for determining days and hours. This prevents two short stays in the same region from each reaching only the lower factor limit. Private stays remain excluded and interrupt the merging. Example: A trip contains two German business legs from 08:00 to 12:00 and from 14:00 to 19:00. With a factor limit from 8 hours, the merged 9 hours can reach the higher range. Without the option, 4 and 5 hours are valued as separate legs and can therefore only yield lower factors or no factor. Test case: Calculate two legs of the same region with the same total time once merged and once separately; then compare the region share and the applied factors. |
| Combine all domestic intervals into one block for the factor calculation | 24-hour | Effect: The periods actually spent domestically are added up into a single time block before the domestic factor table is applied. This option only takes effect if the two fallback options described above are disabled; for a calendar day definition it is only relevant if it delegates to the 24-hour calculation. Example: In a mixed trip, two Austrian business intervals of 3 hours each lie between international legs. With a domestic limit from 4 hours, both intervals individually remain below the limit. With this option, 6 hours are valued as one domestic block and can result in factor 1/3, for example. Test case: First disable both fallback options. Then calculate a trip with two short domestic intervals and check that an added domestic period, not two individual valuations, is the basis. |
| Align the 24h window to the first border crossing instead of the start of the trip | 24-hour | Effect: The 24-hour slices begin at the first international segment, not at the start of the whole journey. This shifts all following windows by the same amount of time and is particularly relevant when international stays last several days or lie shortly before the end of a window. Example: The trip starts in Vienna at 06:00; the first international leg begins at 11:00. Without the option, the first 24 hours run from 06:00 to 06:00 the next day. With the option, the first relevant international window runs from 11:00 to 11:00 the next day. An international leg at 08:00 on the following day thus falls into a different window depending on the setting and can receive a different factor. Test case: Use a two-day trip with a documented border crossing and an international leg shortly before 11:00 on the next day; compare the factor distribution per window. |
| Allow more than the maximum factor per 24h | 24-hour | Effect: By default, the calculator limits the sum of the factors within a 24-hour window to the configured daily maximum factor. If the option is active, factors from several international regions in the same window are not capped to this maximum. Example: Within a 24-hour window, a driver spends sufficient time in region A and region B. The factor table yields factor 2/3 per region. Without the option, the sum of 4/3 is capped at a maximum of factor 1; the portion added last is reduced accordingly. With the option, both portions are retained, i.e. a total factor of 4/3. Which region is reduced when the option is off depends on the order of the legs. Test case: Calculate a multi-region trip within 24 hours with the option enabled and disabled; total factor, region shares and commentary must match the labor law requirement. |
| Ignore domestic portions on arrival and departure days of an international trip | Calendar day | Effect: Arrival and departure days with an international leg are assigned entirely to the international leg in the company view. The domestic portion of that day is not paid additionally; the international leg is extended to the corresponding daily frame for the daily valuation. The setting does not apply to the tax-free view and not to purely domestic days or intermediate days without an international leg. Example: On the day of arrival, the traveler drives to the airport in Austria from 07:30 to 08:00 and is in Germany on business from 08:00 to 23:30. With the option, the Austrian 30-minute portion receives no separate company amount; the outbound journey is attributed to the German international portion for the daily valuation. Without the option, domestic and international portions can be included separately according to the usual daily rules. Test case: For the same international trip, compare arrival day, intermediate day and departure day and check the company view and the tax-free view separately. |
| Settle international legs with the 24h algorithm | Calendar day | Effect: The settlement definition remains a calendar day definition, but the international parts are internally handed over to the 24-hour calculator. For international, the rules on time windows, region merging and maximum factors of the 24-hour method thus apply; the domestic part remains calendar day logic. Example: An international trip begins on Tuesday at 18:00 and ends on Wednesday at 18:00. Without the option, Tuesday and Wednesday are valued according to the factor sets for arrival and departure day. With the option, the international part forms a 24-hour window from Tuesday 18:00 to Wednesday 18:00 and is valued according to the 24-hour factor table. Whether this results in a higher or lower amount is determined by the configured factors and minimum limits. Test case: Record an international trip of exactly 24 hours and one of 23 hours 59 minutes; check factor limits and the cut at midnight. |
| For legs, also settle domestic trips with the 24h algorithm | Calendar day | Effect: As soon as a trip has legs, the calendar day calculator also delegates the domestic calculation to the 24-hour calculator. Without legs, the normal calendar day logic remains. The option thus controls not only the display of the legs but can fundamentally change the factor determination across midnight. Example: A domestic trip with maintained legs starts on Wednesday at 18:00 and ends on Thursday at 10:00. Without the option, Wednesday and Thursday can be valued as two calendar days with arrival and departure factors. With the option, the 16-hour period from Wednesday 18:00 is valued as part of a 24-hour window. With a 12-hour limit, this can result in factor 1, for example, while the calendar day logic yields two lower daily factors. Test case: Save the same domestic trip once without legs and once with at least one leg; the switch to the 24-hour logic may only occur in the second case. |
Rule: Always test options with a counterexample. In particular, the combination of minimum hours, legs, fallback to domestic and the delimitation of 24-hour windows can change the payout amount significantly.
5. Factors, time limits and tax logic
| Field | Meaning | Important notes |
|---|---|---|
| Factor type | The legacy dialog offers Twelfths or Percent. | When switching, the older domestic/international tables and deductions are converted. Factor sets are not converted automatically. After productive use, do not change factor sets by switching the factor type. |
| up to incl. | Defines how the upper range limit is interpreted. | The setting must match the entire factor table. A factor set can override it separately if needed. |
| min. hrs for per diem on purely domestic trips | Minimum duration for a purely domestic trip. | Only values greater than zero take effect. The trip must exceed the value. |
| min. hrs for per diem international | Minimum duration per international leg. | Segments below this value generate no international per diem and, depending on the calculator option, can be re-evaluated as domestic. |
| min. hrs for per diem | Global minimum duration for every type of trip. | Applies to domestic, international and mixed trips; according to the implementation only for values below 24 hours. |
| Minimum factor for arrival/departure day | Lower limit for the company amount on arrival and departure day. | Calendar day logic; test together with the tax-free minimum factor from a business perspective. |
| Minimum factor tax-free for arrival/departure day | Lower limit for the tax-free portion on arrival and departure day. | Calendar day logic. |
| fully taxable after X days | Makes the domestic per diem fully taxable after X days. | Only calendar day and purely domestic trips; the counter applies per individual trip, not across several trips. |
| Reduce tax-free per diem amount to payout amount | Limits the tax-free amount per per diem item to the payout amount. | Only visible where a company view exists. |
| Leave tax-free amounts untouched | Prevents any reconciliation between tax-free and payable amount. | Takes precedence over the reduction option. Enable only if differing totals are permissible from a business and export perspective. |
| Calculates only positive per diems | Limits a result that is negative due to deductions to zero. | Relevant for high meal or long-term deductions. |
6. Calendar day special rules and long-term stays
| Field | Effect | Acceptance |
|---|---|---|
| Last international region per day decisive | For the calendar day, only the international region reached last before midnight determines the daily allowance. | Test two regions on the same day with swapped order. |
| Longest international region per day first | International regions are processed in descending order of length of stay. | Tests cover the longest leg and ties; in a tie, the configured order decides. |
| Special options for international trips in the company view | No special rule; use the domestic per diem if it is higher; or calculate a purely domestic trip against a mixed trip and choose the better amount. | Company view only. Compare a purely domestic trip and the same trip with an international leg. |
| Long-term deduction domestic / international from day | Start day for the automatic percentage reduction of a continuous stay. A value ≤ 0 disables the deduction. | Test with and without legs; if legs are missing, the implementation uses the destination as a fallback. |
| Long-term deduction domestic / international % | Percentage deducted from the configured day of stay onward. | Combine with daily deductions and check the comment in the cost view. |
| Domestic/international: consider first/last day | Controls whether arrival and departure days count for the long-term logic. | In a reference test, start day 15 with 50% and excluded arrival/departure days on a trip from 04/01 to 04/21 leads to a reduction of days 04/16 to 04/20. |
The long-term fields are hidden when a 24-hour calculator is selected. They are therefore to be treated as a calendar day rule.
7. Modern factor sets
Factor sets are available for the modern calculation types. A set describes a part of the trip and contains its own factor table.
| Field in the factor set | Use |
|---|---|
| Description | Business name of the set, for example "Domestic arrival day" or "International full days". |
| International | Assigns the set to the domestic or international logic. |
| tax-free | Display of the associated view; do not use as a free business switch in modern definitions. |
| Trip part | COMPLETE_TRAVEL, ARRIVAL_DAY, DEPARTURE_DAY or TRAVEL_WITHOUT_ARRIVAL_DEPARTURE_DAYS. This allows arrival/departure days and full intermediate days to be treated separately. |
| Script expression (JS) | Expert condition for the factor set. Use only if the standard trip parts are not sufficient; with documented inputs and regression tests. |
| up to incl. | Overrides the setting of the same name of the calculation version for this factor set. |
| Use classifier | Uses a classifier of the regional base amount instead of a pure factor, for example for statutorily defined partial-day rates. When enabled, the factor is kept as output and the classifier is selected. |
In the factor table, Range from, Range to and Factor are maintained. For classifiers, the classifier is selected instead. The "Generate default factors" generator creates a basic twelfths table and is only a technical starting value, not a legal requirement.
8. Legacy factor tables
In legacy definitions, Per diem factors domestic and Per diem factors international are maintained with factor and tax-free factor. Both tables validate:
- Range from must be less than Range to.
- Ranges must not overlap.
- All values must lie within 0 to 25.
- The entire range 0 to 25 must be covered without gaps; 25 stands for "whole day".
Changing the limit interpretation or the factor type changes the calculation retroactively for all trips that use this historical version. Therefore, first create a new validity version and test with a copy of the existing table.
9. Daily per diem deductions
With Daily deductions, a daily deduction step appears in trip entry, typically for meals. The specific deduction types are created separately for domestic and international.
| Field | Effect |
|---|---|
| Name | Deduction type, for example breakfast, lunch or dinner. The list is filtered by domestic and international. |
| Deduction / tax-free | Factor of the company or tax-free portion. The unit corresponds to the factor type of the definition. |
| Dependency group / Dependency group tax-free | Deductions of the same group only take effect together. The groups for payout and tax exemption can differ. |
| Index | Order of the deductions. With multiple rules, define a business order. |
| Daily deductions international prorated | Reduces international deductions proportionally to the actually payable region share. |
| Daily deductions domestic prorated | Reduces domestic deductions proportionally to the actual company share; tax-free deductions remain based on the maximum daily amount. Hidden for legacy and purely tax-free views. |
| No per diem if all daily deductions enabled | Sets the per diem to zero if all available daily deductions are recorded, even if their factor sum is not 12 or 100. |
Important from the calculator tests: A dependency group applies only if all group members lie in the same payable time window. In the 24-hour model they can come from different regions, but not from different 24-hour windows. A deduction without a group is processed on the day actually affected; a deduction on a non-payable leg below the minimum duration must not reduce another payable segment.
10. Multi-trip deductions
Multi-trip deductions reduce daily allowances when the same person repeatedly visits the same destination reference within a time window. Domestic and international are configured separately.
| Field | Effect |
|---|---|
| Name | Readable rule name; it also appears in calculation comments. |
| Criterion | Destination, destination (geo), same business partner or destination region. |
| Window value / Window unit | Length of the rolling comparison window in days, weeks or months. |
| Minimum days per week | Required and greater than zero for week or month windows. Not required for day windows. |
| Reset after / Unit | Optional restart of the chain after a gap. A value of 0 disables resetting. |
| Deduction % / Deduction % tax-free | Percentage reduction of the payout or of the tax-free portion. Values are internally limited to 0 to 100%. |
| Index | Order of multiple rules. |
The form checks mandatorily: window value greater than zero; for weeks or months, a minimum number of days per week. The tests cover all four criteria. They also confirm that a triggered rule is assigned to its cause in the cost view and commented with rule name and percentage.
11. Settlement validations
Under Settlement validations, already created validation scripts are assigned to a calculation version. They apply in addition to the technical form checks. For each rule, document at least one valid and one deliberately invalid trip/leg case.
12. Assignments
Assignments connect the context with a trip type and a target object. Client, group, role or person are available as target objects. Each assignment has its own validity period.
- A default definition has no assignments.
- For the same trip type, the same object type and the same target object, overlapping periods are not permitted; the form validates this.
- The assignment history is independent of the history of the calculation version. A new set can therefore continue to use an existing assignment if its period is correct.
- For person-related tests, always use the personnel number only as a business verification attribute; the person itself is selected in the dialog.
13. Visual acceptance matrix from the AllowanceCalculator tests
| Test scenario | Configuration being checked | Expected result |
|---|---|---|
| Purely domestic trip below/above minimum duration | min. hrs for purely domestic trips | Below the threshold no daily allowance; above it the matching factor row is used. |
| Several international regions in 24 hours | 24h window, merging and maximum factor option | Window and region logic determine whether only one full day or several region shares are payable. |
| Private portions of a trip | Trip with private stay within an international trip | Private time is removed from the calculation; an overlapping private and business segment is rejected as an erroneous travel data constellation. |
| Meals with dependency group | Daily deductions, same group | The deduction takes effect only if all required entries are present in the same calculation window. |
| Meals on several days | Daily deductions domestic, also for mixed trips | The deduction reduces only the affected payable day; a deduction on a fully international day does not reduce a domestic day. |
| Two international regions on the calendar day | "Last region decisive" or "Longest region first" | The selected rule determines the order or the sole decisive region. |
| Long-term stay | Start day, percentage, arrival/departure days | The reduction starts only from the configured day of stay and is assigned to its cause in the detail of the calculated costs. |
| Repeated trips | Multi-trip deduction by destination, geo, business partner or region | Within the window, the rule reduces the matching view; rule name and percentage appear in the calculation comment. |
| Combination of multi-trip and meal | Multi-trip deduction plus daily deduction on the same day | The calculation must run through completely and show both reduction causes traceably. |
14. Recommended procedure
- Create a new context with a clear business name and the appropriate definition type.
- Create the first calculation version with a start date; specify domestic region, base rates, wage types and algorithm.
- Create factor sets or legacy tables completely; do not change the limit interpretation later.
- Add deductions, long-term and multi-trip rules only in line with the written travel expense rule.
- Create trip type, client, group, role or person assignments with unambiguous validity periods.
- Run the test matrix of this article with representative amounts and trip data.
- Check calculation comments, tax-free portions, wage types and export.
Changes during live operation
- Do not overwrite a calculation version in productive use. Instead, copy it and use a new validity start.
- Do not change definition type, factor type, domestic region and algorithm without a complete regression.
- When option switches are changed, retest in particular mixed domestic/international trips, border crossings and minimum hours.
- Delete deductions only when they are no longer needed in any historical trip; the form blocks deletion of deductions that have already been used.
- After every change, check a complete travel expense report including calculation comment and export.
See also: Per diem definitions, Trip types, Settlement validations and Travel system parameters.
Keine Kommentare vorhanden.