Setup

Payroll Engine Setup

This page describes how to install the Payroll Engine on a local Windows computer.

The Container Setup page provides instructions on how to use the payroll engine with a Docker container. In scenarios where the backend server is hosted, automation can be installed locally via the Client Setup.

Prerequisites

In order to use the Payroll Engine, the following services must be available.

.NET Runtime

The Payrfoll Engine is based on the Microsoft.NET Framework 9.0. The following websites offer downloads for installation:

• Windows: Run console apps > Download x64
• Linux: Run server apps > Install .NET
• MacOS: Run server apps > Download x64 (Intel) or Download Arm64 (Apple Silicon)

Database Server

The Payroll Engine Backend uses Microsoft SQL Server version 2017 (v14) or higher as its data store.

Local SQL Server Setup

Installing the free Express version of Microsoft SQL Server involves the following steps:

1. Download from the Microsoft website
2. Run SQL Server Setup with the SQL Server collation setting SQL_Latin1_General_CP1_CS_AS.

Remote database server

Various vendors offer the option of renting a database. The following information is required to connect to a remote SQL server:

• SQL Server name
• Database name
• Login User ID
• Login password

Setup

Installing Payroll Engine 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 > PayrollEngine_v{n.n.n}.zip of the current release.

👉 Continue to 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:

> FileType.Reg.cmd

When registering the file type manually (Windows, Linux, MacOS), 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:

> Admin.cmd

The Admin application is used to set up and run the required Payroll Engine services.

The first step is to set up the Backend:

1. Add the database connection and install the database: Backend > Database > Add
   • Local database: integrated security or SQL Server login
   • Remote database: SQLServer login
   • Confirm database installation
2. Add a Backend API server connection: Backend > Webserver > Add > Edit dialog
3. Start the Backend API server: Backend > Webserver > Start > .NET console window
   • The first time you access a local https address, you will need to confirm the installation of the local developer certificate.
4. Test the Backend API
   • Manual using swagger: Backend > Webserver > API > API Swagger page
   • Automatic tests: Tests > Open > Test.All.pecmd
5. Setting up the start example (optional): Examples > Open > StartPayroll/Setup.pecmd

The web application is then set up:

6. Add the Web Application Server connection: Web Application > Webserver > Add > Edit dialog
7. Start the Web Application Server: Web Application > Webserver > Start > .NET console window
8. Login to the Web Application: : Web Application > Webserver > Login > Web Application login page

If the start example is available, the following data is used for registration

• Name: [email protected]
• Passwort: @ayroll3nginE

Other features of the Admin Applikation:

• 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.

Server Operation

The Admin application provides the following commands for the backend:

• Start the Backend API server: Backend > Webserver > Start > .NET console window
• Browse the Backend API: Backend > Webserver > API > API Swagger page

Control of the web application:

• Start the Web Application Server: Web Application > Webserver > Start > .NET console window
• Login to the Web Application: Web Application > Webserver > Login > Web Application login page

Data Storage

All configuration data is stored in the operating system's environment variables:

Variable	Description	Required	Read by	Set by
PayrollApiKey	The backend API access key	no	Backend	Backend
PayrollDatabaseConnection	The database connection string 1)	yes	Backend	Backend
PayrollApiConnection	The backend connection string 2)	yes	Backend	Web App, Console
PayrollWebAppConnection	The Web App connection string 3)	no	Web App	Admin App 4)

¹⁾ Example: Server=localhost; Database=PayrollEngine; Integrated Security=true; TrustServerCertificate=true; Timeout=30;.
²⁾ Example: BaseUrl=https://localhost; Port=44354; Timeout=02:46:40; ApiKey=MyApiKey;.
³⁾ Example: BaseUrl=https://localhost; Port=7179; ApiKey=MyApiKey;.
⁴⁾ Used to start the web application server within the admin application.

The PayrollApiKey parameter forces a key when accessing the Backend API. This value must be set to restrict access to the API server. Once the API key has been defined, it must be included in the client connection string.

Database updates

If the database is out of date, you can use the Admin Tool to update it:
Backend > Database > Update

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 example
• Resources with documents, blogs, tests and examples