Custom Actions

Custom Actions

The Payroll Engine provides case actions to control and validate user input. The existing case actions can be extended with the regulation object Script.

1. implement case action in C#
2. insert action in regulation
3. test action
4. use action

In the following tutorial example, an action is created to validate the company ID. It is to be checked whether the checksum of the company ID complies with the ISO 7064 standard.

Case Action

The case action consists of metadata in the form of C# attributes and the implementation. For validation actions, errors are included with the AddIssue method. The case action consists of the implementation and the metadata in the form of C# attributes.

1  using PayrollEngine.Client.Scripting;
2  using PayrollEngine.Client.Scripting.Function;
4  namespace ActionPayroll.Scripts;
5
6  [ActionProvider("MyActions", typeof(CaseChangeFunction))]
7  public class MyActions : CaseChangeActionsBase
8  {
9    [ActionIssue("MissingUId", "Missing value (0)", 1)]
10   [ActionIssue("InvalidUId", "(0) with invalid UID (1)", 2)]
11   [CaseValidateAction("CheckUId", "Validate for the UID")]
12   public void CheckUId(CaseChangeActionContext context)
13   {
14     var sourceValue = GetActionValue<string>(context);
15     if (sourceValue?.ResolvedValue == null)
16     {
17       AddIssue(context, "MissingUId", context.CaseFieldName);
18       return;
19     }
20     try
21     {
22       // ISO 7064 digit check with modulus, radix, character-set and double-check-digit option
23       new CheckDigit(11, 1, "0123456789", false).Check(sourceValue.ResolvedValue);
24     }
25     catch (CheckDigitException exception)
26     {
27       AddIssue(context, "InvalidUId", context.CaseFieldName, exception.CheckValue);
28     }
29   }
30 }

The code in detail:

• 6: Action provider registration, used as namespace MyAcions.ActionName (meta data)
• 7-30: Actions container class
• 9: Missing id issue registration with the key MissingUId (meta data)
• 10: Invalid id issue registration with the key InvalidUId (meta data)
• 11: Action registration with the key CheckUId (meta data)
• 12-29: Action CheckUId implementation
• 14-18: Get the action value
• 17: Add missing value issue
• 23: ISO 7064 digit check using CheckDigit
• 27: Add digit check issue

You can also use the predefine digit checks Mod11Radix2, Mod37Radix2, Mod97Radix10, Mod661Radix26, Mod1271Radix36

Regulation Action

Next, the script with the validation function is included in the regulation:

1  "regulations": [
2    {
3      "name": "ActionRegulation",
4      "lookups": [
5        {
6          "name": "MyActions.Actions",
7          "values": [
8            {
9              "key": "InvalidUId",
10              "value": "(0) is invalid: (1)",
11              "valueLocalizations": {
12                "de": "(0) ist ungültig: (1)"
12              }
13            }
14          ]
15        }
16      ],
17      "cases": [
18        {
19          "name": "UId",
20          "caseType": "Employee",
21          "defaultReason": "Test UId",
22          "validateExpression": "true",
23          "fields": [
24            {
25              "name": "UId",
26              "valueType": "String",
27              "timeType": "Period",
28              "valueMandatory": true,
29              "defaultStart": "today",
30              "validateActions": [
31                "MyActions.CheckUId"
32              ]
33            }
34          ]
35        }
36      ],
37      "scripts": [
39        {
39          "name": "MyActions",
40          "functionTypes": [
41            "CaseChange"
42          ],
43          "valueFile": "Scripts\\MyActions.cs"
44        }
45      ]
46    }
47  ]

The structure of the regulation in detail:

• 4-16: Lookups for the localisation of the validation messages
• 6: The lookup name according to the convention ActionNamespace.Action
• 17-36: The case with the field UId
• 31: Use of the case action MyActions.CheckUId
• 37-45: Registration of the validation script
• 41: Using script for case change functions
• 43: Local script source file

Action Test

The validation action UId is checked with the following test:

1  {
2    "$schema": "../../Schemas/PayrollEngine.CaseTest.schema.json",
3    "testName": "Test.UId",
4    "tenantIdentifier": "ActionTenant",
5    "userIdentifier": "lucy.smith@foo.com",
6    "employeeIdentifier": "mario.nuñez@foo.com",
7    "payrollName": "ActionPayroll",
8    "validateTests": [
9      {
10       "testName": "UId.Valid.999999996.Test",
11       "input": {
12         "userIdentifier": "lucy.smith@foo.com",
13         "employeeIdentifier": "mario.nuñez@foo.com",
14         "divisionName": "ActionDivision",
15         "case": {
16           "caseName": "UId",
17           "values": [
18             {
19               "caseFieldName": "UId",
20               "value": "999999996"
21             }
22           ]
23         }
24       },
25       "output": {
26         "values": [
27           {
28             "caseFieldName": "UId",
29             "value": "999999996"
30           }
31         ]
32       }
33     },
34     {
35       "testName": "UId.Invalid.999999997.Test",
36       "input": {
37         "userIdentifier": "lucy.smith@foo.com",
38         "employeeIdentifier": "mario.nuñez@foo.com",
39         "divisionName": "ActionDivision",
40         "case": {
41           "caseName": "UId",
42           "values": [
43             {
44               "caseFieldName": "UId",
45               "value": "999999997"
46             }
47           ]
48         }
49       },
50       "output": {
51         "issues": [
52           {
53             "caseFieldName": "UId",
54             "issueType" : "CaseInvalid",
55             "number": 400
56           }
57         ]
58       }
59     }
60   ]
61 }

The data in detail:

• 9-33: Test with valid UId
• 20: The simulated case value 999999996
• 29: The expected case value 9999996
• 34-59: Test with invalid UId
• 45: The simulated case value 999999997
• 55: The expected HTTP error 400

Command to execute the test

PayrollConsole CaseTest Test.et.json

Action Usage

Finally, the validation also takes effect in the web application with a corresponding error message.

Next steps

• Resources with documents, blogs, tests and examples