Help › Human Resources

Human Resources — A Guide from Scratch

This module puts the person at the centre. Previously one employee lived in four separate places: a name on a customer card, another record in production, a free-typed name in the leave book, a login account. The same human being, four separate identities. Now there is one personnel record, and attendance, pay, leave, health, custody and authorisation all hang from it.

1. What is this module for?

The Personnel window has fourteen tabs. Nobody uses them all; reading the one that matches your job is enough. Even so, everyone should read Sections 2 and 3 — knowing where a record is opened removes the "who is this?" question at month end.

2. The personnel record — where everything starts

For a new employee you first open the personnel card, then an employment period. These are separate, and the separation matters: a person is defined once, but may join, leave and join again. In seasonal work the same person is hired a third time; had we kept a single start–end pair, seniority and leave entitlement would be wrong from the outset.

2.1 Two mandatory fields

Employee number and employment type cannot be left blank. Without an employee number you end up with two of the same name at month end. Without an employment type (payroll / subcontractor / freelance / trainee / outsourced service) turnover, cost per head and the attendance summary break silently: if a subcontracted haulier is counted as staff, three reports go wrong at once.

2.2 Who can see sensitive fields?

Pay, identity number, bank account, health information and address are filtered by role. There is an important design decision here: if you lack permission the field is not shown empty, it does not arrive at all. Masking with asterisks is misleading — "something exists but I cannot see it" is itself information. A foreman enters attendance but does not see pay or identity; it is not needed to enter attendance.

3. Legislation — the numbers are not baked into the code

The overtime multiplier, the weekly maximum, the number of leave days, the deduction ceiling, the notice period — these are all numbers that change by country, and none of them is written inside the program. They live in the Legislation tab and can be edited. Opening in a new country requires no code: copy the existing set and change the figures.

Rows whose source shows "Awaiting confirmation" are figures the program assumed but has not verified. Confirm them with your accountant or advisor before using them for payroll, and update the record. The warning sits in a yellow strip; it does not disappear on its own.

4. Working time — shifts, attendance, overtime

A shift is a template: start, end, breaks, and whether the break is paid. A night shift spills into the next day; the program resolves this itself — do not open a second record because "it passed midnight". Attendance is kept day by day and every day has a status: worked, on leave, sick-noted, work accident, absent, public holiday.

4.1 If you have no time-clock device

A device is not required. A punch can arrive four ways: a shared terminal (a tablet in the workshop, card number + PIN — no extra hardware), a phone (the personnel portal), a CSV import (if you already own a device), and manual entry. Whichever way it arrives, the raw punch is written into the same ledger.

A raw punch is never altered. If a punch is wrong it is not deleted; the correction is written as a separate row and who corrected it and why stays in the record. In an audit this is the only sound answer to "was attendance edited after the fact?".

5. Qualification — not everyone can step up to any machine

Which machine an operator may run, which operation they may perform and which decision they may take is recorded. Where a qualification requirement is defined the program blocks: an unqualified person cannot confirm that work. Where no requirement is defined nothing is blocked — installing the pack does not stop a running production line.

The qualification matrix also shows single-point risk: if only one person can do a job, work stops when that person goes on leave. The dashboard shows this count in red; it is an early warning to train a second person.

6. Occupational health and safety

A medical examination may impose a restriction: "may not work in noise", "may not lift loads". From the moment it is recorded the restriction blocks assignment. It is not a warning; assignment to that environment or duty is not possible. A restriction is specific to the hazard: someone restricted from noise may still be assigned to dusty work.

The same logic works in three more places: anyone under 18 cannot be assigned to night shift or to a hazardous environment; anyone without the mandatory certificate (driving licence, operator certificate) cannot be assigned to that equipment; and when PPE life expires the item lands on the renewal list.

7. Earnings — piece rate, commission, trips, vehicles

7.1 Piece rate

The tariff is kept per operation × product and is date-bound; after a rise, older records keep their old rate. Two rules are fixed: scrap is not paid (pay for parts that failed quality and the piece-rate system collapses) and no entitlement arises without quality approval.

Piece-rate earnings cannot fall below the minimum wage. The difference is topped up by the company and appears in a separate column of the summary — so that "piece rate" and "minimum top-up" are not confused on the payslip. The minimum wage is entered in the Legislation tab; if it has not been entered the top-up is not calculated. Producing nothing is right; producing an invented figure is not.

7.2 Commission — three stages

Commission is not paid in one step; it passes through three states:

1. Accrued — the sale was invoiced and the commission computed, but it is not yet earned.

2. Earned — the money was collected. This is the default rule: no commission is paid on an uncollected sale.

3. Clawback — goods were returned or payment failed. If the commission was not paid it is cancelled; if it was paid it is not deleted — it is marked as recoverable and appears as a deduction on the next payslip. The trail of a paid amount must not vanish.

A clawback cannot be made without a reason. If the reason field is empty the operation is rejected; six months later the answer to "what was this deduction?" must still be in the record.

7.3 Team commission

In some work the commission belongs to the team rather than the individual, and is then split by share. The shares need not add to 100 — a foreman may be given an extra share; the program prorates against the total. The rounding remainder is added to the largest share, so that the distributed total equals the amount given, exactly.

7.4 Trips, vehicles and fines

A trip is opened and closed on return; the number of days and the per-diem are computed automatically. A trip shorter than the threshold counts as half a day. Expenses (accommodation, meals) are attached to the trip and the payable is summed as per-diem + expenses + trip fee.

Vehicle custody answers "who is driving which vehicle". A vehicle can be with only one person at a time; it cannot be handed to another without being returned first. Fuel and odometer entries can be made by the driver from their own phone, but only for the vehicle assigned to them.

8. The personnel portal and the phone app

A worker on the floor has no program account, and does not need one. The portal uses a separate identity: employee number + PIN. HR opens the account (Portal accounts tab); if no user name is given the employee number is used — that is the one thing remembered on the floor.

What the portal can do: a shift punch (one button), a production report, a stock count entry, a leave request, vehicle odometer/fuel, and the person's own summary (leave balance, items in custody, expiring certificates). The address in a browser is /personel.

8.1 First, signing in to the portal: employee number + PIN

The portal opens by adding /personel to the program's address in a browser — for example http://192.168.100.24:5173/personel. Two boxes appear: Employee no / username and PIN. This is not an HNR user: a person on the floor has no program account, HR issues them a separate portal identity. If no username was given, the employee number is used — that is the one thing remembered on the floor.

8.1A If the portal account changed: 409 and refresh

A portal account can be opened by two HR users at the same time. The later save no longer silently overwrites the earlier one. If another person changes that account's PIN, active flag, or role after you opened the list, you receive a 409 / record changed warning when saving.

• This warning is protection, not failure. Refresh the list first; the new version, active flag, and role appear on screen.
• Then enter only the change you truly want to make. Resetting a PIN no longer changes the active flag or role by accident.

8.2 What is on the Shift tab?

The tab has three cards, in a deliberate order: first what to do now, then what you did today, and last what you will do this week.

8.3 Reading the plan table

Above the table the week's range is written (e.g. 17.08.2026 → 23.08.2026). There are three columns:

8.4 The plan and the punch history are not the same thing

Because the two tables sit next to each other they get confused. The difference is both legal and practical: a plan is an intention, a punch is evidence. Your attendance, your overtime and your pay are computed from the punch, not from the plan.

8.5 Step by step: "Which shift am I on tomorrow?"

1. Open the portal in the phone's browser (tap the icon if you added a home-screen shortcut). If your session is still open you go straight in; otherwise employee number + PIN.
2. Tap the Shift tab. The plan table is fetched again every time you enter the tab — so what you see is always the latest plan; you do not need to reload the page.
3. Scroll down to the My weekly shift plan card. The highlighted row is today; the row below it is tomorrow. Read the shift name and the hours.
4. If tomorrow's row carries an amber badge, read its text — a special status was entered for that day (leave, swap…). Small text under the shift cell is the supervisor's note.
5. If you ask the same question on a Sunday, the answer is not in the table: it shows only the week you are in, and Monday opens as a new week. Ask your supervisor about next week.

8.6 The shift plan — frequently asked

The table says "no plan entered for this week".

This is not an error; no row has been written for you yet for that week. The cause is usually one of two: the plan has not been prepared, or it was entered against a different employee number than yours. Ask your supervisor whether this week's plan has been entered — on the HR side it is visible at a glance from the Shift plan screen.

The shift name shows but the hours are "—".

The hours do not come from the plan but from the shift card. If no start/end minute is defined on the card, the portal does not invent one — it honestly shows "—". The fix is on the HR side: enter the hours on that shift card and they appear the next time the table is read. Your plan row is unaffected.

Can I look at a colleague's plan?

No — and that is deliberate. When the portal asks for the plan it reads the employee number not from your phone but from the session you obtained at sign-in. There is no way to ask for another employee number by fiddling with the address; whatever the request says, the server uses the number in its own record. The same protection covers punches, leave requests and vehicle entries.

Does the plan slip a day on the night shift?

No. The week boundaries and the "today" highlight are computed with the server's local calendar — done deliberately so a date does not slip back a day on shifts that cross midnight. If you open the table at 23:00, the highlighted row is still that day's row.

The portal will not open / it says "session required".

"Session required" means the 8-hour window has expired: sign in again with employee number + PIN, nothing is lost. If the page does not open at all the problem is almost always the network — are the phone and the server on the same network, is the address right (http:// and the port), is a firewall blocking it. The third is the most common cause and your system administrator holds the fix.

This is why the Personnel window has an Approvals tab. Count drafts sit there beside the book quantity with the difference shown; approving them issues the slip. Pending production reports are counted on the same screen.

The phone apps use the same endpoints; there is no separate interface. No shared key is kept on the device — the only secret is the person's PIN. After five wrong attempts the account locks briefly, and the lock is per person: on a shared terminal one person's mistake does not lock everyone else out.

9. Defence pack — stamps, signature authority, access

This pack is optional; without it the module works exactly the same. It exists for firms that make parts for defence or aviation.

A quality stamp is a physical item in custody: its number, who holds it and when it was issued are recorded. One stamp cannot be with two people at once. A lost stamp is cancelled, and cancellation cannot be undone: that number is never issued again, because every part struck with it must remain traceable and a new holder would muddle the trail.

Signature authority is tied to a subject and an amount. The critical distinction: some authorities cannot be delegated. Saying "the manager is on leave, let the deputy sign" would, for qualification-bound authorities such as quality release or first-article approval, defeat the very purpose of this pack. The program refuses such a delegation. For delegable authorities the deputy's limit cannot exceed the grantor's — it is clipped automatically if asked for more.

Project access can be tied to a security clearance and a signed confidentiality undertaking. Where a rule is defined the program does not grant access; this is a refusal, not a warning. Clearance is hierarchical: someone cleared to "secret" cannot enter a project requiring "top secret". Where no rule is defined nothing is blocked.

10. Discipline and exit

No disciplinary decision can be recorded without a defence. This is a block, not a warning; a penalty without a defence is procedurally void and will not stand in court. The flow is: record the incident → request the defence → receive the defence → decide. If the defence does not arrive in time, that fact is minuted and the decision is recorded on that basis.

For repeated incidents of the same kind the step rises automatically (verbal warning → written warning → deduction → dismissal). You need not enter the step by hand; the program counts it from earlier records.

10.1 Clearing an employee out

On exit a checklist is opened: stamp return, cash/cheque/receipt-book custody, vehicle keys, closing system and project access, card cancellation, closing the portal account, portfolio handover, settling remaining leave, the release document. Until the mandatory items are ticked the window does not say "clear to leave".

The right-hand panel of the person card also carries a clearance summary: open custody, open stamps, open access, assigned vehicles, leave balance and unpaid commission are visible at a glance. Look here before you sit down for the exit interview.

11. Record forms and attachments

The Personnel module is no longer just a list-and-decision screen. Its record forms now cover the person's optional fields, employment period, shift and rotation definitions, raw-punch linkage, access and defence pack, legislation choice, premium and piece-rate data, plus leave, HSE, PPE, and entry-exit attachments.

📷 Actual screen

Note: no fresh HR-form PNG was captured for this update. This existing screen is the closest real image showing the shared attachment panel's metadata, security-class, and file-identity behaviour.

11.1 Shift and pattern setup — before attendance

A shift card defines working hours; a pattern defines their day-by-day repetition. The HR manager first opens Time → Shifts and records the shift code, name, start, finish, and night/day-overrun status. Then, under Patterns, the manager sequences the shift codes and uses X for a rest day.

1. Save the hours for day/office, morning, evening, and night shifts. If the night shift ends the next day, verify day overrun.
2. For example, create G,G,G,G,G,X,X for office staff and S,S,A,A,N,N,X,X for three-shift production. Use only registered shift codes; X means a day off and is not a shift code.
3. Apply the pattern to one test employee with a start date. If the eight-day plan is correct, apply it to the team in bulk.
4. Check the weekly plan and employee portal. “—” hours mean an incomplete shift card; no shift name means the pattern or plan was not applied.
5. Open attendance only after these checks. Do not delete a historical plan; record the change with a new effective date.

12. Dashboard — today at a glance

The dashboard answers three questions: how does headcount stand (active people, joiners, leavers, turnover), what is waiting (leave requests, production reports, count drafts, expiring certificates, open discipline) and where is the risk (accidents, lost days, single-point risk).

Turnover is the number of leavers over the active headcount. If headcount is zero it is not computed and "—" is shown; saying it cannot be computed is right, inventing a figure by dividing by zero is not.

13. Common mistakes

• Opening a personnel card but no employment period. The card alone does not make someone an employee; a person without a period is not counted in headcount and cannot sign in to the portal.

• Expecting portal punches without entering a card number. Punches attach to the card number; a person without one cannot punch. The error message says so.

• Expecting the piece-rate guarantee without entering the minimum wage. If the minimum wage is 0 in Legislation, no top-up is computed — this is not a fault but a decision not to invent a figure.

• Forgetting to approve a count draft. Stock does not change merely because someone on the floor entered a count. If rows are waiting in the Approvals tab, your inventory has not been updated yet.

• Leaving a departed employee's portal account open. The exit summary counts this as a blocker. Someone without an active employment period cannot sign in anyway, but closing the account is an item on the list.

14. Record forms › "Bulk staff import (CSV / list)" and the "Hire date" field

Entering a fifty-person shift by opening personnel cards one by one meant opening an employment period for each card too — a hundred operations. Two conveniences arrived. (1) "Hire date (opens the period too)": fill this field on the personnel card and the card and the employment period are opened in the same operation; if the period cannot be opened (e.g. an open period already exists) the card is not written either — no half records. (2) The "Bulk staff import (CSV / list)" card: paste a list copied from Excel, give a common hire date, press Upload.

1. HR › Record forms › open the "Bulk staff import (CSV / list)" card.
2. Paste the rows. The separator may be ;, , or tab. A header row is optional; without one the fixed order is expected: sicilno;ad;soyad;istihdam_tipi;giris;departman_kod;gorev_kod;telefon.
3. Optionally give a common hire date (used when a row has no giris). Press Upload.
4. The result arrives row by row: sequence no, period no or an error text. If one row fails the others are still written — partial success is normal; fix the failed rows and upload only those again.

Permission: the HR manager role or system administrator. Limits and messages: a personnel number that appears twice in the same list is refused with "SICIL_TEKRAR" before reaching the database; an already registered number gives "personnel number already in use" (409); more than 500 rows gives 413 — split the list; if every row fails, 422. About 400 rows per upload is the practical ceiling.

15. Portal lock: the login throttle counts only wrong PINs, the lock opens without waiting

The "personnel number + PIN" login of section 8.1 has two protections, and neither locks up a shift change any more:

15.1 Finding the right account in a crowded list

Do not scan a hundred-plus portal accounts by eye. Above the Personnel › Portal accounts table there is a search box (user name, personnel number or full name) and a "locked only" filter. Tick the filter first: the list narrows to rows that are locked or carry failed attempts — and the "Unlock" button only ever appears on those rows.

16. Garnishment files and the period deduction

Garnishment files live in the Garnishment files card at the bottom of Personnel › Earnings. Opening a file needs the personnel number, the type (garnishment or alimony), the file number, the principal amount and the service date — the queue is built from that date, which is why it is mandatory.

16.1 Queue and the legal ceiling

The Calculate period deduction button runs this order: (1) alimony files come first and sit outside the ceiling; (2) the remaining files are ordered by service date and sequence number, and no file is started before the previous one is cleared; (3) the total garnishment may not exceed the kesinti.icra_azami_oran percentage of the net wage (25% in the Turkish set). That rate is a parameter — there is no hard-coded number; change it under Legislation.

16.2 No net wage means no deduction

The deduction sits on the net wage. If the contract carries no approved net figure the program will not invent a gross-based garnishment: the person is flagged NET_UCRET_YOK and no deduction is produced. The fix is to enter the net amount on the contract.

16.3 Preview and write are two separate steps

Calculate period deduction (preview) writes nothing; it shows, with a reason per file, how much would be taken. Write posts the deductions to the ledger, reduces the file balances and closes a file that is fully paid. Running the same period twice does not double-deduct — what is already in the ledger is subtracted.

17. The Payroll tab — summary, bank list, social-security data

Personnel › Payroll has three sub-views: Summary (earnings and deductions per person), Bank list (amount payable + account) and Social-security data. All three offer Download CSV at the top right.

17.1 This summary is GROSS

The amber band at the top is there for a reason: in this version social-security and income-tax deductions are NOT calculated. The summary totals items that each module already calculated and approved (base wage, piece rate, commission, overtime, per-diem, advances, vehicle deductions, garnishment). For net pay, subtract the deductions from your statutory payroll program; the bank list is not a payment order.

17.2 "Not calculated" rows and the payment list

A person with an open garnishment file whose period deduction has not been calculated yet shows a red Not calculated badge; the Garnishment and Payable columns become a dash and the row is kept out of the bank list — it never reaches a payment order and is listed with its reason under "Excluded from the payment list". This case used to bring down the whole summary; now it only marks that row. Fix: write the period deduction from the Garnishment card on the Earnings tab.

17.3 Bank list: checksum and suspicious accounts

The bank list gives the record count, the total in minor units and a SHA-256 digest of the rows; compare the file you send to the bank against those three values. A row whose IBAN check digits fail gets a red Suspicious badge (in countries without IBAN, purely numeric accounts are not checked this way). The bank's own fixed-width file schema is not produced here — it varies per bank and version and is never invented; you get CSV, and mapping is a separate job.

17.4 Social-security data: occupation code and dominant absence reason

The declaration data now also carries the person's occupation code (a field on the personnel card); missing ones are counted. When a person has several absence reasons the institution wants one: the program picks the reason with the most days, breaks ties by the sgk.eksik_gun_oncelik order and states its choice on the row — it never decides silently. Mapping a reason to an official code lives in sgk.eksik_gun_kod; with no mapping no code is produced and the row says so. The official e-declaration file is not generated here — what is produced is the data it rests on.

18. Shuttle service — routes, stops, boarding list, contractor billing

The Shuttle view under Personnel › Shuttle / Canteen / Union holds contractor vehicles, their stops and the staff riding them. A route must carry a capacity; the occupancy percentage comes from it. This is not staff travel (per-diem) — that lives in the Trip records on the Earnings tab.

18.1 Capacity is a gate, not a warning

Adding a rider to a full vehicle is refused (SERVIS_KAPASITE_DOLU). If you knowingly need to record an overloaded run, assign with kapasiteOnay; the record then goes through but a CAPACITY EXCEEDED warning stays in the response and on the route list.

18.2 Billing and lateness

The number of runs is never invented: it is the count of distinct days on which staff assigned to that route actually worked according to the timesheet (the vehicle ran that day). The amount is that count × the run fee. Lateness is only flagged in this version; the program does not apply the penalty clause of the contractor agreement on its own — a human decides and posts the deduction.

19. Canteen — card taps, entitlement checks, catering reconciliation

Each meal is defined by a code, a time window and a unit cost. On a tap the program tries three gates in order and, when it refuses, says why: KART_TANIMSIZ if the card belongs to nobody, MUKERRER_BASIM for a second tap on the same meal, IZINLI_GUN if the person is on approved leave or sick that day, DAMGA_YOK if there is no entry stamp at all.

19.1 Reconciling the catering invoice

Reconciliation counts only accepted taps; a refused card never enters the amount. Enter the contractor's invoice count and total and the program shows both differences. Diet/allergen information comes from the diet code field on the personnel card and is returned with the tap so the kitchen screen can show it.

20. Union and collective agreement

A union is defined by a code, a name and a dues type: daily (dues = daily gross × number of days), rate (a percentage of gross) or fixed. The default number of days is the sendika.aidat_yevmiye parameter — no hard-coded figure.

20.1 Union leave is a paid day

A timesheet day with status sendikal_izin counts as a paid day and enters the social-security premium days; it is not reported as an absence. A representative's weekly leave hours are kept on the membership record. The dues list is grouped per union and can be exported as CSV; it does not create a payment instruction.

21. Social-security declaration (MPHB) — worksheet, workplace record, XML package

The Social-security declaration tab in the Payroll window gathers everything the month-end declaration rests on in one place: premium days, earned wage, bonus/premium, missing days and their reason, start/leave dates and the occupation code per person. This is a review screen — it produces no file, it counts what is missing.

Scope — this is half a declaration. MPHB combines two filings: withholding tax and social-security contributions. Because HNR does not compute income-tax withholding, only the social-security part is produced; the tax fields are left out and not filled with 0 — writing 0 produces a filing the agency will reject. Complete the tax part from your accountant's software before submitting.

The workplace record is mandatory. The declaration wants the 26-digit workplace registration number split into parts. Type the number into one field and press "Parse the number": the new unit, old unit, workplace sequence, province code and subcontractor code are derived from the character ranges in the official guide. The positions of the industry, district and check numbers are not published, so they are not derived — you enter them by hand. If a part you typed contradicts the parsed one the save stops and names the conflicting part; there is no silent correction.

Occupation code (NNNN.NN). The agency wants a 4-digit ISCO-08 code plus a 2-digit sub-breakdown. HNR does not embed the 7,556-line occupation dictionary (copyright, freshness and maintenance cost); it validates the format only and offers two ways to set the code: the person card or the job tag. If you set it on the job tag, everyone in that job inherits it. A person without a code shows in red on the worksheet.

Why XML and the ZIP package are off by default. The agency's machine-readable schema (XSD) is not published and the format changed in the June/2026 period. So HNR does not invent a schema: you define the XML element names yourself on the Declaration schema tab (from your agency software's field names). While Settings › Safety gates › sgk.xml_uret is off, the worksheet and CSV work exactly as before and XML/package are refused. Turn the gate on after you have verified your definition matches your agency software. The package may be at most 15 MB per the guide; if it exceeds that, split the filing with the workplace filter.

A row whose mandatory field is empty is NOT written to the file. If a field you marked "mandatory" in the schema is empty for a person, that person's row does not enter the file and appears in the missing list with its reason. This is deliberate: an empty mandatory field means a filing the agency will reject; seeing the gap on screen beats seeing the rejection letter.

22. Bank salary file — the template engine

Payroll › Bank file converts the bank payment list into the text layout your bank wants. The layout is not hard-coded, and there is a measured reason: no Turkish bank publishes its fixed-width TXT schema; the only official document published is Ziraat's Excel template, and bank manuals themselves say "a custom layout can also be accommodated". So there is no single "bank format" — you get the column map from your bank and define it here.

Six gates, all of them stop the file. (1) If a value does not fit its field the file is not produced; you are told who, which field and by how many characters — silently trimming means sending the bank a wrong IBAN. (2) If two fields overlap the template is not saved. (3) If you set a record length every line is exactly that long. (4) With cp1254 or ASCII, an unconvertible character stops the file — a Turkish name never silently becomes "?"; if you want transliteration you ask for it explicitly with bicimleme=ascii on that field. (5) A person failing the IBAN check does not enter the file; to send anyway you tick "Include invalid accounts too" and that is recorded in the audit trail. (6) The file's record count and total in cents are compared with the list, and the file's own SHA-256 is computed.

Why the preview shows a column ruler. In a fixed-width file a single character shift breaks everything. "Preview" prints a numeric ruler above the first lines so you can count column starts by eye. If you left the template source empty, both the screen and the output carry the "not official — verify with your bank" warning. While Settings › Safety gates › banka.txt_uret is off, the existing CSV and JSON outputs keep working unchanged.

23. The Dates tab — probation, contract end, examination

The Dates tab shows the employees' time-bound records in one list: probation and the last day for termination notice, fixed-term contract end and the legal maximum total term, certificate and document validity, periodic medical examination. Legal warnings are written in red; limits come from the parameters in the Legislation tab. Reminders and escalation belong to the Contract calendar — details: Contract Calendar › Employee dates.