Skip to content

HR Service ​

The HR service is the Human Resources module of Microtec ERP. It lives in a separate Git repository (MicrotecHR) and is deployed as an independent microservice (HR.Apis) on the Private CAE.


Repository Overview ​

ItemValue
RepoMicrotecHR
SolutionMicrotec.Hr.Personnel.sln
ArchitectureClean Architecture — 4 projects
CAE placementPrivate CAE
Backend prefixmic-erp-be
NuGet strategyMicrotecDlls (see below)

Project Structure ​

MicrotecHR/
├── Microtec.Hr.Personnel.Api/           # REST controllers, startup
│   ├── Controllers/                     # 27 controllers
│   ├── Program.cs
│   ├── appsettings.json
│   └── Dockerfile
├── Microtec.Hr.Personnel.Application/   # CQRS handlers, DTOs, validators
│   ├── Employees/
│   ├── Departments/
│   ├── Contracts/
│   ├── PayrollRun/
│   └── ...
├── Microtec.Hr.Personnel.Domain/        # Domain entities, enums, value objects
├── Microtec.Hr.Personnel.Infrastructure/# EF Core, repositories, migrations
├── MicrotecDlls/                        # Shared DLLs (not NuGet feed)
├── General files/                       # Postman collections
└── Documentation/
    └── ExceptionCodes.MD

MicrotecDlls: Shared Libraries Strategy ​

Not from NuGet Feed

The HR service does not consume Microtec.Domain, Microtec.Persistence, or Microtec.Web.Core from the private NuGet feed. Instead, it references the compiled DLLs directly from the MicrotecDlls/ folder.

This means:

  • When shared packages are updated, the DLLs in MicrotecDlls/ must be manually updated.
  • The .csproj files use local entries pointing to MicrotecDlls/.
  • No PAT or NuGet feed configuration is required for the HR repo.

API Modules ​

The HR service exposes 27 controllers covering the full HR lifecycle:

Employee Management ​

ControllerRoute prefixKey Operations
EmployeesController/EmployeesCRUD, activation, reporting
DepartmentsController/DepartmentsCRUD, hierarchy
JobsController/JobsCRUD, job catalogue
WorkLocationsController/WorkLocationsCRUD, site management
BranchController/BranchBranch lookup
CompanyController/CompanyCompany settings

Leave Management ​

ControllerRoute prefixKey Operations
LeaveTypesController/LeaveTypesLeave type catalogue
LeaveSettingsController/LeaveSettingsLeave policy per employee type
LeaveRequestsController/LeaveRequestsSubmit, approve, reject leave requests
LeaveClearanceController/LeaveClearanceAnnual leave settlement

Contracts & Salary ​

ControllerRoute prefixKey Operations
ContractsController/ContractsCreate, activate, renew, upgrade contracts
SalaryTemplatesController/SalaryTemplatesSalary structure templates
SalariesItemsController/SalariesItemsIndividual salary line items
JobAllowancesController/JobAllowancesJob-linked allowances

Payroll ​

ControllerRoute prefixKey Operations
PayrollRunController/PayrollRunExecute and manage payroll runs
PayrollActionController/PayrollActionPost, reverse payroll actions
PayrollPaymentController/PayrollPaymentPayment recording and reconciliation

Loans ​

ControllerRoute prefixKey Operations
LoanTypesController/LoanTypesLoan product catalogue
LoanRequestsController/LoanRequestsEmployee loan requests
EmployeeLoansController/EmployeeLoansActive loan tracking, instalment schedule

Regulatory & Configuration ​

ControllerRoute prefixKey Operations
OfficialHolidaysController/OfficialHolidaysPublic holiday calendar
AirlinesController/AirlinesAirline catalogue (for travel allowances)
SocialInsuranceController/SocialInsuranceSocial insurance configuration
EmploymentCommencementsController/EmploymentCommencementsOnboarding / joining records
SequenceController/SequenceDocument sequence configuration
HrConfigController/HrConfigHR module settings
LookupController/LookupShared lookups and dropdowns

Application Layer Structure ​

The Application project follows feature-folder CQRS organisation:

Microtec.Hr.Personnel.Application/
├── Employees/
│   ├── Commands/
│   │   ├── AddEmployee/
│   │   │   ├── AddEmployeeCommand.cs
│   │   │   ├── AddEmployeeCommandHandler.cs
│   │   │   ├── AddEmployeeCommandValidator.cs
│   │   │   └── Dto/AddEmployeeDto.cs
│   │   └── EditEmployee/
│   └── Queries/
│       ├── GetByIdEmployee/
│       ├── GetAllEmployees/
│       └── GetDropdownEmployee/
├── Departments/
├── Contracts/
├── PayrollRun/
└── ...

Postman Collections ​

Postman collections for all HR endpoints are maintained in:

MicrotecHR/General files/

Import these into Postman to test HR endpoints directly. Collections cover all 27 controllers with example request bodies and environment variables for dev/stage.


Exception Codes ​

The HR service uses the shared exception code system with HR-specific codes in the 9000-9030 range. See the HR API Reference for the full table.

Key HR exception categories:

RangeCategory
9005–9008Entity relationship constraints (delete blocked)
9009–9018Contract business rules
9019–9021Salary template rules
9022–9023Employee-specific rules
9024–9027Record status and financial limits
9028–9030Workflow and lifecycle rules

Configuration ​

The HR service uses the same configuration pattern as other ERP microservices:

json
{
  "ConnectionStrings": {
    "DefaultConnection": "..."
  },
  "Keycloak": {
    "Authority": "https://<keycloak-host>/realms/microtec",
    "Audience": "account"
  },
  "Redis": {
    "Configuration": "<redis-host>:10000,ssl=true,password=..."
  }
}

Environment-specific overrides use appsettings.stage.json, appsettings.prod.json, etc.

Local Development

Copy appsettings.Development.json to appsettings.user.json for local overrides. This file is gitignored.


Deployment ​

The HR service is containerised via the Dockerfile in Microtec.Hr.Personnel.Api/. It is included in the Azure DevOps pipeline service config at:

Devops/azure/config/container-backend/services-config.json

under the key hr.

Internal Documentation — Microtec