Skip to content

Commit 378977e

Browse files
author
Jani Giannoudis
committed
Readme: added action documentation
collector function: fixed action property description metadata wage type function: enabled wage type calendar property for actions
1 parent 090c475 commit 378977e

File tree

3 files changed

+173
-3
lines changed

3 files changed

+173
-3
lines changed

‎Client.Scripting/Function/CollectorFunction.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,11 @@ protected CollectorFunction(string sourceFileName) :
9393
public decimal CollectorSummary { get; }
9494

9595
/// <summary>The minimum collected value</summary>
96-
[ActionProperty("Maximum collected value")]
96+
[ActionProperty("Minimum collected value")]
9797
public decimal CollectorMinimum { get; }
9898

9999
/// <summary>The maximum collected value</summary>
100-
[ActionProperty("Minimum collected value")]
100+
[ActionProperty("Maximum collected value")]
101101
public decimal CollectorMaximum { get; }
102102

103103
/// <summary>The average of the collected value</summary>

‎Client.Scripting/Function/WageTypeFunction.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ protected WageTypeFunction(string sourceFileName) :
6161
public string WageTypeDescription { get; }
6262

6363
/// <summary>The wage type calendar</summary>
64+
[ActionProperty("Wage type calendar")]
6465
public string WageTypeCalendar { get; }
6566

6667
/// <summary>Gets the wage type value</summary>

‎README.md‎

Lines changed: 170 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,179 @@
22
👉 This library is part of the [Payroll Engine](https://github.com/Payroll-Engine/PayrollEngine/wiki).
33

44
The scripting library that defines the commonality between the backend and the clients:
5-
- Scripting functions
5+
- Low-Code Scripting functions
66
- Scripting runtime
77
- Script parsers
88
- System scripts
9+
- No-Code Actions
10+
11+
## No-Code Actions
12+
<p align="center">
13+
<img src="https://github.com/Payroll-Engine/PayrollEngine/blob/main/images/ActionSyntax.png" width="640" alt="Action syntax" />.
14+
</p>
15+
16+
Actions can be used to determine the behaviour of payroll objects, even without any programming knowledge. The following events can be controlled:
17+
- `Case`
18+
- `Available` - the availability of a case
19+
- `Build` - Case creation
20+
- `Validate` - Case validation
21+
- `CaseRelation`
22+
- `Build` - Creation of the case relationship
23+
- `Validate` - Validation of the case relationship creation
24+
- `Collector`
25+
- `Start` - Initialization of the collector
26+
- `Apply` - Application of wage type result <sup>1)</sup>
27+
- `End` - Completion of the collector
28+
- `WageType`
29+
- `Value` - Wage type result <sup>1)</sup>
30+
- `Result` - Additional wage type result
31+
32+
<sup>1)</sup> Function event with return value<br/>
33+
34+
A list of actions is executed sequentially for each event. For events that expect a return value, the final action calculates the result. The following types of action exist:
35+
36+
| Type | Line start | Description |
37+
|:--|:--|:--|
38+
| Comment | `#` | Comment action, not executed |
39+
| Condition | `?` | Conditional action |
40+
| Instructions | Any other | Executiuon action |
41+
42+
The following example shows how the wage types 'WageTypeValue' are calculated when three entry conditions are met.
43+
44+
```yaml
45+
# Boolean entry status condition
46+
? ^^EntryStatus
47+
# Salary limits condition
48+
? ^^Salary >= 1000 && ^^Salary <= 10000
49+
# Salary tax rate limits condition
50+
? ^^SalaryTasRate >= 0.01 && ^^SalaryTasRate <= 0.03
51+
# Wage type result (last action)
52+
^^Salary * ^^SalaryTasRate
53+
```
54+
55+
> Changes in case value that occur during the pay period are taken into account in the calculation.
56+
57+
### Conditional Actions
58+
The following conditions can be set for actions and calculations:
59+
| Syntax | Description | Example |
60+
|:--|:--|:--|
61+
| `? <cond>` | Continue condition for the next action | `? ^^Salary < 1000` |
62+
| `? <cond> ?= <true>` | Continonal action result | `? ^^Salary < 1000 ?= 0.5` |
63+
| `? <cond> ?= <true> ?! <false>` | Continonal action result with fallback value | `? ^^Salary < 1000 ?= 0.5 ?! 0.25` |
64+
65+
The following conditions can be included in an action expression:
66+
| Syntax | Description | Example |
67+
|:--|:--|:--|
68+
| `x && y` | Logical AND of two boolean values | `? ^^Salary > 1000 && ^^Salary < 5000` |
69+
| `x \|\| y` | Logical OR of two boolean values | `? ^^Salary < 1000 \|\| ^^Salary > 5000` |
70+
| `x ?? y` | Null-coalescing: use `y` when `x` is undefined | `? ^^Salary ?? 5000` |
71+
| `x ??= y` | Null-coalescing assigment: assign `y` to `x` when `x` is undefined | `^\|CalcSalary ??= ^^Salary * ^^TaxSalary` |
72+
| `x ? y : z` | Ternary conditional operator: use `y` when `x` is true, else use `z` | `^\|SalaryFactor = ^^Salary > 10000 ? 0.05 : 0.03` |
73+
74+
75+
### Action References
76+
The following values can be referenced when performing actions:
77+
78+
| Syntax | Target | Example | Objects | Access |
79+
|:--|:--|:--|:--|:--|
80+
| `^#` | Lookup value | `^#TaxRate('A')` | All | Read |
81+
| `^^` | Case value | `? ^^Salary < 1000` | All | Read |
82+
| `^:` | Case field <sup>1) | `^:Salary.Start < PeriodStart` | `Case` | Read--write |
83+
| `^<` | Source case field <sup>1) | `^<Salary < 1000` | `CaseRelation` | Read--write |
84+
| `^>` | Target case field <sup>1) | `^>Salary = (5 * 100)` | `CaseRelation` | Read--write |
85+
| `^\|` | Runtime value <sup>2)</sup> | `^\|SalaryWithTax = ^^Salary * ^#TaxRate('A')`| `Collector`, `WageType` | Read--write |
86+
| `^@` | Payrun result <sup>3)</sup> | `^@SalaryFactor = ^^Salary > 1000 = 1 : 0` | `Collector`, `WageType` | Read--write |
87+
| `^$` | Wage type value <sup>4) | `^&MyCollector * 0.2` | `WageType` | Read |
88+
| `^&` | Collector value <sup>4) | `^&Deductions.Cycle` | `WageType` | Read |
89+
90+
<sup>1)</sup> Access to the start date `Start`, the end date `End`, and value `Value` (default) of the dropdown field.<br/>
91+
<sup>2)</sup> Transient value, not saved.<br/>
92+
<sup>3)</sup> Value is saved in the payroll results.<br/>
93+
<sup>4)</sup> Value for the current payroll `Period` (default) and payroll `Cycle` (e.g., year-to-date).<br/>
94+
95+
### Action Value
96+
The following value types can be used in actions:
97+
- `String`
98+
- `Date`
99+
- `Boolean`
100+
- `Int`
101+
- `Decimal`
102+
103+
The following operators exist for value types:
104+
| Syntax | Description | Data types | Example |
105+
|:--|:--|:--|:--|
106+
| `+` | Addition operator | `String`, `Int`, `Decimal` | `^^Salary + ^^Bonus` |
107+
| `-` | Subtraction operator | `Int`, `Decimal` | `^^Salary - ^&Deductions` |
108+
| `*` | Multiplication operator | `Int`, `Decimal` | `^^Salary * ^^TaxRate` |
109+
| `/` | Division operator | `Int`, `Decimal` | `^^Salary / ^^InsuranceFactor` |
110+
| `%` | Remainder operator | `Int`, `Decimal` | `^^Salary % 1000` |
111+
| `&` | Logical AND operator | `Boolean` | `^^Salary < 1000 & ^^InsuranceFactor < 0.1` |
112+
| `\|` | Logical OR operator | `Boolean` | `^^Salary > 10000 \| ^^InsuranceFactor > 0.1` |
113+
| `<` | Less than operator | `Date`, `Int`, `Decimal` | `^^Salary < 1000` |
114+
| `<=` | Less than or equal to operator | `Date`, `Int`, `Decimal` | `^^Salary <= 1000` |
115+
| `==` | Equal operator | All | `^^TaxLevel == 3` |
116+
| `!=` | Not equal operator | All | `^^TaxLevel != 1` |
117+
| `>=` | Greater than or equal to operator | `Date`, `Int`, `Decimal` | `^^Salary >= 3500` |
118+
| `>` | Greater than operator | `Date`, `Int`, `Decimal` | `^^Salary > 2800` |
119+
120+
121+
The following mathematical operations are available for numeric values:
122+
| Syntax | Description | Example |
123+
|:--|:--|:--|
124+
| `Round(decimals?, rounding?)` | Round decimal value | `^^Salary.Round(2)` |
125+
| `RoundUp(step?)` | Round decimal value up | `^^Salary.RoundUp()` |
126+
| `RoundDown(step?)` | Round decimal value down | `^^Salary.RoundDown()` |
127+
| `Truncate(step?)` | Truncate decimal value | `^^Salary.Truncate()` |
128+
| `Power(factor)` | Power factor to a decimal value | `^^TaxFactor.Power(2)` |
129+
| `Abs()` | Absolute decimal value | `^^Deduction.Abs()` |
130+
| `Sqrt()` | Square root of decimal value | `^^Deduction.Sqrt()` |
131+
132+
133+
### Runtime Properties
134+
The following function properties can be used in read mode in an action:
135+
| Property | Description | Data type | Function |
136+
|:--|:--|:--|:--|
137+
| `UserIdentifier` | User identifier | `String` | All |
138+
| `UserCulture` | User culture | `String` | All |
139+
| `SelfServiceUser` | Test for self service user | `Boolean` | All |
140+
| `EmployeeIdentifier` | Employee identifier | `String` | `PayrollFunction` |
141+
| `Namespace` | Regulation namespace | `String` | `PayrollFunction` |
142+
| `CycleStart` | Payroll cycle start date | `Date` | `PayrollFunction` |
143+
| `CycleEnd` | Payroll cycle end date | `Date` | `PayrollFunction` |
144+
| `CycleDays` | Payroll cycle day count | `Decimal` | `PayrollFunction` |
145+
| `EvaluationDate` | Payroll evaluation date | `Date` | `PayrollFunction` |
146+
| `PeriodStart` | Payroll period start date | `Date` | `PayrollFunction` |
147+
| `PeriodEnd` | Payroll period end date | `Date` | `PayrollFunction` |
148+
| `PayrunName` | Payrun name | `String` | `PayrunFunction` |
149+
| `IsRetroPayrun` | Test for retro payrun | `Boolean` | `PayrunFunction` |
150+
| `IsCycleRetroPayrun` | Test for cycle retro payrun | `Boolean` | `PayrunFunction` |
151+
| `Forecast` | Forecast name | `String` | `PayrunFunction` |
152+
| `IsForecast` | Test for forecast payrun | `Boolean` | `PayrunFunction` |
153+
| `PeriodName` | Payrun perido name | `String` | `PayrunFunction` |
154+
| `CollectorName` | Collector name | `String` | `CollectorFunction` |
155+
| `CollectMode` | Collect mode | `String` | `CollectorFunction` |
156+
| `Negated` | Test for negated collector | `Boolean` | `CollectorFunction` |
157+
| `CollectorThreshold` | Threshold value | `Decimal` | `CollectorFunction` |
158+
| `CollectorMinResult` | Minimum allowed collector result | `Decimal` | `CollectorFunction` |
159+
| `CollectorMaxResult` | Maximum allowed collector result | `Decimal` | `CollectorFunction` |
160+
| `CollectorResult` | Collector result value | `Decimal` | `CollectorFunction` |
161+
| `CollectorCount` | Collected values count | `Decimal` | `CollectorFunction` |
162+
| `CollectorSummary` | Summary of collected values | `Decimal` | `CollectorFunction` |
163+
| `CollectorMinimum` | Minimum collected value | `Decimal` | `CollectorFunction` |
164+
| `CollectorMaximum` | Maximum collected value | `Decimal` | `CollectorFunction` |
165+
| `CollectorAverage` | Average of collected values | `Decimal` | `CollectorFunction` |
166+
| `WageTypeNumber` | Wage type number | `Decimal` | `CollectorApplyFunction`|
167+
| `WageTypeName` | Wage type name | `String` | `CollectorApplyFunction`|
168+
| `WageTypeValue` | Wage type value | `Decimal` | `CollectorApplyFunction`|
169+
| `WageTypeNumber` | Wage type number | `Decimal` | `WageTypeFunction` |
170+
| `WageTypeName` | Wage type name | `String` | `WageTypeFunction` |
171+
| `WageTypeDescription` | Wage type value | `String` | `WageTypeFunction` |
172+
| `WageTypeCalendar` | Wage type calendard | `String` | `WageTypeFunction` |
173+
| `ExecutionCount` | Wage type value execution count | `Int` | `WageTypeValueFunction` |
174+
| `WageTypeValue` | Wage type value | `Decimal` | `WageTypeResultFunction`|
175+
176+
### Integrated Actions
177+
The Payroll Engine offers various predefined actions, see [Client.Scripting](https://github.com/Payroll-Engine/PayrollEngine/blob/66bf478587956b163cc14674e49e52bb25b01f02/docs/PayrollEngine.Client.Scripting.md). In addition to these, you can create your own predefined actions using low-code; see [Custom Actions](https://github.com/Payroll-Engine/PayrollEngine/wiki/Custom-Actions).
9178

10179
## HTML documentation
11180
The client scripting library contains static HTML documentation for scripting developers. This is created using [docx](https://github.com/dotnet/docfx) [MIT]. The following commands are available in the `docfx` folder:

0 commit comments

Comments
 (0)