PayrollEngine.Client.Scripting 0.9.0-beta.17

Payroll Engine Client Scripting

👉 This library is part of the Payroll Engine.

The scripting library that defines the commonality between the backend and the clients:

• Low-Code Scripting functions
• Scripting runtime
• Script parsers
• No-Code Actions

No-Code Actions

<p align="center"> <img src="https://github.com/Payroll-Engine/PayrollEngine/blob/main/images/ActionSyntax.png" width="640" alt="Action syntax" />. </p>

Actions can be used to determine the behaviour of payroll objects, even without any programming knowledge. The following events can be controlled:

• Case
  • Available - Availability of a case
  • Build - Case creation
  • Validate - Case validation
• CaseRelation
  • Build - Creation of the case relation
  • Validate - Validation of the case relation creation
• Collector
  • Start - Initialization of the collector
  • Apply - Application of wage type result ¹⁾
  • End - Completion of the collector
• WageType
  • Value - Wage type result ¹⁾
  • Result - Additional wage type result

¹⁾ Function event with return value<br/>

A list of actions is executed sequentially for each event. For events that expect a return value, the final action calculates the result.

Action Namespace

The relevant action uses the name of the object in order to access it. This could be the name of a case field or wage type, for example. To distinguish between objects in different regulations, it is recommended that you define the regulation namespace.

For regulations with a namespace, this is added automatically to the name. If an object from another regulation is referenced, the relevant namespace must be provided. In the following example, the regulation has the US namespace.

# access to case field US.Salary
^^Salary
# access to case field CA.Salary
^^CA.Salary

Action Type

The following types of action exist:

The following example illustrates how a wage type value is calculated under specific conditions.

# Boolean entry status condition
? ^^EntryStatus
# Salary limits condition
? ^^Salary >= 1000 AND ^^Salary <= 10000
# Salary tax rate limits condition
? ^^SalaryTaxRate >= 0.01 AND ^^SalaryTaxRate <= 0.03
# Wage type result (last action)
^^Salary * ^^SalaryTaxRate

The result of the last action, ^^Salary * ^^SalaryTaxRate will be treated as wage type value.

Action Conditions

The following conditions can be used to control the action execution:

The following conditions can be included in an action expression:

Action Reference

The following payroll objects can be accessed when performing controls and calculations on actions:

• Lookup value - simple or JSON property.
• Case value - employee, company, national or global.
• Case field - value with start and end dates.
• Runtime value - a transient value per employee.
• Payrun result - stored as payroll result.
• Wage type value - value for the current and retro periods.
• Collector value - Value for the current and retro periods.

The reference to the payroll object starts with the circumflex character ^, followed by the object marker.

Lookup Action Reference

Lookup values are referenced using the ^# syntax. The value access is possible through the lookup value key, and/or by rangeValue. In cases the lookup value is a JSON object, use the field parameter to access the JSON object property.

^#LookupName(key)
^#LookupName(key, field)
^#LookupName(rangeValue)
^#LookupName(rangeValue, field)
^#LookupName(key, rangeValue)
^#LookupName(key, rangeValue, field)

The following example shows how income is calculated using the tax rate obtained from the TaxRate lookup table. The income-dependent tax rate is determined by the ^^Salary case value.

^^Salary * ^#TaxRate(^^Salary)

Case Value Action Reference

The syntax ^^ can be used to access employee or company case data.

^^Salary * ^^Factor

If several case values are being calculated against each other as part of an action, any changes to the values occurring within the payroll period will be taken into account (time values). Time values are only supported in numeric case fields with time type Period or CalendarPeriod.

Please note that time values are not supported when calculating a case field value against the values of other payroll objects!

Case Field Action Reference

During a case change, you can access the case field using the ^: syntax. The symbol ^< is used to access the source case and the symbol ^> is used to access the target case in case relations.

There is access to the following case field data:

• Value - case field value aof any type (default)
• Start - case field start date
• End - case field end date
• Duration - duration between case field start end end date

Case field example actions:

# access to cae field value
^:Salary < ^|MinSalary
# access to case field start
^:Salary.Start < PeriodStart
# access to case field duration
? ^:Salary.Duration.Days < 30

Collector and Wage Type Action Reference

The syntax used to reference collectors is ^&, while the syntax used to reference wage types is ^$. The scope of the value can be specified using the time selector:

• Period: collector or wage type value of the current payrun (default).
• Cycle: collector or wage type value of the previous calendar cycle payruns.

The following example shows how to calculate the year-to-date value of the Deductions wage type, which has a higher processing order:

# consolidated deduction from previous payruns + deduction from current payrun
^$Deductions.Cycle + ^$Deductions

Action Value

An Action supports the following value types:

The following operators exist for action values:

¹⁾ Adding or subtracting a TimeSpan from a Date results in a Date value.<br /> ²⁾ Undefined value: 0.<br/> ³⁾ Undefined value: 1.<br/>

Action value operator examples:

# multiple decimal values
^^Salary * ^^TaxFactor
# add time range to date
^|StartDate = :Salary.Start < PeriodStart

Properties to test action values:

Properties to convert action values:

Mathematical operations for numeric action values:

Properties and methods for date action values:

¹⁾ Substraction with negative values.<br />

Runtime Properties

The following function properties can be used in read mode in an action:

In accordance with the function inheritance hierarchy, all derived functions have access to the properties. For example, all functions except the reporting functions can access the PayrollFunction properties.

Integrated Actions

The Payroll Engine offers a variety of predefined actions. Here are a few examples:

• IIf(expression, onTrue, onFalse) - Returns one of two parts, depending on the evaluation of an expression.
• Concat(str1, ..., strN) - Concat multiple strings.
• Contains(test, sel, ..., selN) - Test if value is from a specific value domain.
• Min(left, rigtht) - Get the minimum value.
• Max(left, rigtht) - Get the maximum value.
• Within(value, min, max) - Test value is within a value range.
• Range(value, min, max) - Ensure value is within a value range.
• ApplyRangeLookupValue(key, rangeValue, field?) - Apply a range value to the lookup ranges considering the lookup range mode.
• GetTimeSpan(start, end) - Get the time range between two days.
• SameYear(left, rigtht) - Test for same date year.
• SameMonth(left, rigtht) - Test for same date year/month.
• SameDay(left, rigtht) - Test for same date year/month/day.
• YearDiff(start, end) - Get year count between two dates.
• Age(birthDate, testDate?) - Get persons age.
• Log(message, level?) - Log a message.

The full list of predefined actions is listed on Client.Scripting page.

In addition to these, you can create your own predefined actions using low-code; see Custom Actions.

HTML documentation

The client scripting library contains static HTML documentation for scripting developers. This is created using docx [MIT]. The following commands are available in the docfx folder:

• Static.Build - builds the static HTML content (output is the _site subdirectory)
• Static.Static - opens the static help (_site\index.html)
• Server.Start - start the static help on http://localhost:5865/ (dark mode support)

Third party components

• Documentation generation with docfx - license MIT
• Tests with xunit - license Apache 2.0

Build

Supported runtime environment variables:

• PayrollEnginePackageDir - the NuGet package destination directory (optional)