# Payroll Engine Client Setup

This document describes how to install the [Payroll Engine Console Client](https://github.com/Payroll-Engine/PayrollEngine.PayrollConsole) on your local computer.
The Console Client is required for automation, installation, and testing of regulations.

## Prerequisites
In order to use the Payroll Engine Client, the Microsoft.NET Framework 9.0 must be installed.
The Payrfoll Engine is based on the Microsoft.NET Framework 9.0. The following websites offer downloads for installation:
- [Windows](https://dotnet.microsoft.com/en-us/download/dotnet/9.0/runtime?initial-os=windows): `Run console apps` > `Download x64`
- [Linux](https://dotnet.microsoft.com/en-us/download/dotnet/9.0/runtime?initial-os=linux): `Run server apps` > `Install .NET`
- [MacOS](https://dotnet.microsoft.com/en-us/download/dotnet/9.0/runtime?initial-os=macos): `Run server apps` > `Download x64 (Intel)` or `Download Arm64 (Apple Silicon)`

## Setup
Installing Payroll Engine Client involves the following steps:
1. Download and extract the setup file
2. Register the data types
3. Set up applications

### 1. Download Setup
The Payroll Engine setup is available as a zip download in the `Assets` > `PayrollEngineClient_v{n.n.n}.zip` of the current release.
| 👉 **[Continue to Releases](https://github.com/Payroll-Engine/PayrollEngine/releases)** |
|:------------------------|

After unpacking the zip file into a local directory, the installation is ready.

### 2. Register File Types
To automate the Payroll Engine, the file type `.pecmd` must be registered for the Payroll Console.

To do this, run the following command file in Windows in *Administrator mode*:
```txt
> FileType.Reg.cmd
```

> When registering the file type manually ([Windows](https://www.lifewire.com/how-to-change-file-associations-in-windows-2624477), [Linux](https://help.ubuntu.com/stable/ubuntu-help/files-open.html.en), [MacOS](https://support.apple.com/en-sa/guide/mac-help/mh35597/mac)), the file extension `.pecmd` must be assigned to the application `{SetupPath}/Console/PayrollEngine.PayrollConsole.exe`.

### 3. Setup Applications
To start the setup, run the command:
```txt
> Admin.cmd
```
<p align="center">
  <img src="https://github.com/Payroll-Engine/PayrollEngine/blob/main/images/PayrollEngineClientAdmin.png" width="800" alt="Payroll Engine Client Admin" />
</p>

The first step is to set up the Backend:
1. Add a Backend API server connection: `Backend Remote` > `Webserver` > `Add` > Edit dialog
2. Test the Backend API
    - Manual using swagger: `Backend Remote` > `Webserver` > `API` > API Swagger page
    - Automatic tests: `Tests` > `Open` > `Test.All.pecmd`
3. Setting up the start example (optional): `Examples` > `Open` > `StartPayroll/Setup.pecmd`

If the start example is available, the following data is used for registration
- Name: `lucy.smith@foo.com`
- Passwort: `@ayroll3nginE`

Other features of the [Admin Applikation](https://github.com/Payroll-Engine/PayrollEngine.AdminApp):
- All configuration data is stored in the operating system's environment variables.
- The `Edit` button can be used to change the settings.
- The database connection can be checked.

### Data Storage
The connection to the backend server is stored in the environment variables of the operating system.

| Variable               | Description                    | Example                  |
|:--|:--|:--|
| `PayrollApiConnection` | The backend connection string  | `BaseUrl=https://localhost; Port=44354; Timeout=02:46:40; ApiKey=MyApiKey;` |

> If the Backend API server uses an API key, it must be listed in the connection string.

## Setup Archive Content
The installation file contains additional folders:
- `docs` - Payroll Engine documentation
- `Tests` - Backend payroll tests (run by the setup)
    - `Tests\Test.All.pecmd` - Runs all payroll tests on the Engine
    - `Tests\<Test>\Test.pecmd` - Runs a single test
- `Examples` - Payroll samples (setup installs one sample)
    - `Examples\Setup.All.pecmd` - Installs all billing samples
    - `Examples\<Example>\Setup.pecmd` - installs a single payroll example
- `Schemas` - JSON validation schemas

## Next steps
- [Basic Payroll](Basic-Payroll) example
- [Resources](Resources) with documents, blogs, tests and examples