# Open Core HR # Installation overview The order of steps for installing and running a self-hosted Open Core HR server. This guide is for the person installing and maintaining Open Core HR. For everyday HR and employee tasks, start with the [Welcome](https://czappstudio.com/docs/getting-started/welcome) page. Open Core HR is a self-hosted Laravel application supplied with source code. It needs a PHP application server and a database. This guide accompanies **version 1.0.0**. The deployment recipes are checked against the repository configuration. Fresh installations on each named hosting platform have not yet been certified. ## Installation sequence 1. Buy Open Core HR from [CZ App Studio](https://czappstudio.com) and download the release package. 2. Check [requirements and hosting](https://czappstudio.com/docs/installation/requirements). 3. [Prepare the source package, domain and database](https://czappstudio.com/docs/installation/prepare). 4. Follow the recipe for [cPanel](https://czappstudio.com/docs/installation/cpanel), [Linux VPS](https://czappstudio.com/docs/installation/linux-vps), [another platform](https://czappstudio.com/docs/installation/other-platforms) or [local development](https://czappstudio.com/docs/installation/local-development). 5. [Configure and initialize](https://czappstudio.com/docs/installation/configuration) the application. 6. Set up [email and background services](https://czappstudio.com/docs/installation/services). 7. Complete the [installation checklist](https://czappstudio.com/docs/installation/checklist). 8. Activate the installation from **Settings → Modules → Activate product**, then install the add-ons you own from the same page; see [Licences and activation](https://czappstudio.com/docs/installation/activation) and [Installing and managing add-ons](https://czappstudio.com/docs/installation/add-ons). Keep third-party licence notices with the installation. Your licence and support terms are those of your CZ App Studio purchase. --- # Install with an AI agent Let Claude Code, Cursor, Codex, GitHub Copilot or Gemini set up Open Core HR for you, on your own computer or on a server, free, using this documentation. Open Core HR is built to be installed by AI coding agents. Every guide in this manual is published as plain Markdown, the whole manual is available as [llms.txt](https://czappstudio.com/llms.txt) and [llms-full.txt](https://czappstudio.com/llms-full.txt), and the install steps are deterministic shell and Artisan commands that agents run well. There is no charge for this: it is part of your licence. Choose an [installation plan](https://czappstudio.com/installation) only when you want our engineers to do the work, build your mobile apps or train your team. ## Two ways to use this guide - **Locally, to try it out.** Run Open Core HR on your own Mac, Windows or Linux machine with Laravel Herd, Docker or any local PHP stack. Nothing is exposed to the internet, you can reset it at any time, and the same agent can later move you to a server. The [local development](https://czappstudio.com/docs/installation/local-development) guide has the stack details. - **On a server, to go live.** Install on a cPanel account, a Linux VPS or [another platform](https://czappstudio.com/docs/installation/other-platforms) for your company to use. The prompt below works for both. Tell the agent which one you want. ## What you need - **Locally:** a computer that can run PHP 8.5, Composer, Node.js and a database (Laravel Herd on Mac and Windows gives you all of this), plus the release package extracted in a folder. - **On a server:** a server or hosting account that meets the [requirements](https://czappstudio.com/docs/installation/requirements), with SSH access (or cPanel Terminal) for the agent to run commands, and the release package extracted there. - The release package itself, from [your CZ App Studio account](https://czappstudio.com/account). - An AI coding agent that can run shell commands where the files are: Claude Code, Cursor, Codex CLI, GitHub Copilot in VS Code, Gemini CLI or similar. - For a server: your domain, database credentials and SMTP details. Give them to the agent through environment variables or files on the server, never by pasting them into the chat. ## Step 1: Open the agent where the files are Start the agent in the folder where you extracted the Core download (the guides call it `backend/`). It contains `AGENTS.md` and `INSTALL-WITH-AI.md`, which your agent reads first. Locally, open that folder in your editor or terminal: ```bash cd ~/Projects/open-core-hr claude # or: cursor . / codex / gemini ``` On a server, connect first and then start the agent: ```bash ssh deploy@your-server cd /var/www/open-core-hr claude # or: cursor . / codex / gemini ``` ## Step 2: Paste the install prompt Copy this prompt into the agent. It tells the agent where the documentation is and sets the ground rules. ```text You are setting up Open Core HR, a self-hosted Laravel application, in this directory. Read AGENTS.md and INSTALL-WITH-AI.md in this folder first; they describe this release. For the full manual, use the open-core-hr MCP server if it is connected, otherwise read https://czappstudio.com/llms-full.txt. Follow these guides in order: Requirements, Prepare, the recipe for my target (Local development, cPanel, Linux VPS or other), Configuration, Services, then the Installation checklist. For a local setup, skip HTTPS, domain and production hardening steps and say which ones you skipped. Rules: - Explain what each step does before you run it, and run one step at a time. - Ask me before anything destructive (dropping databases, overwriting files, restarting services). - Run `php artisan doctor` after each stage and fix what it reports. - Never ask me to paste passwords, API keys or licence keys into this chat. Tell me which environment variable or file to fill in, then continue once I confirm. - Only backend/public may be served over HTTPS. Verify this. - When finished, write a deployment report in DEPLOYMENT-REPORT.md listing versions, the checks you ran from the Installation checklist, and anything you could not verify. My target is: . My domain (server only) is: . ``` ## Step 3: Let the agent work, and answer its questions The download includes `AGENTS.md`, `INSTALL-WITH-AI.md`, ready-made skills and an MCP connection to this manual, so your agent starts with the architecture and the rules already loaded (see [Using AI coding agents](https://czappstudio.com/docs/installation/ai-agents)). The agent reads the manual, checks PHP, extensions and the database, writes `.env`, runs migrations, builds assets, configures the queue worker and scheduler and, on a server, sets up HTTPS and email. It will stop to ask you for credentials or decisions. Keep these rules in mind: - Fill secrets into `.env` yourself when asked, then tell the agent to continue. - If the agent proposes a command you do not understand, ask it to explain. A good agent will. - Let it finish the [installation checklist](https://czappstudio.com/docs/installation/checklist); the report it writes is your record of what was verified. - Started locally and ready to go live? Open the agent on the server and paste the same prompt; it can also read your local `DEPLOYMENT-REPORT.md` and `.env` layout to reproduce your choices. ## Step 4: Sign in and activate Open your local address or your domain, sign in as the administrator the agent created and remove the bootstrap password from configuration as described in [Configuration](https://czappstudio.com/docs/installation/configuration). Then open **Settings → Modules**, choose **Activate product** and approve on the CZ App Studio website; you return to the product activated. Activation is what lets you install the add-ons you own and receive updates. A local trial uses your licence's separate local slot. See [Licences and activation](https://czappstudio.com/docs/installation/activation). ## Using AI on any page of this manual Every page has an **Use this page with AI** toolbar: - **Copy as Markdown** copies the page in plain Markdown to paste into any chat. - **Open in Claude** and **Open in ChatGPT** start a conversation with the page already loaded. - **Copy prompt for your coding agent** copies a short prompt that points your agent at this page. - **View as Markdown** opens the raw `.md` file at the same address with `.md` appended, for example `/docs/installation/requirements.md`. Agents that look for `llms.txt` find it at the site root. ## When to ask our team instead AI handles a standard installation well. Choose a paid [installation plan](https://czappstudio.com/installation) when you want our engineers to install on your infrastructure, build and submit branded Android and iOS apps, hand the system over to your administrators in person or run live training. Installation plans are for people's time; the AI route stays free. ## If something goes wrong Work through [Troubleshooting](https://czappstudio.com/docs/installation/troubleshooting) with your agent. If you need us, open a ticket from [your account](https://czappstudio.com/account/support) and attach the agent's `DEPLOYMENT-REPORT.md` with secrets removed. It tells us exactly what was done. --- # Requirements and hosting Server software, PHP extensions and hosting platforms that Open Core HR needs. ## Application requirements | Component | Requirement | | --- | --- | | PHP | 8.5.12 or later within PHP 8.x; use the same version for web and CLI | | Composer | 2.11.1 or later within Composer 2.x; verify with `composer check-platform-reqs --no-dev` | | PHP extensions | All extensions required by `composer.lock`; includes intl, curl, PDO/MySQL, zip, mbstring, XML/DOM, fileinfo and OpenSSL | | Database | MySQL 8.4 LTS; validate migrations on the exact server version | | Web server | Nginx or Apache with its document root set to `backend/public` | | Build and PDF runtime | Node.js 26.13.0 LTS and npm 12.2.1, or later releases within those major versions | | PDF rendering | Chromium installed through Playwright or a configured system binary; fonts covering enabled languages; PHP must be able to launch the Node process | | Background services | A scheduler every minute and a persistent worker for asynchronous jobs | | HTTPS | Required for a customer-facing deployment | | Real-time features | Persistent Reverb process and WebSocket proxy when enabled | Install dependencies from the supplied lockfiles. Runtime version files in `backend/` and its Docker image specify the development baseline; validate the target hosting platform before use. ## Choose your hosting | Platform | Confirm with the provider | | --- | --- | | Linux VPS | Compatible PHP/CLI, database, SSH, cron, web server and process manager | | cPanel / Plesk | Compatible web and CLI PHP, Composer/SSH, configurable document root, cron and persistent workers | | Shared hosting | All requirements above; many plans cannot run workers or WebSockets | | Windows / IIS | PHP/MySQL compatibility, URL rewriting, scheduling and service management; separate acceptance required | Prefer a VPS for live chat, calls and other real-time features. Cloudflare DNS/proxy does not provide a PHP runtime or MySQL database. ## Verification status Fresh-installation acceptance on cPanel, Linux VPS, Plesk/Apache and Windows remains pending. Local regression tests do not certify these hosting environments. --- # Prepare your installation Extract the release, create the database, install dependencies and create the private configuration. 1. Extract the release package from your CZ App Studio purchase into a private working directory. 2. Extract the Core download into a folder for the application, for example `backend/`. The guides call this folder `backend/`; run application commands from it. Add-ons are installed later from **Settings → Modules**. 3. Create a dedicated database and a user restricted to that database. 4. Point an application hostname, such as `hr.example.com`, to the application server. 5. Configure HTTPS and set the web document root to the full path of `backend/public`. 6. Arrange SMTP delivery, scheduled tasks and worker services. Do not expose the repository root, `.env`, source, backups or private uploads through the public document root. ## Install dependencies ```bash cd backend composer install --no-dev --prefer-dist --optimize-autoloader composer check-platform-reqs --no-dev npm ci npm run build npx playwright install --with-deps chromium ``` Use the supplied lockfiles. Node.js and Chromium are also required on the application server for letters, payslips and PDF exports. Run the browser installation for the account that runs PHP and queue workers, or set `PDF_CHROMIUM_BINARY` to an installed Chromium executable. Set `PDF_NODE_BINARY` if Node is not on the service account's PATH. Install fonts for the languages you enable; the Docker image includes Noto fonts. Keep Chromium sandboxing enabled and run application services as a non-root user. Do not deploy a development `public/hot` file. Composer dependencies must match the server's PHP platform. ## Create private configuration On a new installation only: ```bash cp .env.example .env php artisan key:generate php artisan jwt:secret ``` Continue with [configuration](https://czappstudio.com/docs/installation/configuration). Do not overwrite an existing `.env` or regenerate encryption/authentication keys during updates. --- # Install on cPanel Install Open Core HR on a cPanel account that supports SSH, Composer, cron and persistent workers. This recipe requires compatible web/CLI PHP, Terminal/SSH, Composer, cron and persistent worker support. cPanel alone does not guarantee these capabilities. 1. In **Select PHP Version** or **MultiPHP Manager**, select compatible PHP and its required extensions. Confirm the Terminal and cron PHP binary uses the same compatible version. 2. In **MySQL Databases**, create the database and user, assign permissions on this database, and record the full prefixed names privately. 3. Extract the backend outside `public_html`, for example `/home/account/open-core-hr/backend`. 4. In **Domains**, set the application hostname's document root to `/home/account/open-core-hr/backend/public`. 5. Enable HTTPS with the host's SSL/AutoSSL controls. 6. Open Terminal, change into `backend`, and follow [preparation](https://czappstudio.com/docs/installation/prepare) and [configuration](https://czappstudio.com/docs/installation/configuration). 7. In **Cron Jobs**, run the scheduler every minute using absolute paths: ```bash /path/to/php /home/account/open-core-hr/backend/artisan schedule:run >> /home/account/open-core-hr/backend/storage/logs/scheduler.log 2>&1 ``` Use the provider's actual compatible PHP binary. Monitor and rotate this log. Ask the provider to supervise `queue:work` and Reverb if needed; see [services](https://czappstudio.com/docs/installation/services). If the host cannot set `public` as the document root or run required services, use a compatible plan or VPS. Moving the front controller into a public repository root is not an approved workaround. Finish the [installation checklist](https://czappstudio.com/docs/installation/checklist). cPanel acceptance remains pending. --- # Install on a Linux VPS Install Open Core HR on a Linux server with Nginx, PHP-FPM, MySQL and a process manager. Use a maintained Linux distribution. Install Nginx, compatible PHP-FPM/CLI and extensions, MySQL, Composer and a process manager using supported packages. Package names and socket paths vary by distribution. 1. Create a deployment account and dedicated database/user. 2. Put the application in `/srv/open-core-hr/backend` or your chosen private path. 3. Follow [preparation](https://czappstudio.com/docs/installation/prepare) and [configuration](https://czappstudio.com/docs/installation/configuration). 4. Give PHP-FPM write access to `storage` and `bootstrap/cache`. Keep source and secrets private; do not use world-writable permissions. 5. Configure Nginx, replacing the hostname, path and socket below: ```nginx server { listen 80; server_name hr.example.com; root /srv/open-core-hr/backend/public; index index.php; client_max_body_size 20m; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ ^/index\.php(/|$) { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; fastcgi_pass unix:/run/php/php8.5-fpm.sock; fastcgi_hide_header X-Powered-By; } location ~ \.php$ { return 404; } location ~ /\.(?!well-known).* { deny all; } } ``` 6. Test the Nginx configuration and reload it. 7. Issue an HTTPS certificate and configure HTTP-to-HTTPS redirection. 8. Set up [cron and supervised services](https://czappstudio.com/docs/installation/services). 9. Complete the [installation checklist](https://czappstudio.com/docs/installation/checklist). Align upload limits in PHP, Nginx and application validation. This starting configuration still needs acceptance on the exact Linux/PHP stack. --- # Plesk, Apache and Windows Notes for installing Open Core HR on Plesk, Apache and Windows with IIS. These environments require their own fresh-installation checks before being advertised as supported. ## Plesk Create the application domain, select compatible PHP for web and CLI, set its document root to `backend/public`, create its database and enable SSL. Use SSH for [preparation](https://czappstudio.com/docs/installation/prepare) and [configuration](https://czappstudio.com/docs/installation/configuration). Configure Scheduled Tasks for `artisan schedule:run` every minute. Arrange persistent queue/Reverb services with the hosting provider. ## Apache Set `DocumentRoot` to `backend/public`. Enable `mod_rewrite`, permit the supplied `public/.htaccess` rules, configure compatible PHP and HTTPS, and deny access to hidden files. Follow common setup and services instructions. If only the homepage works, check rewriting and virtual-host settings. ## Windows / IIS Install compatible PHP/extensions and MySQL. Set the site root to `backend/public`. Configure IIS URL Rewrite rules equivalent to the Apache front controller; IIS does not read `.htaccess`. Adapt Unix commands for PowerShell. Use Task Scheduler for the scheduler and supervised Windows services for queue workers and Reverb. Verify filesystem permissions and storage links. Windows production hosting is not currently certified by this guide. Arrange deployment-specific validation or use the VPS recipe. --- # Local development Run Open Core HR on your own computer for development and testing. Install compatible PHP, Composer, MySQL and Node.js. Use a separate local database with demonstration data only. Follow [preparation](https://czappstudio.com/docs/installation/prepare), using `composer install` with development dependencies instead of `--no-dev`. Set `APP_ENV=local`, configure a new local database, and follow [configuration](https://czappstudio.com/docs/installation/configuration). ```bash # Terminal 1, from backend php artisan serve --no-reload --host=127.0.0.1 --port=8000 # Terminal 2, from backend npm run dev ``` The `--no-reload` option preserves the environment needed by the PDF subprocess on Windows. Restart the server after changing `.env`. Set `APP_URL=http://localhost:8000`. Run additional services when testing asynchronous or real-time features. Use local mail capture instead of customer email accounts. Use a real web server and compiled assets for customer hosting. Keep local configuration and uploads out of source packages. --- # Configure and initialize Set environment values, initialize a fresh database and configure modules, reCAPTCHA and maps. Edit `.env` privately. Set the real application URL and database credentials. The values below are placeholders: ```dotenv APP_ENV=production APP_DEBUG=false APP_DEMO=false APP_URL=https://hr.example.com TELESCOPE_ENABLED=false DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=your_database DB_USERNAME=your_database_user DB_PASSWORD=your_private_password QUEUE_CONNECTION=database CACHE_STORE=file SESSION_DRIVER=file ``` `DOCUMENTATION_URL` sets where the **Documentation** link in the application footer points; set it to the Open Core HR documentation on the CZ App Studio website. `APP_URL` also controls password reset email links and passkey sign-in. Passkeys need HTTPS and are tied to the host name in `APP_URL`: people must open the application at that address, and changing the host name later stops existing passkeys from working, so everyone has to add theirs again. Configure outgoing mail in **Settings → Mail** before testing recovery. Set currency, timezone and formats in **Settings → Localisation** after installation. ## Initialize a fresh database Initialization uses command-line tools. Before running it, configure your own administrator in `.env`: ```dotenv BOOTSTRAP_ADMIN_EMAIL=your-administrator-address BOOTSTRAP_ADMIN_PASSWORD=your-own-password-of-at-least-12-characters BOOTSTRAP_ADMIN_FIRST_NAME=Your BOOTSTRAP_ADMIN_LAST_NAME=Name APP_DEMO=false ``` There is no supplied production administrator password. On a **new, empty database only**: ```bash php artisan migrate --force php artisan db:seed --force php artisan storage:link php artisan optimize ``` The default seeder installs required system data and enabled-module defaults. It creates only your configured administrator and the system bot. It does not create demo employees, company scenarios or sample transactions, regardless of `APP_DEMO`. The bot has a dedicated role without browser or mobile portal access. Keep access restricted while initializing. Verify administrator credentials, company settings and role/portal access before opening to employees. After initialization, remove `BOOTSTRAP_ADMIN_PASSWORD` from configuration and refresh the configuration cache. Existing administrator credentials are preserved when rerunning seeds, but fresh-install seeding is not an update procedure. For a separate local demonstration database, `php artisan demo:seed --fresh` builds the Orionis Group demo company and connected sample activity. It wipes that configured database. The command is restricted to local/testing environments; never use a customer database for a demo. `APP_DEMO` controls demo interface behavior, not which data is seeded. To add missing scenarios to an existing local demo without resetting it, run `php artisan demo:seed --no-interaction` from `backend/`. Existing demo payroll runs and payment history are preserved. With Payroll and its optional source modules enabled and a two-decimal deployment currency, **Northstar · Integrated payroll** demonstrates loan deductions, expense reimbursements, and a leaver's prorated salary plus approved Lifecycle adjustments. It includes full and partial payment, a reversed receipt, released reservations on a cancelled run, and a replacement draft. These sample runs capture their own integration choices; seeding does not change the administrator's Payroll settings. When Payroll is enabled, the demo includes fixed-salary, manual-timesheet and attendance-review groups. Explore a published prior-month payroll with private payslips and payment history, a calculated manual run, and current drafts. Attendance exceptions remain available to practice reviewing source data. Demo payroll uses the configured currency and timezone; it does not send money or notifications. Never reset a database, run `migrate:fresh`, re-run demo seeders or regenerate existing keys during updates. ## Files and modules The web process needs write access to `storage` and `bootstrap/cache`. Keep private documents private; do not link all of storage publicly. Use authorized application downloads. Configure durable file storage in [Settings → Storage](https://czappstudio.com/docs/administration/mail-storage-and-notifications#section-6). New uploads use the active connection; existing files retain their original connection. Back up every referenced destination along with the database and application encryption key. A super administrator manages installed modules in **Settings → Modules**. Open a module’s details to check its installed version, supported Core and mobile releases, and required modules before enabling it. The mobile version range describes compatibility; it does not report versions installed on employee devices. Enable required modules first. A module cannot be enabled if its release is incompatible with the installed Core version. To disable a module that others depend on, disable those dependent modules first. Changes apply across the organisation, while user permissions still control access. Disabling a module preserves its records but makes it unavailable until enabled again. This page manages packages already installed on the server. For package changes, follow the [maintenance guide](https://czappstudio.com/docs/installation/backups-and-updates). Public documentation remains visible regardless of enabled modules; add-on module workflows are described in the Modules section. **Import & Export** is a standard module. Its available data types depend on the requester's permissions and enabled source modules. Configure its [queue worker and cleanup schedule](https://czappstudio.com/docs/installation/services#section-3) before relying on bulk transfers. ## Google reCAPTCHA reCAPTCHA is a core feature configured in **Settings → Security**. It is disabled on installation. Do not put its runtime keys into `.env`; saved credentials are encrypted using the installation's `APP_KEY`. Preserve that key in protected backups. For **Google Cloud**, enable the reCAPTCHA Enterprise API and create a **Checkbox** (v2) or **Score-based** (v3) website key for the selected version. Obtain a separate server API key restricted to that API and, where possible, your server's outbound IP addresses. Check assessment quotas and billing requirements in [Google's setup guide](https://docs.cloud.google.com/recaptcha/docs/create-assessment-website). For **Classic**, enter the matching site key and legacy secret key for the selected version. A Cloud API key cannot replace a legacy secret. See [Google's SiteVerify guide](https://docs.cloud.google.com/recaptcha/docs/verify). Keep domain validation enabled in Google. Add the exact hostnames used to access this installation to the application's allowed-hostname list, and permit those domains in Google. Use separate development and live keys; allow `localhost` only in development keys. Do not activate Google's public testing keys on a live installation. The server needs outbound HTTPS access to `recaptchaenterprise.googleapis.com` for Cloud verification or `www.google.com/recaptcha/api/siteverify` for Classic verification. Browsers must be able to reach Google's reCAPTCHA scripts and frames. If your reverse proxy adds a Content Security Policy, use Google's [documented reCAPTCHA CSP configuration](https://developers.google.com/recaptcha/docs/faq#im-using-content-security-policy-csp-on-my-website-how-can-i-configure-it-to-work-with-recaptcha) and keep the visible widget/badge and legal links intact. Complete the [administrator activation test](https://czappstudio.com/docs/administration/settings#section-3) with your own keys and domain. Automated tests cannot validate a customer's Google credentials or network. ## Maps and customer place search Maps are optional and are configured by an administrator in **Settings → Maps**, not in the environment file. Use two separate Google keys: - **Browser key** draws the web maps (live tracking, route playback). Enable the Maps JavaScript API and restrict the key to your application's web addresses. A Map ID is optional. - **Server key** powers customer place search. Enable the Places API and restrict the key to that API and your server's outbound IP addresses. It is stored encrypted and is never shown again after saving. The server needs outbound HTTPS access to `places.googleapis.com`. Test search and selection on a customer form; the selected result should populate the address and coordinates. If the provider is unavailable, users can enter coordinates or capture their device location, and tracking information remains available as lists and timelines without the map. The mobile app's map key is part of the mobile build configuration; see the mobile build guide. --- # Email, queues and real-time services Set up outgoing email, the queue worker, the scheduler, webhook delivery and Reverb. ## Email After installation, an administrator configures outgoing mail in **Settings → Mail**: the provider, SMTP credentials and sender address. Use **Send a test email** there to confirm delivery, and verify the sender domain with your provider. `log` and `array` mailers do not deliver email. Test password recovery and confirm the email link opens the reachable HTTPS application hostname. ## Queue worker For a database queue, apply its migrations and supervise a worker from `backend`: ```bash php artisan queue:work --queue=default --sleep=3 --tries=3 --timeout=60 ``` Ensure queue `retry_after` exceeds the worker and job timeout: the default database value of 90 seconds is longer than this 60-second timeout. Run with access to storage/configuration. Use systemd, Supervisor or the host's worker manager to restart on failure and reboot. After code deployment: ```bash php artisan queue:restart php artisan queue:failed ``` The `sync` queue runs jobs inline; it does not demonstrate asynchronous worker health. ## Import & Export operations The standard **Import & Export** module uses the `default` queue for confirmed imports and requested exports. Apply its migration through the normal `php artisan migrate --force` update process, then restart workers. Do not reset the database. Its jobs have a 60-second timeout and imports do not retry automatically, regardless of the worker's general retry setting. Test with a small permitted export and a harmless import preview after installation. Confirm that preview creates no records, a confirmed job reaches a final result, and the requester can download the completed file. Only test a confirmed import with records intended for that installation. Uploaded files, validation results and generated downloads use private storage. Give the application and worker access to the same storage, including on hosts with separate worker processes. Do not place transfer storage behind a public web URL. Files expire after seven days; transfer history metadata is retained. ## Scheduler Add a cron entry every minute: ```cron * * * * * cd /srv/open-core-hr/backend && /path/to/php artisan schedule:run >> /srv/open-core-hr/backend/storage/logs/scheduler.log 2>&1 ``` Replace paths, monitor/rotate logs, review `php artisan schedule:list` and confirm timezones. Modules can contribute additional schedules when enabled. Confirm that the hourly `data-transfers:cleanup` task appears in the schedule and runs successfully. It removes expired files and validation content while retaining history metadata. It also marks processing jobs interrupted for more than five minutes as failed so their requester can investigate. It can be run manually from `backend`: ```bash php artisan data-transfers:cleanup ``` ## Webhook delivery When the optional **Webhooks** module is enabled, its deliveries use the default queue. Keep the worker and scheduler running. In `php artisan schedule:list`, confirm that `webhooks:retry-failed` runs every minute and `webhooks:cleanup-logs` runs daily at 03:00 in the scheduler's configured timezone. The delivery service controls its own retries: by default, one initial attempt and up to three retries after 1 minute, 5 minutes and 1 hour. The worker's `--tries` option does not replace that schedule. Completed, failed and cancelled delivery logs expire after 30 days by default; pending work is retained until it finishes. Use a harmless test delivery to the configured receiver and verify both its signature check and the delivery result. Deactivating an endpoint or disabling the module cancels pending work. See [Webhooks setup](https://czappstudio.com/docs/modules/webhooks) for endpoint and signing-secret configuration. ## Real-time services Configure `REVERB_*` and public `VITE_REVERB_*` before building assets. Keep private Reverb secrets out of frontend variables. Supervise `php artisan reverb:start` and configure HTTPS/WSS proxying with WebSocket upgrade headers. Restart long-running services after configuration changes. Microsoft 365, Firebase and other external providers need customer-owned credentials and separate live acceptance. Do not ship configured service accounts. --- # Installation checklist Checks to complete before you invite employees to a new installation. Record product version, hosting platform, PHP/database versions, date and outcome. Complete before inviting employees: - [ ] Composer platform requirements pass and migrations finish. - [ ] HTTPS works; only `backend/public` is served. - [ ] Secrets, logs, source, backups and private documents cannot be downloaded publicly. - [ ] Debug/demo modes are off; keys are private and backed up. - [ ] The explicitly configured administrator can sign in; the bootstrap password has been removed from configuration. - [ ] Only the intended administrator and system bot were initialized; master data and enabled-module defaults are reviewed. - [ ] Administrator and employee accounts reach the expected portals. - [ ] Employee creation, attendance, leave and approvals work with expected roles. - [ ] Uploads and authorized downloads work; unrelated employees cannot read private files. - [ ] SMTP reaches an inbox; password recovery uses the correct hostname. - [ ] Queue jobs run and workers survive reboot; failed jobs are reviewed. - [ ] Import & Export preview makes no record changes; a permitted export completes on the default queue and only its requester can download it. - [ ] Transfer cleanup is scheduled, expired files are removed and transfer history remains available. - [ ] Cron, policy publication/reminders and optional-module schedules run. - [ ] WebSocket features work when included. - [ ] Mobile API/live integrations pass when included; mocks do not replace acceptance. - [ ] A backup restores successfully to an isolated installation. - [ ] The installation is activated from your CZ App Studio account. - [ ] The **Documentation** link in the application footer opens the online manual. Documentation publication is separate from customer-installation acceptance, secure bootstrap review and live integration verification. --- # Licences and activation Link an installation to your licence so it can install add-ons and receive updates. Open Core HR works without activation. Activation unlocks the add-ons you own, one-click add-on installs, Core updates and the add-on store inside the product. It never sends employee or business data to CZ App Studio. ## Before you start - Sign in to the product as the **super administrator** of the main organization. - Set `APP_URL` in `.env` to the exact address people use, for example `https://hr.example.com`. Activation is tied to that host name. - The server must be able to reach `https://czappstudio.com` over HTTPS (port 443). If a firewall or proxy blocks outgoing traffic, allow that address. - Have your CZ App Studio account details ready. The licence must be in that account. ## Activate 1. In the product, open **Settings → Modules** and choose **Activate product**. 2. The CZ App Studio website opens. Sign in if asked. 3. Check the product, address and code, choose the licence to use, tick the confirmation and choose **Approve activation**. 4. You return to the Modules page, which now shows **Activated** with your address. ![Settings → Modules: choose Activate product (1).](https://media.czappstudio.com/screens/docs/activate-product/light-1f8707a1d6-2880.webp) If the browser cannot return to the product (for example the server is reachable only inside your network), the product shows a 10-character code instead. Open [Activate your product](https://czappstudio.com/account/activate), enter the code, approve, then choose **Check again** in the product. Activation requests expire after 10 minutes. Start again if the code has expired. ## Local and production slots Each core licence has two activation slots: | Slot | Used when `APP_URL` is | Typical use | |---|---|---| | Local development | `localhost`, `127.0.0.1` | A trial or development copy on your own computer | | Production | A real domain name | The installation your staff use | Each slot holds one installation at a time. Add-ons follow the core licence they are assigned to. ## Moving to a new server or domain 1. Back up the old installation (see [Backups and updates](https://czappstudio.com/docs/installation/backups-and-updates)). 2. On [your licence page](https://czappstudio.com/account), choose **Deactivate** for the production slot. 3. On the new installation, choose **Activate product** again. On the old installation you can also choose **⋯ → Remove activation from this server**. That forgets the activation locally; the slot is released only when you deactivate it in your account. ## Add-ons and your licence Add-ons you buy are attached to a core licence automatically when you buy them with **Buy now** from the product, or when you own exactly one core licence. Otherwise, open the add-on's licence in your account and choose the core licence to attach it to. Then choose **Check for updates** in the product; the add-on shows **Install**. ## How the licence is checked The product checks in with CZ App Studio once a day and when you choose **Check for updates**. Each check returns a receipt signed by CZ App Studio; the product only trusts a receipt whose signature, installation and address match. If the website cannot be reached, the last valid receipt keeps working. Each check sends the installation's address, product and add-on versions, and basic server facts (PHP, database and web server versions, PHP extensions, memory and disk limits, time zone, organization and user counts). This helps support and compatibility. No employee, attendance, payroll or other business records are sent. ## Messages and what to do | Message | Fix | |---|---| | *This server cannot reach czappstudio.com* | Allow outgoing HTTPS to `czappstudio.com` in the firewall or proxy, then retry. | | *The return address must be on the server being activated* | `APP_URL` does not match the address in the browser. Correct `APP_URL`, run `php artisan config:clear`, and start again. | | *No slot is available* | Deactivate the old installation in your account, or choose another licence. | | *The store no longer recognises this installation* | The activation was deactivated or revoked. Choose **⋯ → Remove activation from this server**, then activate again. | | *The store refused this request* | The server address changed since activation. Remove the activation and activate again. | | *The licence receipt could not be verified* | `APP_URL` does not match the activated address, or the files were modified. Correct `APP_URL`; reinstall Core from your download if needed. | Repeated failed licence requests from one address are recorded and may be blocked. --- # Installing and managing add-ons Buy, install, update, switch on and configure add-ons from **Settings → Modules**. Add-ons are optional modules such as Payroll, Tasks or Geofence Attendance. They are installed into the `Modules/` folder of your installation and are never overwritten by Core updates. The page is available to the super administrator of the main organization. Activate the installation first (see [Licences and activation](https://czappstudio.com/docs/installation/activation)). ## What each card shows | Card shows | Meaning | What you can do | |---|---|---| | **In the store** + **Buy now** | Not owned and not installed | Open its page on czappstudio.com and buy it | | **Free** + **Claim free** | A free add-on you have not claimed yet | Open its page on czappstudio.com and complete the order; there is nothing to pay | | **Owned** + **Install 1.2.0** | Owned, not yet on this server | Install it | | **Enabled** / **Disabled** | Installed and licensed | Switch it on or off | | **Update to 1.3.0** | A newer release you are entitled to | Update it | | **Not licensed** / **Off until licensed** | Files are on the server but no licence is attached | Buy it, or attach your licence in your account | | **Configure** | The add-on has settings | Open its settings without leaving the page | Use **Filters → Available to install** to see only add-ons that are not on the server yet. ![Settings → Modules: Filters (1), Buy now (2) on an add-on in the store, and Configure (3) on an installed one.](https://media.czappstudio.com/screens/docs/modules-store/light-f75dea0e58-2880.webp) ## Buy an add-on Choose **Buy now**. The add-on's page opens on czappstudio.com in a new tab; complete the purchase there. A purchase started from **Buy now** is attached to this installation's licence automatically. Back in the product, choose **Check for updates**; the card shows **Install**. Free add-ons show **Claim free** instead. The steps are the same, except that the order completes without payment; you need to be signed in to your czappstudio.com account. A free add-on receives updates for as long as the Core licence it is attached to. ## Install or update Choose **Install** (or **Update to …**), then **Install**. Keep the window open while it: 1. downloads the release, checks it against CZ App Studio's signature, and places the files in `Modules/`; 2. switches the add-on on, which runs its database changes and adds its permissions. When it finishes, choose **Configure** if the add-on has settings. Some add-ons need another first: Calls needs Chat, and the Microsoft 365 add-ons need the Microsoft 365 Connector. Install and enable those first. ## If an install fails The dialog shows what to fix on the server, then **Try again**. The previous copy of an add-on is kept until the new one is in place. | Message | Fix | |---|---| | *PHP (running as www-data) cannot write to …/Modules* | Give the PHP user write access, for example `sudo chown -R www-data /path/to/backend/Modules`, then retry. | | *Not enough free disk space* | Free space on the server's storage disk. | | *The PHP zip extension is missing* | Install and enable it (for example `php-zip`) and restart PHP. | | *The download does not match the store's signature* | Nothing was installed. Try again; if it repeats, contact support. | | *The database refused a change* | The add-on stays off. Check the database user's permissions (CREATE, ALTER, INDEX) and retry. | | *This add-on needs a licence* | Buy it, or attach it to this installation's licence in your account. | ## Switch off or remove **Disable module** hides the add-on and its menus; its data is kept and comes back when you switch it on again. An add-on cannot be switched off while another add-on or an attendance policy uses it. ## Free modules and your own modules Modules you build yourself have no store code and are never licensed or updated by CZ App Studio. See [Building your own module](https://czappstudio.com/docs/installation/custom-modules). --- # Backups and updates Back up an installation, update Core from the product or the command line, roll back, and recover access when reCAPTCHA blocks login. ## Backups Open **Settings → Backups** as the super administrator. - **Back up now** saves the database plus the application files: uploads, `.env`, your modules and settings. Dependencies (`vendor`) and compiled assets are left out because a release restores them. - **Back up database only** saves just the database. - **Download** a backup to keep a copy off the server. Backups contain your encryption key (`.env`) and employee data: store them encrypted and restrict access. ![Settings → Backups: Back up now (1) or Back up database only (2).](https://media.czappstudio.com/screens/docs/settings-backups/light-a98e7b6aaa-2880.webp) The database is also backed up every night at 02:15 (server time) and old backups are pruned automatically, as long as the scheduler runs (`* * * * * php artisan schedule:run`). Backups are kept in `storage/app/private/backups`. Database backups use your database's command-line client (`mysqldump` for MySQL). If a backup reports that `mysqldump` cannot be found, install the MySQL client package, or set the folder that contains it in `.env`: ```dotenv DB_MYSQL_DUMP_PATH=/usr/bin ``` Test a restore on a separate copy at least once. Do not send production backups to support. ## Update Core from the product Activated installations show **Open Core HR x.y.z is available** on **Settings → Modules** when an update is released and your updates are current. Read the notes, then choose **Update now → Start update**. Keep the window open while it: 1. checks the server (PHP version and extensions, free space, write access), downloads the release and checks it against CZ App Studio's signature; 2. backs up the database; 3. shows a maintenance page for a few moments while the Core folders are replaced; 4. applies database changes and brings the site back online. Your `.env`, `storage`, `Modules` folder, add-on switches, files you added to `public/` and the `public/storage` link are never replaced. The previous Core files are kept until the update finishes. If the database backup cannot be made, the update stops. Fix the backup, or tick **I have my own recent database backup** to continue without one. An update is not offered, with the reason shown, when: - an enabled add-on does not support the new Core version: update that add-on first; - the installation is a git checkout: update it with git instead (see below); - demo mode is on. ## If an update fails If replacing files fails, the previous version is kept automatically. If the last step fails, the site stays in maintenance mode and the page shows the error with **Put the previous version back**. That restores the previous Core files; database changes that already ran are not reversed, so restore the database backup if the old version misbehaves. ## Update from the command line From the `backend` folder: ```bash php artisan core:update --check # show whether an update is available php artisan core:update # check, download, back up, update php artisan core:update --rollback # put the previous Core files back ``` Use `--without-database-backup` only when you have your own backup, and `--force` to skip the confirmation (for scripts). ## Git checkouts and custom deployments If you deploy from your own git repository, update from your repository instead of the product. Merge the new release into your copy, then on the server: ```bash php artisan down composer install --no-dev --prefer-dist --optimize-autoloader php artisan migrate --force php artisan optimize php artisan queue:restart php artisan up ``` Never run `migrate:fresh`, `migrate:refresh`, `db:wipe` or the demo seeders on a live installation: they delete data. Production installations refuse these commands. ## Recover access when reCAPTCHA blocks login If a signed-in administrator still has access, disable reCAPTCHA under **Settings → Security** and save. Otherwise, a server administrator can run this from `backend/`: ```bash php artisan recaptcha:disable --no-interaction ``` This disables enforcement in the same settings store and keeps the saved keys. It does not reset accounts, passwords or application data. Sign in, correct the Google configuration, and complete a new configuration test before enabling protection again. --- # Customization and integrations Guidance for source changes, provider integrations and building the mobile app. Start with company details, localization, roles, approval workflows and module settings. See the [settings overview](https://czappstudio.com/docs/administration/settings) and [roles and permissions](https://czappstudio.com/docs/administration/roles-and-permissions). For source changes, put your features in your own module so Core updates never overwrite them (see [Building your own module](https://czappstudio.com/docs/installation/custom-modules)); keep it in version control and re-test after updates. Keep business rules in the backend and use the shared API across clients. Rebuild assets after changing frontend source/public configuration. Never put secrets in `VITE_*` variables. Provider integrations require customer accounts, permissions and their own costs. Enable only configured and tested integrations. Distribute examples rather than customer credentials. The mobile source contains one HR application in `apps/hr/`, including chat, calls, email/calendar, feed, presence and contacts when enabled. Preserve its HR application identity, signing and Firebase registration when updating an existing HR installation. The former Communications application is retired; users sign in to HR. Grant **HR app** access explicitly to roles that previously only had Communications access. Existing Communications sessions cannot be reused. Server conversation history remains available, but local drafts and cached files from the old app are not automatically transferred. Save any unsent work before uninstalling that app. Source builds need the application, composition package, core package and selected optional feature packages. Follow `apps/README.md` to export a full, core-only or selected-feature build. Calls requires Chat. Removing a package from a build does not delete its server data. Server modules and user permissions still control access; compiling a feature does not grant it to users. Organizations enable backend modules and configure Microsoft 365, calling and push providers. Keep one backend and user directory. Add-ons are bought and installed from **Settings → Modules** (see [Installing and managing add-ons](https://czappstudio.com/docs/installation/add-ons)). Signing, store distribution and physical-device acceptance remain separate tasks; validate background push and calling with your actual providers. For mobile sign-in legal links, set `OPEN_CORE_HR_TERMS_URL` and `OPEN_CORE_HR_PRIVACY_URL` to your organization-owned HTTPS documents in the app's local Dart configuration. Empty or invalid values omit the links; the app does not show placeholder agreement buttons. --- # Building your own module Add your own features without breaking Core updates or store add-ons. Open Core HR is built from Core plus modules in `backend/Modules/`. Your own features belong in your own module. Core updates replace Core folders but never touch `Modules/`, so a module you build survives every update. Before building something, check [the add-on store](https://czappstudio.com/addons): a ready-made add-on may already cover it (for example Geofence Attendance, Journey Plans or Payroll), and store add-ons receive updates and support. Building your own is always fine. ## Rules that keep updates safe 1. **Do not edit Core files** (`app/`, `config/`, `database/`, `resources/`, `routes/`, `vendor/` …). Core updates replace them and your changes are lost. Extend Core from your module instead: its service provider, routes, migrations, permissions, menu entries and settings sections. 2. **Do not edit store add-ons** in `Modules/`. Their updates replace the folder. Copy behaviour into your own module instead. 3. **Give your module a unique name** with your company prefix, for example `AcmeTimesheets`, never the name of a store add-on. A clashing name would collide if you later install the store add-on. 4. **Leave out `sku`** in your `module.json`. Modules without a store code are yours: they are never licensed, updated or replaced by CZ App Studio. 5. **Keep it in version control** together with a record of the Core version you built it against. ## Create a module From `backend/`: ```bash php artisan module:make AcmeTimesheets ``` Then edit `Modules/AcmeTimesheets/module.json`: ```json { "name": "AcmeTimesheets", "alias": "acmetimesheets", "title": "Timesheets", "description": "Weekly timesheets for project staff.", "version": "1.0.0", "core": "^1.0", "mobile": "^1.0", "category": "People", "icon": "Blocks", "requires": [], "providers": ["Modules\\AcmeTimesheets\\Providers\\AcmeTimesheetsServiceProvider"], "files": [] } ``` - `core` is the range of Core versions it supports. Core refuses to update to a version outside it until you widen the range, so test first, then raise it. - `requires` lists other modules it needs (by name). Switch it on from **Settings → Modules**. Switching on runs its migrations and registers its permissions. ## What a module can contain | Folder | Purpose | |---|---| | `app/Providers` | Service provider: register routes, events, bindings | | `database/migrations` | Its own tables. Never alter Core tables destructively; add your own tables or nullable columns | | `config/permissions.php`, `config/permission-grants.php` | Its permissions and which roles get them by default | | `config/navigation.php` | Menu entries | | `routes/` | Web and API routes | | `resources/js/pages`, `resources/js/settings` | Screens (React) and a settings section that also appears under **Configure** | | `lang/` | Translations | Look at a store add-on such as `Modules/Announcements` for a complete example; copy patterns, not files. ## Screens and Core updates Module screens are compiled together with Core's screens into `public/build`. After you add or change screens, rebuild: ```bash npm ci && npm run build ``` Core updates ship assets compiled for Core and every store add-on, not your module. When an installed module's screens are not in the release, the update rebuilds the assets automatically if Node.js is available on the server, and otherwise tells you to run the command above. Until then, your module's screens do not load. ## Test before you rely on it Run the application's tests and your module's tests after building it and after every Core update: ```bash php artisan test ``` Try changes on a copy of your production data, never on the live installation first. See [Using AI coding agents](https://czappstudio.com/docs/installation/ai-agents) to build modules with an agent safely. --- # Using AI coding agents Set up, customise and extend Open Core HR with Claude Code, Codex, Cursor, GitHub Copilot or any coding agent. Open Core HR is built to work with AI agents. Installation with an agent is free (see [Install with an AI agent](https://czappstudio.com/docs/installation/ai-assisted)). This page covers what the download gives your agent, how to connect it to always-current documentation, and the safety rules it follows. ## What is in your download Open the folder where you extracted the Core download (the guides call it `backend/`) in your agent. It reads these automatically: | File | What it gives the agent | |---|---| | `AGENTS.md` (and `CLAUDE.md`) | The architecture, module system, commands, and the rules that keep updates safe | | `INSTALL-WITH-AI.md` | The step-by-step install and first-run checklist | | `.claude/skills/` | Ready-made skills: **setup**, **create-module**, **customize**, **update-and-backup**, **troubleshoot** | | `.mcp.json` | A connection to the Open Core HR documentation server | Agents other than Claude Code read `AGENTS.md`; point them at the skill files in `.claude/skills/` when you ask for those tasks. Useful first prompts: - "Install Open Core HR on this server using INSTALL-WITH-AI.md." - "Run `php artisan doctor` and fix anything it reports." - "Create a module called AcmeTimesheets for weekly timesheets." - "Change the company branding and add French translations." ## Connect the documentation server (MCP) The Open Core HR MCP server gives your agent the current documentation, add-on catalogue, installation plans and release notes, so it does not rely on what it remembers. It is read-only and needs no account. **Address:** `https://czappstudio.com/mcp` Claude Code (already configured by the `.mcp.json` in your download): ```bash claude mcp add --transport http open-core-hr https://czappstudio.com/mcp ``` Cursor, VS Code and other MCP clients: add a remote (HTTP) MCP server with the address above, for example in `.cursor/mcp.json`: ```json { "mcpServers": { "open-core-hr": { "url": "https://czappstudio.com/mcp" } } } ``` Codex (`~/.codex/config.toml`): ```toml [mcp_servers.open-core-hr] url = "https://czappstudio.com/mcp" ``` Without MCP, agents can read [llms-full.txt](https://czappstudio.com/llms-full.txt), which contains every guide as plain text. Once connected you can also simply ask questions, for example "How do leave balances carry over?" or "Which add-on handles customer visits?". ## Safety rules your agent follows The agent files tell agents to: - **Check the environment first.** When `APP_ENV=production`, the agent will not run commands that delete or reset data (`migrate:fresh`, `migrate:refresh`, `migrate:reset`, `db:wipe`, demo seeders, deleting `storage` or `Modules`, changing `APP_KEY`) unless you clearly confirm you want that on production. Open Core HR itself also refuses the database reset commands in production. - **Back up before risky changes** (see [Backups and updates](https://czappstudio.com/docs/installation/backups-and-updates)) and prefer trying changes on a copy. - **Keep changes update-safe**: build features as your own module, never edit Core or store add-on files (see [Building your own module](https://czappstudio.com/docs/installation/custom-modules)). - **Never put secrets** in code, commits, prompts or support tickets. In Claude Code, a hook in `.claude/settings.json` enforces the production rule even if the agent forgets. ## Ready-made add-ons and services When you ask for a feature that an existing add-on already provides, the agent mentions it once with a link, so you can choose between buying it and building your own; it builds your own if you prefer. If installation keeps failing, it may mention CZ App Studio's [installation plans](https://czappstudio.com/installation), where an engineer does it for you. Prices and plans always come from the website. --- # Troubleshooting and FAQ Fixes for common installation problems such as 500 errors, missing assets and stuck imports. ## 500 error Read `storage/logs` and web/PHP logs privately. Check PHP compatibility, dependencies, database credentials, keys and writable storage/cache. After configuration changes, run `php artisan optimize` and restart services. Keep public debug mode off. Share sanitized errors only. ## Blank page or missing assets Build the matching frontend source and deploy `public/build`. Remove a development `public/hot` file. Check document root, asset URLs and browser errors. ## Homepage works; other pages return 404 Check Nginx `try_files`, Apache rewriting or IIS URL Rewrite. The root must be `backend/public`. ## Login fails or returns 419 Check `APP_URL`, HTTPS, sessions, application key, writable session storage and cookies. Clear stale cookies after correcting the hostname. Check account status and roles if the wrong portal opens. ## Reset emails do not arrive Send a test email from **Settings → Mail**; a failure shows the provider's reason. Then check the sender domain, spam folders, queue workers and failed jobs. The log mailer does not deliver. Confirm reset links use the reachable application hostname. ## Upload/download errors Check storage permissions, disk settings and PHP/server limits. Private files require authorized downloads. Do not expose private storage to work around authorization errors. ## Live updates fail Check module enablement, Reverb, WSS hostname, proxy upgrade headers and firewalls. Rebuild after `VITE_REVERB_*` changes. Shared hosting may lack persistent WebSocket support. ## Imports or exports remain pending Check that a supervised worker consumes the `default` queue, has the current application code and can access private transfer storage. Review failed jobs and sanitized application logs. Restart workers after deployments. The configured queue `retry_after` must exceed the 60-second transfer-job timeout; see [services](https://czappstudio.com/docs/installation/services#section-3). Do not blindly retry a failed import job or re-upload its file. Review transfer history and destination records first, then use a fresh upload and validation when the cause is resolved. The hourly cleanup detects processing jobs interrupted for more than five minutes and marks them failed. If a transfer is denied after it was requested, check the requester's current permissions and whether its source module remains enabled. ## A transfer download has expired Transfer files are available for seven days. Request a new export; if an import had not been confirmed, upload and validate it again. Completed imports do not need to be repeated when their source file expires. History metadata remains for reference. If expired files accumulate on disk, check the scheduler and `data-transfers:cleanup`. ## Installation without SSH? Only with a secure provider equivalent for Composer, Artisan, scheduling and workers, validated on that host. Uploading files does not initialize the database. ## Can Cloudflare host the HR app? No. Cloudflare DNS and proxy services do not provide a PHP runtime or MySQL database. This Laravel app needs a PHP server and database. ## A documented feature is missing from my menu The manual covers optional modules and different roles. Ask the administrator to check enablement/permissions. Documentation does not grant access. --- # Support and licences How to ask for help, what your licence covers, and third-party licences. ## Asking for help Open a ticket from [your account](https://czappstudio.com/account/support). Include the output of `php artisan doctor` (it lists versions and server checks without secrets), sanitized errors, reproduction steps and the guide step that failed. Do not send credentials, employee records or production databases. Installation, customization, infrastructure and mobile publication services are scoped according to purchased terms. This guide does not promise a support period or service entitlement. ## Buying and activating Open Core HR is a commercial self-hosted product supplied with source code. Buy it from [CZ App Studio](https://czappstudio.com), then activate your installation from **Settings → Modules** in the product (see [Licences and activation](https://czappstudio.com/docs/installation/activation)). Your purchases, licences and activations are listed in [your account](https://czappstudio.com/account). Your licence terms are those of your CZ App Studio purchase. Third-party components retain their own licences. ## Credits The product uses Laravel, React, Inertia, Flutter and dependencies in its Composer/npm/pub lockfiles. Retain their supplied notices. The dependency list is not a completed redistribution audit; release acceptance must confirm included assets and rights. --- # Welcome to Open Core HR An introduction to Open Core HR for employees, managers, HR teams and installers. Open Core HR is your company's people and operations app. Employees, managers and HR teams use one module-based workspace. Personal records and requests appear alongside the team and company pages your permissions allow. ## Mobile application Use **Open Core HR** for HR tasks and team communications with one company account. **Home** and **Work** provide HR workflows. **Connect** provides chat, calls, feed and Microsoft 365 mail. Its **More** area includes calendar when mail is enabled, contacts, notifications and profile/presence settings. Availability depends on your company's selected mobile features, backend modules, permissions and provider setup. Attendance-device verification follows your attendance policy. If you previously used the separate Communications app, sign in to HR; ask your administrator to grant HR app access if necessary. Conversation history remains on the same company server. Your organization supplies and configures the app; this guide does not imply public app-store availability. ![The Today tab of the Open Core HR mobile app.](https://media.czappstudio.com/screens/mobile/today/light-9532238cee-1206.webp) ## Choose your starting point - **Employees:** [First login](https://czappstudio.com/docs/getting-started/first-login) and [Personal work](https://czappstudio.com/docs/self-service/overview). - **HR teams and managers:** [The HR & Admin guide](https://czappstudio.com/docs/administration/overview). - **Installers:** the [installation guide](https://czappstudio.com/docs/installation/overview). ## Roles and optional modules This public manual covers documented product features. Your company chooses which modules to enable and permissions to grant. Reading a page does not grant access to its feature. If a screen is missing, ask your HR administrator to check your access and module enablement. Microsoft 365 features require your company's configured tenant and integration. ## Online help This manual is published on the [CZ App Studio](https://czappstudio.com) website and does not require an application login. Use **Documentation** in the application footer to open it. --- # Signing in for the first time Sign in to Open Core HR for the first time and set up your account. Your administrator invites you using your work email address. Open the invitation and set your own password before signing in. Invitations expire; ask your administrator to send a new one if your link no longer works. 1. Follow the link in your invitation email and choose a password. 2. Open your organisation's Open Core HR sign-in page, HR mobile app. 3. Sign in with the invited email address and your new password. If your organisation enables reCAPTCHA on web login, complete the verification checkbox before selecting **Sign In**. Some installations check automatically when you submit. If verification expires or sign-in fails, complete it again before retrying. If verification cannot load, use **Try again**; contact your administrator if it remains unavailable. This verification does not apply to the HR mobile app in this release. Access depends on the roles and apps your administrator assigned. An account can be active while HR is still completing employment onboarding. Completing onboarding does not grant additional roles or app access. If you forget your password, use **Forgot password**. If access is disabled, contact your administrator; resetting a password does not enable a disabled account. See [Changing your password](https://czappstudio.com/docs/getting-started/changing-your-password) after signing in. On the web you can also add a passkey and sign in with your fingerprint, face or screen lock; see [Your profile](https://czappstudio.com/docs/self-service/profile). --- # Changing your password Change your Open Core HR sign-in password from the account menu or your profile. You can change your sign-in password from your profile page at any time. ## Steps 1. Open **Change Password** from the account menu at the bottom of the sidebar. (You can also open **My Profile** and click **Change Password** in the **Security** card.) 2. In the **Change Password** window, enter your **Current Password**. 3. Enter your **New Password**. 4. Enter the same new password again in **Confirm New Password**. 5. Click **Change Password**. ![Change Password window: enter your current password (1) and your new password (2), then choose Change Password (3).](https://media.czappstudio.com/screens/docs/change-password/light-39627116e2-2880.webp) Use the new password the next time you sign in. ## Tips - Your new password must be at least 6 characters long. - If you have a Microsoft 365 account through Open Core HR, your new password is applied there too. ## Troubleshooting - **"Current password is incorrect"** — re-enter your existing password and try again. - **The new password and confirmation don't match** — make sure both boxes contain exactly the same password. --- # Finding your way around Learn the layout of the Open Core HR workspace and how to move between pages. Everyone uses the same sidebar. **My Workspace** is one dropdown for all your personal pages: attendance, leave, expenses, payslips, assets, loans, documents, policies and more. Each enabled module adds its own personal pages automatically. Team and company work, reports and setup stay in their module menus. Breadcrumbs on the left of the top bar show your current location. Use **Search** on the right (Ctrl+K or Cmd+K) to find an available page. Type at least two characters to also find people and, if you can view customers, customers by name or code; results include only the records your permissions allow. Missing pages may require a permission or an enabled module; contact your administrator if you need access. ![The workspace: My Workspace (1) holds your personal pages, Search (2) finds pages and people, and the account menu (3) sits at the bottom of the sidebar.](https://media.czappstudio.com/screens/docs/navigation/light-48231fe698-2880.webp) ## Search and filter lists Use search to find records by the text supported by the current list. Open **Filters** to narrow the results, then choose **Apply filters**. The filter section expands within the page, so you can keep the results in view. Changes in the filter section are drafts until you apply them. **Cancel** discards the draft; **Reset filters** restores the page's defaults in the draft and still requires Apply. Remove an applied filter individually, or use **Clear filters** to restore all defaults. Clearing filters keeps your search text. ![A list with its filters open: search (1), open Filters (2), then choose Apply filters (3).](https://media.czappstudio.com/screens/docs/list-filters/light-33d5f17846-2880.webp) ## Pin frequent pages Hover over a module or page, or focus it with the keyboard, to reveal its star. On touch screens the star appears inside the row. Select it to add the item to **Pinned**, or select it again to remove it. Pins belong to your account and follow you across browsers and devices. A pin is hidden when its module is disabled or your permission is removed; pinning never grants access. ## Account and alerts Your account menu is at the bottom of the sidebar. Open it for **My Profile**, **Change Password**, or **Logout**. **Bank Details** is inside **My Workspace**. **Notifications** in the header contains decisions on requests and other alerts. **Settings** contains company-wide configuration for authorized administrators. Open available communication modules from the sidebar. The **Documentation** link in the footer opens this public manual. Use the top-bar shortcuts to open Chat or Email. On phones, open **Shortcuts** first. **Quick create** opens relevant forms across enabled modules, including employee records, leave and expense requests, tasks, loans, assets, policies, announcements, job postings, warnings, feed updates, and payroll drafts. Only actions allowed for your account appear. Payroll drafts require a configured pay group; Email requires a provisioned mailbox. Open your account menu at the bottom of the sidebar to change **Choose appearance** or **Language**. --- # Using the mobile app Sign in to the Open Core HR mobile app and use its main areas. The HR app has five tabs. Each feature has one place, so you always find it in the same tab. - **Today** shows your workday, your shortcuts and the cards your role needs, such as your next customer visit, your team's attendance or approvals waiting for you. - **Calendar** combines your meetings and events. - **Work** lists everything you can open, grouped into Workday, Pay & expenses, Your records and Your team. Use the search box to find a feature by name. - **Inbox** holds approvals you can decide (**To do**), notifications (**Updates**) and the status of your own requests (**My requests**). The tab shows a count while something is waiting. - **Me** holds your profile, appearance, language and sign-out. ![Today shows your workday, shortcuts and the cards your role needs.](https://media.czappstudio.com/screens/mobile/today/light-9532238cee-1206.webp) When chat, calls, Outlook Email or the company feed are enabled for you, **Connect** on Today opens them together, with **People** for finding colleagues. ## On a tablet The app runs on Android tablets and iPads with a layout made for the wider screen. The five tabs sit in a bar down the side, and lists stay in view while you work: choose a request, a chat or a setting and it opens beside the list. Choose another to replace it, or **Close** to put it away. Today and Work use two columns, and Calendar shows the whole month next to the day you picked. Turn the tablet either way and the app keeps your place. ## Shortcuts Your administrator chooses the shortcuts you start with for your role. To change them, choose **Edit** beside **Shortcuts** on Today, pick up to four in the order you want, and save. The same choice appears as favourites in Work and on the web dashboard. **Use my profile's** returns to your administrator's choice. ![Work lists every feature you can open, grouped by area.](https://media.czappstudio.com/screens/mobile/work/light-e1572e5211-1206.webp) Shortcuts only open features you already have access to. If you lose access to a feature, its shortcut disappears. ## Sync status The cloud button at the top of Today shows whether everything you recorded on this phone has reached the server: - **Green**: everything is synced. - **Amber with a number**: changes are saved on the phone and waiting to send, for example attendance or field visits recorded without signal. - **Red**: the server refused a change. Open the sync sheet, then open the item to correct it. - **Grey**: the phone is offline. Saved changes send automatically when the connection returns. Choose **Try now** in the sync sheet to send them immediately. A waiting change is not confirmed until the server accepts it, so keep the app installed and signed in until the button turns green. ## Appearance In **Me**, choose **System** to follow your phone's light or dark setting, or choose **Light** or **Dark** to keep one appearance. --- # Personal work An overview of your personal workspace and the dashboard you see after signing in. Open **My Workspace** in the sidebar for all your personal pages, including **My Attendance**, **My Leaves**, **My Expenses**, **Payslips** and **Bank Details**. Available pages depend on your permissions and the modules your company uses. Your account menu at the bottom of the sidebar contains **My Profile**, **Change Password** and **Logout**. Read [Finding your way around](https://czappstudio.com/docs/getting-started/finding-your-way-around) for navigation, global search and personal pins. Requests follow your company's approval process. Opening a personal page never grants access to another employee's records. Contact your administrator if a page you need is missing. ## Your dashboard Open **Dashboard** and select **My Work** to review your attendance, leave balances and recent requests. Open a request to see its details. The attendance action opens today's attendance screen, where your normal check-in rules still apply. Working hours include recorded work and elapsed time in open sessions. Leave balances use the current leave year. Holidays and announcements follow their location and access rules. Optional modules may add tasks or requested documents; follow a required document notice to provide what HR has requested. ### Shortcuts Shortcuts under the page title open the tasks your role uses most. Your administrator sets the starting list. Choose **Edit shortcuts** to pick up to six in your own order; the mobile app shows the first four. **Use my profile's** returns to the starting list. ![Your dashboard: My Work (1), Edit shortcuts (2) and Edit dashboard (3).](https://media.czappstudio.com/screens/docs/my-dashboard/light-33e1cb3909-2880.webp) ### Personalize your dashboard Choose **Edit dashboard** to show or hide optional widgets and move them into your preferred order. Save to keep your choices for your account, including when you use another browser. You can also choose the view that opens by default. **Reset this view** restores the current view's widgets and order. Required notices remain visible. Access to a new view or widget must be granted by an administrator; personalization cannot grant access. Choose **Refresh** to update the current information. Retry a failed widget instead of interpreting the failure as an empty balance or request list. If you manage people or HR work, see [Using team and HR dashboards](https://czappstudio.com/docs/administration/overview#section-1) for scope and attendance definitions. --- # Your profile View and update your profile, contact details, private details, picture, letters, bank details and status. Your profile shows your work and personal details and lets you keep some of them up to date. Open it from the **My Profile** link in your account menu at the bottom of the sidebar. 1. **My Profile** — Click your name and photo at the bottom of the sidebar, then choose **My Profile**. ## Updating your information Your department, designation, shift, and reporting manager come from your HR record; contact HR if they need correction. You can [change your profile picture](https://czappstudio.com/docs/self-service/profile#section-5), [update contact information](https://czappstudio.com/docs/self-service/profile#section-3), [update personal and emergency contact information](https://czappstudio.com/docs/self-service/profile#section-4), or [change your password](https://czappstudio.com/docs/getting-started/changing-your-password). ## Tips - If a detail under **About** is wrong (such as your department or who you report to), ask your HR team to correct it — you cannot edit those fields yourself. - Anything you can change has its own **Save** button. Changes aren't kept until you click it. ## Updating your contact information Use **My Profile** to keep the contact details you can edit current. Your work phone is a colleague directory contact. Use the separate personal phone and personal email fields for private contact details. Check your information before saving, including any country code your organisation needs. Optional fields can be cleared if they no longer apply. Ask HR to correct your name or sign-in email when those fields are not editable. For emergency contact and other private information, see [Updating your private details](https://czappstudio.com/docs/self-service/profile#section-4). ## Updating your private details Keep your personal contact information and emergency contact current in **My Profile**. Your private email and phone are separate from the work contacts colleagues use to reach you. Update the optional personal fields your organisation needs: date of birth, gender, address, personal email, and personal phone. For an emergency contact, provide the person's name, phone number, and relationship to you. Check the number with them before saving. Your private profile details are available to you and authorised HR users. They are not included in colleague directory or Connect contacts. If a detail is managed by HR and you cannot edit it, ask HR to correct it. ## Changing your profile picture You can upload or replace your profile photo from your profile page. It's the round photo at the top of the page. ### Steps 1. Open **My Profile** from the account menu at the bottom of the sidebar. 2. Move your pointer over the photo at the top of the page — a camera icon appears. 3. Click the photo. 4. Choose an image file from your device. In the mobile app, open **Me**, tap your photo (or your initials if you have no photo yet) and choose a photo from your phone. Until you add one, your initials are shown instead. ![My Profile: edit your contact details and choose Save Contact Info (1).](https://media.czappstudio.com/screens/docs/my-profile/light-5a76d6ab02-2880.webp) ### Tips - Use a JPG or PNG image, up to 2 MB. - Uploading a new photo replaces the old one. ### Troubleshooting - **"Failed to update profile picture"** — check that the file is a JPG or PNG and under 2 MB, then try again. ## Reading your employment letters Open **My Letters** to read and download the employment letters available to you, including offers, appointments, confirmations, employment changes, and separation letters. Existing letters remain available when their originating module is disabled. Check your name, role, effective date, and any pay terms. Ask HR to correct an inaccurate record before relying on a downloaded copy. A previously downloaded file does not update when HR changes the record. For warnings and acknowledgments, use [My Warnings](https://czappstudio.com/docs/modules/disciplinary-actions#section-30). ## Your bank details This page is where you record the bank account used for your salary. Open it from **Bank Details**. > **Availability:** This area may not be turned on for your company yet. If you don't see it in your menu, it isn't enabled — check with your HR team. ### Steps 1. Go to **Bank Details**. 2. Select **Add Bank Details** (or **Edit** if you've added an account before). 3. Fill in **Bank Name**, **Branch** and **Account Number**, then whichever identifiers your bank uses: **Bank Code**, **IBAN** or **SWIFT / BIC**. Leave **Account Holder Name** empty to use your own name. 4. Select **Save Bank Details**. To leave without saving, select **Cancel**. ### Tips - For your security, your account number is shown partly hidden once saved — only the last few digits stay visible. - Updating these details replaces what was there before. Make sure the new details are correct so your salary isn't delayed. ## Signing in with a passkey A passkey lets you sign in to the web application with your fingerprint, face or screen lock instead of typing your password. It is saved on your device or in your password manager. The mobile app signs in with your email address and password. ### Add a passkey 1. Open **My Profile** and find the **Security** card. 2. Select **Add a passkey** and enter a **Name** that helps you recognise the device, such as "Work laptop". 3. Enter your **Current password**, select **Continue** and confirm with your device's prompt. ### Sign in or remove a passkey - On the sign-in page, select **Sign in with a passkey**, choose your account in the prompt and confirm. Your password keeps working on devices that have no passkey. - To remove one, open its menu in the **Security** card and select **Remove**. Do this when you stop using a device or lose it. ### Troubleshooting - **There is no "Sign in with a passkey" button** — your browser cannot use passkeys. Update it, or sign in with your password. - **"We couldn't sign you in with that passkey"** — the passkey was removed from your profile or belongs to another account. Sign in with your password and add a new one. ## Your status Colleagues see a small coloured dot next to your name in conversations, calls and your profile, so they know whether you can be reached right now. Statuses appear when Chat, Calls, Feed or Outlook Email is turned on for your company. | Status | When it shows | | --- | --- | | **Available** | You have the app or the website open. | | **Busy** / **Do not disturb** | You chose it yourself. | | **On a call** | You are on a voice or video call in the app. | | **In a meeting** | Your calendar has a meeting right now that you have not declined. | | **On a break** | You are checked in and have started a break. | | **On leave** | You have approved leave right now. A half day or a few hours off shows only while it lasts. | | **Out of office** | Today is a public holiday or one of your days off, and you are not using the app. | | **Offline** | You closed the app, signed out or lost your connection for a few minutes. | Most of this happens on its own. Leave, meetings, breaks, holidays and days off are shown automatically, so you do not need to change anything when you start or finish work, go on leave or join a meeting. ### Set Busy or Do not disturb 1. In the mobile app, open **Me** and tap the status row under your name. On the website, open the account menu at the bottom of the sidebar and select your status at the top of the menu. 2. Choose **Available**, **Busy** or **Do not disturb**. 3. Optionally type a short message, such as "Back at 3". Colleagues see it next to your status. 4. Under **Clear after**, choose how long it should last, then save. When the time is up, your status and message clear by themselves. Choose **Available** to clear a status sooner, or **Clear message** in the mobile app to remove only the message. A call always shows as **On a call**; your own choice returns when the call ends. If you leave the app while Busy, colleagues see **Offline** until you come back. A message stays with whatever status is showing, including On leave, so you can say when you are back. --- # Your Inbox Read and manage the notifications that Open Core HR sends you. The Inbox brings together everything that needs your attention. Open it from the **Inbox** icon in the top bar. The number on the icon counts approvals waiting for you and updates you haven't read. It changes as soon as something new arrives, and a short message appears in the corner of the screen. Choose **Open** on that message to go straight to it. The Inbox has up to three tabs: - **To do**: requests waiting for your approval, such as leave, expenses and loans. You see this tab if you approve requests. See [Approval inbox](https://czappstudio.com/docs/administration/approvals). - **Updates**: messages Open Core HR has sent you, such as decisions on your requests, announcements and finished exports. - **My requests**: your recent leave requests and expense claims with their current status. Use **All leave** or **All expenses** to see everything. ## Managing updates Use **Filters** to show only unread updates or one category. **Mark all as read** marks them read; **Clear all** removes them. Use **Load more** to see older updates. 1. Click an update to mark it as read. If it relates to something you can open, such as a leave request, you go straight to that page. 2. To remove one update, choose **Clear notification** from its actions menu. 3. To mark everything as read without opening it, click **Mark all as read**. 4. To empty the list, click **Clear all**. ![Inbox Updates (1): Mark all as read (2) or Clear all (3).](https://media.czappstudio.com/screens/docs/inbox-updates/light-df3c994ced-2880.webp) ## Tips - You can link to a tab directly, for example `/inbox?tab=updates`. - Clearing an update only removes it from your list. It doesn't undo what it was about. --- # Your attendance Check in and out, review today's status and look back at your sessions and monthly summary. The **My Attendance** screen shows your attendance history along with a snapshot of how the current month is going. Open it from **My Workspace > My Attendance**. ## Checking your records Review your first check-in, last check-out, and total hours for each day. An **Active** session means you have not checked out. If multiple check-ins are enabled, review the sessions to confirm each work period. ## Steps ### Filter the list 1. Use the **From Date** and **To Date** pickers above the table to limit records to a date range. 2. Type in the **Search attendance...** box to search within the table. 3. Click **Clear** to remove the date filters. ![My Attendance: Filters (1), search (2) and a day's actions menu (3) to view its details.](https://media.czappstudio.com/screens/docs/my-attendance/light-823bbb3c90-2880.webp) ### View a day's details 1. Click the view (eye) button in the **Actions** column for the day you want. 2. A panel titled **Attendance Details** slides in from the right showing the status, check-in and check-out times, working hours, shift, and any late, early-leave, or overtime amounts. 3. If that day had more than one session, each one is listed under **Sessions**. Break times, if any, appear under **Breaks**. ## Tips - Use the **Today** button in the top-right corner to jump to today's attendance screen, where you can check in and out. ## Today's attendance status The **Today's Attendance** screen shows where you stand for the day — whether you're checked in, your check-in and check-out times, working hours so far, and a breakdown of your sessions. Open it from **My Workspace > Today**, or by clicking the **Today** button on the My Attendance screen. 1. **Attendance** — Open the **Attendance** group in the menu. 2. **Today** — Then choose **Today**. ### Checking today’s attendance ![Today's Attendance with today's sessions and timeline.](https://media.czappstudio.com/screens/docs/attendance-today/light-f4cd89bc5e-2880.webp) Check whether you are **Not Checked In**, **Checked In**, or **Completed** before taking action. Review the recorded shift and working hours. Use **Check-in/out Sessions** and **Activity Timeline** to confirm today’s check-in and check-out events. ### Tips - This screen refreshes itself after you check in or check out, so the times and totals update right away. - To check in or out from here, see [Checking in and out](https://czappstudio.com/docs/self-service/attendance#section-9). ## Checking in and out ![Checking in from the mobile app.](https://media.czappstudio.com/screens/mobile/check-in/light-80a71963e6-1206.webp) Office, field, remote and hybrid employees use the same attendance system. Your assigned shift and attendance policy determine whether you can record attendance from the web, the mobile app, or both. Open **Today** in your web workspace or the mobile app. Choose **Check in** to start work and **Check out** when you finish. In the mobile app a sheet lists what will be recorded, such as your shift and, when your policy requires it, your location; confirm there. Start and end breaks during an open session when those actions are available. Location access is requested only when your policy requires it. An open policy does not require location. If a policy uses a location boundary, capture a fresh, accurate position inside the permitted area. Your administrator can set different requirements for check-in and check-out. ### Multiple sessions and overnight work A shift that allows multiple check-ins lets you start another session after checking out. Sessions cannot overlap. Overnight work remains attached to the date the shift starts, including a checkout after midnight. An open session keeps the shift and policy that applied when it started. A later assignment or policy edit applies to future sessions. Attendance and customer visits are separate: recording a visit does not check you into work, and ending a visit does not check you out. ### Interrupted requests If the response is lost, the app keeps the request and sends it again by itself when the connection returns, or straight away when you tap **Send now** on the workday card. It repeats the same action and never turns a check-in into a check-out. The sync icon on Today also shows the saved request; see [Sync status](https://czappstudio.com/docs/getting-started/mobile-app#section-2). Attendance requires a server connection; a saved request is not confirmed attendance until the server accepts it. If attendance is unavailable, refresh first. Contact your manager if your shift or policy is missing, the policy excludes your device, or your employee account cannot record attendance. Approved leave and a completed single-session work date can also prevent another check-in. ## Your attendance sessions for a day A "session" is one check-in paired with the matching check-out. On a day where you check in and out more than once, each pair is a separate session. Open Core HR shows your sessions in two places. ### On the Today's Attendance screen 1. Go to **My Workspace > Today**. 2. The **Check-in/out Sessions** table lists every session for today with its check-in time, check-out time (or an **Active** badge if it's still open), and duration. 3. A summary row shows **Total Sessions**, **Total Duration**, and **Active Sessions**. 4. The **Activity Timeline** below shows the same check-in and check-out events in time order. ### For a past day 1. Go to **My Workspace > My Attendance**. 2. Find the day you want and click the view (eye) button in the **Actions** column. 3. The **Attendance Details** panel opens. If that day had any sessions, they appear under **Sessions**, each numbered with its check-in time, check-out time, and duration. An **Active** badge marks a session that was still open. 4. Any breaks for that day appear under **Breaks**, with start and end times and total break minutes. Starting another session after check-out requires **Allow multiple check-ins per day** on your assigned shift. Adding or changing a security role does not change this setting. If attendance is unavailable, ask your administrator to check your shift and attendance permission. ## Your monthly attendance summary Open Core HR keeps a running summary of your attendance for the current month. You'll see it at the top of the **My Attendance** screen. ### Where to find it 1. Go to **My Workspace > My Attendance**. 2. The cards across the top of the page summarise the current month: - **Present Days** — the number of days you have an attendance record. - **Total Hours** — total working hours recorded this month. - **Avg Hours/Day** — average working hours per present day. - **Late Arrivals** — the number of days you arrived late. - **Total Distance** — total distance recorded for the month. 3. The table below shows the individual days that make up these totals. Use the **From Date** and **To Date** filters to focus on a particular stretch of the month. ### Tips - The summary cards always reflect the current calendar month. To review an earlier period, use the date filters on the table below. ## Fixing your attendance If you forgot to check in or out, or a time was recorded wrongly, ask for a correction. Your manager reviews it, and your attendance changes only once it is approved. On the web, open **Attendance → Corrections** and select **Fix attendance**. In the mobile app, open **Attendance**, tap the correction icon at the top, then **Fix attendance**. ### Steps 1. Choose the day. You can only go back as many days as your organisation allows (30 by default). 2. Under **What needs fixing**, choose what happened: **I forgot to check in**, a session that says **never checked out**, a finished session with a wrong time, or **Add a missing session** on shifts that allow more than one check-in a day. 3. Enter the correct times and the reason, then send the request. ### What to expect - New times must include any break you recorded, must not overlap another session and cannot be in the future. - One request can wait for each session or day at a time. To change a waiting request, withdraw it and send a new one. - Your organisation may limit how many requests you make each month. - If a payroll covering that day has already been approved, the day can no longer be changed. Ask HR. - The request shows **Waiting for approval**, **Approved**, **Rejected** or **Withdrawn**. A rejected request shows your manager's note. --- # Leave Apply for leave, follow your requests, cancel them and check your leave balance. ## Applying for leave Use the **Apply for Leave** form to request time off. Open it from **My Workspace > Apply Leave**, or from the **Apply Leave** button on the My Leaves or Leave Balance screens. ### Steps 1. Go to **My Workspace > Apply Leave**. 2. Pick a **Leave Type**. Each type shows how much you have available next to its name. 3. Choose the **From Date** and **To Date**. 4. The form shows how many **working days** that range works out to (it skips weekends and holidays). If you have less balance than the days requested, it shows a **Breakdown** with how many are **Paid** and how many would be **LOP** (loss of pay). 5. If you only need part of a day, turn on **Half Day Leave** and choose **First Half** or **Second Half**. A half day must be for a single date. 6. Enter the **Reason** for your leave. 7. If the leave type needs proof, a **Supporting Document** field appears. Attach a PDF, JPG, or PNG (up to 5 MB). 8. If you'll be **Travelling Abroad**, turn that on and enter the location. 9. Optionally fill in an **Emergency Contact** name and **Emergency Phone** number. 10. Click **Submit Leave Request**. You'll be taken back to the My Leaves list, where the request appears with a **Pending** status. ![Apply for Leave: choose the leave type (1) and dates (2), then Submit Leave Request (3).](https://media.czappstudio.com/screens/docs/apply-leave/light-d84e929b8e-2880.webp) ### Checking the day count Review the day count and Paid/LOP breakdown after setting your dates and any half-day option. ### Troubleshooting - **"Half-day leave must be for a single date."** — Set the From Date and To Date to the same day. - **"You already have a leave request for the selected dates."** — You already have a pending or approved request that overlaps those dates. Cancel or adjust it first. - **Supporting document errors** — Only PDF, JPG, and PNG files are allowed, and the file must be under 5 MB. For sick leave, a document may be required only for the second and later requests in the same month. - Other messages about advance notice, monthly or yearly limits, or balance come from your organisation's leave rules. Adjust your dates or leave type and try again, or check with HR. ## Your leave requests The **My Leave Requests** screen lists every leave request you've made, with its current status. Open it from **My Workspace > My Leaves**. ### Tracking a decision Check each request’s status and any Paid/LOP breakdown. Open a request to review the decision and supporting details. ### Steps #### Filter the list 1. Use the **Status** and **Leave Type** dropdowns above the table. 2. Use the **From Date** and **To Date** pickers to limit by date. 3. Type in the **Search leave requests...** box to search the table. 4. Click **Clear** to reset the filters. ![My Leave Requests: Filters (1), a request's actions (2) and Apply Leave (3).](https://media.czappstudio.com/screens/docs/my-leaves/light-ad408dd65d-2880.webp) #### Open, cancel, or apply - Click the view (eye) button in the **Actions** column to see a request's full details. See [Viewing a leave request](https://czappstudio.com/docs/self-service/leave#section-8). - For a **Pending** request, an extra cancel button appears in the **Actions** column. See [Cancelling a leave request](https://czappstudio.com/docs/self-service/leave#section-11). - Use the **Apply Leave** button (top right) to make a new request, or **View Balance** to open your leave balance. ## Viewing a leave request You can open any leave request to see its full details and current status. ### Steps 1. Go to **My Workspace > My Leaves**. 2. Find the request in the table and click the view (eye) button in the **Actions** column. 3. The **Leave Request Details** window opens. ### Checking your request Review the dates, day count, status, and Paid/LOP breakdown. Check who approved the request and download supporting proof when needed. If it is still **Pending**, use **Cancel Leave Request** to [cancel it](https://czappstudio.com/docs/self-service/leave#section-11). ## Cancelling a leave request You can cancel a leave request you no longer need. You can cancel a **Pending** request at any time, and an **Approved** request only if it hasn't started yet. ### Steps 1. Go to **My Workspace > My Leaves**. 2. For a **Pending** request, click the cancel button in the **Actions** column. (You can also open the request with the view button and use the **Cancel Leave Request** button at the bottom of the details window.) 3. In the **Cancel Leave Request** confirmation, click **Yes, Cancel Leave** to confirm, or **No, Keep It** to back out. 4. The request's status changes to **Cancelled**. ### After you finish - If the leave was already approved, your leave balance is returned to you when it's cancelled. ### Troubleshooting - **"Cannot cancel approved leave that has already started or passed."** — Approved leave can only be cancelled before its start date. Talk to HR if you need to change leave that has already begun. - If the cancel button isn't shown for a request, it isn't in a state that you can cancel yourself. ## Your leave balance The **Leave Balance** screen shows how much leave you have for the current year, broken down by leave type. Open it from **My Workspace > Leave Balance**, or from the **View Balance** button on the My Leaves screen. 1. **Leave** — Open the **Leave** group in the menu. 2. **Leave Balance** — Then choose **Leave Balance**. ### Understanding your balance Review **Entitled**, **Carried Forward**, **Additional**, **Used**, and **Available** days for each leave type. **LOP** means loss of pay. Check available compensatory offs and their expiry dates before planning leave. ### Tips - Use the **Apply Leave** button at the top right to start a new request. ## Balance for a leave type Every leave type's balance is shown on the **Leave Balance** screen — there's no separate page for a single type. Open the screen from **My Workspace > Leave Balance**. ### Where to find it 1. Go to **My Workspace > Leave Balance**. 2. Each leave type has its own card showing: - A bar showing **Used** out of the type's total. - **Entitled**, **Carried Forward**, **Additional**, and **Available**. - An **LOP** note if loss-of-pay days were taken against that type. 3. The **Detailed Breakdown** table lower on the page lists the same numbers for every type in one place, including the **Total** for each. ![Leave Balance: a card per leave type and the detailed breakdown.](https://media.czappstudio.com/screens/docs/my-leave-balance/light-ac9fe3b66e-2880.webp) When you go to apply for leave, the **Apply for Leave** form also shows the available balance next to each leave type and, in its sidebar, a per-type balance with a usage bar. --- # Compensatory offs Request, edit and track compensatory offs earned for extra work. The **My Compensatory Offs** screen lists the comp-offs you've earned for extra hours worked, along with their status. Open it from **My Workspace > Compensatory Off**. ## Checking available days Check the approval status, available days, and expiry date before using a comp-off. A used or expired comp-off is no longer available. ## Steps ### Filter the list 1. Use the **Status** dropdown above the table (**All Statuses**, **Pending**, **Approved**, **Rejected**). 2. Use the **From Date** and **To Date** pickers to limit by worked date. 3. Type in the **Search compensatory offs...** box to search the table. 4. Click **Clear** to reset the filters. ### Open or edit a comp-off - Click the view (eye) button in the **Actions** column to see a comp-off's details. - For a **Pending** comp-off, an edit (pencil) button also appears. See [Editing a compensatory-off request](https://czappstudio.com/docs/self-service/compensatory-offs#section-13). ### Request a new comp-off Use the **Request Comp Off** button at the top right. See [Requesting a compensatory off](https://czappstudio.com/docs/self-service/compensatory-offs#section-10). ## Your compensatory-off balance Your available compensatory offs (comp-offs you've earned that are approved and not yet used or expired) show up in a couple of places in the web application. ### On the Leave Balance screen 1. Go to **My Workspace > Leave Balance**. 2. If you have any available comp-offs, an **Available Compensatory Offs** section appears near the bottom, with a badge showing your total comp-off days available and a table listing each one's **Worked Date**, **Days**, and **Expiry Date**. ### On the My Compensatory Offs screen 1. Go to **My Workspace > Compensatory Off**. 2. The cards at the top include an **Available** count, alongside **Total Earned**, **Used**, **Expired**, and **Pending**. ### When applying for leave If your organisation has a compensatory-off leave type, picking it on the **Apply for Leave** form shows how many comp-off days you have available, and the request draws from your oldest comp-offs first. ## Requesting a compensatory off If you worked extra hours, you can request a compensatory off so the time can be taken later. Open the **My Compensatory Offs** screen from **My Workspace > Compensatory Off**. ### Steps 1. On the **My Compensatory Offs** screen, click **Request Comp Off**. 2. In the **Request Compensatory Off** panel that slides in, fill in: - **Worked Date** — the date you put in the extra hours (must be today or earlier). - **Hours Worked** — the number of hours. - **Comp Off Days** — this fills in automatically based on the hours you entered (every 4 hours counts as half a day). You can't edit it directly. - **Reason** — why you're requesting the comp-off. 3. Click **Submit Request**. 4. Confirm in the **Submit Compensatory Off Request?** dialog by clicking **Yes, Submit**. 5. A confirmation appears and the new request shows in the list with a **Pending** status, waiting for approval. ![Request Compensatory Off: pick the worked date (1), enter hours worked (2) and Submit Request (3).](https://media.czappstudio.com/screens/docs/comp-off-request/light-b757422a02-2880.webp) ### Troubleshooting - **"A compensatory off request already exists for this date."** — You already have a pending or approved comp-off for that worked date. Edit the existing one instead. - If the **Submit Request** button does nothing, check that all four fields are filled in. ## Editing a compensatory-off request You can change a compensatory-off request while it's still **Pending**. Once it's approved or rejected, it can't be edited. ### Steps 1. Go to **My Workspace > Compensatory Off**. 2. Find the **Pending** request and click the edit (pencil) button in the **Actions** column. (You can also open it with the view button and use the **Edit** button in the details window.) 3. In the **Edit Compensatory Off** panel, update the **Worked Date**, **Hours Worked**, or **Reason**. The **Comp Off Days** value recalculates automatically from the hours. 4. Click **Update Request**. 5. A confirmation appears and the list refreshes with your changes. ### Troubleshooting - If you don't see an edit button for a request, it's no longer pending and can't be changed. - If **Update Request** does nothing, check that all four fields are filled in. --- # Your expenses Create, submit, track and cancel expense and travel claims. Open **My Expenses** to see your drafts and submitted claims. This feature is included in core HR and requires expense permissions. Use **New Expense** to create a claim. A claim can contain several receipts, categories, and expense dates. ## Find a claim Search the list, select a status, or filter by expense dates. Date filters match individual items; amounts shown are totals for the complete claim. - **Draft** — saved and editable; not sent for approval. - **Submitted** — awaiting one or more approval decisions; editing is locked. - **Approved** — the claim has completed approval. - **Rejected** — review the comments and copy it into a new draft if needed. - **Cancelled** — the draft was cancelled or the submitted claim was withdrawn. An approved claim shows **Reimbursed** once payment has been recorded. Approval alone does not mean payment has been made. Open a claim to view its items, receipts, approval history, and reimbursement details. See [Viewing an expense](https://czappstudio.com/docs/self-service/expenses#section-7). ## Creating and submitting an expense Use **My Expenses → New Expense** to request reimbursement. This feature is included in core HR and requires expense permissions. ### Create a claim 1. Optionally enter a title and notes for the claim. 2. For each expense, select a category and enter its date and amount. 3. Optionally add an item description. 4. Attach receipts if required by the category, or optionally add them as evidence. An item can have up to five receipts. 5. Choose **Add another expense** for additional items. Each item can have a different date and category. 6. Review the total. 7. Choose **Save Draft** to continue later, or **Submit** to send the claim for approval. ![New Expense: choose a category (1), attach receipts (2) and Add another expense (3) for more items.](https://media.czappstudio.com/screens/docs/new-expense/light-11c09cf772-2880.webp) Expense dates must be today or earlier and amounts must be positive. Category limits, when configured, apply per item. The form uses your organization's currency. Your organization may also set a maximum expense age: when it does, the form shows the limit and an item dated earlier than that cannot be submitted. The claim is still saved as a draft, so you can remove or correct the item. Drafts can be edited. Submitted claims are locked while they are reviewed. See [Cancelling or withdrawing a claim](https://czappstudio.com/docs/self-service/expenses#section-8) if a submitted claim needs correction. If your connection drops while you save or submit, try again from the same screen. A repeated request is recognized, so it does not create a second claim or submit the claim twice. ### Correct a returned claim An approver can return a claim for correction instead of rejecting it. The claim shows **Returned for correction** with the approver's reason. 1. Open the claim and choose **Correct claim**. 2. Make the requested changes. You can edit items and add or remove receipts. 3. Choose **Submit** on the form, or **Resubmit claim** from the claim. The resubmitted claim goes through the approval workflow again from the first step. The approval history keeps the earlier review, numbered by review round. You can also withdraw a returned claim instead of resubmitting it. If a claim is rejected, open it and choose **Copy to Draft**. Correct the new draft and submit it. The original rejected claim and its reviewer notes remain available. ### Receipts Attach JPG, PNG or PDF files of up to 10 MB each, with up to five receipts per item. Receipts are stored privately and can be read only by people authorized to view the claim. Receipts can be added or removed while a claim is a draft or has been returned for correction; existing receipts stay attached unless you remove them. A category that requires receipts needs at least one on each of its items when you submit. With the [Receipt scanning](https://czappstudio.com/docs/ai/receipt-scanning) add-on, attaching a photo or scan of a receipt fills in the date, amount, category and description for you to check, on the web and in the mobile app. Only empty fields are filled, and you still save or submit the claim yourself. ## Claiming travel expenses Claim travel costs using **My Expenses → New Expense**, just like any other expense. This feature is included in core HR and requires expense permissions. 1. Select the appropriate category, such as Travel, Meals, or Accommodation. 2. Enter the date, amount, and a description of the cost. 3. Attach the receipt, following the category's receipt requirement. 4. Add other costs from the trip as separate items. Different dates can be included in the same claim. 5. Save a draft or submit the claim for approval. For mileage reimbursement, enter the amount agreed under your organization's arrangements and describe the journey and calculation in the item description. Open Core HR does not automatically calculate mileage or per diem allowances in this version. All travel claims appear in the same expense list. You do not need to classify a claim as local or outstation. ## Viewing an expense Open a claim from **My Expenses**. This feature is included in core HR and requires expense permissions. The detail shows the title, notes, total, status, and receipt items. Each item includes a date, category, amount, description, and links to its receipts. The approval history shows reviewer decisions and notes for each review round. Approved claims also show whether reimbursement has been recorded, the payment method and reference, and any reimbursement that finance reversed. Available actions depend on the claim's state: - **Draft:** edit, submit, or cancel. - **Submitted:** withdraw before a final approval decision. - **Returned for correction:** read the approver's reason, correct the claim and resubmit it, or withdraw it. See [Correct a returned claim](https://czappstudio.com/docs/self-service/expenses#section-4). - **Rejected:** copy into a new draft to correct and resubmit. - **Approved or cancelled:** view the retained record. You cannot change a submitted or finalized claim. A copied claim is a new draft with its own future approval history. ## Cancelling or withdrawing an expense You can cancel your draft, withdraw your submitted claim before a final approval decision, or withdraw a claim returned for correction. This feature is included in core HR and requires expense permissions. 1. Open the claim in **My Expenses**. 2. Choose **Cancel Draft** or **Withdraw**, depending on its state. 3. Confirm the action. The claim becomes **Cancelled** and remains in your history. Withdrawing a submitted claim also cancels its active approval request, so it cannot be approved afterward. Approved, rejected, and already-cancelled claims cannot be cancelled. If approval completes while you are viewing a claim, reload it to see its current state. --- # Holidays See the holidays that apply to you. The holidays page shows the holiday list for the current year at your location. Open **Holidays** in the module menu. 1. **Holidays** — Open **Holidays** from the menu. ## Planning around holidays Review the holiday dates for the selected year and your location before planning leave. ![Holidays for your location, with the Upcoming count (1).](https://media.czappstudio.com/screens/docs/holiday-calendar/light-99e8d8bf54-2880.webp) ## Tips - The list is for your location, so colleagues at other locations may see a different set. - Use the **Upcoming** tile to see at a glance how many days off are still ahead this year. --- # Your calendar Use the Core calendar to view, create, edit and respond to events. Open **Calendar** to see personal events, invitations and schedules shared by HR modules. Calendar is included in Core and works without Microsoft 365 or Outlook Email. Choose Month, Week or Agenda on the web, then select a date to review its events. On mobile, use the calendar format control for month, two-week or week views, with the selected day’s agenda below. Open an event for its details, participant responses and available actions. Private personal events are visible to their organizer and invited employees. Approved leave, holidays, interviews and task deadlines follow the permissions of their source records. Use **Open source record** to change a module event. Cancelling an interview, completing a task or withdrawing approved leave updates its calendar entry. Calendar does not replace those modules' workflows or notifications. Outlook appointments appear only when your organization enables [Outlook Calendar Sync](https://czappstudio.com/docs/microsoft-365/outlook-calendar-sync) and you opt in. Imported appointments are private and edited in Outlook. ## Creating an event 1. Open **Calendar** and choose **New Event**. 2. Enter a subject, start and end, and an optional location or description. For an all-day event, select the first and last included dates. 3. Add attendees. Employees with matching HR email addresses can see and respond in Core. External email addresses receive invitations only when the organizer publishes the event through Outlook Calendar Sync. 4. Choose recurrence and a reminder if needed, then save. ![New Event: enter a subject (1), add attendees (2) and choose Create Event (3).](https://media.czappstudio.com/screens/docs/calendar-event/light-68f4758285-2880.webp) Timed events are stored as instants and displayed in your device timezone. Recurring events preserve the event's timezone across daylight-saving changes. The mobile app uses the organization's timezone for the recurrence rule. All-day dates remain calendar dates. Reminders appear in your Open Core HR notifications; they are not email or SMS reminders. A declined attendee is not reminded. The scheduler must be running. Requesting an online meeting takes effect when Outlook Calendar Sync publishes the event and the administrator has enabled Teams meetings. The join link appears after successful sync. Existing links remain when sync is turned off. ## Editing and cancelling events Open a personal event you organized and choose **Edit** or **Cancel event**. An invited employee can respond but cannot change the organizer's event. For a recurring event, the normal edit or cancel action changes that occurrence. The web event details also offer **Edit series** and **Cancel series**. Series changes can remove exceptions that no longer belong to the revised recurrence rule. Module events are changed through **Open source record**. Imported Outlook events are read-only here; edit them in Outlook. Cancellation removes the event from participants' Core calendars. If it was published to Outlook, the next successful sync cancels that exported copy. If sync is off, no remote change occurs until you enable it again. A conflicting Outlook change requires your review. ## Responding to invitations Open an event you were invited to and choose **Accept**, **Tentative** or **Decline**. Your Core response is visible to the organizer and the other invited employees. For a recurring event, it applies to the selected occurrence. Core responses and Outlook invitation responses are separate. Respond to an Outlook invitation in Outlook; this version does not forward Core RSVP actions to Microsoft. Imported appointments cannot be responded to here. ## Availability and privacy Use the calendar to review events you can access. A private event is shared only with its organizer and invited employees; adding it does not publish it to the entire company. The shared API provides busy-only availability for scheduling clients. Looking up another employee requires employee-view permission and returns busy periods without event titles, descriptions or attendees. The standard month calendar currently shows your events rather than a separate scheduling assistant. --- # HR and administration An overview of the HR and admin guide and the administrator dashboard. Use the same module sidebar as employees. Your permissions add team and company pages, such as employee records, attendance reports, leave approvals and payroll. Related types and setup live inside their module; company-wide controls live in **Settings**. There is no separate administration or employee portal to switch to. Use **Approvals** to review requests assigned to you. A management permission may cover your reporting team or the whole company; the application enforces that scope on records and actions. See [Finding your way around](https://czappstudio.com/docs/getting-started/finding-your-way-around) for search and personal pins, or choose the relevant feature guide for its workflow. ## The admin dashboard Use **Dashboard** to review work that needs attention and open the relevant records. The views available to you depend on your permissions: - **My Work** shows your own attendance, leave and requests, plus any approvals assigned to you. - **My Team** shows your direct reports. It does not include their reports or everyone in your department. - **HR Operations** shows the company information you are allowed to access. ![The dashboard: switch views (1), choose Edit dashboard (2) to change widgets, and Refresh (3) for a new snapshot.](https://media.czappstudio.com/screens/docs/dashboard-views/light-7d16c4b348-2880.webp) Someone with several responsibilities can switch views without signing out. Optional modules add their own widgets when enabled and available to you. The initial layout shows common daily widgets; additional widgets, including company leave requests and incomplete employee records, are available in **Edit dashboard**. ### Choose what you see 1. Open the view you want to change, then choose **Edit dashboard**. 2. Show or hide optional widgets and use the move controls to change their order. 3. Choose your default view if you want a different view when opening Dashboard. 4. Save your changes. Your preferences follow your account across browsers. Required notices cannot be hidden. **Reset this view** restores the current view's widgets and order; it does not change your other views. Changing the layout never changes your permissions. A widget disappears if you lose access or its module becomes unavailable. ### Review requests and attendance **Needs my approval** contains current workflow steps you can act on. Open the approval inbox to review and decide. **Company leave requests** and the optional expense backlog contain pending business requests; these may include requests assigned to other approvers. Their oldest-request figure measures elapsed days, not an approval deadline. **Missing check-in** means an employee's shift has started without a recorded check-in. It excludes applicable holidays, days off and approved non-working leave. It is a current snapshot, not a finalized full-day absence. Employees whose shift has not started appear separately. Late arrival and missing checkout are exceptions and may overlap attendance totals. A checkout is missing only after the recorded shift has ended. Working hours use recorded sessions and include elapsed time in open sessions. Company time settings determine the workday; overnight shifts may belong to the previous calendar date. Use **Refresh** when you need an updated snapshot. If a widget fails to load, retry it; a failed load does not mean there are no records. --- # Employees Find, add, import, export and manage the status and history of employees. Use **Employees** to find an employee by name, code, or work contact information. Filter account access and employment status separately: an active account may belong to someone who is still onboarding, and an ended employment record may retain account access if HR explicitly allows it. Select **Filters** to expand the filter options, choose the criteria you need, then select **Apply filters**. Changes do not affect results until you apply them; **Cancel** discards your changes. **Reset filters** clears the pending choices and still requires Apply. Remove an applied filter or use **Clear filters** to broaden the results without clearing your search. ![Employees: Add employee (1), search the directory (2) and use a row's actions menu (3) to change account access.](https://media.czappstudio.com/screens/docs/employees/light-b3d2c19750-2880.webp) With permission to edit employees, use a row's actions menu to disable an active employee's account access or enable a disabled one. You can add an optional reason, which is kept in the audit log. Employment status is not changed this way; use onboarding or separation for that. Open an employee to manage the details your permissions allow. The colleague directory and Connect contacts contain work contact information. Private details, home-location information, and compensation require the appropriate employee-profile access. Use [Deleted employees](https://czappstudio.com/docs/administration/employees#section-4) when a record has been deleted. Before adding a new employee with an existing email or code, check whether the original record should be restored. ## Adding an employee Add an employee directly when recruitment and an offer are not needed. You can create a person who has already joined or is still onboarding. 1. Open **Employees** and choose **Add Employee**. 2. Enter their name and work email. Check for an existing or deleted record before creating a duplicate. 3. Enter the work assignment and joining details your organisation uses. Select only the roles and app access the employee needs. 4. Choose the employment state, add optional contact or compensation details where needed, and save. 5. Saving sends the employee an invitation. They set their own password using the expiring invitation link; resend it from their profile if needed. The form suggests the next employee code. Keep it, or replace it with a unique custom code. If someone else takes the suggested code first, the next free one is used. Codes remain reserved for deleted records, so restore an existing employee instead of reusing their code. Employment onboarding and account access are separate. An invited employee cannot sign in until they accept the invitation; an active account can sign in while employment onboarding is still underway. Recruitment, an offer, and probation are optional paths rather than requirements for every employee. ## Account access and employment status Account access and employment progress answer different questions. Review both before changing an employee's record. | Account access | Meaning | | --- | --- | | Invited | The employee must accept an invitation and set a password. | | Active | The employee can sign in to the apps allowed by their roles and permissions. | | Disabled | Sign-in and authenticated access are blocked. The employment record is retained. | | Employment status | Meaning | | --- | --- | | Onboarding | Joining arrangements are still being completed. | | Employed | The employee has joined. | | Ended | The employment has ended. | Use the employee directory's filters to find a group, then open the employee before changing access or employment details. Disabling access does not end employment. Ending employment is recorded through a separation; HR decides separately whether to disable account access. Before access is disabled, HR is warned when the employee still manages direct reports, owns field customers or has open journey plans. Users with **Reassign customers to employees** can choose a successor in the same step; the customers move and their assignment history records the change. Otherwise continue and reassign customers later from **Field Operations → Customers**. Pause or end open journey plans separately. The employee's **Field work** tab lists their customers and journey plans within your own visibility. ### Invitations and restoring access Send a new invitation when an employee's original link has expired. They choose their own password. Enabling an account restores only the access its roles already allow; review those roles before restoring access. Do not delete an employee simply to block sign-in. [Deleted employees](https://czappstudio.com/docs/administration/employees#section-4) describes deletion and recovery; [Managing a separation](https://czappstudio.com/docs/modules/employee-lifecycle#section-20) describes recording an exit. ## Deleted employees Deleting an employee moves the record to **Deleted employees** and stops its normal use. Choose disabling account access when you need to stop sign-in but keep the employee in ordinary management views. Choose separation when employment has ended. To recover a deleted record, open **Employees → Deleted**, find the person, and choose **Restore**. A restored account is disabled. Review its roles and employment record before explicitly enabling access; restoration does not restart employment or automatically restore sign-in to Microsoft 365. Permanent deletion is a separate action available from the deleted list. It removes the employee record and, when linked, requests deletion of the Microsoft 365 account. Verify that required records and mailbox content have been retained before using it. This action cannot be undone in Open Core HR. ### Reviewing an account deletion request An employee can request account deletion from the mobile app. In **Employees**, filter **Deletion requests** to pending requests, then open the employee profile. The reason and request date are restricted to users allowed to view private employee details. Review the request before taking action. Deleting the employee completes the request. If the record should remain, use **Dismiss request** and optionally record review notes; dismissal requires employee editing and private-details management access. Dismissing a request does not delete the employee or change their employment state. ## Importing employees Open **Import & Export**, choose **Employees** under imports, and download the current template. Import permission is required. The file creates new employees; it does not update existing accounts. Follow the [shared import workflow](https://czappstudio.com/docs/administration/import-export#section-3) to upload, validate, review and explicitly confirm the file. Only `first_name` and `email` are required. Each email must be unique. Leave optional organisation, private, and compensation columns empty when you do not need them. A supplied department or designation name, location or shift code, or reporting manager email must match an existing active record. Set `requires_onboarding` to `1` when the employee should complete joining tasks through the Employee Lifecycle module; otherwise use `0` or leave it blank. Employment and account access are separate. Imported employees receive an invitation to set their own password. Use dates in `YYYY-MM-DD` format to avoid ambiguity. Enter phone numbers as text so the spreadsheet preserves their international prefix and leading zeros. When supplying compensation, include amount, currency, pay period, and effective date together. Private fields and compensation require their respective management permissions. ### Roles and codes The optional `roles` column accepts permanent role identifiers separated by semicolons, for example `employee;manager`. Every role must exist, duplicates are rejected, and you must be allowed to assign it. Leave the column blank to use the normal employee role. System Bot is not an employee role. Leave `code` blank to allocate one automatically, or supply a unique employee code. Codes are normalised to uppercase and must remain unique against deleted records as well. If validation reports row numbers, correct the affected rows and validate a new upload. No employees are created during preview, and any validation errors block confirmation. Check **History** for the confirmed import's result and the employee directory before importing the same people again, so you do not mistake an invitation delivery problem for a missing employee. ## Exporting employees Open **Import & Export** and choose **Employees** under exports when you need a spreadsheet of employee records. Export permission is required. Filter by department, location, designation, account status or employment status, choose the permitted columns you need, and request an XLSX or CSV file. Filters on the employee directory do not carry over; the scope you choose in Import & Export controls this download. Account access and employment status are separate columns. Private fields appear only when you have permission to view employee private details; current compensation appears only with compensation access. The export contains current terms, not the full compensation history. The file is generated in the background. Download it from **History** after completion and before the expiry shown, seven days after the request. Your data access is checked again at generation and download; changing your permissions can prevent completion or access. See [Transfer history and downloads](https://czappstudio.com/docs/administration/import-export#section-17). Review the file before sharing it, particularly if it contains personal contact information or pay. Keep exported copies only as long as needed; later changes to an employee record do not update an existing download. ## An employee's change history Open Core HR keeps a history of changes made to each employee record. You can review it on the **Activity** tab of the employee's profile — it isn't a separate screen. ### Steps 1. Open the employee's profile from **Employees**. 2. Click the **Activity** tab. The history loads as a timeline, newest first. 3. Each entry shows what happened (for example a record being created or updated), when it happened, the fields that changed (old value to new value), a **Reason** if one was given, and who made the change. ![The Activity tab (1) of an employee's profile lists changes newest first.](https://media.czappstudio.com/screens/docs/employee-activity/light-457dc190d1-2880.webp) ### Tips - If nothing has been recorded yet, you'll see "No activity recorded yet." - When someone changes the employee's status (Suspend, Relieve, Terminate, Reactivate), any reason they typed shows up here as part of that entry. ## Reviewing an employee timeline Use the employee timeline to understand when joining, probation, employment changes, disciplinary actions, and separation were recorded. Open it from the employee's profile when you need the context behind their current record. Read the date, action, and responsible person, then open the related record where available. An employment effective date may differ from the date HR recorded or approved the change. The timeline is supporting history. Check the employee profile for current work terms, the separation for the employment end date, and the settlement for payment status. Completing one does not imply that the others are complete. ## Using employment letters Employment letters record the terms or outcome of a lifecycle action, such as an offer, appointment, confirmation, employment change, or separation. Open the employee profile’s **Letters** tab to download available documents. Their originating workflow controls when they are released. Check the employee or candidate identity, effective dates, role, and any compensation terms. If details are incorrect, correct the underlying record through the permitted workflow before producing a corrected letter. Downloaded copies do not change when the underlying record changes. Employees can find available letters in **My Letters**. [Disciplinary warnings](https://czappstudio.com/docs/modules/disciplinary-actions) are managed in Disciplinary Actions. ### Choosing stationery New installations use **Plain stationery**, which prints the configured company name and address without a letterhead image. Keep [company information](https://czappstudio.com/docs/administration/settings#section-7) accurate before issuing letters. If your organisation uses branded letterhead, an administrator can upload a PNG or JPG through **PDF Templates → Manage Letterhead Stationery**. Choose it as the default or select it for an individual template. Leave enough space around the content for your letterhead and check a preview before issuing documents. Existing custom letterheads remain available. --- # The employee profile Maintain an employee's identity, work, compensation, personal, contact, bank, leave, device and location details. Use an employee's profile as the current record of their identity, work assignment, private contact information, and employment terms. Open it from **Employees** after checking the employee code to avoid changing a person with a similar name. Manage each type of information where it belongs: - [Identity and work contacts](https://czappstudio.com/docs/administration/employee-profile#section-1) are used to identify and contact the employee. - [Work information](https://czappstudio.com/docs/administration/employee-profile#section-2) determines the employee's department, role, manager, location, and joining arrangements. - [Personal information](https://czappstudio.com/docs/administration/employee-profile#section-4) and [emergency contact](https://czappstudio.com/docs/administration/employee-profile#section-5) are private. - [Compensation](https://czappstudio.com/docs/administration/employee-profile#section-3) records agreed pay terms and requires compensation access. - [Bank accounts](https://czappstudio.com/docs/administration/employee-profile#section-6), [documents](https://czappstudio.com/docs/modules/documents#section-4), and leave balances have their own controls. ![An employee profile: the Bank (1), Leaves (2) and Attendance phones (3) tabs hold the details described below.](https://media.czappstudio.com/screens/docs/employee-profile/light-f618b2c8a4-2880.webp) [Account access and employment status](https://czappstudio.com/docs/administration/employees#section-2) are independent. Use access controls to invite, enable, or disable sign-in. Use lifecycle records for onboarding, employment changes, and separation. Review the [employee audit log](https://czappstudio.com/docs/administration/employees#section-9) when you need to understand a previous change. ## Editing identity and work contact details Open the employee from **Employees** and edit their contact information when their name, work email, work phone, or employee code changes. The work email is also the sign-in identifier, so check the spelling and tell the employee when you change it. Work contact information is available to colleagues through the directory. Put a private number in **Personal Phone**, not the work phone field. Store a private email in **Personal Email**. Names and email must meet the form's validation. A new employee code must not be used by any other employee, including deleted ones. Imports match employees by code, so use the new code in later import files. Optional details may be left blank. Use the deployment's supported phone format; there is no universal ten-digit requirement. For private details, see [Personal information](https://czappstudio.com/docs/administration/employee-profile#section-4). For a change of role, manager, or joining date, see [Work information](https://czappstudio.com/docs/administration/employee-profile#section-2). ## Editing work information Open the employee profile and edit **Work information** to maintain department, designation, shift, location, reporting manager, roles, and joining date. These details are optional; remove an assignment when it no longer applies instead of creating placeholder organisation records. Roles control application access and can be changed only by someone allowed to assign them. Saving other profile sections leaves roles unchanged. Removing all assigned roles may remove the employee's app access even while the account remains active. Use an [employment change](https://czappstudio.com/docs/modules/employee-lifecycle#section-18) when an organisational or pay change needs an effective date and approval. For a correction to the current record, edit the profile directly. Neither action should be used to disable account access or record a separation. ## Maintaining current compensation Current compensation records the agreed amount, currency, pay period, and effective date. The pay period explains whether the amount is hourly, daily, weekly, monthly, or yearly; always check it before comparing amounts. Open the employee's profile and edit compensation if your permissions allow it. Enter the agreed amount with its currency and pay period, then the date from which it applies. Enter a reason when changing existing terms. Each saved change adds to compensation history. Use an employment change when the change needs approval. Compensation is restricted to the employee and users with compensation access. Directory access alone does not grant access to pay. This record captures agreed terms; it does not calculate payroll, tax, statutory deductions, or a payslip. ## Maintaining private personal information Record only the personal information your organisation needs to support the employee. Date of birth, gender, address, personal email, and personal phone are optional. Open the employee's profile and edit the relevant personal or contact section. A personal email or phone is separate from the work contact information used in the colleague directory. Check the employee's preferred contact details before replacing them. Personal information is available to the employee and authorised HR users. It is not part of colleague directory or Connect contact responses. Collect emergency contact information separately; see [Emergency contacts](https://czappstudio.com/docs/administration/employee-profile#section-5). ## Maintaining an emergency contact Keep one current emergency contact for the employee: their name, phone number, and relationship to the employee. These details are optional; ask the employee to supply accurate information and confirm that the person is appropriate to contact. Open the employee's profile and edit **Emergency Contact**. Update the name and number together when the contact changes. Use the supported phone format for your deployment, including a country code where needed. Emergency contact information is private HR information. It is not shown in the colleague directory or Connect contacts. Employees can keep their own emergency contact current from their profile. ## Employee bank accounts The **Bank** tab on an employee's profile holds the bank account used for their pay. ### Steps 1. Open the employee's profile from **Employees**. 2. Go to the **Bank** tab. The **Bank Account Details** card shows the account name, bank name, branch, account number, and the bank identifiers — or a note if nothing is on file yet. 3. Click the edit (pencil) button on the card. 4. In the **Edit Bank Account** panel, check the **Account Holder Name**. Leave it empty to use the employee's name. Enter the **Bank Name**, **Branch** and **Account Number**, which are all required, then whichever identifiers your banks use: **Bank Code** (an IFSC in India, a sort code in the UK, a routing number in the US), **IBAN**, and **SWIFT / BIC**. Those three are optional. A bank code may contain only letters, digits, spaces and hyphens. IBAN and SWIFT / BIC must follow their international formats. 5. Click **Update** to save, or **Cancel** to close without saving. ### Tips - The account holder name is taken from the employee's name automatically. - The **Account Number** must be digits only. The identifier fields are stored in upper case and are not checked against any one country's format, so they work wherever you run Open Core HR. ## Employee leave balances The **Leaves** tab on an employee's profile shows their leave balance for the current year. ### Viewing leave balances 1. Open the employee's profile from **Employees**. 2. Go to the **Leaves** tab. You'll see a card for each leave type the employee has an allocation for, showing the year and the **Entitled**, **Used**, and **Available** counts. Cards may also show **Carried Forward** and **Additional** days, and a **LOP** marker with the number of loss-of-pay days if any apply. 3. If nothing has been allocated, you'll see "No leave allocations found for this employee." ### Setting leave counts Starting leave counts are set when you first add an employee, on the **Leave Allocation** step of the **Add Employee** form. The profile's Leaves tab shows balances only and has no edit control. For ongoing changes to leave balances, use **Leave Management → Balance Management** from the **Human Resources** section of the menu. ## Employee devices The **Device** tab on an employee's profile shows the mobile device they've registered for the Open Core HR app, and lets you remove it. ### Viewing the registered device 1. Open the employee's profile from **Employees**. 2. Go to the **Device** tab. The **Registered Device** card shows details such as **Device Name**, **Device Model**, **OS Version**, **App Version**, **Registered On**, **Device Type**, **Device ID**, **Battery Level**, **GPS Status**, **WiFi Status**, and **Location**. 3. If the employee hasn't registered a device, you'll see "No device registered for this employee." ### Removing a device 1. On the **Device** tab, click **Remove Device**. 2. The device is removed. > **Caution:** After you remove the device, the employee can't use the mobile app until they register a new one. ## Employee work locations In addition to an employee's main location, Open Core HR can record extra work locations for them. These appear as the **HR Locations** card on the **Overview** tab of the employee's profile. ### Viewing work locations 1. Open the employee's profile from **Employees**. 2. On the **Overview** tab, look for the **HR Locations** card. It lists each extra location as a tag. The card only appears when the employee has at least one extra location. ### Adding or removing a work location > **Note:** The **HR Locations** card lists the extra locations but has no add or remove control on this screen. The employee's main location is set on the **Work Information** card — see [Editing work information](https://czappstudio.com/docs/administration/employee-profile#section-2). --- # Attendance Review attendance records and analytics, close open sessions and set attendance policies. Open **Attendance → Team attendance** to review daily attendance for the employees you can see: everyone with full attendance access, or yourself and your direct reports as a manager. The page has three tabs: **Records**, **Needs review** and **Refused attempts**. ## Finding records Search by employee name, code, shift name or date. Select **Filters** to narrow the list by: - **Status** — **Still checked in**, **Completed**, **Late**, **Early departure**, **Overtime** or **Corrected** (closed by a manager or HR). - **From date** and **To date** — the work dates to include. - **Employee** — one person. ![Team attendance: the Records, Needs review and Refused attempts tabs (1), search (2) and Filters (3).](https://media.czappstudio.com/screens/docs/team-attendance/light-066b846fc9-2880.webp) Expand a row for its session timeline or open the details panel for the full day. See [Attendance sessions](https://czappstudio.com/docs/administration/attendance#section-7). Each record keeps the shift that applied on that work date, so later shift changes do not alter past days. ## Needs review **Sessions left open** lists employees who are still checked in after their scheduled shift end plus the review allowance set in [Attendance policies](https://czappstudio.com/docs/administration/attendance#section-13). Close each one at the time the employee actually stopped working. See [Closing a session left open](https://czappstudio.com/docs/administration/attendance#section-10). **Refused attempts to review** lists check-ins and check-outs that the attendance rules rejected and nobody has reviewed yet. ## Refused attempts When a check-in or check-out is refused for a business reason, the attempt is kept with the employee, time, web or mobile channel, the message the employee saw and any location they sent. Typical reasons are an inaccurate, out-of-date or simulated location, no attendance-enabled shift, leave, an already completed day, a module requirement such as outstanding documents, or checking out without being checked in. Requests rejected because required details were missing or malformed are not recorded. Filter by review status, action, employee or date. Select **Mark reviewed** after you have followed up, for example by contacting the employee or correcting their policy. You cannot review your own attempts. Location evidence on attempts is removed after the retention period in [Attendance policies](https://czappstudio.com/docs/administration/attendance#section-13); the attempt itself remains. Closing sessions and reviewing attempts require the **Close open sessions and review refused attempts** permission. HR and Manager presets include it. ## Attendance analytics The Analytics screen turns attendance data into trends, department comparisons, tracking-quality figures, and a list of anomalies. Open **Attendance → Analytics** from the left menu (you can also reach it from the **Analytics** button on the All Attendance screen). ### Steps 1. Open **Attendance → Analytics**. 2. Choose a **Period**: **Last 7 Days**, **Last 30 Days**, **Last 90 Days**, or **Custom**. If you pick **Custom**, set a **Start Date** and **End Date**. 3. Optionally pick a **Department**, or leave it on **All Departments**. 4. Click **Apply** to refresh the figures. Click **Clear** to reset to the last 30 days and all departments. ![Attendance analytics filters: choose a period (1) and department (2), then Apply filters (3).](https://media.czappstudio.com/screens/docs/attendance-analytics/light-2509ec16b4-2880.webp) ### Reviewing attendance Compare attendance, punctuality, and working hours over the selected period and across departments. Review flagged anomalies before following up with an employee. ## A day's attendance sessions Each attendance record can hold several work sessions and breaks for the same day. You can see the session log without leaving the All Attendance screen — it opens as a slide-over panel, not a separate page. ### Steps 1. Open **Attendance → All Attendance**. 2. Find the row for the employee and date you want. 3. To see a quick session timeline, click the chevron at the start of the row. A **Session Timeline** strip expands under the row, listing each event (**Check In**, **Check Out**, **Break Start**, **Break End**) with its time and address, plus the session count. 4. For full details, click the eye icon in the **Actions** column. The **Attendance Details** panel slides in from the right with three tabs: - **Summary** — employee, date, shift, working hours, check-in and check-out times, late hours, overtime, and any notes. - **Sessions** — the full list of check-in, check-out, break-start and break-end events, each with its time, address, and notes. A "Session is active (not checked out)" banner appears if the employee is still checked in. - **Metrics** — a time summary of the day: late, early, overtime and working hours. 5. Click **Close** to dismiss the panel. ### Record access Session details are read-only; you cannot edit recorded sessions here. ## Closing a session left open When an employee forgets to check out, their session stays open and appears under **Attendance → Team attendance → Needs review** once their shift has ended and the review allowance has passed. A manager or HR user closes it on the employee's behalf. ### Steps 1. Open the **Needs review** tab. 2. In **Sessions left open**, open the row's actions and choose **Close session**. 3. Enter the date and time the employee stopped working, in the organisation's timezone. It must be after the check-in and not in the future. 4. Enter the reason for the correction and select **Close session**. ### What changes The session ends at the time you entered and the day's working hours, early departure and overtime are recalculated from the shift recorded for that day. A break that was still running ends at the same time. The check-out entry records who closed it and your reason, and the record appears under the **Corrected** status filter. The employee can check in again for their next session. You cannot close your own session this way, and you can only close sessions of employees whose attendance you can see. If someone has already closed the session, refresh the list. To add a forgotten day or change recorded times, see **Correcting attendance** below. ## Correcting attendance Attendance is corrected in two ways on **Attendance → Corrections**: employees ask for a fix and an approver decides, or a manager or HR user fixes a day directly. Anything beyond your own requests needs the **Close open sessions and review refused attempts** permission, and you only see employees whose attendance you can see. ### Approving a request Requests follow the **Attendance Correction Approval** workflow, which by default goes to the employee's reporting manager. Change the steps under **Approvals → Workflows**; if the workflow is turned off, employees cannot send requests. Open the request from the approval inbox or from **Corrections**. It shows the requested times next to what was recorded, with the employee's reason. Approve, or reject with a note the employee will see. If the attendance changed after the request was sent, reject it and ask for a new one. ### Fixing a day directly Select **Fix an employee's attendance**, choose the employee and the day, then what to fix, the times and a reason. The change applies immediately, without approval, and is listed as fixed by you. ### Rules and limits - Lateness, working hours, early departure and overtime are recalculated from the shift recorded for that day, and the session appears under the **Corrected** status filter with the times that were replaced. - New times must include the recorded breaks, must not overlap another session, cannot be in the future, and a session cannot be longer than 24 hours. - When the Payroll add-on is on, a day in an approved or finalised payroll run cannot be changed. - Under **Attendance → Attendance policies → Default policy**, set how many days back employees can ask (30 by default) and how many requests each employee can make per month (0 means no limit). These limits do not apply to direct fixes. ## Attendance policies Use **Attendance policies** to configure verification for all employee types. Managing policies requires the attendance-policy management permission; assigning an employee override also requires permission to edit that employee. Create a named, active policy and select web, mobile, or both recording channels. Configure check-in and check-out independently. Leave an action's alternatives empty for open attendance without verification requirements. Each alternative contains checks that must all pass. If there is more than one alternative, passing any complete alternative is enough. Location checks can require a recent position, limit accuracy and reject simulated locations; a location boundary also requires a centre and radius. A required check whose provider is unavailable prevents attendance rather than silently skipping that check. Set the installation default, select a policy on a shift, or assign an employee override. Resolution uses the employee override first, then the shift policy, then the installation default. An open attendance session keeps a snapshot of its original policy for checkout. ![Attendance policies: create one with Add policy (1) and set the installation default on Default policy (2).](https://media.czappstudio.com/screens/docs/attendance-policies/light-9fc9a0e758-2880.webp) Choose requirements employees can meet at their actual workplace. A field employee can use a flexible shift and a mobile location policy, while an office employee uses a fixed shift and an open policy. Both feed the same attendance history and Payroll inputs. If another administrator changes a policy while you edit it, refresh and review the latest version before saving. Deactivating a policy does not replace an explicit assignment with a weaker default; assign a suitable active policy before future check-ins. ### Review settings The default-policy tab also sets **Review open sessions after (hours)** — how long after the scheduled shift end a session still open appears under **Needs review** — and **Keep refused-attempt locations for (days)**, after which location evidence on refused attempts is removed daily. --- # Leave requests Review leave requests, create leave for employees, use the leave calendar and manage compensatory offs. The All Leave Requests screen lists employee leave requests so you can filter and review them. Pending requests are approved or rejected in the approval inbox. Open **Leave Management → All Leave Requests** from the left menu. ## Steps 1. Open **Leave Management → All Leave Requests**. 2. Use the filters above the table to narrow the list: - **Employee** — pick one person, or leave it on **All Employees**. - **Status** — **Pending**, **Approved**, **Rejected**, **Cancelled**, or **All Statuses**. - **Leave Type** — pick a leave type, or leave it on **All Leave Types**. - **From Date** / **To Date** — limit to requests whose leave dates fall in that range. 3. Use the **Search leave requests...** box to find requests by ID, status, reason text, employee name or code, or leave type name. 4. To open a request, choose **View** from the row's actions menu. 5. If you have permission, the **Add Request** button at the top right lets you create a request for an employee — see [Creating leave for an employee](https://czappstudio.com/docs/administration/leave-requests#section-11). ![Leave Requests: Filters (1), search (2) and Add Request (3).](https://media.czappstudio.com/screens/docs/leave-requests/light-3773a50f5b-2880.webp) ## Reviewing requests Check the dates, day count, reason, supporting document, and status. Approve or reject pending requests from **Inbox → To do**; cancel an approved request from its details page. See [Reviewing a leave request](https://czappstudio.com/docs/administration/leave-requests#section-8). ## Tips - What you can see and do depends on your role. People who can only view their own leaves see just their requests; a team leader sees their team's requests. ## A leave request's details Open a leave request to see its dates, type, reason, the employee's leave balance, the approval timeline, and recent leave history. ### Steps 1. Open **Leave Management → All Leave Requests**. 2. Choose **View** from the actions menu of the request you want. The **Leave Request #** page opens. ### Reviewing the request Check the dates, duration, reason, supporting proof, and available balance. Review the timeline and recent leave history for context. Approve or reject a pending request from the approval inbox, and cancel an approved one from this page. See [Reviewing a leave request](https://czappstudio.com/docs/administration/leave-requests#section-8). ### Tips - The **Edit** button (when shown) opens a slide-over to change the dates, half-day setting, reason, supporting document, emergency contact, and abroad details. The leave type itself can't be changed there. ## Reviewing a leave request Pending leave requests are approved or rejected in the approval inbox. A request that's already approved can be cancelled from its detail page. ### Steps #### Approve a request 1. Open **Inbox → To do** and find the leave request. 2. Click **Approve** for that request. 3. Optionally add **Remarks** in the dialog. 4. Click **Approve**. When approved, the leave days are deducted from the employee's balance, any comp-off days they chose to use are marked as used, and the employee is notified. #### Reject a request ![In Inbox → To do, a request's actions menu offers Approve (1) and Reject (3).](https://media.czappstudio.com/screens/docs/approval-decision/light-d6c302391c-2880.webp) 1. Open **Inbox → To do** and find the leave request. 2. Click **Reject** for that request. 3. Enter a reason in **Notes** — this field is required. 4. Click **Reject**. The employee is notified, and any comp-off days they had reserved are released. #### Cancel an approved request 1. Open **Leave Management → All Leave Requests**, choose **View** for the **Approved** request, then click **Cancel** on its detail page. 2. Optionally add **Notes (optional)** in the dialog. 3. Click **Cancel Leave**. The leave balance is restored, any comp-off days are released, and the employee is notified. ### Tips - Only **Pending** requests can be approved or rejected; only **Approved** requests can be cancelled. - An approved leave that has already started or passed can't be cancelled. - The leave screens don't offer approve or reject; use the approval inbox. See [Approving and rejecting a request](https://czappstudio.com/docs/administration/approvals#section-4). - The cancel button only appears if your role allows it. ## Creating leave for an employee If your role allows it, you can submit a leave request on behalf of an employee. Open **Leave Management → All Leave Requests** and click **Add Request** at the top right. ### Steps 1. Open **Leave Management → All Leave Requests** and click **Add Request**. 2. Pick the **Employee**. 3. Pick the **Leave Type**. 4. Set the **From Date** and **To Date**. The screen shows the calculated number of working days (weekends and holidays excluded) once both dates are set. 5. If it's a half day, turn on **Half Day Leave** and choose **First Half** or **Second Half**. 6. Enter a **Reason** — this is required. 7. Optionally attach a **Supporting Document** (PDF, JPG, or PNG). 8. If the employee will be travelling abroad, turn on **Travelling Abroad** and enter the location. 9. Optionally fill in **Emergency Contact** and **Emergency Phone**. 10. Click **Create Leave Request**. ![Create Leave Request: pick the employee (1) and leave type (2), then set the dates (3).](https://media.czappstudio.com/screens/docs/leave-create/light-eed06da32b-2880.webp) ### Tips - The **Add Request** button only appears if your role can create leave for other people. - After it's created, the request shows up in the All Leave Requests list and follows the normal approval flow — see [Reviewing a leave request](https://czappstudio.com/docs/administration/leave-requests#section-8). ## Employee leave calendar The Employee Leave Calendar shows who is off on which days, in a month grid, so you can spot clashes before approving leave. It opens at `/leaves/team` — reach it from the leave area of the workspace. ### Steps 1. Open the **Employee Leave Calendar**. 2. Use the filters to focus the view: - **Status** — **Approved**, **Pending**, or **All Statuses**. - **Leave Type** — pick a type, or leave it on **All Leave Types**. - The employee picker — pick one employee, or leave it on **All Members**. 3. Use the **‹** and **›** arrows above the grid to move between months, or click **Today** to jump back to the current month. 4. Click an employee's name inside a day cell to open a **Leave Details** pop-up for that request. ![Employee Leave Calendar: Filters (1), the month arrows (2) and Today (3).](https://media.czappstudio.com/screens/docs/leave-calendar/light-c2408cb3bc-2880.webp) ### Planning coverage Select a day or employee to review the leave dates, status, and reason. Use the calendar to identify overlapping leave before approving requests or arranging coverage. ### Tips - Half-day leaves are marked with "1st Half" or "2nd Half" next to the leave type in the On Leave Today panel. - The employees shown depend on your role and reporting relationships. ## Compensatory offs A compensatory off ("comp off") is time off an employee earns by working extra. The Compensatory Offs screen lets you review those requests and see who has comp-off days available. Pending requests are approved or rejected in the approval inbox. Open **Leave Management → Compensatory Offs** from the left menu. ### Steps 1. Open **Leave Management → Compensatory Offs**. 2. Use the filters above the table to narrow the list: - **Status** — **Pending**, **Approved**, **Rejected**, or **All Statuses**. - **Employee** — pick one person, or leave it on **All Employees**. - **Usage Status** — **Available**, **Used**, **Expired**, or **All Usage**. - **From Date** / **To Date** — limit by the date the extra work was done. 3. Use the **Search compensatory offs...** box to find requests. 4. To open a request, choose **View** from the row's actions menu. If your role allows, its details page lets you edit or delete a **Pending** request. 5. To approve or reject a **Pending** request, open **Inbox → To do** — see [Approving and rejecting a request](https://czappstudio.com/docs/administration/approvals#section-4). ### Reviewing earned days Check the worked date, hours, reason, and expiry date before deciding on a request in the approval inbox. Four hours convert to half a comp-off day. Admins with permission can edit pending requests from their details. ### Tips - Only **Pending** comp-off requests can be approved or rejected. - An approved comp-off has an expiry date; once it's past, its usage status shows **Expired**. --- # Leave types and balances Set up leave types and set, adjust or bulk import leave balances. Leave types are the categories employees pick when they apply for leave — for example casual leave, sick leave, or earned leave. Open **Leave Management → Leave Types** from the left menu. ## Steps 1. Open **Leave Management → Leave Types**. 2. Use the **Search leave types...** box to find a type by ID, name, code, or notes. 3. Click the eye icon on a row to view that type's full settings in a pop-up. 4. Click the pencil icon to edit a type, or the trash icon to delete it (both appear only if your role allows it). 5. Click **Add New** at the top right to create a new type — see [Creating or editing a leave type](https://czappstudio.com/docs/administration/leave-types-and-balances#section-4). ## Availability and proof Only active leave types are offered when applying for leave. **Proof Required** determines whether the employee must attach a supporting document. ## Tips - A leave type that's already used by existing leave requests can't be deleted — make it **Inactive** instead. ## Creating or editing a leave type You create and edit leave types from a slide-over panel on the Leave Types screen. Open **Leave Management → Leave Types** and click **Add New**, or click the pencil icon on an existing type. ### Steps 1. Open **Leave Management → Leave Types**. 2. Click **Add New** to create one, or the pencil icon on a row to edit one. The **Add Leave Type** / **Edit Leave Type** panel slides in from the right. 3. Fill in the fields: - **Name** (required) — the leave type's name. - **Code** (required) — a short code such as "CL", "SL", or "EL". - **Notes** — optional notes. - **Proof Required** — turn on if a supporting document must be attached when this type is used. - **Compensatory Off Type** — turn on if this type represents compensatory off. - **Deductible** — turn on if using this type should reduce the employee's leave balance. - **Auto Deduct From** — optionally enter another leave type's code to draw from automatically. - **Monthly Limit** — the most days of this type allowed per month; leave blank for no limit. - **Yearly Limit** — the most days of this type allowed per year; leave blank for no limit. - **Requires Advance Notice** — turn on if employees must give notice before taking this leave. When on, set **Advance Notice Days**. - **Status** — on for **Active**, off for **Inactive**. 4. Click **Create** (or **Update** when editing). ![Add Leave Type panel: enter the name (1), set Proof Required (2) and choose Create (3).](https://media.czappstudio.com/screens/docs/leave-types/light-c8c7849ef0-2880.webp) ### Tips - The annual entitlement each employee actually gets is set on the [Leave balance management](https://czappstudio.com/docs/administration/leave-types-and-balances#section-7) screen, not here — this screen only defines the leave type and its limits. - Codes need to be unique; if you enter one that's already in use you'll be asked to change it. > **Note:** There is no separate "annual allotment", "paid" or "carry-forward" field on this form. Yearly entitlement is handled through **Balance Management** rather than on the leave type itself. ## Leave balance management Use **Leave Management → Balance Management** to review current leave balances, set initial entitlements and make documented adjustments. Spreadsheet imports and exports are in **Import & Export**; see [Bulk importing leave balances](https://czappstudio.com/docs/administration/leave-types-and-balances#section-14). ### Steps 1. Open **Leave Management → Balance Management**. 2. Use the **Search employees...** box to find someone by name or employee code. 3. Click the eye icon on a row to open that employee's balance detail page. 4. If your role can manage balances, use **Bulk Set Initial Balance** for a group or open an employee to set or adjust their balance. See [Setting and adjusting leave balances](https://czappstudio.com/docs/administration/leave-types-and-balances#section-11). ![Leave Balance Management: search employees (1), open one from the row's actions (2), or use Actions (3) for bulk changes.](https://media.czappstudio.com/screens/docs/leave-balances/light-b0d4cd1db2-2880.webp) ### Reviewing balances Open an employee to review entitlement, carried-forward days, adjustments, usage, available days, and loss-of-pay (LOP) days for the selected year. Use **Set Initial** for a balance that has not been set, or **Adjust** for an existing balance, if you have permission. Review **Recent Adjustments** for the reason and before/after values of manual changes. Use **View Summary Report** to review entitlement, usage, availability, and pending leave across the organisation. ### Tips - "LOP" stands for loss of pay — days an employee took beyond their available balance. ## Setting and adjusting leave balances There are two ways to change one employee's leave balance: set the initial entitlement for a leave type that doesn't have one yet, or make an adjustment (add or deduct days) on a leave type that already has a balance. Both are done from the employee's balance page. ### Steps #### Set the initial balance for a leave type 1. Open **Leave Management → Balance Management** and click the eye icon next to the employee. 2. Find the leave type card (or table row) that shows no balance yet and click **Set Initial**. A **Set Initial Balance** panel slides in. 3. The **Leave Type** is shown (read-only). 4. Enter the **Entitled Leaves** — the number of days the employee should start the year with (steps of 0.5 are allowed). 5. Click **Set Balance**. #### Adjust an existing balance 1. On the same employee's balance page, find a leave type that already has a balance and click **Adjust**. An **Adjust Balance** panel slides in. 2. The **Leave Type** is shown (read-only). 3. Choose the **Adjustment Type** — **Add** or **Deduct**. 4. Enter the number of **Days** (steps of 0.5 are allowed). 5. Enter a **Reason** — this is required. 6. Click **Apply Adjustment**. The change is recorded in the **Recent Adjustments** log on the page, showing the before/after balance, the reason, and who made it. ### Tips - **Set Initial** appears only before a leave type has any balance for that year; after that, use **Adjust**. - To set a starting balance for many employees at once, use **Bulk Set Initial Balance** or an import instead — see [Bulk importing leave balances](https://czappstudio.com/docs/administration/leave-types-and-balances#section-14). - The **Set Initial** and **Adjust** buttons appear only if your role has the matching permission. ## Bulk importing leave balances Use a spreadsheet to set different initial leave entitlements for many employees, or use **Bulk Set Initial Balance** to apply the same entitlement to a group. Both require permission to manage leave balances. Initial entitlements are the starting allowance for a leave type and year; they are not the employee's remaining available balance. ### Import initial entitlements 1. Open **Import & Export**, choose **Leave balances** under imports, and download the current template. 2. Replace the sample employees with real employee codes or email addresses. Enter a value in each leave-type column you intend to set; leave unrelated columns blank. Use the headings from the current template, which reflects the configured leave types. 3. Select the year explicitly and upload the file. Review the year before validating; the same employee can have different entitlements in different years. 4. Validate and review the result. Correct all errors in a new upload before confirming. No balances change during preview. 5. Confirm the import and check **History** for completion. See [Importing a spreadsheet](https://czappstudio.com/docs/administration/import-export#section-3). Provide either the employee's unique code or their email. Use values from 0 to 365 days for initial entitlement. A blank leave-type cell leaves that entitlement untouched; zero explicitly sets a zero entitlement where initial setup is allowed. The import sets the entitlement for each supplied employee, leave type and year, including replacing an existing entitlement. Available leave is recalculated with existing usage, carried-forward leave and adjustments preserved. An entitlement that would make available leave negative is rejected. Review existing entitlements before importing; use [an adjustment](https://czappstudio.com/docs/administration/leave-types-and-balances#section-11) with a reason when the change is an addition or deduction rather than a new entitlement. ### Export entitlements Choose **Leave balances** under exports in **Import & Export**, select the year and request an XLSX, CSV or PDF file. Download the completed file from **History**. It contains initial entitlement by leave type, not available leave after usage and adjustments. Use the balance detail or summary report when you need those figures. ### Set the same initial balance for many employees 1. Open **Leave Management → Balance Management**, then **Actions → Bulk Set Initial Balance**. 2. Set the **Year**. 3. Pick the **Leave Type**. 4. Enter the **Entitled Days** to give each employee (steps of 0.5 are allowed). 5. Leave **Apply to All Employees** on to set it for every active employee, or turn it off and add specific employees with the search box. 6. Click **Set Balance**. --- # Approvals Work through the approval inbox, approve, reject or reassign requests and configure approval workflows. The approval inbox is your queue for requests waiting on your decision, including leave, expenses, loans and other enabled request types. It shows only current approval steps that you are eligible to act on. ## Review pending requests 1. Open the **Inbox** from the top bar and choose **To do**. 2. Search by requester name or code, workflow name, or step name. Use **Filters** to narrow by request type, workflow, requester or request date. 3. Check the requester, subject and current approval level. Choose **View** from the request's actions menu to review its details, where available. 4. Approve or reject from the actions menu, or select several rows for a shared decision. See [Approving and rejecting requests](https://czappstudio.com/docs/administration/approvals#section-4). ![Inbox: open To do (1), search requests (2) and narrow them with Filters (3).](https://media.czappstudio.com/screens/docs/approval-inbox/light-67dd1a05ff-2880.webp) ## Who can act A step assigned to a specific person is available to that person. Holding the same role does not grant access to someone else's assigned step. An unassigned role-based step can be handled by an eligible member of that role. Super administrators retain their existing administrative access, subject to the request's business rules. If the system cannot resolve an approver, an administrator may need to reassign the step. See [Reassigning an approval](https://czappstudio.com/docs/administration/approvals#section-8). ## Later approval levels A request appears only when it reaches your level. Approving your step may pass it to another reviewer. If you are also the next approver, it appears again after the inbox refreshes and requires a separate decision. ## Approving and rejecting requests Approving a step moves the request to its next approval level, or completes it if this is the final level. Rejecting ends the workflow and skips any remaining approval steps. The requester is informed of the outcome. ### Act on one request 1. Open **Inbox → To do**. 2. Open the request's actions menu and choose **View** to review its details, where available. 3. Choose **Approve** and optionally enter **Remarks**, or choose **Reject** and enter the required reason in **Notes**. For request types that support it, such as expense claims, you can instead choose **Return for correction** and describe what needs to change. 4. Confirm your decision. Remarks and reasons can contain up to 1,000 characters. ![A request's actions menu: Approve (1), Return for correction (2) or Reject (3).](https://media.czappstudio.com/screens/docs/approval-decision/light-d6c302391c-2880.webp) Returning a request ends the current review without rejecting it. The requester corrects and resubmits it, and the resubmission starts again at the first approval level. Returning is available one request at a time. After a single approval, the confirmation message names the next step when another review is needed. If you are also the next approver, the request can reappear in your inbox. ### Act on several requests 1. Review the requests you intend to approve or reject. 2. Select their checkboxes. The checkbox in the table heading selects only the current page, with a maximum of 100 requests per batch. 3. Choose **Approve selected** or **Reject selected**. 4. Check the selected count. Optional approval remarks or the required rejection reason will be saved against every selected step. 5. Confirm the decision. A successful batch clears the selection and refreshes the inbox. Changing the page, search, filters or sorting clears the selection. Each batch acts only on the currently selected steps; it does not approve later levels automatically. All selected requests must still be available for your decision. If a request has changed, you lack authorization, or a request cannot complete its action, the entire batch is refused and none of its decisions are saved. ### Recover from an error - **A rejection needs a reason.** Enter text in **Notes** before confirming. - **A request has already changed or been completed.** Cancel the confirmation, reload the inbox, review the remaining requests and select them again. - **An action fails.** The confirmation retains your notes and selection so you can correct the issue or retry. Check the reported reason before submitting again. ## Reassigning an approval Sometimes an approval needs to move to a different person — for example, when the configured approver role has nobody assigned to it and the request is stuck. ### What you can do today The **Inbox → To do** tab does not have a button to hand an approval to a specific person. What it does instead, for HR admins and admins, is surface the stuck requests so they can be acted on: 1. Open **Inbox → To do** from the left menu. 2. If a request's approval level couldn't be matched to anyone (for example, the workflow points to a role that no one currently holds), it still appears in the inbox for HR admins and admins. 3. From there you can approve or reject it directly — see [Approving and rejecting a request](https://czappstudio.com/docs/administration/approvals#section-4) — so the request doesn't stall. To change who normally approves a given type of request, edit the relevant flow on the **Approval workflows** page — see [Approval workflows](https://czappstudio.com/docs/administration/approvals#section-10). > **Note:** The Inbox To do tab offers view, approve and reject. There is no per-row reassign control on this screen, even though a "reassign approvals" permission exists. ## Approval workflows A workflow decides who reviews a particular kind of request and in what order. There's one workflow per request type — leave, expenses, loans, warnings, promotions, separations, and so on — and each workflow is a list of approval levels. On this page you adjust the levels of an existing workflow. ### Opening the page Open **Approval workflows** from the left menu. Expand a workflow to review its approval levels and approvers before editing. ### Editing a workflow's steps You need the workflow management permission for this. If you don't, the edit button isn't shown. 1. On the **Approval Workflows** page, find the workflow you want to change. 2. Click the pencil (edit) button on its card. The **Edit Workflow** panel slides in from the right. 3. Update the details as needed: - **Name** — the display name of the workflow. - **Code** — fixed once the workflow exists; it can't be changed here. - **Description** — optional explanatory text. - **Active** — turn the workflow on or off. While it's off, requests of that type can't be submitted through it. 4. Adjust the **Approval Levels**: - Each level has a **Step Name** (for example, "HR Manager Approval") and an **Approver Type**. The approver type currently offered is **Role**, with a **Role** picker to choose which role approves at that level. - Use the up and down arrows on a level to reorder it. - Use **Add Level** to add another level, or the delete (trash) button to remove one. A workflow must keep at least one level. 5. Click **Update** to save. ![Edit Workflow panel: choose the approving role (1), add levels with Add Level (2), then choose Update (3).](https://media.czappstudio.com/screens/docs/approval-workflow-edit/light-130ecb6948-2880.webp) ### After you finish - Requests submitted from now on follow the updated levels. In-progress requests continue on the flow they started. ### Tips - There's no "Add Workflow" button — the set of workflows matches the request types Open Core HR supports, so you edit the steps of the existing ones rather than creating new flows. - A workflow that's set to **Inactive** blocks new submissions of that request type. If issuing a warning or submitting a request is being refused, check that the matching workflow is active. This includes leave and compensatory off requests: employees can't apply for either while its workflow is inactive. - New installations start the Leave and Compensatory Off workflows with **HR Officer** as the approver. Installations set up earlier keep their original approver, which this screen shows with an empty **Approver Type**. Choose a role and click **Update** to set it. > **Note:** The workflow editor offers **Role** as the approver type. Other approver types exist in the system but are not selectable on this screen. --- # Expense administration Review expense claims, record reimbursements and set up expense categories and approvals. Open **Expenses → Expense Claims** to review expense claims. Expense claims are included in core HR and require the appropriate expense-viewing permission. The list includes every category. Travel, meals, supplies, and claims containing several categories appear together. ## Review claims 1. Open **Expense Claims**. The initial filter shows submitted claims awaiting approval. 2. Change the status filter to see other states or all claims. 3. Search by employee or claim, or narrow by category and expense date. 4. Open a claim to review its items and receipts. 5. Approve or reject the whole claim from **Inbox → To do** when you are its authorized reviewer. ![Expense Claims: the status filter (1), search (2) and a claim to open (3).](https://media.czappstudio.com/screens/docs/expense-claims/light-f26eb2efa6-2880.webp) Date filters match the dates of expense items. A claim may contain items from different days. The list displays the total for the complete claim. Statuses are **Draft**, **Submitted**, **Returned for correction**, **Approved**, **Rejected**, and **Cancelled**. A returned claim is waiting for the employee to correct and resubmit it. An approved claim also shows whether reimbursement has been recorded. See [Claim details](https://czappstudio.com/docs/administration/expenses#section-2) and [Recording reimbursement](https://czappstudio.com/docs/administration/expenses#section-5). ## Expense claim details Open a claim from **Expenses → Expense Claims**. This feature is included in core HR and requires expense permissions. The detail shows the employee, claim title and notes, total amount, status, receipt items, and approval history. Each item has its own date, category, description, amount, and receipts. Receipts are private and require access to the claim; use the claim's receipt download to get all of them in one archive. With the [Receipt scanning](https://czappstudio.com/docs/ai/receipt-scanning) add-on, each item can show **Receipt checks**: notices where the claimed amount or date differs from the receipt, a receipt could not be read, or the same receipt appears on another claim. A notice is a prompt to look, not a decision; the employee does not see these notices. ### Approve, return or reject Claims are reviewed in **Inbox → To do**, not from this page. 1. Review all items and receipts here. 2. Open **Inbox → To do** and find the claim. 3. Choose **Approve**, **Return for correction** or **Reject**, add remarks, and confirm. Return a claim when the employee can fix it, for example a missing receipt or a wrong category. A reason is required; the employee sees it, corrects the claim and resubmits it, and the new submission starts the approval workflow again. Reject a claim that should not be paid; the employee must then copy it to a new draft to claim again. The decision applies to the complete claim. Amounts cannot be reduced by the reviewer, and items cannot be held or approved separately. With multiple approval steps, the claim stays **Submitted** until the final step is complete. An employee cannot approve their own claim. A claim that has been withdrawn or already decided cannot be reviewed again. ### Record reimbursement For an approved claim, authorized users can choose **Mark Reimbursed**, choose the payment method, enter the reimbursement date and an optional payment reference, and confirm. A reimbursement recorded in error can be reversed. See [Recording reimbursement](https://czappstudio.com/docs/administration/expenses#section-5). ## Recording expense reimbursement Record reimbursement after the employee has been paid outside Open Core HR. This feature is included in core HR and requires expense permissions and reimbursement permission. 1. Open **Expenses → Expense Claims** and select an approved claim. 2. Choose **Mark Reimbursed**. 3. Choose the payment method: bank transfer, cash, payroll, cheque or other. 4. Enter the date reimbursement was made, today or earlier. 5. Optionally enter a payment reference. 6. Confirm. ![An approved claim: choose Mark reimbursed (1) to record payment.](https://media.czappstudio.com/screens/docs/expense-reimburse/light-3aa90a0e29-2880.webp) The claim keeps its approval history and records the reimbursement date, method, reference, and the user who recorded it. Employees can see that reimbursement has been recorded. Only approved claims can be reimbursed, and the same claim cannot be marked reimbursed twice. This action records the full claim amount; it does not initiate a bank transfer or record partial payments. If Payroll has reserved the claim, record the employee's payment in Payroll. The claim becomes reimbursed when the employee's full net pay is recorded; a partial payroll payment leaves it reserved. Reversing that payment reopens its reimbursement status. To pay a reserved draft item separately, first cancel the unfinalized payroll run. Do not enter the expense again as a manual payroll adjustment. ### Reverse a reimbursement Reverse a reimbursement that was recorded against the wrong claim or was not actually paid. 1. Open the reimbursed claim and choose **Reverse reimbursement**. 2. Enter the reason and confirm. The claim becomes approved and unpaid again, so it can be reimbursed later or picked up by Payroll. The reversed payment, its method and reference, the reason, and who reversed it stay in the claim's history and the audit log. Reimbursements recorded by Payroll cannot be reversed here; reverse the payment in Payroll instead. ## Expense categories Expense categories organize claims and define simple receipt and amount rules. This feature is included in core HR and requires expense permissions. Open **Settings → Master Data → Expense Categories**. The initial categories include Travel, Meals, Accommodation, Office Supplies, Communication, and Other. Edit them to match your organization. ### Create or edit a category 1. Choose **Add Category**, or edit an existing category. 2. Enter the name and optional notes. Leave **Code** blank to generate it when saving, or supply a custom code of up to 50 characters. The saved code is read-only. 3. Choose whether a receipt is required. 4. Optionally set a maximum amount per item. Leave it empty for no category limit. 5. Set the category to active or inactive, then save. ![Expense Categories: choose Add Category (1) to create one.](https://media.czappstudio.com/screens/docs/expense-categories/light-62b536f4b6-2880.webp) Amounts use your organization's currency. A limit applies to each expense item, not to the employee's daily or monthly spending. There are no designation, attendance, distance, or travel-class rules. Deactivate categories you no longer use. Existing claims keep their category and receipts. Categories referenced by claims cannot be deleted. Approval routing is configured in [Expense approvals](https://czappstudio.com/docs/administration/expenses#section-9), separately from categories. ## Expense approvals Expense claims use the shared approval workflow. This feature is included in core HR and requires expense permissions. Open the central **Approval Workflows** settings and select **Expense Approval**. The default workflow has one reporting-manager step. Configure the appropriate approver for your organization; additional steps can be added when needed. ### What approval means An employee submits a complete claim with one or more dated items. Approvers review the receipts and approve or reject the whole claim. Individual items do not have separate approval, hold, or adjusted-amount states. A claim remains **Submitted** until all required approval steps are complete. An employee cannot approve their own claim. The approval history records decisions and reviewer notes. Rejected claims remain unchanged. The employee can copy a rejected claim into a new draft, correct it, and submit the new claim. Approval does not record a payment. After reimbursement is made outside Open Core HR, an authorized user records it using [Mark Reimbursed](https://czappstudio.com/docs/administration/expenses#section-5). Receipt requirements and optional per-item limits are managed in [Expense categories](https://czappstudio.com/docs/administration/expenses#section-7). --- # Organization and master data Maintain the organization hierarchy, departments, designations and locations. Master data is the set of building blocks the rest of Open Core HR relies on — departments, designations, levels, locations, shifts, holidays, expense types and policies, and document types. You set these up once (and keep them tidy over time) so that everywhere else in the app — employee records, attendance, expenses, onboarding — can refer to them. These screens live in the left **menu** under **Settings**. Two of them sit directly under **Settings**, and the rest are grouped in a **Master Data** submenu. ## What's here Directly under **Settings**: - **Organization Hierarchy** — a read-only view of the org chart, reporting lines and departments. Under **Settings → Master Data**: - **Departments** — the departments in your organization, optionally arranged in a parent/child structure. - **Designations** — job titles, each optionally tied to a department. - **Locations** — your offices and sites. - **Shifts** — work-schedule definitions (start and end time plus working days). - **Holidays** — public and company holidays per location, with import and bulk tools. - **Expense Categories** — the kinds of expenses people can claim, with receipt requirements and optional per-item limits. - **Document Types** — the documents employees must provide (ID proof, certificates, and similar). > **Note:** You only see the items your role gives you access to. If something described here isn't in your menu, ask an administrator. ## Organization hierarchy The **Organization Hierarchy** screen gives you a read-only picture of how your organization is structured — reporting lines and departments. Open it from the left **menu** under **Settings → Organization Hierarchy**. It pulls everything from your employee records and departments, so there's nothing to edit here directly. ### Finding reporting relationships Search by name, code, designation, or department. Use **Org Chart** or **Reporting Tree** to follow reporting relationships, or **By Department** to find employees and department heads. ### Steps 1. Open **Organization Hierarchy** under **Settings**. 2. Pick the tab that matches what you want to see — the chart, the reporting tree, or a grouping by department or level. 3. Type a name, code, designation, or department in the search box to highlight matching people and trim the view to just them and their reporting line. 4. Click any person's name to open their employee profile. ![Organization Hierarchy: pick a view (1) and search for people (2).](https://media.czappstudio.com/screens/docs/org-hierarchy/light-0cc55d5259-2880.webp) ### Tips - If the chart looks empty or incomplete, check that employees have a **reporting to** manager and a **department** set on their records — that's what builds this view. - The search affects the Reporting Tree and By Department tabs. ## Departments Departments are the org units you assign people to. You can keep them as a flat list or arrange them in a parent/child structure. Open the screen from the left **menu** under **Settings → Master Data → Departments**. ### Adding a department 1. Click **Add department**. 2. In the **Add Department** panel, enter a **Name**. 3. Optionally enter a **Code**, or leave it blank to generate one. 4. Optionally pick a **Parent Department** — choose **No Parent** for a top-level department. 5. Optionally add **Notes**. 6. Use the **Status** switch to set whether the department is active. 7. Click **Create**. ![Add Department panel: enter the name (1), optionally choose a parent (2), then Create (3).](https://media.czappstudio.com/screens/docs/department-form/light-a7231ae310-2880.webp) ### Editing or removing a department - Click the pencil icon on a row to open the **Edit Department** panel, make your changes, and click **Update**. When editing, the department itself and any departments beneath it won't appear in the **Parent Department** list (so you can't create a loop). - Click the delete icon and confirm in the **Delete Department** dialog to remove it. This cannot be undone. ### Tips - Use the search box above the list to find a department by name or code. - A department's place in the parent/child structure is what builds the **By Department** view on the Organization Hierarchy screen. ### Codes Code is optional when creating a record. Leave it blank to generate a code when saving, or supply an existing code of up to 50 characters. Custom codes use uppercase letters, digits, hyphens and underscores; surrounding whitespace is removed. Once saved, the code is read-only and remains reserved when the record is deleted. ## Designations Designations are the job titles you assign to employees — for example "Sales Executive" or "HR Manager". Each one can be linked to a department. Open the screen from the left **menu** under **Settings → Master Data → Designations**. ### Adding a designation 1. Click **Add designation**. 2. In the **Add Designation** panel, enter a **Name** and optionally a **Code**. 3. Optionally choose a **Department**. 4. Optionally add **Notes**. 5. Use the **Status** switch to set whether the designation is active. 6. Click **Save**. ### Editing or removing a designation - Open **More actions → Edit** on a row to open the **Edit Designation** panel, make your changes, and click **Update**. - Open **More actions → Delete** and confirm in the dialog ("This will permanently delete the designation") to remove it. ### Tips - Use the search box above the list to find a designation by name or code. ### Codes Code is optional when creating a record. Leave it blank to generate a code when saving, or supply an existing code of up to 50 characters. Custom codes use uppercase letters, digits, hyphens and underscores; surrounding whitespace is removed. Once saved, the code is read-only and remains reserved when the record is deleted. ## Locations Locations are your offices and sites. They're used in other parts of the app — for example holidays are set per location, and company policy documents are attached to a location. Open the screen from the left **menu** under **Settings → Master Data → Locations**. ### Adding a location 1. Click **Add New**. 2. In the **Add Location** panel, enter a **Name**. 3. Optionally enter a **Code**, or leave it blank to generate one. 4. Optionally add **Notes** and an **Address**. 5. Use the **Status** switch to set whether the location is active. 6. Click **Save**. ### Editing or removing a location - Click the pencil icon on a row to open the **Edit Location** panel, make your changes, and click **Update**. - Click the delete icon and confirm in the dialog ("This will permanently delete the location") to remove it. ### Tips - Use the search box above the list to find a location by name or code. - Keep codes short and consistent — they show up alongside the location name in other screens, such as the **Location** picker on the Holidays screen. ### Codes Code is optional when creating a record. Leave it blank to generate a code when saving, or supply an existing code of up to 50 characters. Custom codes use uppercase letters, digits, hyphens and underscores; surrounding whitespace is removed. Once saved, the code is read-only and remains reserved when the record is deleted. --- # Shifts and holidays Define work shifts and maintain the holiday calendar. ## Shifts A shift defines working days, attendance eligibility and a fixed or flexible schedule for any employee, including field employees. Open the screen from the left **menu** under **Settings → Master Data → Shifts**. ### Adding a shift 1. Click **Add New**. 2. In the **Add Shift** panel, enter a **Name**. Leave **Code** blank to generate it when saving, or supply your own code. 3. Optionally add **Notes**. 4. Choose fixed or flexible scheduling, set the late-arrival grace period, and set different **Start Time** and **End Time** values. An end time earlier than the start time means the shift ends the next day. All shift times use the application timezone. 5. Under **Working Days**, tick at least one day this shift runs (**Sun** through **Sat**). 6. Use the **Status** switch to set whether the shift is active. 7. Choose an attendance policy or inherit the default. Set **Attendance enabled** and **Allow multiple check-ins per day**. These settings apply to employees assigned to this shift. 8. Optionally enable **Default shift**. A default must be active; choosing a new default replaces the previous one. 9. Click **Create**. ![Add Shift panel: enter the name (1), tick working days (2) and choose Create (3).](https://media.czappstudio.com/screens/docs/shift-form/light-4d5edcb017-2880.webp) ### Editing or removing a shift - Open **More actions → Edit** on a row to open the **Edit Shift** panel, change the details (the **Code** remains read-only), and click **Update**. - Open **More actions → Delete** and confirm to remove a shift. First reassign employees who use it and choose another default if needed. Assigned or default shifts cannot be deleted or deactivated. Attendance history is retained. ### Tips - Use the search box above the list to find a shift by name or code. ### Attendance policy An active employee needs an active assigned shift (or the active default when no shift is assigned) with attendance enabled and permission to record their own attendance. The Employee preset supplies that permission. Adding an administrative role does not enroll a person for attendance. When multiple check-ins are disabled, employees can complete one session per work date. Overnight attendance belongs to the date the shift starts, including checkout after midnight. Full-day, half-day and hourly leave for an overnight shift use that same work date. When enabled, they can start another session after checking out. Two overlapping sessions are never allowed. The same rules apply to web and mobile. An explicit inactive shift assignment disables attendance; it does not fall back to another shift. Working days determine which days count toward leave. Fixed shifts evaluate lateness against the scheduled start and grace period. Flexible shifts retain a work-date window without treating a late start as fixed-shift lateness. Working hours come from recorded sessions and breaks. Use **Assignments** to schedule an employee's shift from an effective date. A dated assignment takes priority over their recurring employee shift. Open attendance keeps its original schedule when an assignment changes. Review overnight times in the deployment timezone before assigning them. Leave days, weekly offs in attendance reports and daily attendance use the shift in force on each date, so a dated assignment changes only the days from its effective date. You can remove an assignment that has not started yet; one already in force is replaced by adding a new assignment. Employees receive an in-app and push notification with the effective date when an assignment is added, changed or removed, when their recurring shift changes, or when the start time, end time, mode or working days of the shift they are on today change. [Attendance policies](https://czappstudio.com/docs/administration/attendance#section-13) control recording channels and verification rules independently from shift hours. ### Codes Code is optional when creating a record. Leave it blank to generate a code when saving, or supply an existing code of up to 50 characters. Custom codes use uppercase letters, digits, hyphens and underscores; surrounding whitespace is removed. Once saved, the code is read-only and remains reserved when the record is deleted. ## Holidays The **Holidays** screen is where you record public and company holidays for each location. Open it from the left **menu** under **Settings → Master Data → Holidays**. ### Finding holidays Filter by **Year** and location to review the holidays that apply. ### Adding a holiday 1. Click **Add Holiday**. 2. In the **Add Holiday** panel, enter a **Name**. 3. Pick the **Date**. 4. Choose a **Location** — or pick **All Locations** to add the holiday to every location at once. 5. Set the **Status** to **Active** or **Inactive**. 6. Optionally add **Notes**. 7. Click **Create**. ### Editing or removing a holiday - Open the holiday's row actions menu and choose **Edit**, make your changes, and click **Update**. - Choose **Delete** from the row actions menu and confirm in the **Delete Holiday** dialog to remove it. This cannot be undone. ### Importing holidays Open **Import & Export** and choose **Holidays** under imports. Permission to create holidays is required. Download the current template and enter one holiday per row, using an existing active location's code and an unambiguous date. Create the locations first; importing holidays does not create them. Duplicate dates for the same location are rejected. Upload and validate the file, correct all reported row errors, then confirm the import. Validation does not save holidays. Check **History** for the result before uploading the same holidays again. See [Importing a spreadsheet](https://czappstudio.com/docs/administration/import-export#section-3) for the full workflow. ### Bulk actions 1. Tick the holidays you want to change. The header checkbox selects the current page only, up to 100 holidays. 2. Choose **Activate Selected**, **Deactivate Selected**, or **Delete Selected** from the selection bar. For deletion, confirm in the **Delete Selected Holidays** dialog. ![Holidays: Add Holiday (1), or tick holidays (2) for bulk actions.](https://media.czappstudio.com/screens/docs/holidays/light-967e34e945-2880.webp) Selection and actions are available according to your edit and delete permissions. Use **Clear selection** to start again. Changing the search, filters, sort order, page or page size, or refreshing the list clears your selection. Each batch is saved together. If a selected holiday is no longer available, nothing in the batch changes; refresh the list and select again. Other failures keep your selection available for retry. The result reports the number actually changed, so activating holidays that are already active does not count them again. ### Tips - Use **Filters** to choose a year and location together, then apply them to review one site's holidays. - Use the search box above the list to find a holiday by name. ### Codes Code is optional when creating a record. Leave it blank to generate a code when saving, or supply an existing code of up to 50 characters. Custom codes use uppercase letters, digits, hyphens and underscores; surrounding whitespace is removed. Once saved, the code is read-only and remains reserved when the record is deleted. Choosing all locations generates a separate code for each location. A custom code can only be supplied for a single location. --- # Import and export Import spreadsheets and setup data, export records and download files from transfer history. Open **Import & Export** in the workspace to upload spreadsheets, generate files and reports, and review transfers. This standard module requires the relevant permissions for each data type, including separate access to employee private details and pay. Start all imports and exports here. Set the scope in this module before requesting a file; filters on Employees, Leave Management or another page are not carried over. ## Choose the right transfer | Data | Import purpose | Export purpose | | --- | --- | --- | | Departments, designations, locations, shifts and leave types | Create setup records | Export setup, optionally by status | | Module categories and types | Create asset, expense and policy categories, document types and warning types | Export setup for enabled modules | | Employees | Create new employees from a spreadsheet | Download employee records with the filters and permitted columns you select | | Holidays | Create holidays for existing locations | Export by year, location and status | | Leave balances | Set initial leave entitlements for the chosen year | Download initial entitlements for the chosen year | | Assets | Create asset records when Asset Management is enabled | Export the register by category and status | | Policies manual | — | Generate a PDF of current published policy content; drafts and expired policies are excluded | | Attendance, leave and expense reports | — | Generate a report for a month or date range; expense reports require Expenses | | Job postings, applicants and tasks | Create draft postings, new applicants and new tasks through their normal creation rules | Export their operational registers | | Other operational registers | — | Export recruitment, employee lifecycle, loans, tasks, documents, assets, policies, disciplinary records, compensatory offs, actionable approvals and audit metadata | Read the relevant data guide before preparing a file. Importing leave entitlements preserves usage and adjustment history; it does not directly replace available balances. Use [Importing setup data](https://czappstudio.com/docs/administration/import-export#section-8) for dependencies and field decisions, [Choosing export data and scope](https://czappstudio.com/docs/administration/import-export#section-12) for coverage and permissions, [Importing a spreadsheet](https://czappstudio.com/docs/administration/import-export#section-3) for validation and confirmation, [Generating reports](https://czappstudio.com/docs/administration/reports) for report options, and [Transfer history and downloads](https://czappstudio.com/docs/administration/import-export#section-17) for results, cancellation and recovery. ## Access and privacy History contains your own transfers. Required module access and data permissions are checked again at execution and download. A permission change or disabled source module can therefore prevent a previously available transfer. Downloads contain a snapshot of data at generation time. Later edits do not update a file you already downloaded. Store and share employee, leave and expense files only with people entitled to see their contents. Files are retained for at most seven days after the transfer request; successful or cancelled imports release their source file earlier. History remains available after files expire. Letters, individual policy attachments and other files already attached to a record remain available from that record. ## Importing a spreadsheet Use an import when you have many supported records to create or initial leave entitlements to set. You need permission for the selected operation and access to its source module. Preparing or validating a file does not change business records; confirmation starts the import. ### Prepare and validate 1. Open **Import & Export**, choose an import data type, and download its current template. 2. Fill the template with your data, replacing example rows if provided. Keep the template headings, use one record per row, and create any required departments, locations, leave types or asset categories first. 3. Select a CSV, XLS or XLSX file and any required options, such as the leave entitlement year. Check the limits for that source. The overall limits are 10 MB and 1,000 records per file; a source can have a lower limit. Assets allow at most 170 records per file. 4. Validate the file. Review the preview and row errors before continuing. Validation errors block confirmation for the whole file; they do not cause the other rows to be applied. 5. Correct errors in the original spreadsheet, upload the corrected file and validate it again. Download the error report when you need to work through several problems. ![Import & Export: on Imports (1), download the template (2), then choose your file and Validate and preview (3).](https://media.czappstudio.com/screens/docs/import-export/light-cf5d1ab773-2880.webp) The preview helps check the proposed operation and a sample of its data. It is not evidence that the records have been saved. Read the total row count and validation result as well as the sample. ### Confirm and check the result Confirm only after the file, operation and options are correct. The import is queued, and you can follow it in **History**. Rows are applied together; an invalid row prevents the file from being applied. Wait for completion and review the result before starting another upload of the same data. Validation runs against current records. A change after preview, such as another person creating the same employee or changing a required category, can make the confirmed import fail. Review the error, refresh any changed reference data, then upload and validate a corrected file. Imports are not automatically retried. If a job fails or its outcome is unclear, check its history and the destination records before submitting again. A slow worker or missing invitation email does not mean an employee was not created. See [Transfer history and downloads](https://czappstudio.com/docs/administration/import-export#section-17) for pending, failed and expired transfers. You may cancel an import while it is awaiting confirmation or queued. Once processing starts, cancellation is unavailable. Completed imports have no automatic undo; correct records through the relevant management pages. ### Creating job postings, applicants and tasks These imports create the starting record for a workflow; they cannot import approvals, completion, hiring or other later states. Use the current template, the same 10 MB/1,000-row file limits, and the validation/confirmation steps above. Unknown columns are rejected. Existing records are never updated by these imports. #### Draft job postings With Employee Lifecycle enabled and **manage job postings** permission, import a title and description for each new vacancy. Optional department, designation and location references use existing codes. Create that setup data before validating the file. Openings default to `1`. Optional salary minimum/maximum values require a pay period: `hourly`, `daily`, `weekly`, `monthly` or `yearly`. A blank currency uses the deployment currency when salary is supplied. Closing and expected-joining dates, when supplied, use `YYYY-MM-DD` and must be today or later. Every imported posting starts as **Draft** with its own generated URL identifier. Review it in recruitment and publish it through the normal workflow. Importing does not publish vacancies automatically, and uploading the same title again can create another draft; check history before repeating a completed upload. #### New applicants With Employee Lifecycle enabled and **conduct interviews** permission, provide the applicant's name and email. Use an existing `job_posting_slug` to associate a vacancy, or leave it blank for a general application. Optional fields are phone, current location, cover letter and source. Source defaults to `manual`; other accepted values are `referral`, `agency` and `other`. Applicants start as **New**. An active application with the same email and vacancy, including a repeated row in the file, is rejected. Emails are normalized to lowercase. The import does not upload CVs, send candidate messages or set interview/hiring outcomes. Keep CV files and later recruitment actions in their normal workflows. #### New tasks With Task enabled, the normal task-creation policy applies. Provide a task name, another active employee's `assigned_to_code` and a due date of today or later. Dates use `YYYY-MM-DD`; optional due time uses `HH:MM`. Priority defaults to `medium`, attachment requirement to `0`, and recurrence to `never`. For recurring tasks choose `daily`, `weekly` or `monthly`, and provide a recurrence end date after the first due date. In addition to the row limit, the whole file may generate at most **1,000 recurring instances**. Shorten the recurrence period or split the tasks into smaller files when validation reports this limit. Tasks start as **New** and create their normal recurring instances. Voice recordings and file attachments are not imported. Importing the same task details again can create another task, so check completion before repeating an upload. Mark completion and record task updates through the Task workflow. ### Data-specific guidance - [Setup data](https://czappstudio.com/docs/administration/import-export#section-8): departments, designations, locations, shifts, leave types and module categories/types. - [Employees](https://czappstudio.com/docs/administration/employees#section-6): required fields, role assignments, private details and compensation. - [Holidays](https://czappstudio.com/docs/administration/shifts-and-holidays#section-11): location references and holiday dates. - [Leave entitlements](https://czappstudio.com/docs/administration/leave-types-and-balances#section-14): year, employee identity and initial balance rules. - [Assets](https://czappstudio.com/docs/modules/assets#section-9): categories, statuses, duplicates and the row limit. ## Importing setup data Use setup imports to create departments, designations, locations, shifts, leave types and the categories used by enabled modules. They create new records only. To change an existing record, use its management page; uploading its code again produces an error rather than an update. ### Prepare dependencies first 1. Import parent departments before their children. A parent in another row of the same file does not yet exist during validation. Import designations after their referenced departments. 2. Create locations and shifts before importing employees, and locations before holidays. 3. Create leave types before importing entitlements. If a leave type deducts from another type, create the referenced type first. 4. Enable the relevant module before importing its setup data. Create asset categories before assets. Any approval workflow referenced by a category must already exist; create workflows through Approval Workflows. Download the current template from **Import & Export** for each data type. Some templates contain headings only. Keep those headings and one record per row; remove helper columns, internal IDs, totals and extra worksheets. Unknown columns are rejected for setup imports. Files accept CSV, XLS or XLSX, up to 10 MB and 1,000 data rows. Use `1` and `0` for boolean fields, and `active` or `inactive` for status. Preserve identifiers as text so spreadsheet software does not remove leading zeroes. Use codes rather than database IDs for department and leave-type references. ### Field decisions | Data | Required decisions and reference rules | | --- | --- | | Departments | Provide a unique `code` and `name`. Optional `parent_department_code` must already exist. | | Designations | Provide a unique `code` and `name`. Optional `department_code` must already exist. | | Locations | Provide a unique `code` and `name`; address and notes are optional. | | Shifts | Provide a unique code, name, different start/end times and all seven weekday flags. At least one day must be enabled. Use `HH:MM` or `HH:MM:SS`. Overnight shifts can end earlier than they start. Imports cannot change the default shift; keep `is_default` at `0`, then select the default on Shifts. | | Leave types | Provide a unique code and name. `auto_deduct_from`, when supplied, must name an existing leave-type code. Blank monthly/yearly limits mean no limit; `0` remains an explicit zero limit. | | Asset categories — Asset module | Provide a unique name. A blank slug is derived from the name. A supplied `approval_workflow_code` must exist. `has_accessories` controls accessory handling, not an accessory inventory import. | | Expense categories | Provide a name. Supply a unique code or leave it blank for allocation. `max_amount` is an optional positive amount with at most two decimal places; blank means no category maximum. | | Document types — Documents module | Provide a name. Supply a unique code or leave it blank for allocation. `is_required` and `is_legal` set the submission rules. PDF templates are attached through Document Types after creation. | | Policy categories — Policies module | Provide a unique name. The URL identifier is derived from it; names that produce an existing identifier are rejected. Color, icon, description and sort order are optional. | | Warning types — Disciplinary Actions module | Provide a unique name. Severity is `low`, `medium`, `high` or `critical`; appeal deadline is 0–365 days. Review acknowledgment and appeal settings before confirmation. | Blank status defaults to active. For shifts, attendance is enabled and multiple check-ins are disabled by default. For leave types, deductible defaults to `1`; proof, compensatory-off, short-leave and advance-notice flags default to `0`. For module setup data, blank booleans default as follows: asset accessories `0`, expense proof `0`, document required/legal `0`, and active flags `1`. Policy sort order and expense display order default to `0`. Warning severity defaults to low, appeal deadline to `0`, and acknowledgment requirement to `1`. Enter explicit values where these defaults do not match your policy. ### Validate before applying Follow [Importing a spreadsheet](https://czappstudio.com/docs/administration/import-export#section-3) to validate and confirm. The entire file must pass; there are no silently skipped or partially applied rows. A preview does not allocate codes or create records. Confirmation rechecks permissions and current references before applying the rows together. If a duplicate is reported, check whether the record already exists or another row repeats its identifier. A deleted record may still reserve its code or slug. Do not change an identifier merely to force the same record through again. Correct the original data, or edit the existing record through its management page. An export is useful for checking existing setup and preparing a different installation. It is not an update file or a full backup. Keep dependency order, remove records already present at the destination, and validate against that destination's current template. ## Choosing export data and scope Choose a data source under **Import & Export**, set its scope and format, then request the file. Download it from your transfer history when processing finishes. All tabular sources support XLSX and CSV; leave entitlements also support PDF, and the policy manual is PDF only. The available sources depend on enabled modules and your existing permissions. Exports preserve the visibility rules of the underlying data, including team, employee and legal-document restrictions. A broad report permission does not grant access to another domain. ### Setup and employee data | Source | Available scope | | --- | --- | | Departments, designations, locations, shifts, leave types | Active/inactive status | | Asset, expense and policy categories; document and warning types | Active/inactive status; requires the corresponding module | | Employees | Department, designation, location, account status, employment status and permitted columns | | Holidays | Year, location and active/inactive status | | Leave balances | Entitlement year; these are initial entitlements, not remaining available leave | | Assets | Category and status; this register does not include assignment history | Setup, holiday and asset register exports also allow at most 10,000 records. Select a status, year, location or category where available to reduce the result. A request over the limit fails rather than omitting rows; if the available filters cannot reduce it enough, use another supported reporting scope or contact your administrator. Setup exports use their template fields. The asset register, employee export and operational registers are reporting files; do not assume they can be uploaded unchanged as import templates. ### Operational registers These sources export existing workflow records. Job postings, applicants and tasks also support [creation imports](https://czappstudio.com/docs/administration/import-export#section-6), starting as Draft or New. Other operational registers are export-only. Approve, issue, acknowledge, hire, settle or complete records through their normal workflows; spreadsheet imports cannot set those outcomes. Operational registers accept inclusive from/through dates and, where offered, status. The date meaning differs by source. They allow at most 10,000 matching records; a larger request fails with guidance to narrow the scope instead of returning a truncated file. | Source | Date scope and important limits | | --- | --- | | Compensatory offs | Worked date; permitted employee scope | | Approval inbox | Creation date; only currently actionable pending approval steps available to you | | Audit log | Creation date; actor, record identity and event metadata only, without changed values, URLs or user agents | | Employee document register — Documents | Submission creation date and status; no document numbers, review notes or file contents | | Policy register — Policies | Creation date; version/publication metadata, without policy text or attachments | | Policy acknowledgments — Policies | Assignment date and status; assigned versions, deadlines and acknowledgments | | Asset assignments — Asset | Assignment date; includes assignment and return details | | Asset return requests — Asset | Request creation date; request/completion information | | Asset maintenance — Asset | Performed date; maintenance work, costs and next due dates | | Warnings — Disciplinary Actions | Issue date and status; no evidence files or private statements | | Warning appeals — Disciplinary Actions | Submission date and status; no evidence or appeal statements | | Job postings — Employee Lifecycle | Creation date and status | | Applicants — Employee Lifecycle | Application date and status | | Interviews — Employee Lifecycle | Scheduled date and interview outcome | | Offer and appointment registers — Employee Lifecycle | Creation date and status; no letter contents or compensation details | | Onboarding and probations — Employee Lifecycle | Creation date and status | | Employment changes — Employee Lifecycle | Effective date; no compensation details | | Separations and final settlements — Employee Lifecycle | Creation date and status; settlement data requires settlement access | | Loans — Loan | Creation date and status; permitted employee scope | | Loan repayments — Loan | Repayment date and status; permitted loan scope | | Tasks — Task | Due date and status; permitted task scope | | Recurring task instances — Task | Scheduled date and status; permitted parent-task scope | For attendance, leave and expense reporting, use the report sources with a month or date range of at most 93 inclusive days. The policy manual exports current published policy content; use the separate policy register when you need version metadata instead of the manual. ### Permissions and sharing Setup imports require the corresponding create/manage permission; exports require the corresponding view/manage permission. Employee imports and exports have separate capabilities. Leave-type exports require create or edit leave types; leave-entitlement transfers require manage leave balances. Warning-type transfers require manage warning types. Asset assignments and return requests require both view assets and view all asset assignments. The asset register and maintenance require view assets. Policy exports require view policies; category exports also allow manage policy categories. Document types require view document types; the employee document register requires view employees or verify legal documents and still respects legal-document visibility. Expense categories allow manage expense types, view expenses or view team expenses. Operational exports use their existing view permissions, except job postings and onboarding, which require their manage permissions. Job-posting imports require manage job postings, applicant imports require conduct interviews, and task imports follow the normal active-user task-creation policy. Export permission alone does not authorize applicant imports. Reports require view reports plus access to the corresponding attendance, leave or expense data. Employee private details and compensation retain separate checks. Transfers grant no new roles or permissions. A revoked permission can stop a queued transfer or prevent a later download. Review file recipients and storage, particularly for applicant, employee, financial or disciplinary records. See [Transfer history and downloads](https://czappstudio.com/docs/administration/import-export#section-17) for expiry and recovery. ### What these files do not replace Use normal record pages for attachments, issued letters and binary document templates. Chat, mail, feed and other communication content, security/role configuration, API credentials, integrations, application configuration and technical backing logs are outside spreadsheet transfer coverage. Use the documented backup procedure when you need a complete recoverable installation. ## Transfer history and downloads Open **Import & Export → History** to follow your imports and exports. History belongs to the person who requested the transfer. You must still have the required data permissions and source module access to inspect or download its contents. ### Understand a transfer's status | Status | What to do | | --- | --- | | Ready for review | The import passed validation but has not been applied. Review it and confirm when ready. | | Needs correction | Validation found problems. Download the errors, correct the spreadsheet and validate a new upload. | | Queued | The transfer is waiting for a worker. Avoid submitting the same import again. | | Processing | Work has started. Wait for a final result; cancellation is unavailable. | | Completed | Review the import result, or download the generated export. | | Failed | Read the error and resolve its cause before making a new request. Check destination records before repeating an import. | | Cancelled | Work was stopped before processing. Create a new request if it is still needed. | | Expired | The file is no longer available. Request a new export, or re-upload and validate an unconfirmed import. | You may cancel transfers that are ready for review, need correction or are queued. Cancellation does not reverse completed changes. Refresh history to obtain the latest state before deciding whether a transfer needs attention. ### Download and retain files Download a completed export before its expiry shown in History, seven days after the request. Uploaded source files and error downloads have the same maximum retention; a successful or cancelled import releases its source file earlier. History remains after files expire. Expiry does not undo an import or change the records from which an export was generated. If a download is denied, ask an administrator to check your current permissions and whether the source module remains enabled. Do not use another person's download link: the file is restricted to its requester. ### Recover from a failed or delayed transfer For validation problems, correct the indicated rows and submit a fresh upload. For an export error, correct its filters or ask an administrator to investigate, then request it again. Imports do not retry automatically. If transfers remain pending, ask the server administrator to check the [queue worker](https://czappstudio.com/docs/installation/services#section-2). If an import stops during processing, review the destination records before repeating it. Do not assume refreshing the page or closing the browser cancels server work. --- # Generating reports Generate reports from the data you are permitted to see. Generate downloadable attendance, leave and expense reports from **Import & Export**. Report access and permission to view the relevant attendance, leave or expense records are both required. Expense reports are included in core HR. ## Steps 1. Open **Import & Export** and choose the report in the export data types. 2. Choose **Month** and a month, or **Date range** and the start and end dates. A custom range can cover at most 93 days, including both dates; split a longer period into separate reports. 3. Optionally select an employee to narrow the report. Review the filters before requesting it; filters from other workspace pages do not carry over. 4. Choose XLSX or CSV and request the export. The file is generated in the background. 5. Open **History** to check the result and download the completed file. See [Transfer history and downloads](https://czappstudio.com/docs/administration/import-export#section-17). ![Exports: choose the report in Data to export (1), pick a file format (2) and Generate export (3).](https://media.czappstudio.com/screens/docs/reports/light-1de871357f-2880.webp) ## Choose a report - **Attendance report** includes attendance records, check-in/out times and working hours. - **Leave report** includes leave requests overlapping the selected period. Use it for requests and their status; use the leave entitlement export for initial annual entitlements. - **Expense report** includes expenses dated within the selected period. You can leave the page while a report runs. Check the result before sharing it: exports are snapshots, and later record changes do not update a downloaded file. Download before the expiry shown in History, seven days after the request. --- # Settings Configure general, security, code prefix, localisation, signature and app update settings. The **Settings** screen is where you manage company-wide options for the whole workspace. Open **Settings** from the application navigation. ## Choose the settings to change ![Settings: choose a tab (1) and save your changes (2).](https://media.czappstudio.com/screens/docs/settings-general/light-6c646dc95c-2880.webp) Choose the section for the settings you need. Some sections require an enabled module: - **General** — company information (legal business name, address, phone, email), the two **Attendance** check-in rules, and the **Letter Signatory** (name, designation, and signature image used on generated lifecycle letters). - **Brand settings** — the web product name, logos, colors, login text, footer, help/legal links, email logo and default document logo. See the instructions below. - **Security** — Google reCAPTCHA for web login, with separate v2 and v3 configuration. See the setup steps below. - **Localisation** — currency and number formatting, timezone, date and time formats, distance unit, dialling code and the shortest and longest phone number accepted. - **Code Prefix** — the prefixes used to build codes for employees, departments, designations, locations, shifts and holidays, plus enabled module masters. - **Recruitment** — the HR notification email addresses for new applications, the careers website address used in application tracking links, when missed interviews are reported, and when probation-ending reminders are sent. - **Mobile App** — minimum app versions and force-update options for iOS and Android, plus maintenance mode and its message. - **Mail** — how email is sent: provider, SMTP credentials, sender name and address, and a test email. See [Mail settings](https://czappstudio.com/docs/administration/mail-storage-and-notifications#section-1). - **Push notifications** — the Firebase service account used for mobile push notifications. See [Push notifications](https://czappstudio.com/docs/administration/mail-storage-and-notifications#section-5). - **AI** — the connection to your AI provider (Claude, Gemini, OpenAI or a self-hosted model) and its connection test. Switches, access and limits are on the **AI** menu. See [AI in Open Core HR](https://czappstudio.com/docs/ai/overview). - **Storage** — file storage connections, the active provider and upload limits. See [Storage settings](https://czappstudio.com/docs/administration/mail-storage-and-notifications#section-6). - **Expenses** — the maximum age of an expense, in days, when it is submitted. Items dated earlier are refused at submission; drafts are still saved. Enter 0 for no limit. The limit applies on web and mobile. - **Joining and exit tasks** — the default tasks added to every onboarding and separation, and which of them must be done before completion. Requires the Employee Lifecycle module. See [Default joining and exit tasks](https://czappstudio.com/docs/modules/employee-lifecycle#section-36). - **HR assistant** — what Ask HR answers from, whether it may prepare requests, and the questions it could not answer. Requires the HR assistant add-on. See [HR assistant](https://czappstudio.com/docs/ai/hr-assistant). - **Feed** — birthday, work anniversary and optional welcome posts, automatic posting or review through Approvals, and the notification audience. Requires the Feed module. - **Calls** — Agora credentials, call token lifetime and when unanswered calls become missed. Requires the Calls module. - **Loans** — loan number prefix, maximum repayment period, deduction day and automatic closing. Requires the Loan module. - **Webhooks** — delivery timeout, retries and log retention. Super administrators only; requires the Webhooks module. Each tab has its own **Save Changes** button, so you save one tab at a time. ## Customize your web branding You need permission to manage settings to save or reset branding. Branding applies to the whole installation. It does not change the mobile application or the legal business name in **General**. 1. Open **Settings → Brand settings**. 2. Enter the product name and any custom login text. Leave the login heading or tagline blank to use the translated defaults. 3. Choose logos for light and dark backgrounds, and a square browser/navigation icon. Upload a PNG or JPG, or choose an image from your media library. Images must be no larger than 2 MB or 4096 × 4096 pixels. A library selection becomes a separate branding copy. 4. Set the colors and default theme. The preview shows unsaved changes; it does not change the application until you save. A user's own theme choice takes precedence over the default. 5. Set any support, privacy, terms and help links, then select **Save changes**. Refresh another open browser tab to see the updated branding. No build or code change is needed. ![Brand settings (1): logos, colours and links, saved with Save changes (2).](https://media.czappstudio.com/screens/docs/settings-brand/light-e2e4b75257-2880.webp) Saved brand images are publicly accessible so they can appear before login and in emails. Upload only images intended for public display. Private employee files remain protected. The footer accepts `{year}` and `{brand}` placeholders. Leave it blank for the default product-name copyright text. Turning off the copyright footer keeps configured support and legal links available. Use complete HTTPS URLs for links. A custom help URL is used directly, including for old `/docs` bookmarks; it does not add a documentation path. Leaving it blank uses the installation's documentation destination. Changing this link does not rebrand the externally hosted manual. Under **Email & documents**, you can select separate email and document logos. They use the light-background logo when no separate image is selected. The email sender name and address are set in [Mail settings](https://czappstudio.com/docs/administration/mail-storage-and-notifications#section-1). The document logo appears on newly rendered plain letters, payslips and policy manuals. Existing letterheads, employer details and saved PDFs are preserved. Replacing a logo does not rewrite previously generated files. **Reset branding** restores Open Core HR's default branding and removes the installation's custom branding copies. It keeps company details, letterheads and original media-library files. If saving fails, keep the draft open, correct any field errors or storage connection problem, and try again. ## Protect web login with Google reCAPTCHA You need permission to manage settings. Protection is off initially and applies to web login, including demo sign-in buttons. Mobile app login, password recovery and public forms do not use it in this release. 1. Open **Settings → Security**. Choose **Google Cloud** for a new integration, or **Classic site key and secret key** for an existing compatible integration. Your server administrator can help create the [Google credentials](https://czappstudio.com/docs/installation/configuration#section-3). 2. Enter the allowed hostnames, one per line, such as `hr.example.com`. Do not enter a protocol, port, path or wildcard. The current browser hostname must be listed here and allowed in Google's key settings. For Google Cloud, enter the project ID and restricted server API key. 3. Choose one **reCAPTCHA version** and enter its site key. The selected version applies to every protected area. **v2 — Checkbox** asks the visitor to complete a checkbox challenge. **v3 — Score-based** runs when the visitor submits the form; scores below **Minimum v3 score** are rejected. Start at `0.5` and review real traffic in Google before adjusting. Classic connections also require its matching secret key. 4. Select **Test V2** or **Test V3** for your chosen version. Complete the checkbox when shown, then select **Verify configuration**. This verifies the draft on the current hostname without changing active protection. 5. Under **Protected areas**, enable **Web login**. Turn on **Enable reCAPTCHA**, then select **Save** within ten minutes of a successful test. 6. Keep your current administrator session open and check sign-in in a separate private browser window. Only the selected version is active. Previously entered keys are retained when you switch versions or connections; switching does not require you to configure both versions. Saved secrets are never shown again. Leave a secret field blank to retain it; use **Remove saved credential** to clear it. Changing a key, connection, hostname list or the applicable v3 threshold requires another test before saving with protection enabled. Saving a disabled configuration is allowed without a test. If a test fails, check the key type, credentials and domain restrictions. For Cloud connections, also check that the reCAPTCHA Enterprise API is enabled and that the project can create assessments within its current quota. A successful setup test does not guarantee every visitor will pass v3; the score depends on the individual attempt. If verification becomes unavailable, sign-in is blocked while protection is enabled. Signed-in administrators can disable **Enable reCAPTCHA** and save. If nobody can sign in, use the [server recovery command](https://czappstudio.com/docs/installation/backups-and-updates#section-3). If another administrator changes these settings while you edit, reload and review your draft before saving. ## Publish a landing page Requires the **Landing Page** feature and permission to **Edit and publish landing page**. A super administrator enables it from **Modules**. When enabled, visitors see a starter home page at the installation's root address. Signed-in users continue to their dashboard. Disabling the feature restores the login entry point and keeps your saved content for later. Open **Settings → Landing page → Open landing page editor**, or **Landing page** in the navigation. The page inherits the installation's logos, colors, theme, copyright and support/legal links from **Brand settings**. Change those there; the landing page editor controls only its own content. 1. Edit headings, descriptions, buttons and section items. Show or hide sections and use the move controls to change their order. The header and footer stay in place. The gallery and testimonials appear only when they contain images or entries. 2. Upload your own hero, gallery or sharing images, or select them from the media library. PNG, JPG and WebP images may be up to 4 MB and 6000 × 6000 pixels. A selected library file becomes an independent copy. Captions describe gallery images for visitors using screen readers. 3. Select **Save draft**, then **Preview draft** to check desktop and phone layouts. Saving does not change the live page. Unsaved edits must be saved before previewing or publishing. 4. Select **Publish** and confirm to replace the live content with the saved draft. **View live page** opens the public page even when you are signed in. Button destinations accept complete HTTPS URLs, local paths such as `/auth/login`, or section links such as `#features`. Buttons pointing to a hidden section are hidden too. Contact details are optional; this page does not collect enquiries or newsletter subscriptions. Under **Search & sharing**, set the page title, description and optional sharing image. A blank title uses the brand name. Search indexing is off by default, and draft previews always request no indexing. The published page and its published images remain publicly accessible regardless of that setting. Write page content in the language intended for your audience; changing the interface language does not translate your saved content. Draft images require editor permission. Replacing an image in a draft keeps the current live image available until you publish. If a save fails, correct the reported fields or storage connection and retry; your draft edits remain on screen. If another editor has saved since you opened the page, copy your pending changes before reloading and applying them to the newer draft. ## Tips - If your role doesn't allow managing settings, you may be able to view this screen but not save changes. ## See also - [General settings](https://czappstudio.com/docs/administration/settings#section-7) - [Localisation settings](https://czappstudio.com/docs/administration/settings#section-15) - [Code prefixes](https://czappstudio.com/docs/administration/settings#section-11) - [Feed settings](https://czappstudio.com/docs/modules/feed#section-4) - [App update settings](https://czappstudio.com/docs/administration/settings#section-23) - [Authorized signature](https://czappstudio.com/docs/administration/settings#section-20) ## General settings The **General** tab on the **Settings** screen holds your company details, the automatic check-out time, and the signatory used on generated letters. Open Settings from the **gear icon** in the top bar, then stay on the **General** tab. ### What you can set **Company Information** - **Legal Business Name** - **Phone** - **Email** - **Address** These appear on generated lifecycle letters and other company documents. The web product name, email identity and logos are managed separately in [Brand settings](https://czappstudio.com/docs/administration/settings#section-2). **Attendance** - **Only allow registered devices** — refuse a check-in from a phone the employee has not registered. - **Block check-in until documents are uploaded** — stop an employee checking in while a mandatory document is still missing. **Letter Signatory** - **Signatory Name** and **Signatory Designation** — the name and title printed on generated lifecycle letters (offer, appointment, confirmation, increment, warning, relieving) and shown on the candidate offer-acceptance page. - **Signature Image** — the signature picture. See [Authorized signature](https://czappstudio.com/docs/administration/settings#section-20) for how to upload it. ### Steps 1. Open **Settings** from the **gear icon** in the top bar. 2. Stay on the **General** tab. 3. Update the fields you need. 4. Click **Save Changes** at the bottom of the tab. ### Tips - The company details here feed into generated documents and letters, so keep them accurate. - The Letter Signatory name and designation are typed in here; the signature image is uploaded separately (the file picker on this tab handles it). ## Code prefixes The **Code Prefix** tab on the **Settings** screen sets the text at the start of the codes Open Core HR generates. Open Settings from the **gear icon** in the top bar, then choose the **Code Prefix** tab. ### What you can set There is a prefix for each kind of record Open Core HR generates a code for: - **Employee** — `EMP-0001` - **Department** — `DEP-0001` - **Designation** — `DSG-0001` - **Location** — `LOC-0001` - **Shift** — `SHF-0001` - **Holiday** — `HOL-0001` - **Expense Category** — `EXP-0001`, when Expenses is enabled Document Type prefixes are configured in the Documents module's settings; the default is `DOC`. Leave types, salary components and approval workflows retain their separate business-key policies. Prefixes contain 1 to 8 letters or digits and are stored in uppercase. `TMP` is reserved for temporary onboarding identities and cannot be the employee prefix. Codes are allocated on save using an independent sequence for each entity. Sequences continue past 9999 and do not reset when a prefix changes. Existing codes are never renamed or reused through normal deletion. Gaps are allowed. ### Steps 1. Open **Settings** from the **gear icon** in the top bar. 2. Open the **Code Prefix** tab. 3. Type the prefix you want in each field. 4. Click **Save Changes**. ### Tips - Changing a prefix affects codes generated from then on; it doesn't rename codes that already exist. - Keep prefixes short and consistent so codes stay easy to read. ## Localisation settings Use **Settings → Localisation** to choose your organization's currency, number formatting, timezone, date formats, distance unit and dialling code. Viewing settings requires settings access; saving requires permission to manage settings. ### Choose the application language Open **Languages & translations** in the administration navigation. This requires **Manage translations and languages** permission. Choose the company default and enable the languages people may select. English remains available as the fallback for missing translations. People can choose a personal language from the web header or **Profile → Language** in the mobile app. **Use company default** follows your organization's choice. Language selection does not change currency, number formatting or timezone. Before signing in, use the language dropdown at the top right of the login page. Switching language preserves the details already entered. After signing in, your saved personal preference or the company default applies. To change wording, choose the translation language, search for the text and select **Edit**. Standard sign-in, password and validation messages are included. Keep placeholders such as `:name` and `:attribute` unchanged; they are replaced with a person's name, a field label or another value when displayed. Save to publish the wording, or choose **Restore default** to remove your customization. If someone else changed the same entry, close and reopen it to review their wording before saving again. Web pages pick up changes on their next visit. The mobile app checks at startup and when returning to the foreground, and keeps downloaded wording available offline. The editor includes standard web, mobile and backend messages. Employee names, policy text and other content entered by your organization remain as entered. Count messages can have separate forms for zero, one, two, few, many and other quantities. Edit each available form and keep its `:count` placeholder. The application selects the correct form for the language and quantity. 25 interface languages are included: English, Arabic, Spanish, French, Hindi, Portuguese (Brazil), Indonesian, Chinese (Simplified), Bengali, Urdu, German, Russian, Japanese, Korean, Turkish, Vietnamese, Thai, Filipino, Swahili, Tamil, Telugu, Marathi, Persian, Malay and Italian. Arabic, Urdu and Persian use right-to-left layouts. Administrators enable the languages they need and customize their wording here; further languages can be supplied with the application. Adding a language also requires reviewing its email and PDF template variants. ### Translate email and letter templates Open **Mail Templates** or **PDF Templates** with permission to manage templates. Each template has a content language independent of your interface language. Select an existing translation, or create a language draft from the saved content. Save pending changes before switching languages. Translate the subject and body while preserving variable tokens. Preview the result before activating it. Activation applies only to that language; deactivating it restores the built-in message or letter for that language. Attachments belong to each email language separately and are not copied into a new draft. Generated letters keep their original language when refreshed after a template edit. Their reference number stays the same, and the template version is recorded. Finalized payslips keep the employee's language at finalization. Employee names, company details and other entered content remain as entered. ### Set currency and number formatting 1. Choose the **Default currency**. Selecting a currency fills its standard symbol; you can edit the symbol. 2. Choose **Decimal places**, decimal and thousands separators, digit grouping, symbol position and spacing. Thousands and decimal separators must differ when grouping is enabled. Indian grouping displays numbers such as `12,34,567`; **None** removes grouping. 3. Check the live preview, including its negative and large amounts. Change the preview amount to try a value relevant to your business. 4. Select **Save Changes** to apply the preferences. Decimal places affect display only. **Currency default** uses each amount's currency precision; **Show decimals** is a shortcut for hiding or restoring decimal places. Calculations, validation and stored amounts retain currency precision. For example, displaying USD `1234.56` as `$1,235` does not change the amount owed. Rounded summaries include the exact amount; financial documents retain full currency precision. Use the selected decimal separator when entering an amount. Correctly grouped pasted amounts are accepted; ambiguous or incorrectly grouped values must be corrected. Hiding decimals does not prevent entering the currency's fractional units. Changing the default currency does not convert or rewrite amounts. Payroll and compensation records keep their recorded currencies. Records without a separate currency use the current default, so review the effect on existing records before changing it. PDFs use the configured currency symbol and support Arabic text. If a new language shows empty squares, ask the administrator to install fonts that cover that language on the application server. **Reset preview** changes only the sample amount. **Use format defaults** restores the draft formatting choices without changing the currency or other localisation settings. **Discard changes** restores the saved form. These actions take effect elsewhere only after saving. If another administrator saves first, your save is rejected and your draft remains visible. Use **Reload saved settings**, review the newer values, and reapply your intended changes. Invalid or failed saves leave the saved configuration unchanged. Saved preferences apply to web views and refresh in the mobile apps at login or when returning to the foreground. Offline mobile apps retain their last saved preferences. Issued payslips and financial letters retain their original formatting when downloaded again. Machine-readable exports retain exact decimal amounts and currency codes, independent of display separators. ### Set time, distance and phone preferences - **Timezone** controls attendance timestamps, report boundaries and scheduled jobs. - **Date Format**, **Time Format** and **Date & Time Format** control displayed dates and times. Check their previews before saving. - **Distance Unit** selects kilometres or miles for measured distances. - **Dialling Code** appears alongside phone fields. Leave it blank to hide it. ## Authorized signature The authorized signature is the signature image printed on generated lifecycle letters (offer, appointment, confirmation, increment, warning, relieving) and shown on the candidate offer-acceptance page. You upload it in the **Letter Signatory** section of the **General** tab on the **Settings** screen. There isn't a separate tab for this — it lives alongside the **Signatory Name** and **Signatory Designation** fields on the **General** tab. ### Steps 1. Open **Settings** from the **gear icon** in the top bar. 2. Stay on the **General** tab and scroll to **Letter Signatory**. 3. (Optional) Fill in **Signatory Name** and **Signatory Designation**. 4. Under **Signature Image**, click **Upload** (or **Replace** if a signature is already there). 5. Choose a PNG or JPG image. A PNG with a transparent background works best, and the file must be 2 MB or smaller. The signature uploads on its own — you don't need to press **Save Changes** for the image (that button saves the other General fields, including the signatory name and designation). ### Tips - Use a clean scan or export of the signature on a transparent background so it sits well on letter templates. - The signatory name and designation are typed in separately and saved with the rest of the General tab. ## App update settings The **Mobile App** tab on the **Settings** screen controls the minimum mobile-app version employees must be on, whether updating is mandatory, and an overall maintenance mode for the app. Open Settings from the **gear icon** in the top bar, then choose the **Mobile App** tab. ### What you can set **iOS Settings** - **Minimum Version** (required) — the lowest iOS app version allowed, in the form X.Y.Z (for example, 1.2.0). - **App Store URL** — the link employees are sent to in order to update. - **Force Update** — when on, employees on an older version can't use the app until they update. **Android Settings** - **Minimum Version** (required) — the lowest Android app version allowed, in the form X.Y.Z. - **Play Store URL** — the update link for Android. - **Force Update** — same as for iOS. **Maintenance Mode** - **Enable Maintenance Mode** — when on, all app access is blocked. - **Maintenance Message** — the message shown to employees while maintenance mode is on. ### Steps 1. Open **Settings** from the **gear icon** in the top bar. 2. Open the **Mobile App** tab. 3. Set the minimum versions, store links, and force-update switches for iOS and Android. 4. If you need to take the app offline, turn on **Enable Maintenance Mode** and write a **Maintenance Message**. 5. Click **Save Changes**. ![Mobile app settings (1): minimum versions and maintenance mode, saved with Save changes (2).](https://media.czappstudio.com/screens/docs/settings-mobile/light-67d6f1b817-2880.webp) ### Tips - Use **Force Update** sparingly — it locks employees out of the mobile app until they update. - Turn maintenance mode back off as soon as the work is done so employees can use the app again. --- # Mail, storage and push notifications Configure outgoing mail, push notifications, file storage and the media library. ## Mail settings Open Core HR sends notifications, password-reset links and letters by email. Administrators with permission to manage settings configure this under **Settings → Mail**. You don't need to edit the server's `.env` file, and changes apply to the next email sent, including queued ones. ### Connect a mail provider 1. Under **Send mail using**, choose **SMTP server**. 2. Choose your **Mail provider**. This fills in the provider's standard server, port and security, and a fixed username where the provider requires one. You can still change any field. Choose **Other SMTP server** for a provider that isn't listed. 3. Enter the **Username** and **Password** supplied by your provider. Read the note under the provider; many providers require an app password or API key, not your normal sign-in password. 4. Enter the **Sender email address** and **Sender name** that recipients will see. Your provider must allow sending from this address. 5. Select **Save**. ![Mail settings: choose how to send mail (1), Save (2), then Send test email (3).](https://media.czappstudio.com/screens/docs/settings-mail/light-696569d237-2880.webp) The password is stored encrypted and is never shown again. To keep it, leave the password field blank when you save. To remove it, select **Remove the saved password** and save. | Provider | Server | Port and security | Notes | |---|---|---|---| | Gmail / Google Workspace | smtp.gmail.com | 587, STARTTLS | Use an app password | | Microsoft 365 | smtp.office365.com | 587, STARTTLS | Turn on Authenticated SMTP for the mailbox | | Amazon SES | email-smtp.*region*.amazonaws.com | 587, STARTTLS | Use SES SMTP credentials, not AWS access keys | | SendGrid, SparkPost, Resend | Filled in automatically | 587, STARTTLS | Fixed username; use an API key as the password | | Zoho Mail, Yahoo Mail | Filled in automatically | 465, SSL/TLS | Zoho accounts outside the US use a regional server | Mailgun, Postmark, Brevo, Mailjet, MailerSend and Outlook.com are also listed. ### Send a test email Save your changes first. In **Send a test email**, enter the address that should receive the test and select **Send test email**. If sending fails, the message shows the provider's reason, such as a rejected password or an unreachable server. ### Other ways to send - **Write to the application log** records messages in the server log without delivering them. Use it only for testing. - **Microsoft 365 (Graph)** appears when the Microsoft 365 Connector module is enabled. It sends through the connector's configured sender mailbox. See [Microsoft 365](https://czappstudio.com/docs/microsoft-365/setup). If the module behind a chosen option is turned off, Open Core HR falls back to SMTP and logs a warning. Select another option and save. ## Push notifications The mobile app's push notifications, such as incoming calls, approvals and new messages, are sent through Firebase Cloud Messaging. An administrator with permission to manage settings connects Firebase under **Settings → Push notifications**. Nothing needs to be added to the server's `.env` file. 1. In the [Firebase console](https://console.firebase.google.com), open your project, then **Project settings → Service accounts**. 2. Select **Generate new private key** and download the JSON file. 3. In Open Core HR, open **Settings → Push notifications**, choose the file and select **Upload key**. 4. Select **Test connection** to confirm Firebase accepts the key. The key is stored encrypted and can't be downloaded again. Keep the downloaded file somewhere safe or delete it. To change projects or rotate the key, upload a new file with **Replace key**. **Remove key** turns push notifications off until a new key is uploaded. The mobile apps must be built with the same Firebase project. See the mobile app's build guide for its Firebase files. ## Storage settings Administrators with permission to manage settings can configure file storage under **Settings → Storage**. Available providers are local server storage, Amazon S3, Wasabi, Cloudflare R2 and S3-compatible storage. 1. Add a connection and choose its provider. 2. For cloud storage, enter the bucket, region, endpoint where required, and access credentials supplied by your provider. Use a private bucket and credentials limited to the required bucket operations. 3. Save the connection and test it. The test writes, reads and removes a small temporary object. 4. Activate the connection when the test succeeds. Review the displayed upload limits; individual forms may apply stricter limits. ![The Storage tab (1) in Settings lists storage connections.](https://media.czappstudio.com/screens/docs/settings-storage/light-19de2784b6-2880.webp) Activation changes where **new files** are stored. Existing files remain on their original connection and continue to download through the application. Keep the old bucket and credentials available. Changing a destination requires a new connection; replacing credentials for the same destination does not move its files. Saved secrets are encrypted and are never displayed again. If credentials expire, update the connection's credentials and test it before retrying failed operations. Storage failures do not cause files to be saved publicly or to another provider. Back up the database, application encryption key and every storage destination containing files. A database backup alone does not contain the files, and losing the encryption key prevents the application from reading saved credentials. See [Media library](https://czappstudio.com/docs/administration/mail-storage-and-notifications#section-7) for uploading and reusing files. ## Media library Use **Media library** on the web to keep reusable files and choose them in forms. Upload files from your device, organize them into folders, or search by filename. Uploads are private to you unless an administrator explicitly shares them with the workspace. In an attachment field, choose **Choose from library** to reuse an available file. The form's file-type and size restrictions still apply. Saving the form creates its own attachment copy: later changes to the library file do not alter a submitted HR record. Employee documents, receipts, conversations and other confidential record attachments remain in their original feature. They are not exposed as general library files. Access to each attachment follows the permissions on its record. You can rename, move or delete files you own. Sharing requires permission to manage settings and makes a file available to other authorized library users, so share only material intended for reuse across the workspace. A file that still has a direct record reference cannot be deleted. If an upload fails, check the displayed file restriction and ask an administrator to test the active storage connection. A failed operation does not switch storage providers automatically. The employee mobile application continues to provide self-service uploads and downloads; it does not have a media library screen. --- # Roles and permissions Control what people can see and do with roles and individual permission overrides. The **Roles & Permissions** screen lists every role in the workspace and lets you see — and change — exactly what each role can do. Open it from **Roles & Permissions** in the left **menu**, under the Settings heading. ## Reviewing access Expand a role to review permissions by feature. Built-in roles cannot be deleted. The System Administrator role has all permissions. ## Changing what a role can do On an expanded role card: 1. Click **Roles & Permissions** in the left **menu**. 2. Click the role to expand it. 3. Tick or untick individual permissions, or tick a group's checkbox to turn all of its permissions on or off. 4. Changes save automatically. ![Roles & Permissions: Add Role (1), or expand a role card (2) to change its permissions.](https://media.czappstudio.com/screens/docs/roles/light-094e5e589c-2880.webp) For larger changes (including changing the display name or app-access permissions), use the **pencil** button to open the full edit screen — see [Creating and editing a role](https://czappstudio.com/docs/administration/roles-and-permissions#section-6). ## Notes - **System Administrator** always has every permission. Its permissions can't be changed — the expanded card says so. - Whether you can add, edit, delete roles, or change their permissions depends on your own role. - To delete a role, it must have no users assigned. If it does, the confirmation dialog tells you to reassign those users first. ## See also - [Creating and editing a role](https://czappstudio.com/docs/administration/roles-and-permissions#section-6) - [Giving an individual extra permissions](https://czappstudio.com/docs/administration/roles-and-permissions#section-11) ## Supplied presets The standard presets are System Administrator, HR Administrator, HR Officer, Manager, Employee, Finance Officer, Asset Administrator, Recruiter and Compliance Reviewer. Optional-feature permissions are included only when the relevant modules are enabled. Assign Employee alongside functional roles when a staff member needs personal services. Manager permissions use the configured Reporting To relationships; a manager role does not create a reporting relationship. Permissions in **App Access** control each portal and app separately. Access to an app does not automatically grant administrative actions. Field operations separates routine customer management from bulk data access. **Reassign customers to employees** controls changing a customer's employee, including bulk reassignment and reassignment while disabling an employee. **Export customers** and **Export field reports** control downloads. HR Administrator and Manager receive all three by default; HR Officer receives the two export permissions. ## Creating and editing a role Roles group permissions. An employee can hold several roles, and permissions from all assigned roles apply together. Open **Roles & Permissions** under Settings. ### Adding a role 1. Click **Add Role**. 2. Enter a **Role Identifier**. It is the permanent reference used for assignments and imports. 3. Select the permissions the role needs. The **App Access** group controls entry to Administration, the web application and the unified HR mobile app independently. 4. Click **Create Role**. ![Create Role: enter the role identifier (1), find permissions (2) and choose Create Role (3).](https://media.czappstudio.com/screens/docs/role-create/light-bf390d1b8f-2880.webp) Use the search box and group checkboxes to review permissions. App entry alone does not grant permission to view or change employee records. ### Editing a role 1. Click the pencil button on the role's card. 2. Change its **Display name** or selected permissions. The identifier remains unchanged. 3. Click **Update Role**. The **System Administrator** role always holds every permission. Other supplied presets can be customized. An administrator cannot grant permissions they do not hold. Permission and app-access changes apply to subsequent requests. Removing HR app access blocks existing mobile tokens as well as new sign-ins. ### Assigning roles to an employee Use the **Roles** checkboxes when adding an employee, editing Work Information or completing onboarding. A person might hold **Employee**, **Manager** and **Finance Officer** together. **Employee** provides personal services. Other roles add responsibilities; department and designation describe the person's job, and Reporting To determines their team relationship. Role assignment requires permission, and only a System Administrator can assign or remove System Administrator membership. At least one active System Administrator must remain. ### Deleting a role Custom roles can be deleted after all assigned users have been reassigned. Supplied presets cannot be deleted. Attendance behavior is configured on shifts, not roles; see [Shifts](https://czappstudio.com/docs/administration/shifts-and-holidays#section-1). ## Giving an individual extra permissions In Open Core HR, what a person can do is decided by their **role**. There isn't a separate screen in the current app for granting one individual extra permissions on top of their role. To change what someone can access, you either move them to a different role or adjust the permissions on the role itself. 1. **Roles & Permissions** — Open **Roles & Permissions** from the menu. ### How to change one person's access Pick whichever fits: - **Move the person to a different role** — open their employee profile and change the **Role** in the work information section. They immediately get whatever that role allows. Use this when an existing role already matches the access they need. - **Create a role for the access you want** — on the **Roles & Permissions** screen, click **Add Role**, tick exactly the permissions needed, and assign that role to the person. Use this when no existing role fits. See [Creating and editing a role](https://czappstudio.com/docs/administration/roles-and-permissions#section-6). - **Adjust an existing role's permissions** — on **Roles & Permissions**, expand the role and tick or untick permissions. Remember this affects *everyone* with that role, not just one person. ### See also - Roles and permissions - [Creating and editing a role](https://czappstudio.com/docs/administration/roles-and-permissions#section-6) --- # Audit logs Review the record of changes made across Open Core HR. The **Audit Logs** screen is the system activity trail — a record of who changed what, and when. Open it from **Audit Logs** in the left **menu**, under the Settings heading. 1. **Audit Logs** — Open **Audit Logs** from the menu. ## Investigating a change Search for the record or user, then open an entry to check who made the change, what changed, and when it happened. The actor may be **System** for an automated change. ![Audit logs: search the trail (1) and open an entry from its row's actions menu (2).](https://media.czappstudio.com/screens/docs/audit-logs/light-6e8d430005-2880.webp) ## Opening an entry Click the **view** (eye) button on a row to open **Audit Log Details**. That page shows: - **Overview** — the user (name and email), the **Event**, the **Model** and **Record ID**, plus the **Timestamp**, **IP Address**, **User Agent**, **URL**, and **Tags** when those were recorded. - **Changes** — a table with **Field**, **Old Value**, and **New Value** columns. Fields that actually changed are highlighted (old value in red, new value in green). If the event didn't record any field changes, it says "No changes recorded for this event." Use the back arrow at the top of the details page to return to the list. ## Settings changes Saving **Settings → Field visits**, **Settings → Field tracking** or **Settings → Maps** records one entry tagged `settings`, with the model **FieldSettings**, **FieldTrackingSettings** or **MapsSettings**. It lists only the fields that changed, with their old and new values, and the administrator who saved them. The Maps server key is shown as `********` so the entry shows when it was set, replaced or cleared without revealing it. The **version** field increases with every save. ## Tips - Audit entries are read-only — you can view them but not edit or remove them from here. - Use the search box to narrow down to a person, a record type, or a date you're looking for. --- # Home profiles Choose what different groups of people see on their home screen. A home profile decides what each kind of person sees first: their shortcuts, the cards on Today in the mobile app, and the widgets on each web dashboard view. A profile never grants access. Anything a person cannot open is left out, whatever the profile lists. Open **Home profiles** under Settings. You need the **Manage home profiles** permission. Four profiles are built in: **HR**, **Manager**, **Field sales** and **Employee**. You can edit them but not delete them. ## How a person's profile is chosen 1. A profile that names the person directly wins. 2. Otherwise the profile with the lowest **Priority** number that matches the person is used. A profile matches if the person holds one of its roles or meets its rule. 3. If nothing matches, the person sees the everyday shortcuts and no profile cards. Rules let you match people without listing roles: - **Anyone with direct reports** matches managers, whatever their role. - **Can record field visits** matches field staff. - **Everyone** matches all people and is useful for a final default with a high priority number. Someone who manages people but uses another profile, such as an HR officer with a team, also gets the **Your team today** card at the end of Today. ## Create or edit a profile 1. Choose **New profile**, or **Edit** from a profile's actions. 2. Enter a name and priority, then choose the roles and the rule it applies to. 3. Choose up to six **Shortcuts** in order. The mobile app shows the first four that have a mobile screen; items marked **Web only** appear only on the web dashboard. 4. Choose the **Mobile Today cards** in order. 5. For each dashboard view, choose the widgets and their order. Widgets you leave out remain available to people in **Edit dashboard**. 6. Save. ![New profile: enter a name (1), choose the roles it applies to (2) and pick its shortcuts (3).](https://media.czappstudio.com/screens/docs/home-profile-form/light-76e976fd5b-2880.webp) Changes apply the next time people open Today or the dashboard. People who chose their own shortcuts keep them until they choose **Use my profile's**. A person's own dashboard layout also takes precedence over the profile. ## Delete a profile Deleting a custom profile moves its people to their next matching profile. Their own shortcuts and dashboard layouts are kept. --- # Customer visits and offline work Record customer visits on mobile, review your team and recover work saved offline. Customers, visits, journey plans and field reports are included in core HR. Your permissions determine which employees and customers you can access. Use mobile **Field work** to record visits and prepare your own journey plans when permitted. Managers plan work on the web and can review their team's work on the web or in the mobile app. ## Prepare and record a visit 1. Open **Field work** while connected and refresh to download your assignments. Refresh again before leaving for work so customer details, visit requirements and permissions are current. 2. Open a planned visit, or create an unplanned visit when your administrator allows it. Choose an assigned customer and visit date. 3. Check in on arrival. If attendance is required, check into your shift first. If location is required, allow location access and obtain an accurate position. 4. Add any required notes and photos, then check out when finished and choose the outcome. Use the camera or select a photo from your device. A visit photo is a private attachment available to authorized viewers. ![Checking in to a customer visit in the mobile app.](https://media.czappstudio.com/screens/mobile/visit-check-in/light-eae12b55b5-1206.webp) Photos can be added only while a visit is in progress, up to 10 per visit; add them before checking out. Each photo is recorded in the visit history. Photos taken offline count toward the limit and upload in order before the checkout is sent. The visit page shows the check-in and checkout location evidence: whether the position was inside the customer area, its distance from the customer's location and its GPS accuracy. A large accuracy value means the position is uncertain, so a distance close to the boundary may not be reliable. Attendance and visits are independent records. Checking out of a visit does not end your work session, and ending attendance does not prevent finishing an open visit. The policy captured for an active visit governs its checkout, even if settings change later. Check-in and checkout may have different location requirements. If you cannot record a visit normally, use the available correction request and explain the change needed. An authorized manager reviews the request and records any correction with its reason. Missed or stale visits remain visible for follow-up; they do not become completed automatically. ## Review your team on mobile Managers and HR open **Team field work** from **Work** or the home screen. It appears when you can view your team's or everyone's visits, journey plans or customers, even if you do not record visits yourself; you see only the employees and customers your permissions allow. - **Today** summarises your team's scheduled, completed and on-duty work, and lists visits that need follow-up: change requests, visits left checked in too long, and visits missed in the past week. - **Visits**, **Journey plans** and **Customers** list your team's records. Search them, or use the filter to show one employee. ![Team field work: today's summary for your team.](https://media.czappstudio.com/screens/mobile/team-today/light-c71f3b66fb-1206.webp) Team field work needs a connection and is read-only. Approve or reject submitted journey plans in **Approvals**; correct or reassign visits and maintain customers on the web. Checking in to a visit and creating your own customers stay in your own **Field work** and need visit-recording permission. ## Recover saved work Your visits download automatically when you open the app, check in or come back online, so they are ready if you lose signal. The app can save actions for those visits while offline and sends them automatically when the connection returns. Keep the app's data intact until the sync icon on **Today** shows everything is sent. Saved work is encrypted and separated by account and server. Recent completed visits remain available in downloaded history. Tap the sync icon on **Today** and choose **Try now** to send straight away. If the server refuses a change, for example because the visit was reassigned, cancelled or changed, the visit shows the reason with **Discard this change**, and the sync sheet lists it too. A rejected check-in prevents its dependent checkout from being sent. Discarding removes all unsent actions and photos for that visit from this device; do this only when they are no longer needed. When a visit needs you to be at work, **Check in** offers to check you in to work first. Customer and visit creation require a connection. If their response is lost, the app sends the same request again automatically, so it cannot create a duplicate; you can add another record once it is sent. New customers are numbered automatically using the customer code prefix in **Settings → Code prefix**. To place a customer on the map, choose **Use current location** or **Find an address**; coordinates are never typed by hand. --- # Plan and review field work Plan journeys, maintain customers and review field work on the web. Create customers in **Field Operations → Customers**, assign the responsible employee, and maintain contact details and a location when visits require a location boundary. Customer categories help organize accounts. A manager's access is limited by their employee visibility permissions. Open a customer to call, email or get directions, see the location on a map, review recent visits and open the full visit list for that customer. Managers who can see team or all customers also see the assignment history: who held the customer, when, and who made each change. Changing a customer's employee requires **Reassign customers to employees**. Reassign one customer from its page, or select several rows in the list and choose **Reassign customers**. Customers with open journey plans or planned or active visits cannot move until that work is resolved; the request names the affected customers and moves none of them. ![Customers: New customer (1), select rows (2) to reassign several at once, or Import customers (3).](https://media.czappstudio.com/screens/docs/customers/light-f0f6a609cc-2880.webp) Use device location, enter coordinates, or search for a place when your administrator has configured the server-side Google Places key. Place search fills the address and coordinates; check them before saving. An unavailable search does not prevent manual entry. To add customers in bulk, choose **Import customers**, download the template, and fill in unique customer codes, existing active category names and assigned employee codes. The file may contain up to 1,000 rows and must be under 2 MB. **Preview import** checks all rows without creating records; correct any errors and preview again. **Confirm import** creates the whole valid batch. Confirmation rechecks permissions and assignments, so changes made after the preview can require another review. A preview expires after 30 minutes. Retrying the same confirmation does not create duplicates. Imports create new customers; edit existing customers individually. **Export customers** requires **Export customers** permission and downloads the customers you are allowed to see that match the list's current search and filters. Values that a spreadsheet could treat as a formula are exported with a leading apostrophe; imports remove it again, so an exported file can be edited and imported without changing those values. Users who manage field settings can import and export customer categories from **Categories** on the Customers page. Category files have `name` and `status` (`active` or `inactive`) columns, follow the same preview and confirmation steps, and create new categories only. Create individual visits for an employee and date, or use **Journey plans** to schedule recurring visits. Choose weekly, fortnightly or monthly recurrence and place customers in the intended order for each scheduled day. Fortnightly schedules start with the week containing the plan's start date. A monthly date that does not exist in a month is skipped. Preview the itinerary and resolve scheduling issues before submission. ![Journey plans: choose New journey plan (1) to schedule recurring visits.](https://media.czappstudio.com/screens/docs/journey-plans/light-3afc0d24ed-2880.webp) To repeat a day's route, use **Copy day to…** on the web or **Copy day** in the mobile editor and choose the other days. Copying replaces the customers already on those days with the source day's customers in the same order, and adds any day that was not yet scheduled. From a plan, choose **View visits** to open the visit list filtered to that plan. The visit list can also be filtered by customer. Employees with permission can prepare and submit their own plans in the mobile **Field work** area. Managers can prepare plans for employees within their scope. Authorized reviewers use the shared approval inbox on the web or **Approvals** in the mobile app, and may narrow the approved date range by setting an approval period on the plan before approving. An active approved plan generates visits automatically through the scheduler, within that approved range. Pause a plan when its future schedule must stop; editing a paused plan keeps it paused. You can revise any plan. While a revision is a draft or awaiting approval, the previously approved schedule keeps generating visits; editing a plan that is awaiting approval withdraws that request. When the revision is approved it replaces the earlier schedule and its planned future visits; if it is rejected, the earlier approved schedule stays in force. Existing visits preserve their history. Visits that a manager has manually rescheduled or reassigned keep those adjustments when the plan is paused. They cannot be started while it is paused and become available again on resume. After pausing or resuming a plan, refresh downloaded visits before starting them offline. Visits already in progress can still be finished. Use field reports to review visit completion and customer coverage within your authorized employee scope. Filter by employee, reporting team, category and visit coverage. Exporting report files requires **Export field reports**. In the employee summary, choose **Daily breakdown** for one employee's visits, distance travelled, stops and tracking gaps per day, or **View visits** to open their visits for the report period. Employees who can see only their own visits see only their own report. Completed work is counted by its actual checkout time. Reports describe recorded work; they do not create sales orders, collections or target achievement. ![Field reports: narrow with Filters (1) and export coverage (2).](https://media.czappstudio.com/screens/docs/field-reports/light-491f9c2329-2880.webp) ## Visit requirements Field visit settings, in **Settings → Field visits**, control check-in and checkout location separately. Each location boundary can be off, warn when outside, or enforce the boundary. Boundaries require customer coordinates. Configure position accuracy and age, unplanned visits, and whether employees must have active attendance to start a visit. A visit can still be finished after its attendance session ends. Completion can require an outcome, notes and photos. Planned visits use the customer's current details and coordinates; those details and the visit requirements freeze when the visit starts. A downloaded offline start must be refreshed if the customer pin changes. Managers can review missed visits and visits left open beyond the configured stale limit. When exceptions are enabled, authorized managers can record or correct another employee's visit with a reason; employees can request a correction for review. The event history preserves the previous values. Resolve planned and active visits before transferring a customer's owner. Managers can instead reassign a planned visit to another employee and one of that employee's customers. Previously approved journey schedules retain their original date bounds. Location retention removes old visit coordinates after the configured period (90 days by default), while keeping business notes and recorded times. Retention and visit generation require the scheduler. The server scheduler must run for recurring visit generation. Contact your administrator if an approved active plan is not creating visits. --- # Live tracking Follow field employees on a live map and play back their routes. Field tracking is a core capability that administrators enable in **Settings → Field tracking**. It records work-route samples during an authorized attendance session. Recording and viewing require separate permissions; managers and HR can only view the employee scope their permissions allow. Tracking has no screen of its own in the mobile app. When your attendance policy records field routes, checking in turns on location sharing and checking out turns it off. The first time, the check-in sheet explains background location and asks for the phone's location permissions. Choose **Allow all the time** so your route stays complete when the app is closed. Tracking never starts or ends attendance for you. While sharing is on, the **Today** workday card shows **Sharing your location**. Android also keeps a notification in the status bar, and iOS shows its blue location indicator. If sharing stops, the card shows **Location sharing is off** with the reason and a **Turn on** button. Sharing stops when a permission is removed, when it is stopped from the Android notification, or when it moves to another phone. **Turn on** asks for anything still missing and moves sharing to the phone you are using. Signing out stops sharing and detaches the phone. Tracking can only be recorded from the mobile app; the web application can display tracking but cannot send location samples. The phone keeps saved samples when it is offline and uploads them when it reconnects. The sync icon on **Today** counts location points that are waiting or that the server refused. Open it to try again, or to discard refused points. Discarded points cannot be recovered from that phone. For support, **Me → Help & about → Diagnostics** lists the tracking state, queue, last location and sync time, recording limit and phone permissions, and can share them as a report. Administrators choose a sampling profile, session limit and retention period. More frequent sampling can use more battery. Retention removes old stored tracking records and their daily summaries. Distance, time and stops for a finished day are calculated once and stored; today's figures are calculated as samples arrive. When a phone uploads late samples for an earlier day, that day is recalculated by the scheduler within about an hour, or when someone next opens it. The scheduler must run for this. ## Review tracking on the web Open **Live Tracking**, directly below **Dashboard** in the sidebar. - **Live map** shows on-duty employees with their latest received position and a status: recent, stale (no fresh fix), no location yet, or a location-permission problem reported by the phone. Use the filters to include off-duty employees, or show one status, department or employee. The list beside the map shows battery, app version and any customer visit in progress. Positions refresh every 30 seconds. - **Journey timeline** shows one employee's day: distance, observed and stationary time, coverage gaps, customer visits, and a route map with stops longer than five minutes. Use **Play route** to replay the day. Attendance check-in and checkout, breaks, customer arrivals and departures, and phone events appear in time order beside the map. - **Export CSV** downloads the day's route segments. Administrators who manage tracking can open **Raw points** to inspect each received sample, including its accuracy and movement. ![Journey timeline: choose an employee (1) and a date to review the day's route, then download its segments with Export CSV (2).](https://media.czappstudio.com/screens/docs/journey-timeline/light-d0d1d921dd-2880.webp) ![Live Tracking: the Live map (1) and Journey timeline (2) tabs, with Filters (3).](https://media.czappstudio.com/screens/docs/live-map/light-5f9cf2983a-2880.webp) The live map shows the latest evidence received, which may be delayed when a device is offline or its operating system restricts background work; it does not prove a person's current location. Gaps mean the phone sent no usable samples for that period. Maps need a browser key in **Settings → Maps**; without one, the lists, timeline and export still work. --- # Announcements Post announcements to employees and read the announcements sent to you. The **Announcements** screen lists the notices you've posted for the organization — either to everyone or to a particular location. Open it from **Announcements** in the left menu. ## Steps 1. Open **Announcements** from the left menu. 2. Use the **Search announcements...** box to find an announcement by title, description, or audience. 3. Click a column header to sort. **ID**, **Title**, **Description**, **For** and **Expiry Date** are sortable. 4. To post a new announcement, click **Add New**. See [Posting an announcement](https://czappstudio.com/docs/modules/announcements#section-4). 5. To change one, click the edit (pencil) icon. To remove one, click the trash icon. ![Announcements: search (1) and Add New (2).](https://media.czappstudio.com/screens/docs/announcements/light-42f5b3ba23-2880.webp) ## Checking the audience Check whether an announcement applies to everyone or a specific location. The expiry date determines when it stops showing. ## Tips - Deleting an announcement can't be undone. You'll be asked to confirm first. ## Posting an announcement Post a notice for the whole organization or for a single location, with an optional expiry date. ### Steps 1. Open **Announcements** from the left menu and click **Add New** (the form panel opens). 2. Choose **Announcement For**: - **All** — everyone sees it. - **Location** — only that location sees it. A **Location** field appears; pick the location (required). 3. Enter the **Title** (required). 4. Enter the **Description** (required) — this is the message body. 5. Optionally pick an **Expiry Date** of today or later. After this date the announcement no longer shows. 6. Click **Create**. Use the panel close control to discard. ![Add Announcement: choose the audience (1), enter a title (2) and choose Create (3).](https://media.czappstudio.com/screens/docs/announcement-form/light-279a3c5408-2880.webp) ### Who gets told Publishing sends a notification to everyone in the audience you picked — it appears under the bell icon, is pushed to the mobile app, and is emailed if your deployment has email configured. Inactive employees and the system bot account are skipped. Only **Create** notifies. Editing an announcement afterwards, or switching it between Active and Inactive, changes what people see on the noticeboard but does not notify anyone again. ### Editing an announcement 1. On the **Announcements** list, click the edit (pencil) icon. 2. Change the audience, location, title, description, or expiry date. 3. Click **Update**. ### Changing whether it's active New announcements are **Active**. An announcement can also be **Inactive** so it stops showing without being deleted. Making one Active again does not re-notify. > **Note:** The create and edit form has no status control. An announcement's active or inactive state is changed from the **Status** column on the Announcements list. ### Tips - Only the location you pick will see a location-targeted announcement; switching back to **All** clears the location. - To remove an announcement entirely, use the trash icon on the **Announcements** list. See Announcements. ## Reading announcements as an employee The announcements page shows company notices for everyone and for your location. Open **Announcements** in the module menu. 1. **Announcements** — Open **Announcements** from the menu. ### Reading a notice Use **Read more** to open the full announcement and **Download** to save an attachment. See [Reading an announcement](https://czappstudio.com/docs/modules/announcements#section-13). ### Tips - The newest announcements appear first. - You only see announcements meant for everyone or for your location. ## Reading an announcement Most announcements show their full text right on the [Announcements](https://czappstudio.com/docs/modules/announcements#section-10) card. For longer ones, you can open the complete announcement in a pop-up window. ### Steps 1. Open **Announcements** in the module menu. 2. On an announcement that has a **Read more** link, click **Read more**. 3. The full announcement opens in a window showing: - The **title**. - **Posted on** — the date and time it was published. - **Expires** — the end date, if the announcement has one. - The complete text. 4. Click **Close** when you're done. ![Announcements in the mobile app.](https://media.czappstudio.com/screens/mobile/announcements/light-0fe1e6e294-1206.webp) ### Tips - Shorter announcements don't have a **Read more** link — their full text is already on the card. --- # Assets Track company assets through inventory, assignment, return, maintenance and documents. The **All Assets** screen lists every asset your organization tracks, with search, filters, and quick actions. Open **Asset Management → All Assets** to get there. ## Steps 1. In the left menu, open **Asset Management → All Assets**. 2. Use the **Search assets...** box to find an asset by name, serial number, brand, model, or category. 3. Use the **All Categories** dropdown to show only assets in one category. 4. Use the **All Statuses** dropdown to show only assets with a given status: **Available**, **Assigned**, **Maintenance**, or **Retired**. 5. Click a column header (**Name**, **Category**, **Serial Number**, **Status**) to sort by it. 6. Use the row actions on the right to view, edit, or delete an asset. ![Assets: search (1), Filters (2) and Add Asset (3).](https://media.czappstudio.com/screens/docs/assets/light-07f27f22a3-2880.webp) ## Checking availability Check the status, condition, and current holder before assigning an asset. Status distinguishes assets that are **Available**, **Assigned**, in **Maintenance**, or **Retired**. ## Tips - The view (eye) action is always available; the edit and delete actions appear only if your role allows them. - To see assets handed out to staff, open **Asset Management → Assignments** instead — see [Asset assignments](https://czappstudio.com/docs/modules/assets#section-23). ## Adding an asset Add a new asset to your inventory from the **All Assets** screen. A new asset starts with the status **Available** so you can assign it later. ### Steps 1. In the left menu, open **Asset Management → All Assets**. 2. Click **Add Asset** at the top right. A panel slides in from the right. 3. Choose a **Category** (required). 4. Enter a **Name** (required). 5. Fill in the optional details as needed: - **Serial Number** - **Asset Tag** - **Brand** and **Model** - **Purchase Date** and **Purchase Price** - **Warranty Expiry** - **Condition** — **New**, **Good**, **Fair**, **Poor**, **Damaged**, or **None** - **Notes** 6. If the chosen category supports accessories, an **Accessories** section appears. Click **Add** to include an item shipped with the asset, then fill in its **Name** (required), serial number, condition, and notes. Repeat for each accessory, or use the trash icon to remove one. 7. Click **Create** to save the asset. ### After you finish The new asset appears in the **All Assets** list with the **Available** status and the condition you chose, if any. ### Tips - **Serial Number** and **Asset Tag** must be unique — if another asset already uses the same value, you'll see an error and the asset won't be saved. - **Purchase Price** must be zero or a positive number. - Accessories are only shown when the chosen category is set up to have them. You can also add or change accessories later from the asset's details page. ### Troubleshooting - **"Category is required" / "Name is required"** — fill in the highlighted field and try again. - **The save fails with a field error** — read the message under the field, fix the value, and click **Create** again. ## Bulk uploading assets Import new asset records from **Import & Export** when you have many items to add. Asset Management must be enabled, and you need permission to create assets. Each file can contain at most 170 assets. ### Steps 1. Open **Import & Export**, choose **Assets** under imports, and download the current template. 2. Replace the example row with one row per asset. Supply a **name** and an existing active **category** for every row. Category names are matched without case or surrounding-space differences; duplicate category names must be resolved first. 3. Enter dates as `YYYY-MM-DD` and prices as plain numbers, such as `85000.00`. Allowed statuses are `available`, `in_maintenance`, `decommissioned` and `lost`; allowed conditions are `new`, `good`, `fair`, `poor` and `damaged`. Record assignments separately after import. 4. Upload the file and validate it. Review the preview and any row errors. Correct errors and upload again; the whole file must pass validation before confirmation. 5. Confirm the import and check **History** for its result. See [Importing a spreadsheet](https://czappstudio.com/docs/administration/import-export#section-3) for the shared workflow. ### Tips - Accessories are not part of bulk upload. Add them from each asset's details page after the import — see [An asset's details](https://czappstudio.com/docs/modules/assets#section-13). - An import creates new assets. It does not update an asset with a matching serial number or tag. Resolve duplicate identifiers in the file or existing records before confirming. ### Troubleshooting - **"Category '...' not found"** — the category name in that row doesn't match any existing category. Create the category first (see [Asset categories](https://czappstudio.com/docs/modules/assets#section-18)) or correct the spelling. - **A date or price error** — make sure dates are written as YYYY-MM-DD and prices are plain numbers (for example, 85000.00). - **"Maximum 170 rows allowed"** — split your data into smaller files and upload them one at a time. - **The import failed after validation** — review its errors and existing assets before trying again. Another user may have created a matching asset or changed a category after your preview. ## An asset's details The asset details page shows everything about a single asset — its information, who currently holds it, its full history, maintenance records, documents, and an activity timeline. It's also where you assign, return, and maintain the asset. ### Steps 1. In the left menu, open **Asset Management → All Assets**. 2. Find the asset and click the view (eye) action on its row. 3. Review the sections on the page (described below). 4. Use the buttons at the top right to act on the asset, if you have permission: - **Edit** — change the asset's details. - **Assign Asset** — hand the asset to an employee (shown when the asset is **Available**). See [Assigning an asset](https://czappstudio.com/docs/modules/assets#section-28). - **Return Asset** — record the asset coming back (shown when the asset is **Assigned**). See [Returning an asset](https://czappstudio.com/docs/modules/assets#section-33). - **Add Maintenance** — log a maintenance event. See [Asset maintenance](https://czappstudio.com/docs/modules/assets#section-38). - **Delete** — permanently remove the asset. ### Reviewing an asset Check the current holder and condition, then review assignment and maintenance history when investigating damage or arranging a handover. Supporting files are available under **Documents**; the **Activity Timeline** records assignments, returns, maintenance and other changes. ### Tips - The action buttons that appear depend on both the asset's current status and your permissions. - The **Edit** button opens the same edit panel used on the **All Assets** screen. ### Troubleshooting - **The page doesn't load** — go back to **Asset Management → All Assets** and open the asset again; it may have been deleted. ## Asset categories Categories group your assets — for example, Laptops, Phones, or Furniture. Every asset belongs to a category. Open **Asset Management → Categories** to manage them. ### Steps #### View categories 1. In the left menu, open **Asset Management → Categories**. 2. Use the **Search categories...** box to find a category by name, slug, or description. 3. Click the **Name** or **Slug** column header to sort. #### Add a category 1. Click **Add Category** at the top right. A panel slides in from the right. 2. Enter a **Name** (required). 3. Optionally enter a **Slug** — leave it blank to have one generated automatically. 4. Turn on **Has Accessories** if assets in this category come with accessories you want to track. 5. Optionally add a **Description**. 6. Click **Create**. #### Edit a category 1. Click the edit (pencil) action on the category's row. 2. Update the fields in the panel. 3. Click **Update**. #### Delete a category 1. Click the delete (trash) action on the category's row. 2. Confirm by clicking **Delete**. ### Checking category usage Check the asset count before changing or removing a category. **Has Accessories** indicates whether assets in the category can include accessories. ### Tips - Turning on **Has Accessories** makes the **Accessories** section appear when adding or editing an asset in that category. - A category's **Asset Count** helps you see which categories are in use before deleting one. ### Troubleshooting - **The delete fails** — a category that still has assets may not be removable. Move or remove its assets first, then try again. ## Asset assignments The **Assignments** screen shows who has which asset — every current and past hand-out across your organization. Open **Asset Management → Assignments** to see it. ### Steps 1. In the left menu, open **Asset Management → Assignments**. 2. Use the **Search assignments...** box to find an assignment by asset name, serial number, category, or employee name or code. 3. Use the **All Statuses** dropdown to show only assignments with a given status. 4. Click a column header (**Asset Name**, **Category**, **Assigned At**, **Status**) to sort. ### Checking an assignment Check the recipient, handover date, condition, and status. Assignments take effect immediately. **Active** means the employee currently holds the asset; **Returned** means the assignment has ended. ### Tips - To assign a new asset or record a return, open the asset's details page (see [An asset's details](https://czappstudio.com/docs/modules/assets#section-13)) and use the **Assign Asset** or **Return Asset** button there. - An **Active** assignment is the one the employee currently holds; **Returned** assignments are completed. ### Troubleshooting - **An assignment isn't listed** — clear the **Search** box and reset the **All Statuses** filter, then look again. ## Assigning an asset Hand an asset to an employee from the asset's details page. The assignment takes effect immediately and the asset moves to the **Assigned** status. ### Steps 1. In the left menu, open **Asset Management → All Assets**. 2. Find the asset (it must be **Available**) and click the view (eye) action to open its details. 3. Click **Assign Asset** at the top right. A panel slides in from the right. 4. Choose the **Employee** to assign the asset to (required). 5. Set the **Condition at Assignment** — **New**, **Good**, **Fair**, **Poor**, or **Damaged**. 6. Optionally add **Notes** about the hand-over. 7. Click **Assign Asset**. ![An available asset: choose Assign Asset (1) to hand it to an employee.](https://media.czappstudio.com/screens/docs/asset-detail/light-b8c2fc3dd0-2880.webp) ### After you finish The asset's status changes to **Assigned**, the employee appears under **Current Assignment**, and a new entry is added to **Assignment History** and the **Activity Timeline**. ### Tips - The **Assign Asset** button only appears when the asset is **Available** and has no assignment in progress. - To hand the asset back later, use **Return Asset** on the same page — see [Returning an asset](https://czappstudio.com/docs/modules/assets#section-33). ### Troubleshooting - **"Select an employee"** — you must pick an employee before you can assign the asset. - **The assignment is rejected** — the asset may no longer be available (someone else may have assigned it). Reopen the asset's details to check its current status. ## Returning an asset When an employee hands an asset back, record the return from the asset's details page. The asset then moves back to the **Available** status so it can be assigned again. ### Steps 1. In the left menu, open **Asset Management → All Assets**. 2. Find the asset (it must be **Assigned**) and click the view (eye) action to open its details. 3. Click **Return Asset** at the top right. A panel slides in from the right. 4. Set the **Return Date** (required) — it defaults to today. 5. Set the **Condition on Return** (required) — **New**, **Good**, **Fair**, **Poor**, or **Damaged**. 6. Optionally add **Notes** with any remarks about the return. 7. Click **Confirm Return**. ### After you finish The asset's status changes to **Available**, the **Current Assignment** clears, and the assignment is closed out in **Assignment History** with the return date and condition. The return is also added to the **Activity Timeline**. ### Tips - The **Return Asset** button only appears when the asset is currently **Assigned**. - Logging maintenance with the asset status set to **Available** also returns the current assignment automatically — see [Asset maintenance](https://czappstudio.com/docs/modules/assets#section-38). ### Troubleshooting - **The return fails** — the assignment may no longer be active (it may already have been returned). Reopen the asset's details to check its current status. > **Note:** The details page records a return in a single action — there is no separate return-request step to approve first. ## Asset maintenance Record repairs, servicing, and inspections against an asset so you have a full maintenance history. You can also change the asset's status as part of logging maintenance. ### Steps #### View maintenance history 1. In the left menu, open **Asset Management → All Assets**. 2. Open the asset's details (the view / eye action). 3. Scroll to the **Maintenance History** card. Each record shows the date performed, type, description, cost, vendor, next due date, who logged it, and notes. #### Log a maintenance event 1. On the asset's details page, click **Add Maintenance** at the top right. A panel slides in from the right. 2. Set the **Performed On** date (required) — it defaults to today. 3. Choose the **Type** — **Preventive** or **Corrective**. 4. Enter a **Description** (required) of the work done. 5. Optionally enter the **Cost** and the **Vendor**. 6. Optionally set a **Next Due Date** for the next service (it must be on or after the **Performed On** date). 7. Optionally add **Notes**. 8. If the asset's status should change after this maintenance, turn on **Update asset status after maintenance?** and choose the **New Asset Status** — **Available**, **Assigned**, **In Maintenance**, **Decommissioned**, or **Lost**. 9. Click **Save Maintenance**. ### After you finish The new record appears at the top of **Maintenance History**, and the event is added to the **Activity Timeline**. If you changed the asset's status, the **Asset Details** card updates to show it. ### Tips - If you set the new asset status to **Available** while the asset is currently **Assigned**, the current assignment is automatically returned. ### Troubleshooting - **"Description is required"** — enter what was done before saving. - **The next due date is rejected** — it must be the same as, or later than, the **Performed On** date. ## Asset documents Attach files to an asset — purchase invoices, warranty certificates, manuals, and more — so they're kept alongside the asset record. ### Steps #### View documents 1. In the left menu, open **Asset Management → All Assets**. 2. Open the asset's details (the view / eye action). 3. Scroll to the **Documents** card. Each file shows its name, type, and size. Click a file name to open it in a new tab. #### Upload a document 1. On the asset's details page, in the **Documents** card, click the **File** picker and choose a file. 2. Choose a **Type** — **Invoice**, **Warranty**, **Manual**, or **Other**. 3. Click **Upload**. #### Delete a document 1. In the **Documents** card, click the delete (trash) action next to the file. 2. Confirm by clicking **Delete**. The file is permanently removed. ### After you finish The uploaded file appears in the **Documents** list, and the upload is added to the **Activity Timeline**. ### Tips - You can upload PDF, JPG, PNG, Word, and Excel files, up to 10 MB each. - The upload and delete controls only appear if you have permission to manage asset documents. ### Troubleshooting - **The upload is rejected** — check the file type and that it's under the size limit, then try again. - **"Pick a file to upload"** — choose a file in the **File** picker before clicking **Upload**. ## Your assets (employees) The **My Assets** screen in the **Documents** module lists the company assets currently assigned to you. ### Checking your equipment Open an asset to check its serial number, assignment date, and included accessories. Confirm these details when receiving or returning equipment. ### Steps 1. Open **My Assets** from the module menu. 2. Use the search box to find an asset by name. 3. Click the eye icon in the **Actions** column to open the details panel, which shows the **Serial Number**, **Asset Tag**, **Brand**, **Model**, **Assigned Date**, **Condition When Assigned**, **Assignment Notes**, and a list of **Accessories**. ### Tips - The details panel also lists documents attached to the asset and its maintenance history — see [An asset's documents](https://czappstudio.com/docs/modules/assets#section-52) and [An asset's maintenance history](https://czappstudio.com/docs/modules/assets#section-55). ## Your asset's documents Each asset assigned to you can have documents attached, such as a warranty card or handover form. You view them inside the asset's details panel. ### Steps 1. Open **My Assets** from the module menu. 2. Click the eye icon next to the asset. The details panel slides in from the right. 3. Scroll to the **Documents** section. 4. For any document with a **View** link, click it to open the file in a new browser tab. ### Tips - Documents here are managed by your IT or admin team — you can view them but not upload to an asset from this screen. ## Your asset's maintenance history If an asset assigned to you has been serviced or repaired, those records appear in the asset's details panel. ### Steps 1. Open **My Assets** from the module menu. 2. Click the eye icon next to the asset. The details panel slides in from the right. 3. Scroll to the **Maintenance Log** section. ### Reviewing maintenance Check what work was performed and the next due date, if recorded, before arranging further maintenance. ### Tips - Maintenance records are added by your IT or admin team; this screen is read-only. --- # Chat and calls Message colleagues in conversations and groups, share files and make audio or video calls. Chat is the built-in messaging area in Open Core HR. You can send direct messages to a colleague, create group chats, share files and images, and react to messages. > **Availability:** This area may not be turned on for your company yet. If you don't see it in your menu, it isn't enabled — check with your HR or IT team. ## Finding a conversation Use **Search chats...** to find an existing conversation, or **New Chat** to start one. Open a conversation to read and send messages. ## Steps 1. Open **Chat** from your menu. 2. In the conversation list on the left, select a chat to open it, or use **Search chats...** to find one. 3. Type in the message box at the bottom and press Enter to send. ![Chat: search chats (1), type in the message box (2), or start one with New Chat (3).](https://media.czappstudio.com/screens/docs/chat/light-0e7a84b11a-2880.webp) To start a new conversation or a group, see [Conversations and groups](https://czappstudio.com/docs/modules/chat-and-calls#section-3). ## Conversations and groups Start a one-to-one chat with a colleague, or create a group chat for a team or project. You can add more people to a group later from the group info panel. ### Starting a one-to-one chat 1. In Chat, select **New Chat**. 2. On the **Direct Message** tab, type a name in **Search employees...** and pick the person. 3. In the **Message** box, type your first message. 4. Select **Send Message**. The conversation opens. ### Creating a group 1. In Chat, select **New Chat**. 2. Switch to the **Group Chat** tab. 3. In **Group Name**, type a name for the group. 4. Use **Search employees to add...** to find people, and select each one to add them. Selected members appear as chips above the search box — select the small x on a chip to remove someone. 5. Select **Create Group**. The button shows how many members you've added. ### Adding people to a group 1. Open the group chat. 2. Select the **Info** button at the top of the conversation to open the group info panel. It shows the group name and the list of members. 3. Select **Add**, search for the person in **Search employees...**, and select them. They're added to the group. ## Messages, reactions and files Send text messages, react with an emoji, share files and images, and forward a message to another chat. ### Sending a message 1. Open the conversation. 2. Type in the message box at the bottom ("Type a message..."). 3. Press Enter to send. To start a new line instead of sending, press Shift+Enter. A tick appears next to your sent message; it changes once the other person has read it. You'll also see a "is typing" indicator when someone in the chat is typing. ### Reacting to a message 1. Hover over the message. 2. Select the menu button (the three dots) that appears next to it. 3. Pick an emoji from the row at the top of the menu. Your reaction appears under the message; pick a different emoji to change it. ### Sharing a file or image 1. Select the paperclip button to the left of the message box. 2. Choose **Image**, **Video**, or **File**, then pick the file from your device. 3. The file uploads and is sent to the chat. You can also drag a file onto the message area, or paste an image you've copied. To view an image someone sent, select it — it opens full size, with a button to download it. Press Escape or select the x to close it. Other file types show as a card you can select to download. ### Forwarding a message 1. Hover over the message and select its menu button (the three dots). 2. Choose **Forward**. 3. In **Search chats...**, find the chat you want to send it to and select it. The message is forwarded. ### Other actions - **Copy** — on a text message, the menu has a **Copy** option to copy its text. - **Delete** — on your own messages, the menu has **Delete**. You're asked to confirm; deletion can't be undone. ## Calls Audio, video and group calls between colleagues happen in the mobile app. The web version of Open Core HR Chat has no call buttons — use Chat on the web for messaging, files, and reactions. ### Setting up calling (administrators) Calls carry their audio and video through [Agora](https://www.agora.io). Until Agora is set up, the mobile app tells anyone who tries to call that calling is not set up yet. Call history and missed-call notifications are kept by Open Core HR, not by Agora. 1. In the Agora Console, create a project with **Secured mode: APP ID + Token** authentication. 2. Copy the project's **App ID** and **Primary Certificate**. 3. In Open Core HR, go to **Settings → Calls**. 4. Enter the **Agora App ID** and **Agora App Certificate**, then select **Save**. The status changes to **Calling is configured**. You need the **Manage settings** permission to see this tab. Nothing needs to be added to the server's `.env` file, and the mobile app does not need rebuilding — it collects the App ID from the server before each call. | Setting | What it does | |---|---| | Agora App ID | Identifies your Agora project. Phones receive this value. | | Agora App Certificate | Signs each call's access token on the server. It is stored encrypted and is never shown again or sent to phones. Leave the field blank to keep the stored certificate; use **Remove the stored certificate** to turn calling off. | | Call token lifetime | How long a call's access token is valid. The app renews it automatically during long calls. Default 60 minutes. | | Mark unanswered calls as missed after | Calls that ring this long without an answer — for example because the caller lost signal — are recorded as missed. Default 10 minutes. | --- # Disciplinary actions Issue and review warnings and appeals, and respond to warnings you receive. The Warnings screen lists every disciplinary warning in the system. From here you can filter and search the list, open a warning's details, work on drafts, and start the process of issuing a new warning. ## Steps 1. Open **Disciplinary Actions → Warnings** from the left menu. 2. Use the toolbar above the table to narrow the list (see below). 3. Click the view (eye) button on a row to open [a warning's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-17). 4. To raise a new one, click **Issue Warning** — see [Issuing a warning](https://czappstudio.com/docs/modules/disciplinary-actions#section-11). ![Warnings: Filters (1), a warning's actions (2) and Issue Warning (3).](https://media.czappstudio.com/screens/docs/warnings/light-4a9c21a668-2880.webp) ## Filtering and searching The toolbar above the table has: - An **All Employees** picker to show warnings for one employee. - An **All Types** dropdown to filter by warning type. - An **All Statuses** dropdown with: **Issued**, **Acknowledged**, **Appealed**, **Appeal Approved**, **Appeal Rejected**, **Withdrawn**, **Expired**. - A **Search warnings...** box that matches the warning number, the reason text, the employee's name or code, and the warning type name. You can also sort by the **Warning No.**, **Issue Date**, and **Status** columns. ## Following up on a warning Check severity, expiry, and status before acting. A **Draft** can be edited or submitted for approval if you have permission. Open the warning to review acknowledgment and appeals. ## Tips - A warning isn't issued until it has gone through its approval workflow. New warnings start as a draft, then get submitted for approval — see [Issuing a warning](https://czappstudio.com/docs/modules/disciplinary-actions#section-11). - Use **Acknowledged** to find warnings employees have already acknowledged. ## Warning types Warning types are the categories you choose from when issuing a warning — for example, "Verbal Warning" or "Written Warning". Each type sets a severity, how long an employee has to appeal, and whether the employee must acknowledge the warning. ### Opening the page Open **Disciplinary Actions → Warning Types** from the left menu. ### Adding a warning type 1. On the **Warning Types** page, click **New Type**. The **New Warning Type** panel slides in from the right. 2. Fill in the form: - **Name** — required (for example, "Verbal Warning"). - **Description** — optional. - **Severity** — Low, Medium, High, or Critical. Required. - **Appeal Deadline (days)** — the appeal window in days (0–365). - **Requires employee acknowledgment** — tick this if employees must acknowledge warnings of this type. - **Active** — tick to make the type available when issuing warnings. 3. Click **Create**. ![Warning Types: choose New Type (1) to add one.](https://media.czappstudio.com/screens/docs/warning-types/light-8b4d735225-2880.webp) ### Editing a warning type 1. Click the edit (pencil) button on the row. 2. Update the fields in the **Edit Warning Type** panel. 3. Click **Update**. ### Deleting a warning type 1. Click the delete (trash) button on the row. 2. Confirm in the **Delete Warning Type?** dialog by clicking **Delete**. A type that's already used by existing warnings can't be deleted. If you no longer want it offered, set it to **Inactive** instead. ### Tips - The severity you set on the type is the severity that appears on every warning of that type. - Only **Active** types appear in the warning type picker when issuing a warning. ## Issuing a warning Use this to record a disciplinary warning for an employee. A warning is first created as a draft, then submitted for approval — once the approval workflow finishes, it's officially issued and the employee is notified. ### Steps 1. Open **Disciplinary Actions → Warnings** from the left menu. (You can also use **Issue Warning** from the quick-create menu.) 2. Click **Issue Warning**. The **Issue Warning** panel slides in from the right. 3. Fill in the form: - **Employee** — the person the warning is for. Required. - **Warning Type** — pick from the configured types; the type's severity is shown next to its name. Required. - **Issue Date** — the date of the warning. Required; it can't be in the past. - **Expiry Date** — optional date after which the warning lapses. It can't be in the past or before the issue date. - **Reason** — the reason for the warning. Required. - **Incident Details** — optional space to describe what happened in more detail. 4. Click **Save as Draft**. The warning is saved with **Draft** status; it isn't issued yet. 5. To put it forward for approval, find the draft in the warnings list and click the submit (send) button on its row — or open the draft for editing and click **Submit for Approval**. This runs it through the configured approval workflow. If the draft's issue date has passed, update it before submitting. ![Issue Warning panel: choose the employee (1) and warning type (2), then Save as Draft (3).](https://media.czappstudio.com/screens/docs/warning-form/light-4d9b88a216-2880.webp) ### After you finish - After saving, you're returned to the **Warnings** list with the new draft showing. - Issuing the warning runs it through the configured approval workflow; saving as a draft holds it until you're ready. - Once submitted, the status moves through approval; when the workflow approves it, the warning becomes **Issued** and the employee is notified. ### Editing a draft 1. On the **Warnings** list, find a row with **Draft** status and click the edit (pencil) button. 2. Update the fields in the **Edit Draft Warning** panel. 3. Click **Save as Draft** to keep editing later, or **Submit for Approval** to send it into the workflow now. ### Troubleshooting - **Submitting for approval is refused.** The approval workflow for warnings may be turned off. An admin can check it on **Approval workflows** — see [Approval workflows](https://czappstudio.com/docs/administration/approvals#section-10). - **You don't see the Issue Warning button.** You need the permission to issue warnings. ## Issuing warnings to several employees Issue a separate warning for each employee, even when several employees are involved in the same incident. Review each employee's reason and incident details before submitting their warning for approval. Follow [Issuing a warning](https://czappstudio.com/docs/modules/disciplinary-actions#section-11) for each employee. Each warning has its own approval workflow and acknowledgment history. ## A warning's details The warning detail page shows the full record of a single warning — what it was for, who issued it, whether the employee has acknowledged it, and any appeals that have been raised against it. ### Steps 1. Open **Disciplinary Actions → Warnings** from the left menu. 2. Click the view (eye) button on the warning you want to open. 3. Use the back arrow at the top to return to the warnings list. ### Reviewing the warning Check the reason, incident details, expiry, and acknowledgment. Review **Appeal History** for any decision, resolution notes, and reviewer. Use **Download Warning Letter** to save the letter. ### Tips - Use the **Appeal History** section to track whether an appeal is still pending or has been resolved. To act on appeals, go to [Appeals](https://czappstudio.com/docs/modules/disciplinary-actions#section-21). ## Appeals When an employee disagrees with a warning, they can appeal it. The Appeals screen lists every appeal so you can review the employee's case and decide the outcome. ### Steps 1. Open **Disciplinary Actions → Appeals** from the left menu. 2. Use the status filter and search box to find an appeal. 3. From the appeal's actions menu, choose **View** to read its details, or **Review** to decide it — see [Reviewing an appeal](https://czappstudio.com/docs/modules/disciplinary-actions#section-26). ### Filtering and searching - An **All Statuses** dropdown with: **Pending**, **Under Review**, **Approved**, **Rejected**, **Withdrawn**. - A **Search appeals...** box that matches the appeal reason, the employee's name or code, the warning number, and the warning type name. You can sort by **Appeal No.**, **Submitted**, and **Status**. ### Choosing an appeal to review Open an appeal to review the related warning and employee’s statement. **Review** is available for **Pending** or **Under Review** appeals if you have permission. ### Tips - Appeals you can still act on are in **Pending** or **Under Review** status. Once an appeal is **Approved** or **Rejected**, **View** shows the recorded resolution but you can't change it. - Filter on **Pending** to see appeals that haven't been looked at yet. ## Reviewing an appeal When an employee appeals a warning, you review their case and record a decision — approve the appeal (and choose what happens to the warning) or reject it. Your decision updates the warning's status and notifies the employee. ### Steps 1. Open **Disciplinary Actions → Appeals** from the left menu. 2. Find an appeal that's **Pending** or **Under Review** and choose **Review** from its actions menu. **View** opens the appeal read-only. The **Review Appeal** panel slides in from the right. 3. Read the employee's case — the panel shows the **Appeal Reason**, the **Employee Statement** if one was given, and any **Supporting Documents** they attached. 4. Choose a **Decision**: - **Approve Appeal** — you're upholding the employee's appeal. - **Reject Appeal** — the warning stands. 5. If you chose **Approve Appeal**, pick an **Outcome**: - **Upheld** — the appeal is upheld. - **Reduced** — the warning is reduced. Choosing this reveals a **New Warning Type** picker; select the lower-severity warning type to move the warning to. This is required. - **Dismissed** — the warning is dismissed. 6. Enter **Resolution Notes** explaining your decision. This is required. 7. Click **Submit Review**. ### After you finish - The appeal's status changes to **Approved** or **Rejected**, with the outcome and your notes recorded against it. - The warning's status updates accordingly — **Appeal Approved** or **Appeal Rejected** — and if you chose the **Reduced** outcome, the warning is switched to the new warning type you picked. - The employee is notified of the resolution. - The recorded resolution then shows on the appeal's details (via the view button) and in the warning's **Appeal History** — see [A warning's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-17). ### Troubleshooting - **There's no Review button on the appeal.** You can only review appeals that are **Pending** or **Under Review**, and you need the permission to review appeals. - **Submit Review won't go through.** Resolution notes are mandatory, and if the outcome is **Reduced** you must also pick a new warning type. > **Note:** The Appeals screen goes straight from the list to the Review panel. There is no step for assigning an appeal to a specific reviewer before deciding it. ## Your warnings (employees) This page lists the warnings on your record so you can read them, download a copy, and acknowledge any that need a response. Open it from **My Warnings**. ### Following up Open a warning to read it, download the letter, or acknowledge it when required. Drafts and warnings still going through approval are not shown here. ### Steps 1. Go to **My Warnings**. 2. Use the **Status**, **From Date**, and **To Date** filters, or the **Search warnings...** box, to narrow the list. 3. On any row, use the actions: - The view icon opens [the warning's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-34). - The document icon downloads the warning letter. - The check icon (shown only when a warning is **Issued** and needs a response) opens the **Acknowledge Warning** window — see [Acknowledging a warning](https://czappstudio.com/docs/modules/disciplinary-actions#section-38). 4. Use **View My Appeals** to switch to [your appeals](https://czappstudio.com/docs/modules/disciplinary-actions#section-42). ### Tips - A warning only shows the acknowledge action while its status is **Issued** and it requires acknowledgment. ## Viewing a warning you received This page shows the full details of a single warning, plus any appeals raised against it. Open it from [your warnings](https://czappstudio.com/docs/modules/disciplinary-actions#section-30) by selecting the view icon on a row. ### Responding to a warning Read the warning and use **Download Letter** to save a copy. **Acknowledge** is available when an issued warning needs a response. **Appeal** is available while the warning is **Issued**; see [Raising an appeal](https://czappstudio.com/docs/modules/disciplinary-actions#section-46). Review existing appeals for their status and decisions. ### Steps 1. Open **My Warnings** from the menu. 2. Click the **view** icon on the warning you want. 3. Read the warning information and description. 4. Use **Download Letter** if you want a copy. 5. If the warning is **Issued**, decide whether to [acknowledge it](https://czappstudio.com/docs/modules/disciplinary-actions#section-38) or [raise an appeal](https://czappstudio.com/docs/modules/disciplinary-actions#section-46). ### Tips - Acknowledging a warning closes off the option to appeal it, so review it carefully before choosing. ## Acknowledging a warning Acknowledging a warning confirms that you have read and understood it. You can do this from [your warnings](https://czappstudio.com/docs/modules/disciplinary-actions#section-30) list or from [the warning's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-34). ### Steps 1. Open **My Warnings**, or open a warning's details page. 2. Select the acknowledge action — the check icon on a row, or the **Acknowledge** button on the details page. It only appears when the warning's status is **Issued** and it requires acknowledgment. 3. In the **Acknowledge Warning** window, optionally type a note in the **Comments (Optional)** box. 4. Select **Acknowledge**. ### After you finish After acknowledging, the warning's status changes to **Acknowledged**, and the acknowledged date and your comments appear on the warning's details page. ### Tips - Acknowledging a warning means you can no longer appeal it. If you want to contest the warning, [raise an appeal](https://czappstudio.com/docs/modules/disciplinary-actions#section-46) instead — both options are available while the warning is **Issued**. ## Your appeals This page lists the appeals you've raised against warnings, with their status and outcome. Open it from **My Appeals**. ### Tracking your appeal Check the status and, once decided, the outcome: **Warning Upheld**, **Warning Reduced**, or **Warning Revoked**. Open the appeal to read HR’s decision. ### Steps 1. Go to **My Appeals**. 2. Use the **Status**, **From Date**, and **To Date** filters, or the **Search appeals...** box, to narrow the list. 3. On any row, use the actions: - The view icon opens [the appeal's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-50). - The X icon (shown only while the appeal is **Pending** or **Under Review**) starts a withdrawal — see [Withdrawing an appeal](https://czappstudio.com/docs/modules/disciplinary-actions#section-53). 4. Use **View My Warnings** to switch to [your warnings](https://czappstudio.com/docs/modules/disciplinary-actions#section-30). ### Tips - To raise a new appeal, open the warning you want to contest and use its **Appeal** button — see [Raising an appeal against a warning](https://czappstudio.com/docs/modules/disciplinary-actions#section-46). ## Raising an appeal against a warning If you disagree with a warning, you can submit an appeal for HR to review. You start an appeal from the warning itself. ### Steps 1. Open [the warning's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-34) from **My Warnings**. 2. Select **Appeal**. (This is available while the warning is **Issued** and the appeal deadline hasn't passed.) 3. On the **Submit Appeal** page, review the **Warning Summary** — it shows the warning number, type, reason, and the **Appeal Deadline**. 4. Fill in the appeal form: - **Reason for Appeal** (required) — a brief description of why you're appealing. - **Your Statement** (required) — your detailed statement and any relevant context. - **Supporting Documents (Optional, max 5 files)** — use **Upload Files** to attach evidence. Accepted file types are PDF, JPG, JPEG, PNG, DOC, and DOCX. Use **Remove** next to a file to take it off. 5. Select **Submit Appeal**. To stop without submitting, select **Cancel**. ### After you finish After you submit, the appeal is created with status **Pending**, the warning's status changes to **Appealed**, and you're taken to [the appeal's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-50). ### Tips - You can have only one active appeal per warning. - If the deadline to appeal has already passed, or an appeal is already in progress, you'll be sent back to the warning with a message explaining why. - Acknowledging a warning ends the option to appeal it, so don't acknowledge a warning you intend to contest. ## Viewing your appeal This page shows everything about a single appeal — what you submitted, its current status, and HR's decision once it's reviewed. Open it from [your appeals](https://czappstudio.com/docs/modules/disciplinary-actions#section-42) by selecting the view icon on a row, or from the linked appeal on a warning's details page. ### Reviewing the decision Read **Review Notes** and the outcome once HR has reviewed the appeal. If the warning was reduced, check the new warning type. You can withdraw an appeal while it is **Pending** or **Under Review**. ### Steps 1. Open [your appeals](https://czappstudio.com/docs/modules/disciplinary-actions#section-42) and select the view icon on the appeal you want. 2. Review the overview, your submitted text, and any review notes. 3. If the appeal is still **Pending** or **Under Review** and you no longer want to pursue it, use **Withdraw** — see [Withdrawing an appeal](https://czappstudio.com/docs/modules/disciplinary-actions#section-53). ## Withdrawing an appeal You can withdraw an appeal you've raised, as long as HR hasn't finished reviewing it. Do this from [your appeals](https://czappstudio.com/docs/modules/disciplinary-actions#section-42) list or from [the appeal's details](https://czappstudio.com/docs/modules/disciplinary-actions#section-50). ### Steps 1. Open **My Appeals**, or open an appeal's details page. 2. Select the withdraw action — the X icon on a row, or the **Withdraw** button on the details page. It's only available while the appeal's status is **Pending** or **Under Review**. 3. In the **Withdraw Appeal** confirmation window, select **Withdraw Appeal**. To keep the appeal, select **Cancel**. ### After you finish The appeal's status changes to **Withdrawn**. The related warning goes back to the status it had before you appealed, and any supporting documents you attached are removed. ### Tips - Withdrawing an appeal can't be undone. If you still want to contest the warning afterward, you'd need to raise a new appeal — and only if the warning is still appealable. --- # Documents Define document types, keep employee documents and upload your own documents. ## Document types Document types define the documents your organisation collects, such as identity documents, qualifications, or signed contracts. Configure them under **Settings → Master Data → Document Types** before requesting files from employees. ### Decide which documents are required ![Document Types: Add New (1) or Request resubmission from all (2).](https://media.czappstudio.com/screens/docs/document-types/light-43b00ffa01-2880.webp) Enable **Required** only for documents that every joining employee must provide. An active, required document must be approved before onboarding can be completed. Active optional types can still be requested individually when they apply to a particular employee; they do not block onboarding by default. To add a type, choose **Add New**, enter its name, and set **Required** and **Active** to match your process. Add notes when HR needs guidance about acceptable evidence. Leave **Code** blank to generate it, or supply a unique code of up to 50 characters. The code cannot be changed after creation. ### Retire or change a document requirement Edit the type when its name, notes, or requirement changes. Turning off **Active** stops the type from being required for new onboarding while keeping previously submitted records. Use this when you stop collecting a document. Delete a type only when it is no longer needed. Deletion cannot be undone; retiring it is preferable when existing records still refer to it. ## Employee documents The **Documents** tab on an employee's profile lists one row per document type (for example ID proof, address proof), so you can see at a glance which documents are on file and add or view them. ### Adding or replacing a document 1. Open the employee's profile and go to the **Documents** tab. 2. Find the document type's row. 3. If nothing is on file yet, click **Upload** and pick the file. If a document is already there, click the upload icon to replace it. ### Bulk uploading documents 1. On the **Documents** tab, click **Bulk Upload**. 2. In the **Bulk Document Upload** panel, for each row pick a **Document Type** and choose a **File**. Click **Add Another Document** to add more rows (up to 10). 3. Click **Upload Documents** to save them all, or **Cancel** to close. ![An employee's Documents tab (1) with Bulk Upload (2) and Download All (3).](https://media.czappstudio.com/screens/docs/employee-documents/light-61973dc628-2880.webp) Supported file types are PDF, DOC, DOCX, JPG, JPEG, and PNG, up to 10 MB per file. ### Viewing and downloading For a row that has a document: - Click **View**, then **View in Browser** to open it in a new tab, or **Open Direct Link** to open the stored file directly. - Click the download icon to download just that document. ### Download all Click **Download All** at the top of the **Documents** tab to get a single zip file containing every document on file for the employee, organized by document type. This button appears only when at least one document exists. ## Your documents (employees) The **Documents** screen in the **Documents** module lists the documents you've uploaded and lets you view or download them. ### Steps 1. Open **Documents** from the module menu. 2. To save a copy, click the download icon in the **Actions** column. 3. To open the document in a new browser tab, click the view (eye) icon. ![Your documents in the mobile app.](https://media.czappstudio.com/screens/mobile/documents/light-7ef50faf9c-1206.webp) ### Tips - To add a document, click **Upload Document** — see [Uploading a document](https://czappstudio.com/docs/modules/documents#section-12). ## Uploading a document Use the **Documents** screen to upload a document and file it under a document type. ### Steps 1. Open **Documents** from the module menu. 2. Click **Upload Document**. The **Upload Document** dialog opens. 3. Choose a **Document Type** from the dropdown. 4. Under **File**, choose the file from your device. Accepted formats are PDF, JPG, and PNG, up to 5 MB. 5. Click **Upload**. ### After you finish The document is added to your records. > **Note:** If you upload a new file for a document type you already have on file, it replaces the previous one. ### Troubleshooting - **The upload is rejected** — check that the file is a PDF, JPG, or PNG and within the size limit, and that you selected a document type. --- # Employee lifecycle Manage recruitment, offers, onboarding, probation, employment changes, separations and final settlements. Use Employee Lifecycle for joining arrangements, employment changes, and exits. The module must be enabled and your permissions must allow the action you want to take. Start with the path your organisation needs. Add an employee directly for an existing or confirmed hire. Use [recruitment](https://czappstudio.com/docs/modules/employee-lifecycle#section-1) when you need to advertise a job or track candidates. An offer, interviews, and probation are optional; there is no mandatory chain for every hire. An employee's profile holds their current work information and compensation. Lifecycle records explain the changes: offers and onboarding, optional probation, promotions or other employment changes, and separation. [Account access](https://czappstudio.com/docs/administration/employees#section-2) is managed separately from employment progress. Joining and exit tasks share one task list and track the practical work around a hire or an exit. Tasks marked required must be completed or waived before onboarding is completed or employment is ended; optional tasks never block. Set the default tasks once under [Settings → Joining and exit tasks](https://czappstudio.com/docs/modules/employee-lifecycle#section-36). For an exit, record the last working date and assign practical handover tasks. HR ends employment once the required tasks are done, independently of any payment record. Prepare an optional [settlement](https://czappstudio.com/docs/modules/employee-lifecycle#section-22) only when there are amounts to record. Use [Disciplinary Actions](https://czappstudio.com/docs/modules/disciplinary-actions) for employee warnings. Employment letters and the [timeline](https://czappstudio.com/docs/administration/employees#section-12) provide supporting records. ## Choosing a recruitment path Recruitment helps HR manage jobs, applicants, and interviews before an offer. Employee Lifecycle must be enabled. Viewing applicants, conducting interviews, creating offers, and downloading candidate documents are separate permissions. Choose the shortest path that fits the hire: - Add an employee directly when the hiring decision is already made and no offer record is needed. - [Add an applicant](https://czappstudio.com/docs/modules/employee-lifecycle#section-3) for a referral or other candidate, with or without a job posting. - [Publish a job](https://czappstudio.com/docs/modules/employee-lifecycle#section-2) when people should apply through your public careers page. Interviews are optional records attached to an applicant. You can create an offer for an open applicant without completing a fixed series of interview rounds. An offer records the proposed employment terms; the candidate becomes an employee through the joining process. Keep notes relevant to the hiring decision. Candidate contact information and CVs belong to the recruitment record; they are not colleague-directory entries. ## Publishing a job Create a job when you want candidates to apply through the public careers page. You need permission to manage job postings. A super admin connects the website using [Careers integration](https://czappstudio.com/docs/modules/employee-lifecycle#section-5). 1. Open **Job Postings** and create a draft with a clear title and description. 2. Add the internal designation, department, and location if they are already known. They are optional during recruitment. 3. Add a pay range only if you want to record one. Include the currency and hourly, daily, weekly, monthly, or yearly pay period so candidates can interpret it correctly. 4. Review the opening count and any closing date, then publish when you are ready to accept applications. ![Job Postings: choose Create Job Posting (1) to draft a job.](https://media.czappstudio.com/screens/docs/job-postings/light-b27ff6e1f3-2880.webp) Draft and closed jobs do not accept public applications. Close a job when hiring stops; existing applicants and interviews remain available for follow-up. If a candidate cannot apply, check that the job is published and its closing date has not passed. Public applications require the applicant's name and email. Phone, current location, a message, and CV are optional. Review new submissions in [Applicants](https://czappstudio.com/docs/modules/employee-lifecycle#section-3). ## Managing applicants ![Applicants: Add applicant (1) or open an applicant's actions (2).](https://media.czappstudio.com/screens/docs/applicants/light-0ec20e1a7f-2880.webp) Use **Applicants** for public applications, referrals, and candidates added by HR. Name and email are required; a linked job, phone, current location, message, and CV are optional for an applicant added internally. Review the candidate's relevant experience in their CV or notes. Download a CV only when your permissions allow it. The application form does not require family details, date of birth, gender, or a previous salary slip. Applicants progress through **New**, **Shortlisted**, **Interviewing**, **Offered**, and **Hired** as work is recorded. **Rejected** and **Withdrawn** close an application without hiring. Shortlist a candidate when you want to continue; reject when your organisation decides not to proceed, or withdraw when the candidate leaves the process. You can [schedule an interview](https://czappstudio.com/docs/modules/employee-lifecycle#section-4) when an assessment is useful. An interview is optional: an open applicant can move directly to an offer if you have permission to create one. Before making an offer, check for another offer already in progress so the candidate does not receive conflicting terms. Hiring links the applicant to an employee record. Use that record for employment and access management after the handoff. ## Scheduling and recording interviews Interviews are optional assessments attached to an applicant. Each interview has an assigned interviewer, type, and scheduled time; there are no mandatory interview templates or round counts. 1. Open the applicant and schedule an interview with an interviewer and date/time. Include a meeting link or location instructions where appropriate. 2. Confirm the arrangements with the candidate through your organisation's usual communication process. 3. After the interview, the assigned interviewer records notes and a passed or failed outcome. A numeric score is optional. Reschedule when the time changes, mark a no-show when the interview did not happen, or cancel an interview that is no longer needed. A completed assessment records the interviewer's decision; HR still makes the separate decision to offer, reject, or continue assessing the applicant. An assigned interviewer can use **My Interviews** to find their interviews. Applicant documents remain subject to document-download permission. If you cannot record a result, confirm that you are the assigned interviewer and that the interview is still open. ## Careers integration Connect your careers website to published jobs and candidate applications. This requires **Employee Lifecycle** and a **super admin**. Open **Recruitment → Careers Integrations** to manage each website's credentials separately. ### Set up a website connection 1. Create a client with a recognizable name, unique code and optional contact email and description. 2. Select only the capabilities the website needs: - **Read published jobs** (`careers:read`) — list and display vacancies. - **Submit applications** (`applications:write`) — submit applications and check whether a candidate is eligible to apply again. - **Read application status** (`applications:read`) — provide the supported candidate-status lookup. 3. Leave the client active, save it and open its token controls. 4. Give the token a name and select its capabilities, then generate it and copy it immediately. The complete token is shown once. 5. Give it to the developer configuring the careers website. Store it on that website's server, never in browser JavaScript or a public repository. The website calls `/api/v1/external/careers` with the token as an `Authorization: Bearer` header. Your developer should use the integration routes for published postings, applications, eligibility and candidate status. The website does not receive access to employee records, the administration portal or webhook configuration. ### Change or revoke access A token can use only capabilities allowed by both the token and its client. Removing a client's capability revokes every token that included that capability, including the token's other access. Generate a replacement with the remaining capabilities and update the website's configuration. New clients default to reading published jobs; explicitly select application capabilities when needed. Deactivate a client to pause all its tokens. Revoke an individual token if it is lost or exposed, or delete the client to revoke all its tokens. Create a replacement before removing the website's current token when avoiding downtime matters. Disabling Employee Lifecycle also disables this integration. ### Resolve connection problems - **Unauthenticated:** check that the server sends a valid, unexpired token. Revoked tokens must be replaced. - **Access denied:** check that the client is active and both it and its token allow the requested capability. - **Too many requests:** reduce the website's request frequency and retry after the server's rate-limit interval. - **No vacancies:** confirm the jobs are published and available to candidates; the website cannot retrieve unpublished recruitment records. ### Application tracking links Applicants receive a confirmation email with a link to track their application on your careers website. Enter the website's address in **Settings → Recruitment → Careers website address**. Without it, the confirmation email shows the reference number but no tracking link. The same tab sets when unanswered interview outcomes are reported as missed and how many days before a probation period ends managers and HR are reminded. ## Managing employment offers Use **Offers** when you need to record proposed employment terms and obtain a candidate's response. An offer is optional for a direct hire. A **Draft** can be edited before it is sent. **Sent** means the candidate has a secure link to review the terms. They can accept or decline before the expiry date. **Accepted**, **Declined**, **Expired**, and **Revoked** describe the outcome; acceptance is separate from completing employment onboarding. Before sending or resending an offer, check the candidate's email, joining date, work assignment, and any pay terms. Revoke an open offer if its terms should no longer be accepted. To replace terms after a response, use your organisation's agreed HR process rather than changing an accepted document without review. Acceptance creates or links the employee record, sends an account invitation, and starts a standalone onboarding record. Follow up in [Onboarding](https://czappstudio.com/docs/modules/employee-lifecycle#section-12). ## Creating and sending an offer You need permission to create offer letters. Start from an open applicant when recruitment already has the candidate's details, or create an offer directly in **Offers**. 1. Check the candidate's name and email and enter the planned joining date. 2. Add the designation, department, location, and reporting manager where known. 3. Record an optional agreed pay amount with its currency and pay period. Leave pay blank if it is not part of this offer record. 4. Add an expiry date, probation end date, notice period in days, and terms only where they apply. 5. Save the draft, review it, then choose **Send offer**. The candidate receives a secure link to accept or decline. The link is for that decision; private personal, emergency, and bank details are maintained later in the employee's profile. Accepting the offer sends a separate invitation to set a password and starts [onboarding](https://czappstudio.com/docs/modules/employee-lifecycle#section-12). Probation is created only if an end date was supplied. ## Completing onboarding Onboarding is a standalone record for an employee who is joining. It can begin from an accepted offer or a direct hire; you do not need a recruitment application or offer for every employee. You need **Manage onboarding** access to start, review, or complete these records. Offer-letter permissions are separate. 1. Open **Onboarding** and select an existing record, or start onboarding for an employee. The default joining tasks are added automatically. 2. Check the joining date and add a probation end date only if probation applies. 3. Open the record to review its tasks. Add any further tasks, assign each to a responsible person, and choose whether it must be done before completion. Assignees complete their work through [Assigned joining and exit tasks](https://czappstudio.com/docs/modules/employee-lifecycle#section-35); you can also mark a task **Completed**, or **Waived** when it does not apply. 4. Review the employee's profile and the [required documents](https://czappstudio.com/docs/modules/documents#section-4). Request corrections through the document process when a file is missing or unsuitable. 5. Choose **Complete onboarding** when every required task is completed or waived. Required tasks that are still pending block completion; optional tasks do not. Outstanding documents don't block completion; follow them up through the document process. Personal details, bank details, compensation, and appointment letters are optional. Completion marks employment as **Employed**. If a probation end date was provided, it creates a probation review. Account access still depends on the separate invitation and account status; completing onboarding does not set or reveal a password. ## Appointment letters An appointment letter records employment terms for an employee. It is optional and does not determine whether onboarding or account access is complete. Use **Appointments** to find an existing letter or issue one when your organisation needs it. Check the employee, effective date, work terms, and content before sharing it. See [Issuing an appointment letter](https://czappstudio.com/docs/modules/employee-lifecycle#section-14). ## Issuing an appointment letter An appointment letter is an optional document for an existing employee. Creating the draft and issuing it require the relevant appointment permissions. 1. Open **Appointment letters** and create a record for the employee. 2. Enter working hours and agreed terms where needed, then save the draft. 3. Review the employee and terms. A user with permission to issue the letter selects **Issue letter**. 4. Use the employee's letters to view or download the issued document. Issuing a letter does not complete onboarding, confirm probation, change compensation, or enable account access. Manage those decisions in their own records. ## Tracking optional probation Use **Probations** for employees whose joining terms include a probation period. A review is created during onboarding completion only when an explicit probation end date was supplied. Review the end date before deciding to extend or confirm the employee. **Ongoing** is the original review period, **Extended** means a new end date has been recorded, and **Confirmed** means the confirmation workflow has finished. Probation does not disable sign-in or change the employee's account status. Follow [Managing probation](https://czappstudio.com/docs/modules/employee-lifecycle#section-16) to record a decision. ## Managing probation Use **Probations** when an employee has an explicit probation end date. You need permission to manage probation to extend or submit a confirmation. To extend a review, record the new end date and the reason. Check the agreed terms with the employee before making the change. The record keeps the original and extended end dates. To confirm completion of probation, choose **Confirm** and submit through the configured confirmation workflow. When approval completes, the review becomes **Confirmed**. If no approval workflow is configured, the permitted confirmation is completed directly. Confirmation records the probation decision. It does not change account access, calculate pay, or require an appointment letter. ## Tracking employment changes Use **Employment changes** to record a promotion, transfer, pay change, or another agreed change. Each record preserves the previous terms and the proposed values with an effective date. Check the employee, changed fields, date, and approval state. An approved future change is applied when its effective date arrives. Approval and application are separate events, so check the employee's current profile before assuming a future change is already in force. See [Creating an employment change](https://czappstudio.com/docs/modules/employee-lifecycle#section-18). Current compensation and its history remain available from the employee profile independently of the Lifecycle module. ## Creating an employment change You need permission to create employment changes. Open **Employment changes**, select the employee, and choose **Promotion**, **Transfer**, **Pay change**, or **Other**. 1. Set the effective date and a useful reason. 2. Enter only the terms that should change: designation, department, location, manager, or pay. Leaving an unrelated field blank keeps its existing value. 3. For a pay change, record the amount, currency, and pay period together. 4. Save the draft and review the previous and proposed terms, then choose **Submit change**. The configured approval workflow is used when available. If none is configured, submission records approval directly. Future approved changes wait for their effective date before changing the employee's current terms. This records employment terms and compensation history. It does not calculate payroll or produce a payslip. ## Tracking employee exits A separation records why employment is ending and the last working date. Use **Separations** to find an exit in progress or review a completed one. Review the employee, exit type, last working date, and approval status before taking action. Exit tasks track assigned handover work; an optional settlement records amounts. Neither changes the last working date automatically. Ending employment requires every required exit task to be completed or waived. HR chooses separately whether to disable account access. Optional tasks and unpaid settlement records can remain open after employment ends, so continue following them up from the separation and settlement records. See [Managing a separation](https://czappstudio.com/docs/modules/employee-lifecycle#section-20) for the process and [Recording a final settlement](https://czappstudio.com/docs/modules/employee-lifecycle#section-22) for payments. ## Managing a separation Record an exit when an employee resigns or your organisation ends their employment. You need permission to manage separations; your organisation's approval workflow may also apply. 1. Open **Separations**, select the employee, and record the exit type, resignation or notice date, last working date, and reason. The default exit tasks are added automatically. 2. Submit the record for approval when required. Address rejection notes before resubmitting. 3. Open the record and add any further tasks for the actual work needed, such as returning equipment, transferring responsibilities, or reviewing access. Assign each task to a responsible person and choose whether it must be done before completion. 4. Assignees complete their work through [Assigned joining and exit tasks](https://czappstudio.com/docs/modules/employee-lifecycle#section-35). HR can record **Completed**, or **Waived** when the task does not apply. 5. When every required task is completed or waived and the last working date has been reached, choose **End employment** and explicitly decide whether account access should be disabled. ![Separations: choose Add record (1) to record an exit.](https://media.czappstudio.com/screens/docs/separations/light-f36fb1eee5-2880.webp) Ending employment marks it as **Ended**. Required tasks that are still pending block this step; optional tasks do not. A settlement does not have to be paid first. If money remains to be recorded, create an optional [settlement](https://czappstudio.com/docs/modules/employee-lifecycle#section-22). Do not change the employment end date merely to wait for a payment. ## Tracking final settlements A settlement is an optional payment record associated with an employee's separation. Use it when there are agreed additions or deductions to record at exit. Check the currency, each line's meaning, the net amount, approval progress, and payment date. Amounts are entered and reviewed by authorised staff. The system totals the lines; it does not calculate payroll, tax, gratuity, leave encashment, or other statutory entitlements for you. Employment completion and settlement payment are independent. An employee can have ended employment while a settlement is still being reviewed or remains unpaid. See [Recording a final settlement](https://czappstudio.com/docs/modules/employee-lifecycle#section-22). ## Recording a final settlement Create a settlement only when there are exit-related amounts to record. You need permission to manage settlements and a separation record for the employee. 1. Select the separation, currency and calculation mode. 2. Add a clear label and amount for each **Addition** or **Deduction**. Use the amounts your authorised payroll or finance process has established. 3. Check the net total and supporting notes before submitting for approval. 4. Resolve any review comments before payment. 5. For a **Full settlement**, mark it paid only after payment has actually been made and record the payment details. For **Payroll adjustments**, link it to Payroll and record payment there. Choose **Payroll adjustments** when Payroll calculates the employee's final salary. Enter only additional exit amounts; exclude salary and anything already included in payroll, such as an integrated loan repayment. Complete the separation and approve the adjustments before linking them to the employee's final pay run. The separation's last working date must be within that payroll period. Choose **Full settlement** when an external process has established the whole settlement and you will record its payment here. These records cannot be added to Payroll salary. Calculation mode can change only while the settlement is a draft; check it before approval. Loans, bonuses, and other balances are not automatically imported into this record. Check the relevant source records before entering a line so an amount is not omitted or counted twice. The payment record does not complete the employee's separation or disable their account. Manage those decisions from the [separation](https://czappstudio.com/docs/modules/employee-lifecycle#section-20). ## Checking your employment changes Open **My employment changes** to review promotions, transfers, pay changes, or other recorded changes to your employment. Employee Lifecycle must be enabled. Compare the previous and new terms, effective date, reason, and approval state. An approved future change may not yet appear as your current work assignment or compensation. Ask HR about any discrepancy before the effective date where possible. Your profile contains current agreed compensation and its history. These records describe agreed terms; payroll payments are handled separately. ## Your probation This page shows your probation reviews and confirmation status. Open it from **My Workspace > My Probation**. > **Availability:** This area may not be turned on for your company yet. If you don't see it in your menu, it isn't enabled — check with your HR team. ### Checking your probation Check the original end date and any extension date and reason. Once confirmed, review the confirmation date and HR’s notes. ### Steps 1. Go to **My Workspace > My Probation**. 2. Review each probation review card. ## Your separations This page is where you start a resignation and track its progress. Open it from **My Workspace > My Separations**. ### Tracking your resignation Review your proposed last working day and request status. **Initiate Resignation** is available when you do not already have an active separation in progress. ### Steps 1. Go to **My Workspace > My Separations**. 2. To start a resignation, select **Initiate Resignation** — see [Initiating your separation](https://czappstudio.com/docs/modules/employee-lifecycle#section-30). 3. To check progress, review the card for your request and its status tag. ## Initiating your separation This page covers submitting your resignation for HR to review and approve. You reach it from [your separations](https://czappstudio.com/docs/modules/employee-lifecycle#section-27). ### Steps 1. Go to **My Workspace > My Separations**. 2. Select **Initiate Resignation**. 3. On the **Initiate Resignation** page, fill in the **Resignation Details**: - **Resignation Date** (required) — the date of your resignation. - **Last Working Date** (required) — your proposed last working day. - **Reason for Resignation** (required) — the reason for your decision. - **Additional Notes** — any extra context (optional). 4. Select **Submit Resignation**. To leave without submitting, select **Cancel**. ### After you finish After you submit, you're taken back to [your separations](https://czappstudio.com/docs/modules/employee-lifecycle#section-27), where your request appears with its current status. HR will then review and process it. ### Tips - If you already have a separation request in progress, the **Initiate Resignation** button won't appear — you can only have one active request at a time. ## Checking your final settlement Open **My Settlement** to review a settlement HR has recorded for your exit. Employee Lifecycle must be enabled and you must retain account access. Check the currency, labelled additions and deductions, and net amount. Contact HR or finance about a line you do not understand before relying on the total. A paid status means staff have recorded payment; compare it with the payment you receive. Your employment end date and settlement payment are separate. Ending employment does not mean every payment is complete. If you no longer have access, ask HR for a copy and a way to follow up. ## Completing assigned joining and exit tasks Open **Assigned joining and exit tasks** in self-service when HR assigns you part of an employee's joining or handover. Each row shows whether the task is for someone joining or leaving, the employee, and their joining or last working date. Review the task before marking it complete, and record a useful note, such as where equipment was returned or which person received a handover. Mark a task **Completed** only when the work is done. Ask HR to waive a task that does not apply; assignees cannot waive tasks themselves. Completing a task does not complete the employee's onboarding, end their employment, disable their account, or record a settlement payment. HR cannot complete an onboarding or end employment while a required task is still pending, so complete your tasks promptly or tell HR what is holding them up. ## Default joining and exit tasks With permission to manage settings, open **Settings → Joining and exit tasks**. List the tasks under **When someone joins** and **When someone leaves**. Give each a title, an optional owner, and choose whether it must be done before completion. Changes apply to onboarding started and separations recorded afterwards; existing records keep their tasks. Add one-off tasks on the record itself. --- # Company feed Share posts in the company feed and configure how the feed works. Requires the **Feed** module and access to the web application. Open **Company Feed** from the left menu, alongside the communications tools. The web page and the **Connect → Feed** area of the HR mobile app show the same posts, comments and reactions. Birthday, work anniversary and welcome posts appear in the same feed with their event label. ## Share an update 1. Enter your message under **Share an update** (up to 500 characters). 2. Optionally choose an **Attachment** (up to 20 MB). Images, supported documents, audio and video files can be attached; a file-only post is also allowed. 3. Click **Publish post**. The post appears under your account. If publication fails, your draft stays available to retry. ![Company Feed: write your update (1), attach a file (2) and Publish post (3).](https://media.czappstudio.com/screens/docs/feed/light-94863f438a-2880.webp) Posts are visible to signed-in staff across the company. Use the audience selector to browse **All company posts** or **My location**; this changes the list, not access to posts. Click **Refresh** to reload, and use **Previous posts** or **Next posts** when there are several pages. ## Join the conversation Click a reaction below a post to add your reaction. Click the same reaction again to remove it, or choose another to change it. Click the comment count to open comments. Enter your message under **Add a comment**, then click **Post comment**. Comments allow up to 4,000 characters and show newest first. Use the comment pagination controls to read older replies. Images display inside the post. Click the attachment to open or download it through the authenticated Feed service. ## Configure greetings Click **Feed settings** to open **Settings → Feed**. Viewing requires `view_settings`; saving requires `manage_settings`. Enabled greetings post automatically on the day. See [Feed settings](https://czappstudio.com/docs/modules/feed#section-4). ## Feed settings Requires the **Feed** module. Open **Settings → Feed** in web admin. Viewing requires `view_settings`; saving requires `manage_settings`. ### Greetings Choose which events create Feed posts: - **Birthday greetings** — celebrate active employees on their birthday. - **Work anniversary greetings** — celebrate completed years of service. - **Welcome messages** — welcome active employees on their joining date. This is separate from work anniversaries and is off by default. Each enabled greeting type posts to the Feed automatically on its day; there is no approval step. Birthday and anniversary greetings are on by default on new installations. The scheduler checks active employees at **06:00 in the configured scheduler timezone**. It uses the date of birth and joining date recorded on the employee profile. Disable each event type to stop generating it. Save with **Save Changes**. ### Notifications and mobile **Notify colleagues** chooses **Same location** or **Everyone**. This controls who is notified, not who can see the post: signed-in staff can browse the organization Feed. Published greetings appear in the web Company Feed and as ordinary posts in the **Connect → Feed** area of the HR mobile app, labelled Birthday, Work anniversary or Welcome. Employees can comment and react as usual. Configure greetings in the web admin interface. Greetings require the Laravel scheduler and system bot account. See the installation guide for scheduler setup. --- # Loans Create, approve, disburse, repay and close employee loans, and review loan reports. The **All Loans** page lists every employee loan in your organization, with its amount, monthly instalment, outstanding balance and status. Open it from **Loans > All Loans** in the left menu. ## Steps 1. In the left menu, choose **Loans > All Loans**. 2. Use the **Search loans...** box to find a loan by loan number or by the employee's name or code. 3. Use the status dropdown (showing **All Statuses** by default) to narrow the list to one status: **Pending**, **Approved**, **Active**, **Completed**, **Rejected** or **Cancelled**. 4. Click the **Loan Number**, **Amount**, **Status** or **Start Date** column headers to sort. 5. Use the eye icon in the **Actions** column to open a loan's details. See [A loan's details](https://czappstudio.com/docs/modules/loans#section-19). ![Loans: search (1), Filters (2) and a loan's actions menu (3) to view it.](https://media.czappstudio.com/screens/docs/loans/light-86c7f1a35c-2880.webp) ## Loan statuses - **Pending** — submitted and waiting for approval. - **Approved** — approved, but not yet disbursed. - **Active** — disbursed; repayments are in progress. - **Completed** — fully repaid or closed. - **Rejected** — turned down during approval. - **Cancelled** — withdrawn before approval finished. You can edit a loan while it is **Pending** or **Approved**, and disburse it once it is **Approved**. ## Tips - Loan applications go through your organization's approval workflow. Review and approve them from the **Approvals** inbox — see [Approving and disbursing a loan](https://czappstudio.com/docs/modules/loans#section-13). - Employees apply for their own loans from the personal page in its module under **My loans**. - To edit a pending or approved loan, click the pencil icon in the **Actions** column. You can change the **Amount**, **Tenure (months)**, **Start Date**, **Purpose** and **Notes**; the estimated EMI is recalculated automatically. ## Loan settings Administrators set loan rules in **Settings → Loans**: - **Loan number prefix**: new loans are numbered *PREFIX*-*YEAR*-0001. Existing loans keep their numbers. - **Maximum repayment period**: the longest tenure employees and HR can enter. - **Create monthly deductions on day**: the day each month when payroll deductions are created. In shorter months they are created on the last day. - **Close loans automatically when fully repaid**: when off, HR closes repaid loans manually. ## Creating a loan A loan starts as a request: the employee applies for it from the personal page in its module, and you take over from there to approve and disburse it. The admin **All Loans** page does not have a "new loan" button — loans always begin as an employee application. ### How a loan is created 1. The employee opens **My loans** in the web application and chooses **Apply for Loan**. 2. They fill in the request: - **Amount** — the amount they want to borrow. - **Tenure (months)** — how many months to repay over, up to the maximum in **Settings → Loans** (60 by default). - **Start Date** — when the repayments should begin. - **Purpose** — the reason for the loan (optional). - **Notes** — any extra detail (optional). - **Security Deposits / Supporting Documents** — optionally, one or more entries. Each entry has a type (**Supporting Document**, **Blank Cheque**, **Post-Dated Cheque** or **Other**); cheque entries need a cheque number and bank name, and any entry can include an uploaded file. 3. When they submit, the request enters your organization's approval workflow and appears in **Loans > All Loans** with the status **Pending**. ### Your part 1. Review the application in the **Approvals** inbox and approve or reject it. See [Approving and disbursing a loan](https://czappstudio.com/docs/modules/loans#section-13). 2. While the loan is still **Pending** or **Approved**, you can adjust it from **All Loans**: click the pencil icon in the **Actions** column to change the **Amount**, **Tenure (months)**, **Start Date**, **Purpose** or **Notes**. The estimated EMI updates automatically. 3. Once approved, disburse the loan to activate it and create the repayment schedule. See [Approving and disbursing a loan](https://czappstudio.com/docs/modules/loans#section-13). ### Tips - The EMI is the loan amount divided evenly across the tenure — there is no separate interest field. - The loan number is generated automatically when the request is submitted. ### Troubleshooting - The admin **All Loans** page offers view, edit and disburse only — there is no "add loan" action, so every loan starts from the self-service application route described above. ## Creating a loan on behalf of an employee In the web admin area there is no "new loan" button on the **All Loans** page — loans always start as an employee application from the personal page in its module. There is no admin form that lets you pick an employee and raise a loan for them from **Loans > All Loans**. 1. **Loan Management** — Open the **Loan Management** group in the menu. 2. **All Loans** — Then choose **All Loans**. ### What you can do instead - Ask the employee to submit the request themselves from **My loans** in the web application. Once it is in, it appears under **Loans > All Loans** as **Pending**, and you can approve, edit and disburse it. See [Creating a loan](https://czappstudio.com/docs/modules/loans#section-5) and [Approving and disbursing a loan](https://czappstudio.com/docs/modules/loans#section-13). - While the request is **Pending** or **Approved**, you can fine-tune the **Amount**, **Tenure (months)**, **Start Date**, **Purpose** and **Notes** from the pencil icon in the **Actions** column. ### Troubleshooting - The underlying create action accepts an employee selection, but no employee picker is exposed on the web admin **All Loans** screen. ## Approving and disbursing a loan A loan application moves through two steps before repayments begin: it is approved through your organization's approval workflow, and then it is disbursed. Disbursing the loan activates it, builds the repayment schedule and notifies the employee. ### Approving a loan 1. When an employee submits a loan request, it appears in the **Approvals** inbox in the left menu (and under **Loans > All Loans** with the status **Pending**). 2. Open the request from the **Approvals** inbox, review the amount, tenure and any attached documents, and approve or reject it. 3. After approval, the loan's status changes to **Approved** on the **All Loans** page. If it is rejected, the status becomes **Rejected**. ### Disbursing a loan 1. In the left menu, choose **Loans > All Loans**. 2. Find the loan — its status must be **Approved**. Use the status dropdown to show only **Approved** loans if needed. 3. In the **Actions** column, click the bank-note (disburse) icon. 4. A confirmation appears, showing the amount and loan number and noting that this will activate the loan, create the repayment schedule for the loan's tenure, and notify the employee. 5. Click **Disburse** to confirm. ### What happens after disbursing - The loan's status changes to **Active**. - A repayment schedule is created with one instalment per month for the loan's tenure. - If the loan is set to deduct from salary, monthly payroll deductions are scheduled — these appear in the [Upcoming deductions report](https://czappstudio.com/docs/modules/loans#section-41). - The employee receives a notification. ### Tips - You can still edit an **Approved** loan (amount, tenure, start date, purpose, notes) before disbursing it — use the pencil icon in the **Actions** column. - A loan can only be disbursed once. If a schedule already exists, the disburse action is not available. ### Troubleshooting - **No disburse icon on a loan** — the loan is not in the **Approved** state, or it has already been disbursed. Only **Approved** loans can be disbursed. - There is no separate approve button on the **All Loans** page: approval happens in **Inbox → To do**, through the loan approval workflow. ## A loan's details The loan details panel shows everything about one loan: its summary figures, the month-by-month repayment schedule, and any security deposits or supporting documents attached to it. It opens as a slide-over from the **All Loans** page. ### Steps 1. In the left menu, choose **Loans > All Loans**. 2. Find the loan and click the eye icon in the **Actions** column. 3. The **Loan Details** panel slides in from the right, headed by the loan number. ![Loan Details: Log Repayment (1) and Mark as Complete (2).](https://media.czappstudio.com/screens/docs/loan-details/light-c1ddbc58ab-2880.webp) ### Reviewing repayment Check the principal, monthly instalment (EMI), outstanding balance, and repayment schedule. The schedule is created when the loan is disbursed. For an **Active** loan, use **Log Repayment** to [record a payment](https://czappstudio.com/docs/modules/loans#section-27), or **Mark as Complete** to [close the loan](https://czappstudio.com/docs/modules/loans#section-33). Review attached [security deposits and documents](https://czappstudio.com/docs/modules/loans#section-23) when needed. ### Tips - You can also reach this panel directly from the **Approvals** page — opening a loan approval takes you to **All Loans** with the loan's detail panel already open. - There is no separate repayment-history feed: the schedule rows themselves carry each month's payment status. ## Loan security deposits A loan can have one or more security deposits or supporting documents attached to it — for example a blank cheque, a post-dated cheque, or a scanned agreement. You can see them all in the loan's details panel. ### Where they come from When an employee applies for a loan in the web application, they can add **Security Deposits / Supporting Documents** to the request. Each entry has a type — **Supporting Document**, **Blank Cheque**, **Post-Dated Cheque** or **Other** — and cheque entries must include a cheque number and bank name. Any entry can include an uploaded file (PDF or image). ### Viewing a loan's security deposits 1. In the left menu, choose **Loans > All Loans**. 2. Find the loan and click the eye icon in the **Actions** column. 3. In the **Loan Details** panel, scroll to the **Security Deposits / Documents** section. 4. Each row shows the type, a status badge, the cheque number and bank name (for cheque entries), a link to download any attached file, and any notes. ### Tips - Security deposit and document records are kept for the life of the loan as part of its history. - A deposit moves from pending to received to returned, but those transitions are not exposed as buttons in the web admin loan details panel. ## Loan repayments When a loan is disbursed, it gets a repayment schedule with one instalment per month. As payments come in, you record them against the loan; the schedule then shows which months are paid and how much is still outstanding. ### Recording a repayment 1. In the left menu, choose **Loans > All Loans**. 2. Find the loan — it must be **Active** — and click the eye icon in the **Actions** column. 3. In the **Loan Details** panel, click **Log Repayment**. 4. In the **Log Repayment** dialog, fill in: - **Amount** — the payment amount. It defaults to the next unpaid instalment's EMI. - **Repayment Date** — the date of the payment. It defaults to the next unpaid instalment's due date. - **Method** — **Bank Transfer**, **Cash**, **Cheque** or **Other**. - **Reference Number** — the UTR, cheque number or transaction ID (optional). - **Comments** — any extra detail (optional). 5. Click **Log Repayment** to save. ### What happens next - The payment is recorded against the matching month in the schedule, and that month is marked as paid. - If you log less than that month's instalment, the unpaid remainder stays pending for the same month so you can log it later. If you log more, the extra reduces the next unpaid instalments. - A month that is already fully paid does not accept another repayment. Log an early payment against the month it covers instead. - The loan's **Outstanding** figure is reduced. - If the loan is fully repaid, it is closed automatically and the employee is notified. ### Viewing the schedule In the **Loan Details** panel, the **Repayment Schedule** section lists every scheduled month with its instalment number, the remaining outstanding after that month, the EMI amount, and a status badge — for example **Pending** (not yet paid), **Completed** or **Verified** (paid), or **Overdue**. ### Tips - Loans set to deduct from salary are repaid through payroll; the scheduled deductions show up in the [Upcoming deductions report](https://czappstudio.com/docs/modules/loans#section-41). ### Troubleshooting - **No "Log Repayment" button** — the loan is not **Active**, or you do not have permission to manage loan repayments. - A repayment you log here is recorded as already verified. Verifying or rejecting a repayment an employee submitted from the mobile app is supported by the system but has no control in this panel. ## Closing a loan Closing a loan marks it as completed — for example when the employee has settled the balance another way, or the remaining amount is being written off. A loan also closes automatically once it is fully repaid. ### Steps 1. In the left menu, choose **Loans > All Loans**. 2. Find the loan — it must be **Active** — and click the eye icon in the **Actions** column. 3. In the **Loan Details** panel, click **Mark as Complete**. 4. In the **Close Loan** dialog, type a **Final Remark** explaining why the loan is being closed (for example, settled by the employee, or written off). This is required. 5. Click **Confirm Close**. ### What happens next - The loan's status changes to **Completed**. - Your final remark is added to the loan's notes. - The employee and the relevant administrators are notified. - The change cannot be undone. ### Tips - You don't need to close a loan that has been fully repaid — it closes on its own once the last instalment is recorded. - Closing is only available for **Active** loans. A loan that is still **Pending** can instead be cancelled before approval finishes. ## Outstanding loans report The **Outstanding Loans** report lists every active loan that still has a balance to be repaid. Use it to see, at a glance, who owes what. Open it from **Loans > Outstanding Report** in the left menu. ### Steps 1. In the left menu, choose **Loans > Outstanding Report**. 2. Use the **Search loans...** box to find a loan by loan number or by the employee's name or code. 3. Click a column header to sort. ### Reviewing outstanding loans The report covers active loans with an outstanding balance. Compare the remaining amount, monthly instalment (EMI), and scheduled end date when following up on repayments. ### Tips - Loans that are still pending or approved, and loans that have been completed or rejected, don't appear here — only active loans with a balance. - For the full list of loans in every state, use All Loans. For the deductions due in the next payroll period, use [Upcoming deductions report](https://czappstudio.com/docs/modules/loans#section-41). ## Upcoming deductions report The **Upcoming Deductions** report shows the loan instalments due to be deducted from salary in the coming payroll period. Use it when preparing payroll. Open it from **Loans > Upcoming Deductions** in the left menu. ### Steps 1. In the left menu, choose **Loans > Upcoming Deductions**. 2. Use the **Search employees...** box to find a row by loan number or by the employee's name or code. 3. Click a column header to sort. ### Checking payroll deductions The report lists active loans set to deduct from salary. Check the employee, deduction amount, and payroll month before processing payroll. When **Loan deductions** is enabled in **Settings → Payroll**, a new pay run reserves eligible generated instalments for its month. Refresh payroll inputs after generating a missing schedule, then review and calculate again. Reserved instalments cannot also be paid or closed manually. Cancelling the unfinalized run releases them. Finalizing payroll credits the loan repayment once. A later reversal of the employee's bank payment reopens net salary owed; it does not undo the loan deduction. Do not add the same instalment as a manual payroll deduction. ### Tips - Only loans that are **Active** and set to deduct from salary appear here. Loans repaid manually don't show in this report — record those payments from the loan's details panel instead. See [Loan repayments](https://czappstudio.com/docs/modules/loans#section-27). - For a fuller view of balances across all active loans, see the [Outstanding loans report](https://czappstudio.com/docs/modules/loans#section-37). ## Your loans (employees) The **My Loans** screen in the **Documents** module shows your loan applications and the loans you currently hold. ### Checking your loans Review the monthly instalment (EMI), outstanding balance, and repayment dates. A **Pending** request can be cancelled; open a loan to review its repayment schedule. ### Steps 1. Open **My Loans** from the module menu. 2. Use the search box to find a loan. 3. Click the eye icon in the **Actions** column to view the loan's details and repayment schedule — see [A loan's details](https://czappstudio.com/docs/modules/loans#section-50). ### Applying for a loan 1. On the **My Loans** screen, click **Apply for Loan**. A panel slides in from the right. 2. Enter the **Amount** and **Tenure (months)** (up to the limit your company sets, 60 months by default). An estimated monthly EMI is shown. 3. Pick a **Start Date**. It must be today or a later date. 4. Optionally add a **Purpose** and **Notes**. 5. Optionally add up to five **Security Deposits / Supporting Documents** entries. For each entry choose a **Type** (**Supporting Document**, **Blank Cheque**, **Post-Dated Cheque**, or **Other**); for cheque types, enter the **Cheque Number** and **Bank Name**. You can attach a file (PDF, JPG, or PNG) and add notes. 6. Click **Submit Application**. The request is sent for approval and appears in your list with status **Pending**. ### Cancelling a pending request 1. In the **Actions** column of a **Pending** loan, click the cancel (X) icon. 2. Confirm in the dialog. The request is retracted and the approval workflow stops. You can submit a new request afterwards. ## Your loan's details Open any loan to see its repayment schedule and a summary of what's left to pay. ### Steps 1. Open **My Loans** from the module menu. 2. Click the eye icon next to the loan. The **Repayment Schedule** panel slides in from the right. ### Checking repayment Review the monthly instalment (EMI), outstanding balance, and due dates in the repayment schedule. Ask HR if you need to confirm a security deposit; it is not included in this view. --- # Payroll Set up payroll, prepare and approve payroll runs, record payments and download payslips. ## Set up payroll ![Payroll: Create pay group (1), Enrol employee (2) and Create pay run (3).](https://media.czappstudio.com/screens/docs/payroll/light-f71c880b1a-2880.webp) Payroll is an optional feature. Enable it in **Modules** and give the appropriate people permission to configure, prepare, review, approve, finalize and record payments. Viewing employees or attendance does not grant access to payroll. This release supports monthly, weekly and fortnightly country-neutral payroll. India, UAE and Saudi statutory calculations and filing formats are not included. Confirm your organization's applicable pay rules before using a pay group. ### Payroll settings Open **Settings → Payroll**, or choose **Settings** from Payroll. Set the default monthly pay day and whether payment falls in the payroll month or the following month. If that day does not exist in a shorter month, its last day is used. The suggested pay date remains editable when you create a run. An optional payslip note can provide a contact or short instruction to employees. It is saved with each new run; changing the setting leaves existing runs and their payslips unchanged. Corrections retain the original run's note. Viewing settings requires **View Settings**; saving changes requires **Manage Settings**. #### Optional integrations Enable only the integrations your organization uses. All three start off, and their source module must be enabled before you can turn them on: - **Loan deductions** includes eligible scheduled loan repayments. - **Expense reimbursements** includes approved, unpaid expense claims. - **Final settlements** lets Payroll calculate final salary and add approved Lifecycle settlement adjustments. These choices are saved when a pay run is created. Changing settings affects new runs; it does not remove items from an existing run. Leave an integration off when you manage those amounts outside Payroll. Loan and expense amounts use the organization's currency; the pay group must match it. No currency conversion is performed. ### Create a pay group Open **Payroll** and choose **Create pay group** to open the setup page. Enter a meaningful name, currency and timezone. Group employees who share these settings and salary rules. Employee compensation and the pay group must use the same currency; payroll does not perform currency conversion. Choose **Monthly**, **Weekly (7 days)** or **Fortnightly (14 days)**. Weekly and fortnightly groups need one known cycle start date and the number of days after period end to pay (zero means the final day). The anchor defines the repeating pattern, including earlier cycles. Fortnightly means every 14 days, not twice a month. Once a group has any run, create a new group to change its frequency or anchor; end the old employee assignments before enrolling them in the new group. Compensation keeps its agreed frequency. A monthly salary is prorated across the cycle's dates; a fortnight of fixed weekly salary pays two weeks. Fixed components apply once per run, so review their amounts when configuring shorter cycles. Scheduled-day proration uses the full calendar month's working schedule, including for joiners and leavers. Each run rounds its own pay lines to currency precision. Choose how partial periods and unpaid time reduce salary: - **Calendar days** uses the days in the payroll month. - **Scheduled working days** uses the confirmed working schedule. - **Fixed divisor** uses the number of days you specify. Confirm this divisor against your policy rather than assuming that every month has the same length. Review time conversions when you pay employees by the hour, day or week. Overtime pay requires an overtime component and approval of the recorded overtime. An overtime quantity component uses its straight hourly rate multiplied by the group's overtime multiplier. Overtime also needs approval during the pay run's input review. Leave self-approval off when a different person must approve the preparer's work. If one authorized person operates payroll, explicitly enable self-approval for that pay group. ### Configure approval steps Open **Approval workflows** and edit **Payroll Approval**. Keep it active and configure at least one approval level in the order your organization requires. This workflow applies to every pay group. Each resolved reviewer needs **View Payroll**, **Approve Payroll** and **View Approvals** permissions as well as the role or assignment selected for their step. Self-approval remains subject to the pay group's setting, including for administrators. Submitting payroll creates a request in the shared approval inbox. Only the current step can proceed; later reviewers are notified when their step becomes current. If a step has no eligible reviewer, it remains pending and administrators receive a notification. Correct reviewer access or withdraw and resubmit after updating the workflow. Changes to workflow levels apply to new submissions; requests already in progress retain their original steps. ### Define salary components Base pay comes from the employee's effective-dated agreed compensation. Additional components can be fixed amounts, percentages of base pay or another component, or quantities multiplied by a rate. Choose the correct component type: | Type | Effect | |---|---| | Earning | Increases gross earnings and net pay | | Employee deduction | Reduces net pay | | Employer contribution | Increases employer cost without reducing employee net pay | | Reimbursement | Is paid separately from gross earnings | Use a unique component code. A percentage rule cannot refer to itself or create a circular chain of dependencies. Add one-off adjustments to a particular pay run rather than changing a recurring group component. Choose **Save pay group** when the rules and approval setting are ready. To update a group, open **Payroll → Pay groups** and choose **Edit pay group** from its actions. Changes apply to new pay runs; existing runs retain their saved rules. If you leave an edited form without saving, choose **Keep editing** to retain your entries or **Discard changes** to return to the pay groups list. ### Enrol employees Choose **Enrol employee**, select the employee and pay group, and set the effective date. An optional end date limits the assignment. Confirm the working schedule, including overnight hours and working weekdays. Add fixed unpaid break windows when they reduce scheduled working time; for example, 09:00–18:00 with a 12:00–13:00 unpaid break is an eight-hour day. You can add up to five breaks. **Recorded attendance breaks are paid** controls explicit break start/end records. It does not automatically pay gaps between a check-out and the next check-in. Choose **Fixed salary** when payroll should not depend on attendance. Choose **Manual or imported time** for reviewed time supplied by another process, or **Attendance records** to process Open Core HR attendance and leave. Confirm whether the agreed compensation represents base pay before additional components or total agreed gross pay. Payroll must not guess this distinction. Record compensation on the employee profile with its correct effective date before creating a run. The source compensation records currently retain two decimal places; do not rely on more precise rates that have already been rounded there. To change an ongoing assignment, open its row actions under **Employees** and choose **End enrolment**. Enter the last covered date and a reason, then enrol the employee again from the following day with the new pay group, schedule or input method. Assignments cannot overlap. Review any draft affected by a change; existing finalized payroll retains its saved calculation. Continue with [prepare and approve payroll](https://czappstudio.com/docs/modules/payroll#section-7). ## Prepare and approve payroll Complete [payroll setup](https://czappstudio.com/docs/modules/payroll#section-1) first. The preparer needs permission to prepare payroll, the time reviewer needs permission to review payroll inputs, and the approver and finalizer need their respective permissions. ### Prepare a pay run 1. Open **Payroll** and choose **Create pay run**. 2. Select the pay group and a day in the cycle. Check the suggested period and pay date; only complete cycles matching the group calendar can be created. 3. Create the draft and check the included employees. 4. For attendance-based payroll, refresh inputs after attendance or leave changes. 5. Resolve all input exceptions. Use each employee's **Review inputs and adjustments** action to record confirmed time and one-off amounts. Expand a date to review or change its daily hours. Time entries use decimal hours: 30 minutes is `0.5`. Worked hours exclude unpaid breaks but include overtime; enter overtime separately so it is not also paid as regular time. Confirm paid leave, unpaid time and paid holidays against the underlying records. A correction needs a reason explaining the evidence checked. Fixed salary uses agreed compensation and employment dates. Hourly or daily fixed pay uses scheduled entitlement. Changing worked, unpaid or leave hours does not reduce fixed base pay. Record a documented one-off deduction or use the appropriate manual or attendance assignment when pay should depend on reviewed time. Missing check-outs, conflicting leave and uncertain schedules must be resolved before payroll proceeds. Correct the source record and refresh when possible. Do not treat missing attendance as confirmed absence without reviewing it. **Refresh inputs** asks you to confirm before replacing entered or imported daily time with fresh source inputs. One-off adjustments are kept. Review and calculate the refreshed inputs again before continuing. ### Include loans, expenses and settlement adjustments Check the run's saved integration choices and source items before reviewing pay. Loan instalments are included in the cycle containing their repayment due date. Enabled loan and expense integrations reserve eligible items for this run so they cannot also be processed manually or included in another run. Do not copy those amounts into one-off adjustments. For final salary, complete the employee's separation and approve a Lifecycle settlement using **Payroll adjustments** mode. The last working date must fall within the payroll period. Choose **Link settlement** for that employee and select the approved adjustments. Payroll calculates salary using employment dates; the settlement must exclude salary and amounts already included elsewhere. **Full settlement** records cannot be linked. Changing a settlement link requires fresh input review and calculation. If a source changes or becomes unavailable, resolve the reported issue before continuing. Cancelling an unfinalized run releases its reserved items. ### Import time Choose **Import time** and download the CSV template. Enter an employee code and date for every row; use `YYYY-MM-DD` dates and decimal hours. Import into the correct run and check any row errors before retrying. A successful import still needs input review and payroll calculation. ### Review, calculate and approve ![A pay run: Import time (1) and Submit for approval (2).](https://media.czappstudio.com/screens/docs/payroll-run/light-5971a56808-2880.webp) 1. Choose **Review inputs**, add a review note, and explicitly decide whether to approve the recorded overtime. 2. Choose **Calculate payroll**. Open an employee's calculation to inspect each amount and its explanation, including earnings, deductions and employer costs. 3. Resolve calculation errors, including missing compensation, currency mismatch or deductions that would produce negative net pay. 4. Submit the calculated run to the configured **Payroll Approval** workflow. 5. The reviewer opens the approval notification or **Approvals** inbox, views the pay run and approves the current step or rejects it with a reason. The pay run also offers these actions to eligible reviewers and shows the step history. Each approval notifies the requester; the next reviewer receives a notification when their step becomes current. Self-approval requires the pay group setting. 6. The authorized finalizer confirms **Finalize payroll** after every step approves. Rejection returns payroll to draft and closes the remaining steps. To correct a pending run yourself, choose **Withdraw for correction** and provide a reason. Refresh changed source inputs, review, calculate and submit again. The new request starts at the first step and preserves the previous request's decisions and notes. Compensation and source changes block approval at every level; a reviewer can still reject stale payroll so the preparer can correct it. Editing or refreshing inputs requires a new review and calculation. An approval applies to the reviewed calculation; it cannot be carried over to changed amounts. If another person changes the run while you are working, reload it and review the current state before retrying. Finalization preserves the approved amounts. It does not transfer money or release payslips. Follow [payments and payslip release](https://czappstudio.com/docs/modules/payroll#section-14) next. ### Cancel a draft Cancel an unfinalized draft when it should no longer proceed and record the reason. The cancelled run remains in history. Do not cancel a completed payment to disguise a correction; retain the original financial record and use the supported correction process. ### Correct a finalized run Open the original finalized run and choose **Create correction run**. Set the correction pay date, then enter the additional one-off amounts for the affected employees. The correction starts at zero: it does not pay base salary or recurring components again. Review, calculate, approve and finalize it in the same way as a regular run. This process records explicit adjustments; it does not automatically recalculate past payroll. If recovering an overpayment would make the correction negative, record an authorized deduction in the next regular run and identify the original period in the reason. Never represent a recovery as a negative bank transfer. ## Record payments and release payslips Start with a [finalized pay run](https://czappstudio.com/docs/modules/payroll#section-7). Payment recording requires payment permission; releasing payslips requires payroll finalization permission. ### Record payment Export the payment file when you need the run's payment details. This is a generic export, not a country-specific bank or wage-protection submission. Downloading it does not send money or mark employees paid. After confirming a transfer outside Open Core HR, choose **Record payment** for the relevant employee. Enter the amount actually paid, the payment reference and payment date. For a partial payment, record only the amount received; record the remaining amount when it is confirmed. Check the employee and outstanding amount before saving. If a request fails, keep the payment form open and retry after checking the error. Do not invent a new payment reference merely because the response was delayed; first check payment history to avoid recording the same transfer twice. Payroll approval, finalization and payment are separate events. An approved or finalized run can still be unpaid. A partially paid run remains open for the outstanding amounts. If a transfer is returned or a payment was recorded incorrectly, open **Payments**, choose **Reverse payment** from that record's row actions, and explain the reason. The original record stays in history alongside its reversal, and the amount becomes outstanding again. This corrects the payroll record; it does not reverse a bank transfer. Record a replacement only after it has been confirmed. ### Release payslips Choose **Release payslips** when the finalized statements are ready for employees. Employees can then download their own statements from **Payslips** in the module menu. Payslip release does not confirm bank payment. Payroll documents contain private employee information. Share downloaded payment files and payslips only with the intended people and follow your organization's retention policy. ### Linked source records When integrations are enabled, finalizing payroll applies its loan deductions once. Reversing a payroll payment does not undo the loan deduction: the employee is still owed the outstanding net salary. Linked expenses and settlement adjustments are marked paid only when the employee's full net pay is recorded. A partial payment leaves them unpaid and reserved by Payroll. Reversing payment reopens their paid status and retains the Payroll link. Record the replacement through Payroll instead of paying the source record separately. ### Payroll reports Open **Payroll → Reports** with both **View payroll** and **View and export payroll reports** permissions. Finance officers and administrators receive reporting access by default. Select a pay-date range of up to 366 days and optionally a pay group, then apply the filters. The initial range is year-to-date; use a single month for monthly reporting. Employee totals use finalized payroll snapshots, including finalized corrections as additional amounts. A December salary with a January pay date belongs to January's report. Unpublished or unpaid finalized runs are included; draft and cancelled runs are excluded. Employee renames, later salary changes and payment reversals do not rewrite accrued totals. Each currency stays separate, without conversion or imported opening balances. Export **Summary CSV** for employee earnings, deductions, reimbursements, net pay and employer costs. Employer cost includes earnings, reimbursements and employer contributions. Use the existing payment register to reconcile paid and outstanding amounts instead. The **Accrual journal** groups accounting entries by pay run and component. Before posting its CSV to accounting, map the account categories and component codes to your chart of accounts. Earnings debit payroll expense; deductions credit clearing; net pay credits payroll payable. Employer contributions have matching expense and payable entries. Reimbursements debit clearing so an expense already booked elsewhere is not expensed twice. Review the clearing accounts against the corresponding loan, expense and settlement records. Negative adjustments reverse the debit or credit side. Journal exports do not post entries or include bank payments. Exported files contain confidential payroll data. Both exports include the whole selected date/group scope; the table search only helps browse the displayed report. ## Download your payslips ![Payslips in the mobile app.](https://media.czappstudio.com/screens/mobile/payslips/light-89d8288349-1206.webp) When your organization enables Payroll and grants you access, open **Payslips** in the module menu. You can download only statements the payroll team has released for you. Find the relevant pay period and choose **Download payslip** from its actions. The statement explains earnings, employee deductions, reimbursements and net pay. Employer contributions are separate from deductions taken from your pay. In the employee mobile app, open **My payslips** under **HR services**. Select a pay period to review its breakdown, then choose **View payslip PDF**. Use **Save or share PDF** to save a copy through your device's share options. Pull down to refresh the list; older statements load as you scroll. If loading fails, choose **Retry**. Access requires Payroll and the **View my payslips** permission. If a period is missing, ask the payroll team whether its payslips have been released. If an amount appears incorrect, quote the pay period and the affected component when contacting them. You cannot edit a released payslip yourself. A released payslip is a statement of calculated pay; it does not by itself confirm that your bank has received a transfer. Contact the payroll team about payment timing. Keep downloaded statements private. --- # Performance Set weighted goals, run self and manager reviews on a schedule, sign off final ratings and share them with employees. A review cycle takes a group of employees through goal setting, a self-assessment, a manager review and HR sign-off, and ends with each employee reading and acknowledging their review. Open it from **Performance** in the left menu. Build a review form first, then plan a cycle. ## Building a review form A review form is the set of questions and the rating scale that a cycle uses. People with **Create and edit review forms** manage forms in **Performance → Review forms**. Start from the ready-made **Standard annual review**: a five-level scale (Unsatisfactory to Outstanding), five rated questions, two written questions, and goals counting for 70 %. Change anything before saving. | Part | What to decide | | --- | --- | | Rating scale | Between 3 and 7 levels, each with a name (for example "Meets expectations") and an optional description. The employee sees the name of the final rating, not a number. | | Questions | Up to 30, optionally grouped under section headings. A question is a **rating**, a **rating with a comment** or a **written answer**, and can be marked **required**. | | Goals and questions | How much the goals count towards the overall result, from 0 % to 100 %. The questions count for the rest. Written answers are never scored. | | Self-assessment | When on, the employee answers the form first. When off, the review goes straight to the manager. | A cycle keeps its own copy of the form when it is launched, so editing a form never changes a cycle that has started. A form that a cycle has used cannot be deleted; turn it off instead. ## Planning a review cycle People with **Plan, launch and run review cycles** run cycles in **Performance → Review cycles**. 1. Create a cycle with a name, a review form and the period it covers. 2. Choose who takes part. Combine department, designation, location, named people and a **joined before** date; people must match every rule you set. 3. Set the four deadlines in order: goals, self-assessment, manager review and sign-off. 4. Check the list of included people and the reviewer each would get. A person's reviewer is their manager; anyone without a manager must be given a reviewer before the cycle can start. 5. Launch the cycle. This freezes the form and each person's reviewer, and tells everyone taking part. A cycle can include up to 2,000 active employees. You can add more people, such as new joiners, while it is running. ## Stages You advance the stages yourself. Deadlines do not lock anything; people who are late are chased with reminders instead. | Stage | What happens | | --- | --- | | Goal setting | Employees and managers agree goals. | | Reviews | Employees complete self-assessments, then managers write their reviews. | | Sign-off | HR checks and signs off each final rating. | | Closed | Every review and goal in the cycle becomes read-only. Closing cannot be undone. | Reminders go to whoever a review is waiting for, three days before a deadline and once on the day after it. You can also remind selected people at any time. ## Goals A review can have up to 15 goals, and they must count for 100 % in total before a manager can submit the review. Each goal has a title, what success means, how much it counts for, a due date and one measure: a number, a percentage or done / not done. - Goals an employee proposes wait for their manager's approval. Goals added by a manager or HR are agreed at once. - To give the same goal to many people, select them in the cycle and assign the goal. - A person with no goals yet can copy them from their earlier review. - Once a goal is agreed, the employee and the manager record progress with a new figure and a comment. Progress helps the manager decide the rating but does not calculate it. ## Your reviews (employees) Open **Performance → My reviews**. The page shows what you need to do next. 1. While goals are being set, add the goals you think you should have. They are sent to your manager for approval. 2. Record your progress whenever it changes. 3. When the review stage opens, answer the review's questions. You can save and come back; nothing is sent until you submit. 4. When HR shares your review you are notified. Read the final rating, your manager's comments and any recommendation, then choose **Acknowledge**. You can add a comment. Acknowledging records that you have read the review, not that you agree with it. You cannot see your manager's ratings before HR shares the review, and you never see your manager's private notes. ## Reviewing your team (managers) Open **Performance → Team reviews**. You see only the people assigned to you. 1. Add goals for your people or approve the ones they propose. 2. Once the review stage opens and the employee has submitted their self-assessment (or its deadline has passed), rate each agreed goal and each question. 3. Write an overall summary for the employee. It is required. 4. Optionally record a recommendation: no change, pay increase, promotion or improvement plan. It is recorded and exported but does not change the employee's record. 5. Add private notes if you wish, then submit. Private notes are for you and HR only. They are never shown to the employee and are left out of the printed review. ## Signing off and sharing People with **Sign off final ratings** sign off each review once the manager has submitted it. The final rating starts as the calculated rating; a different one needs a reason, which is kept with the review and appears in exports. Nobody can sign off their own review. Share signed-off reviews one by one or in bulk. Each employee is notified and can then read and acknowledge their review. | Action | When | Effect | | --- | --- | --- | | Send back | A self-assessment or manager review has been submitted and the review has not been acknowledged. A reason is required. | The person can edit again. Any sign-off, final rating and sharing are undone; earlier answers and the history are kept. | | Change reviewer | The manager review has not been submitted yet. | The new reviewer is told. A manager change in the employee's profile does not move reviews by itself. | | Cancel | The review has not been acknowledged. A reason is required. | The person stays in the cycle's records but is left out of reports. | ## How the score is calculated Only the manager's ratings are scored. The self-assessment is shown next to them for comparison. - **Goals:** each goal's rating is weighted by how much the goal counts. Two goals counting for 60 % and 40 %, rated 4 and 3, give 3.6. - **Questions:** the average of the rated questions. Ratings of 3 and 4 give 3.5. - **Overall:** the two combined by the form's split. With goals counting for 70 %, the overall score is 0.7 × 3.6 + 0.3 × 3.5 = 3.57. The calculated rating is the nearest level on the scale, so 3.57 becomes level 4. ## Results and export Open a cycle to see where each person stands, from not started to acknowledged, and who each review is waiting for. People with **Export review results** can download the cycle's results as a CSV file and print a review as a PDF. ## In the mobile app Employees add goals, record progress, complete the self-assessment and acknowledge their review. Managers approve goals and write reviews. The Performance screens need an internet connection; a self-assessment you have not sent is kept on the phone as a draft. Review forms, cycles and sign-off stay on the web. --- # Policies Publish and version company policies, deliver them to employees and track acknowledgments. Policies is the standard library for company and HR policies. Categorize policies by subject, choose their audience, and optionally require acknowledgment or publication approval. You need permission to view policies; creating, editing, assigning and category management have separate permissions. Open **Policies → All Policies** to find a policy by title, category or publication status. The list includes version records so administrators can review drafts and history. Drafts remain private until published. Pending approval versions await their configured reviewers. Scheduled versions take effect on their effective date. Published versions are available to their audience until expiry or replacement; archived versions retain historical evidence. Use [Creating and versioning a policy](https://czappstudio.com/docs/modules/policies#section-1) to publish or replace content, [Delivering policies](https://czappstudio.com/docs/modules/policies#section-7) for audience behavior, and [Assignments and acknowledgments](https://czappstudio.com/docs/modules/policies#section-8) to follow up. With the [HR assistant](https://czappstudio.com/docs/ai/hr-assistant) add-on, employees can ask everyday questions on **Ask HR** and get answers from the policies assigned to them. Generate the policies manual from [Import & Export](https://czappstudio.com/docs/administration/import-export). The PDF contains current written policy content; individual attachments remain available from their policy records. ## Creating and versioning a policy Policies is included in every installation. Use it for company, HR, workplace, safety and IT policies. You need create/edit policy permissions and an active category. ### Create and publish ![Policies: Add Policy (1) or open a policy's actions (2).](https://media.czappstudio.com/screens/docs/policies/light-2125eae3d6-2880.webp) 1. Open **Policies → All Policies → Add Policy**. 2. Enter a title and category; both are required. Add written content, a PDF/Word attachment, or both. Attachments can be up to 10 MB. 3. Choose an audience: everyone, selected locations, selected departments, or selected employees. At least one member is required for a selected audience. 4. Enable **Requires acknowledgment** only when employees must confirm reading this version. Set the number of days after assignment, or leave the deadline blank. 5. Enable **Require approval before publishing** if this version needs review through the configured Policy Publish Approval workflow. 6. Save the draft. Use **Publish**, or **Submit for Approval** when review is required. Publishing delivers the version to active employees who match its audience. Matching new employees receive it automatically. Location and department audiences follow employee changes. ### Dates and approval The effective date controls when a published version becomes available. A future date schedules it; the existing version remains current until then. The review date is a reminder for administrators to reconsider the content. The expiry date is the last day a version is current. A pending approval version cannot be edited. Rejected drafts can be corrected and resubmitted. Approval uses your configured workflow; a fresh installation starts with super admin approval. ### Update a published policy Open the published version's edit page and choose **Create New Version**. Edit the draft, check its audience and acknowledgment requirements, and publish it. When it takes effect, the previous version is archived and matching employees receive the replacement. Published, scheduled and archived content cannot be edited. Employees who acknowledged an earlier version can still read that exact version. Their acknowledgment does not carry over to a replacement. If publication fails, correct the reported content, audience or approval workflow problem and retry. Saving a draft never publishes it. To withdraw a published policy or cancel a scheduled version, open its edit page and choose **Archive Version**. Acknowledged history remains available. A draft can replace or remove its attachment. Removing it from a replacement draft leaves the original published version's file and acknowledgment evidence intact. To cancel a scheduled replacement, archive that scheduled version. The current published version remains available. You can then create another version from the current policy; the canceled version stays in history and its version number is not reused. ## Reviewing a policy Open a policy from **Policies → All Policies** to read its content and review version, effective dates, publication status and employee assignment records. You need permission to view policies. Check pending and overdue acknowledgments to decide whom to follow up with. Reference-only policies require no employee confirmation. Acknowledged records refer to the exact version employees read, including after replacement or expiry. Use the edit page to change a draft or create a replacement for a published version. See [Creating and versioning a policy](https://czappstudio.com/docs/modules/policies#section-1). Publication automatically distributes to the configured audience; [additional delivery](https://czappstudio.com/docs/modules/policies#section-7) does not expand that audience. To create a Policies Manual PDF, open **Import & Export**, choose the policies manual export, and request it. Download the completed file from **History** within seven days. The manual covers current written content; download attachments separately from their policy when the full text is held in a file. See [Import & Export](https://czappstudio.com/docs/administration/import-export). ## Policy categories Categories group policies by subject, such as Workplace, HR, Safety or IT & Security. Every policy version belongs to a category. You need category management permission to create or change them. Open **Policies → Categories** and choose **Add Category**. Enter a unique name, add an optional description, and save. Use the category's actions to edit it or change whether it is active. Only active categories can be selected for new or edited drafts. Deactivating a category does not withdraw its published policies. To withdraw a policy, archive its version instead. A category with policy history cannot be deleted. Reuse its name where appropriate or deactivate it to prevent future selection. Use [Creating and versioning a policy](https://czappstudio.com/docs/modules/policies#section-1) to publish content within a category. ## Delivering policies to employees Publication automatically delivers a policy to active employees in its configured audience. Choose everyone, selected locations, departments, or employees when creating or updating a draft. The audience applies to new joiners and employee moves as well as the initial publication. For an additional delivery attempt, open a current published policy and choose **Assign Policy**. Send it to everyone in the audience or select active employees who belong to it. You can add an assignment note. Existing assignments are skipped, preserving their deadlines and acknowledgment evidence. Reference policies appear as **Available** and create no acknowledgment task. Policies requiring acknowledgment appear as **Pending**, with any deadline measured from the assignment date. Employees acknowledge an exact published version. An employee leaving an audience loses access to unacknowledged assignments. Previously acknowledged versions remain available as history. Drafts, scheduled versions, archived versions and expired policies cannot be newly assigned. To change the audience or policy requirements, create and publish a new version. Selecting people in the delivery panel does not expand the policy's audience. ## Policy assignments and acknowledgments ![Policy Acknowledgments: search (1) and Filters (2).](https://media.czappstudio.com/screens/docs/policy-acknowledgments/light-75b23df87b-2880.webp) Open **Policies → Acknowledgments** to review delivery and acknowledgment records. Filter by policy or status and search by employee, policy title or category. You need permission to view policies. - **Available**: a reference policy that requires no acknowledgment. - **Pending**: the employee must acknowledge this version. - **Acknowledged**: the employee confirmed reading the exact version recorded. - **Overdue**: the acknowledgment deadline passed. - **Expired**: an unacknowledged or reference assignment whose version was archived, replaced or expired. Each record retains its version, assignment date, deadline, acknowledgment date and employee comments. Archived versions retain their evidence; acknowledgments are never transferred to replacement versions. The application scheduler updates overdue assignments and sends in-app reminders for due acknowledgments, at most once every seven days. Reminders start three days before the deadline. Configure the server scheduler as described in the installation guide. Policies without a deadline do not receive deadline reminders. Use the policy audience to control delivery. See [Delivering policies](https://czappstudio.com/docs/modules/policies#section-7). ## Your policies (employees) Open **Policies** in the module menu or the employee mobile app to read policies available to you. Policies is included in every installation. You can read and acknowledge policies in the mobile app without granting location or notification permissions; select **Continue** during permission setup to decide later. Your current policies follow the audience your administrator selected: everyone, particular locations, departments, or named employees. Reference policies appear as **Available**. Policies requiring confirmation appear as **Pending** or **Overdue**. Open a policy to read its content or download its attachment. [Acknowledge it](https://czappstudio.com/docs/modules/policies#section-11) when confirmation is required. Acknowledged previous versions remain available so you can review exactly what you read. If a policy you expect is missing, ask your administrator to check publication dates and your audience membership. A draft or future version is not available yet. Moving out of an audience removes unacknowledged policies from your current list. ## Reading a policy ![Policies in the mobile app.](https://media.czappstudio.com/screens/mobile/policies/light-aa82015ed2-1206.webp) Open a policy from **Policies** in the module menu or the employee app. Read its written content and any attached PDF or Word document. Downloads require your signed-in account and permission to read that version. Check the version and deadline before acknowledging. A reference policy needs no confirmation. For a current policy requiring acknowledgment, confirm after reading; see [Acknowledging a policy](https://czappstudio.com/docs/modules/policies#section-11). You can also read previously acknowledged versions. They preserve the content and confirmation you originally gave, even after the policy changes or expires. A historical version cannot be acknowledged again. If an attachment cannot be displayed, retry the download. If the file is still unreadable, ask your administrator for a readable copy before acknowledging it. ## Acknowledging a policy An acknowledgment records that you read a specific published version. It does not automatically acknowledge later changes. 1. Open **Policies** in the module menu or the employee app and select a pending or overdue policy. 2. Read the content and any attachment. 3. Choose **Acknowledge**, add comments if needed, and confirm. Your confirmation and its date are saved against that version. Repeating the request does not create a second acknowledgment. Reference policies need no acknowledgment and have no acknowledgment action. You can acknowledge an overdue policy while it remains current and you remain in its audience. If it was replaced or expired, read the current version instead. Your earlier acknowledged versions remain available as history. --- # Tasks Create, work and update tasks, handle recurring tasks and monitor the task board. The **Tasks** screen in the **Documents** module is where you track work assigned to you, work you have assigned to others, and any recurring task occurrences. ## Finding your tasks Use **My Tasks** for work assigned to you, **Assigned by Me** for tasks you assigned to others, and **Recurring Instances** for individual occurrences of repeating tasks. Check due dates and overdue work before choosing what to work on. ## Steps ![Tasks: search (1), Filters (2) and New task (3).](https://media.czappstudio.com/screens/docs/tasks/light-616b23ea2e-2880.webp) 1. Open **Tasks** from the module menu. 2. Choose the **My Tasks**, **Assigned by Me**, or **Recurring Instances** tab. 3. On **My Tasks** and **Assigned by Me**, use the **Status**, **Priority**, **From Date**, and **To Date** filters to narrow the list, or type in the search box. 4. On **Recurring Instances**, use the **Filter by Status** dropdown (**All Active**, **Overdue**, **Today**, **Upcoming**). 5. Click the eye icon in the **Actions** column to open a task and see its details. ## Tips - See [Working a task](https://czappstudio.com/docs/modules/tasks#section-12) for the Start, Hold, Resume, and Complete actions. - See [Recurring task occurrences](https://czappstudio.com/docs/modules/tasks#section-21) for handling individual occurrences of a repeating task. ## Creating a task You can create a task and assign it to another person from the **Tasks** screen. The task you create appears under the **Assigned by Me** tab. ### Steps 1. Open **Tasks** from the module menu. 2. Click **Create Task**. A panel titled **Create New Task** slides in from the right. 3. Fill in the fields: - **Task Name** (required) — a short name for the task. - **Assign To** (required) — search for and select the person to assign the task to. You cannot assign a task to yourself. - **Priority** (required) — **Low**, **Medium**, or **High** (defaults to **Medium**). - **Due Date** (required) — when the task is due. Must be today or later. - **Due Time** — an optional time of day. - **Recurring** — **Never**, **Daily**, **Weekly**, or **Monthly**. Choose anything other than **Never** to make the task repeat. - **Recurring End Date** (required when recurring) — the last date the task should repeat. - **Requires attachment before completion** — turn this on if the assignee must upload a document before they can mark the task complete. - **Notes / Description** — optional notes for the assignee. - **Voice Description** — an optional audio file (MP3, WAV, M4A, or AAC, up to 10 MB). 4. Click **Create Task**. ### After you finish ![New task: enter the title (1), choose the assignee (2) and set the due date (3).](https://media.czappstudio.com/screens/docs/task-new/light-23f4df63b6-2880.webp) Find the new task under **Assigned by Me**. For recurring tasks, individual occurrences are created automatically. ### Tips - To cancel without creating the task, click **Cancel** or close the panel. - The assignee tracks the task from their **My Tasks** tab — see Your tasks. ## A task's details and activity Opening a task shows everything about it in a panel that slides in from the right, including a timeline of activity. ### Steps 1. Open **Tasks** from the module menu. 2. Find the task on the **My Tasks** or **Assigned by Me** tab. 3. Click the eye icon in the **Actions** column. The **Task Details** panel opens. ### Reviewing progress Check the due date, priority, assignee, and repeat pattern before working on the task. Use **Activity Timeline** to review previous updates and attachments. See [Adding a task update](https://czappstudio.com/docs/modules/tasks#section-17) and [Working a task](https://czappstudio.com/docs/modules/tasks#section-12) for the available actions. ### Tips - Click **Close** to dismiss the panel. ## Working a task As a task moves from new to done you change its status using the **Start**, **Hold**, **Resume**, and **Complete** actions. These are available only for tasks assigned to you. ### How the statuses flow - **New** — the task has been assigned but not started. Use **Start Task** to begin. - **In Progress** — you are working on the task. From here you can **Hold** it or **Complete** it. - **Hold** — the task is paused. Use **Resume Task** to pick it back up. - **Completed** — the task is done. > **Note:** You can only have one task **In Progress** at a time. If you try to start or resume a task while another is in progress, you'll be asked to complete or hold the other one first. ### Steps 1. Open **Tasks** from the module menu and go to the **My Tasks** tab. 2. Use the buttons in the **Actions** column, or open the task with the eye icon and use the buttons at the bottom of the **Task Details** panel: - **Start Task** — available when the task is **New**. - **Hold** — available when the task is **In Progress**. The task moves to **Hold**. - **Complete** — available when the task is **In Progress**. - **Resume Task** — available when the task is **Hold**. The task moves back to **In Progress**. 3. When using the action buttons in the table, confirm the action in the dialog that appears. ### Completing a task that requires an attachment If the task was set up to require an attachment, clicking **Complete** opens a **Complete Task** dialog: 1. Choose a file under **Attachment** (required). 2. Optionally add **Notes**. 3. Click **Complete Task**. You can also upload the required document ahead of time from the **Upload Required Document** section inside the **Task Details** panel while the task is in progress. ### Troubleshooting - **The Complete button asks for an attachment** — the task requires a document. Attach one in the **Complete Task** dialog or upload it first from the task details panel. - **You can't start a task** — check whether you already have another task in progress and finish or hold it. ## Adding a task update While a task is in progress you can post updates — a written comment, a file, or both. Updates appear in the task's activity timeline so everyone involved can follow progress. ### Steps 1. Open **Tasks** from the module menu and go to the **My Tasks** tab. 2. Click the eye icon next to a task that is **In Progress** to open the **Task Details** panel. 3. Scroll to the **Add Update** section. 4. Type your comment in the box, and/or choose a file to attach. 5. Click **Send**. ### After you finish Your update is recorded in the **Activity Timeline**. ### Tips - You need to enter a message, attach a file, or both — an empty update can't be sent. - For required documents on tasks that need an attachment before completion, use the **Upload Required Document** section instead — see [Working a task](https://czappstudio.com/docs/modules/tasks#section-12). ## Recurring task occurrences A task set to repeat daily, weekly, or monthly generates a separate occurrence for each scheduled date. These are listed on the **Recurring Instances** tab of the **Tasks** screen. ### Finding an occurrence Use **Filter by Status** to find overdue, today’s, or upcoming occurrences. Open an occurrence to review its scheduled date and take action. ### Steps 1. Open **Tasks** from the module menu. 2. Go to the **Recurring Instances** tab. 3. Use the **Filter by Status** dropdown or the search box to find an occurrence. 4. Click the eye icon in the **Actions** column to view the occurrence details, which show the scheduled date, status, priority, the parent task's notes, and who it's assigned to. > **Note:** When you mark the parent recurring task complete from the **My Tasks** tab, the current occurrence (today's, or the earliest pending one) is marked complete automatically. > **Note:** Opening a single occurrence shows a read-only details panel. There is no per-occurrence complete or skip button on this screen, even though the system supports both. ## Task board The Tasks screen is your organisation-wide view of every task: who created it, who it is assigned to, its priority, status, and due date. From here you can create and assign new tasks and open any task to see its full history. ### Steps 1. In the left menu, click **Tasks**. 2. Review the summary cards at the top: **Total Tasks**, **New Tasks**, **In Progress**, **Completed**, **Overdue**, and **Due Today**. 3. Scroll down to the **Filters** section and narrow the list by **Status**, **Priority**, **Assigned To**, **Created By**, **Due Date From**, and **Due Date To**. Tick **Show Overdue Only** to see just overdue tasks, then click **Apply Filters**. Click **Clear Filters** to reset. 4. In the **Task List**, switch between table view and grid view using the layout buttons in the top corner. 5. Click **View** on any task to open its details. 6. Click **Refresh** to reload the page with the latest data. #### Creating and assigning a task 1. Click **Create Task** at the top of the screen. A panel slides in from the right. 2. Fill in **Task Name**. 3. Choose the person under **Assign To**. 4. Set the **Due Date** and, optionally, a **Due Time**. 5. Choose a **Priority** - Low, Medium, or High. 6. Optionally set **Recurring** to Daily, Weekly, or Monthly. If you do, a **Recurring End Date** is required. 7. Add **Notes** if needed. 8. Click **Create Task**. #### Opening task details The details page shows the task name, status, priority, who it is assigned to, who created it, the description, important dates (created, due, last updated), a completion progress indicator, and a **Task Timeline** of every update - starts, holds, resumes, completions, and any text, image, file, link, or chat updates. Use **Print** to print the page. ### Following up on tasks Check overdue tasks and tasks due today when prioritising follow-up. Use status and priority to identify work that needs attention. ### Tips - Progress is shown as a percentage based on status - for example New is 10%, In Progress is 50%, and Completed is 100%. It is not entered manually. --- # Webhooks Send signed event notifications from Open Core HR to your own systems. Use the optional **Webhooks** module to notify another system when an employee account changes. A **super admin** enables it in **Modules** and opens **Webhooks** to configure destinations. It works independently of careers integration and does not require an API client or token. ## Add a destination ![Add webhook: enter a name (1) and endpoint URL (2), then choose the events (3).](https://media.czappstudio.com/screens/docs/webhook-form/light-ebdf5bb72f-2880.webp) 1. Ask the receiving system's administrator for its public HTTPS endpoint. 2. Add an endpoint with a recognizable name and that URL. URLs containing login credentials or fragments, private network addresses and redirect destinations are not supported. 3. Select the employee events the receiver needs, then save the endpoint. 4. Copy the signing secret immediately and configure it securely on the receiving server. It is shown once; it is not an API access token. 5. Send a test delivery and check its delivery history before relying on it. Supported events are employee creation, profile updates, account-status changes, deletion, restoration and permanent deletion. Their event names are `user.created`, `user.updated`, `user.status_changed`, `user.deleted`, `user.restored` and `user.force_deleted`. Payloads contain the event's supported work-profile fields, not passwords, compensation or private employee details. ## Verify and process deliveries The receiving system must verify the signature before acting on a message. Give its developer the following contract: - `X-Webhook-Event` identifies the event. - `X-Webhook-Delivery` is the stable delivery ID; use it to avoid processing a retried delivery more than once. - `X-Webhook-Timestamp` is a Unix timestamp. Reject timestamps outside the receiver's accepted clock-skew window. - `X-Webhook-Signature` is `sha256=` followed by the hexadecimal HMAC-SHA256 of `timestamp + "." + exact request body`, using the endpoint's signing secret. Compare signatures in constant time; do not re-encode the JSON before checking. Return a successful HTTP response after accepting the event. Deliveries may arrive more than once or out of order; design the receiver accordingly. ## Investigate failures Open the endpoint's delivery history to check status and attempts. Fix the receiving server's availability, HTTPS certificate or signature configuration, then send another test. The sender does not follow HTTP redirects. By default, a retryable failed delivery receives up to three retries, after 1 minute, 5 minutes and 1 hour, for a maximum of four attempts. Blocked destinations and oversized payloads fail without retries. Queue workers and the scheduler must be running; see [services setup](https://czappstudio.com/docs/installation/services). Delivery history contains sanitized results, not the receiver's response body. ## Pause, rotate or remove Deactivate an endpoint to stop sending to it. Pending work is cancelled when the endpoint or module is disabled; re-enabling does not replay cancelled events. Changing the destination URL or event subscriptions also cancels pending work. Delete an endpoint when it is no longer needed. If a signing secret is exposed or lost, rotate it and copy the replacement when shown. Pending deliveries are preserved and their next attempt uses the new secret. Update the receiving system promptly so it can verify them. Completed, failed and cancelled delivery logs are removed automatically after 30 days by default. Pending deliveries are not removed by this retention task. ## Delivery settings A super administrator can change delivery behaviour in **Settings → Webhooks**: the request timeout (1–120 seconds), how many times a failed delivery is retried (0–10), and how many days finished delivery logs are kept (1–365). --- # AI in Open Core HR Connect your own AI provider, choose who can use each AI feature and keep usage within your limits. AI in Open Core HR helps people write, answer everyday HR questions, fill in expense claims from receipts and answer questions about HR data, for office and field teams alike. Each feature comes from an add-on on the **Modules** page: the [AI writing assistant](https://czappstudio.com/docs/ai/writing-assistant) is free, the [HR assistant](https://czappstudio.com/docs/ai/hr-assistant), [Receipt scanning](https://czappstudio.com/docs/ai/receipt-scanning) and [Ask your HR data](https://czappstudio.com/docs/ai/ask-your-data) are paid add-ons. Every AI feature is a shortcut: people can still do the same work by hand. AI is switched off on a new installation. Nobody sees an AI feature until an administrator connects a provider and tests it under **Settings → AI**, then turns AI on from the **AI** menu. Both need the **Manage AI** permission. ## Bring your own provider You connect the AI provider you choose and use your own account with it, so its bill comes to you directly. 1. Open **Settings → AI**. 2. Under **Provider**, choose one: - **Claude**, **Gemini** or **OpenAI**: enter the API key from your account with that provider. Leave **Model** empty to use the recommended model, or pick one of the models your key can use. - **Custom or self-hosted**: enter the **Server address** of any server that speaks the OpenAI API, such as Ollama, LM Studio, vLLM, LiteLLM or your own gateway, and the **Model** name exactly as the server lists it. Enter an API key only if your server asks for one. 3. Select **Save**, then **Test connection**. The key is stored encrypted and is never shown again. Text and files used in an AI action are sent to the provider you choose. With a self-hosted model they stay on your own network, so no data leaves it. The server running Open Core HR needs outbound access to the provider or to your server address. ## The connection test The test asks the chosen model four small questions and shows each result as **Works**, **Not supported by this model** or **Could not be checked** with the reason. | Ability | Needed for | | --- | --- | | Writes text | Every AI feature | | Fills in forms | Reading a receipt | | Looks up records | HR assistant answers from a person's own records, preparing requests, and Ask your HR data | | Reads images | Reading a photo or scan of a receipt | Hosted providers normally pass all four. A self-hosted model may pass only some; a feature that needs a missing ability cannot be switched on and says which part is missing. Changing the provider, model, server address or key clears the result, and AI features stop until you test again. ## Turn AI on and set limits Day-to-day control is on the **AI** menu, which has three pages: **Overview**, **Features and access** and **Usage**. 1. Open **AI → Overview** and switch on **Turn on AI**. It is available once the provider has passed its test. 2. Set the **Monthly limit**, the most AI requests the whole workspace can make each month. 3. Set **Requests per person each month**, the most one person can make across all features. 4. Select **Save**. Enter `0` in either limit for no limit. Overview also shows the connected provider, this month's requests against the limit, how many people used AI, and requests and tokens per feature. When the workspace limit is reached, AI features show "This month's AI limit has been reached" until the next month or until you raise it. A person who reaches their own limit sees "You have used your AI allowance for this month"; nobody else is affected, and everything else keeps working. ## Choose who can use each feature Open **AI → Features and access**. Every feature starts switched off. 1. Switch on each feature you want. 2. To limit a feature, select **Who can use it** and choose **Departments** and **People**. Leave both empty to allow everyone who has the permission. 3. Optionally set **Requests per person each month for this feature**, which replaces the general per-person limit for that feature. 4. Select **Done**, then **Save**. Each feature also has its own permission on the **Roles** page. A person sees a feature only when AI is on, the feature is on, one of their roles has its permission, they are in a chosen department or named (if the feature is limited), and no limit has been reached. A feature with options of its own, such as what the HR assistant answers from, has a **More choices** link on its row. Employees have no AI settings of their own. ## Usage and privacy Open **AI → Usage** and choose a month to see requests, people, tokens and requests that did not complete, broken down **By feature**, **By department** and **By person**. Your provider bills by tokens, so compare this page with its invoice. For each request Open Core HR records only who made it, which feature, the model, the size of the request and when. Prompts, answers and files are not stored: only the counts, which are kept for 13 months. ## Hosted workspaces On a hosted SaaS installation the service operator connects the provider under **Settings → AI** in the console, includes the AI add-ons in a plan and can set **AI requests a month** for that plan. Workspaces use the operator's provider and never see its key, so workspace administrators see only the **AI** menu. The plan's limit is shown beside the workspace's own monthly limit, and the lower of the two applies. See [Subscription](https://czappstudio.com/docs/saas/subscription) and [Hosting setup](https://czappstudio.com/docs/saas/hosting-setup). --- # AI writing assistant Draft, improve, shorten, formalise or translate long text with a Write with AI button. The **AI writing assistant** add-on puts a **Write with AI** button under long text fields. It drafts new text from a few words or reworks text you already have. Nothing in your form changes until you choose **Use this**. It is a free add-on. Claim it from **Modules** (activated installations only), then install it like any other [add-on](https://czappstudio.com/docs/installation/add-ons). It needs an AI provider connected under [Settings → AI](https://czappstudio.com/docs/ai/overview). ## Turn it on 1. Turn the add-on on from the **Modules** page. 2. Open **AI → Overview** and switch on **Turn on AI**, then open **AI → Features and access**, switch on **Writing help** and save. 3. On the **Roles** page, give **Use AI writing help** to the roles that should have it. System Administrator, HR Administrator and HR Officer have it to start with. People without the permission never see the button. ## Where the button appears | Screen | Field | | --- | --- | | Announcements | Description | | Job postings (Employee Lifecycle) | Description | | Performance goals | Description | | Performance reviews | Comments and written answers | | Email templates | Subject and body | | Letter templates | Content | ## Write something 1. Select **Write with AI** under the field. 2. Choose an action: - **Draft**: say in a few words what the text should cover, for example "office closed on Friday for maintenance". - **Improve**, **Shorten** or **Make more formal**: rework the text already in the field, with an optional note about anything to keep in mind. - **Translate**: choose one of the languages enabled for your organisation. 3. Select **Write**, read the suggestion and edit it if needed. Select **Try again** for another version. 4. Select **Use this** to put it in the field, then save your form as usual. For an email body or a letter, the suggestion is shown as it will look; choose **Use this**, then make any changes in the editor. Always read a suggestion before using it: AI can be wrong and it only knows what you typed. ## What is sent Only the text in the field, your note and your organisation's name are sent to your AI provider. No employee record is sent, so do not type personal details about a person into the request. Merge fields in emails and letters, such as `{{ employee_name }}`, are kept. A suggestion that drops one is rejected and you are asked to try again. The layout of an email or letter is kept and only the words change; check tables and signatures in the preview, and use the letter's **PDF preview** before saving. ## If it does not work | Message | What to do | | --- | --- | | This AI feature is not switched on. | An administrator turns it on under **AI → Features and access**. | | You do not have access to this AI feature. | Ask an administrator for the **Use AI writing help** permission. | | AI is not set up yet. Ask your administrator. | The provider needs to be connected and tested under **Settings → AI**. | | This month's AI limit has been reached. | Wait for next month, or an administrator raises the limit. | | You have used your AI allowance for this month. | Wait for next month, or ask an administrator to raise your limit. | | AI is not available right now. Try again in a few minutes. | The provider did not answer. You can still write the text yourself. | --- # HR assistant Give employees an Ask HR page that answers from your own policies and prepares requests for them to send. The **HR assistant** add-on adds **Ask HR**, where employees ask everyday questions about leave, holidays, working hours and company policies, on the web and in the mobile app. Answers come from your own [Policies](https://czappstudio.com/docs/modules/policies), and from the person's own records if you allow it. It is a paid add-on that needs the Policies add-on and an AI provider connected under [Settings → AI](https://czappstudio.com/docs/ai/overview). ## Set it up 1. Turn the add-on on from the **Modules** page. 2. Open **AI → Overview** and switch on **Turn on AI**, then open **AI → Features and access**, switch on **HR assistant** and save. 3. On the **Roles** page, give **Ask the HR assistant** to the roles that should use it. Only System Administrator has it to start with. **Ask HR** then appears under **My Workspace** for those people. ## Choose what it answers from Open **Settings → HR assistant** and choose **Answers come from**: - **Policies only** (the default): answers come from the current version of the policies assigned to the person asking. - **Policies and the employee's own records**: it can also look up that person's leave balances, leave requests, attendance for this month and last month, upcoming holidays at their location and today's shift. With the Payroll add-on, it can also look up the totals of their last three released payslips. The second choice needs a model that passed **Looks up records** in the connection test. A person only ever gets their own records, and only records they can already see. With this choice those records, including pay totals, are sent to the AI provider when the person asks about them. A person gets answers only from policies assigned to them. When nothing covers the question, the assistant says "I could not find this in your company's policies. Please contact HR." It does not guess or answer from general knowledge about employment law. ## Ask HR 1. On the web, open **My Workspace → Ask HR**. In the mobile app, open **Work → Ask HR**. 2. Type a question, for example "How many days of annual leave do I get?", and select **Ask**. 3. Read the answer. **From:** links to the policy it came from. Ask a follow-up, such as "And for part-time staff?", if needed. Ask HR needs a connection and is not available offline. The assistant can be wrong, so open the linked policy before relying on an answer for something important. ## Prepare leave requests and attendance corrections Under **Settings → HR assistant**, switch on **Prepare requests for the employee to send**. Employees can then ask in their own words: - "I need Friday off for a family event, annual leave." - "I forgot to check out yesterday. I left at 6pm." Ask HR fills in a leave request or an attendance correction and shows it under its answer, marked **not sent yet**. The person checks the dates, times and reason, then selects **Send request** or **Not now**. Nothing is sent until they choose **Send request**. A sent request is the person's own request through the normal leave or correction process, so every rule, limit and approval applies exactly as if they had used the form. If a rule stops it, for example a required document, they are told and can open the form. The assistant asks for a missing date, time or kind of leave instead of guessing, only offers what the person could request themselves, and cannot approve, cancel or change a request. This needs a model that passed **Looks up records**. ## Privacy - Conversations are private to each employee. HR and managers cannot read them or see who asked. - Conversations are deleted after 30 days. Employees can select **Clear my questions** to remove them sooner. - The person's name and contact details are not sent to the AI provider: only the question, the matching passages of their policies, your organisation's name and, if allowed, the result of a record lookup. ## See what it could not answer People with **See what the HR assistant could not answer** see **Last 30 days** under **Settings → HR assistant**: how many questions were asked, how many were answered, and the general subjects that went unanswered, such as "parental leave". A subject that keeps appearing usually means a policy is missing or unclear. --- # Receipt scanning Fill in expense claims from a receipt photo and point reviewers to claims that do not match their receipts. The **Receipt scanning** add-on reads expense receipts with AI, on the web and in the mobile app. It fills in claims from a receipt for the employee to check, and shows reviewers where a claim and its receipts do not agree. It never approves, rejects or changes a claim. It is a paid add-on. It needs an AI provider connected under [Settings → AI](https://czappstudio.com/docs/ai/overview), with a model that passed **Fills in forms** and **Reads images** in the connection test. ## Turn it on 1. Turn the add-on on from the **Modules** page. 2. Open **AI → Overview** and switch on **Turn on AI**, then open **AI → Features and access**, switch on **Receipt scanning** and save. Every role has the **Fill expense claims from a receipt** permission to start with. Remove it on the **Roles** page from roles that should type their claims by hand. ## Fill in a claim from a receipt 1. Open **My Expenses → New Expense** on the web, or **Expenses → New expense** in the mobile app. 2. Under **Receipts**, attach a photo or scan of the receipt. In the mobile app you can use the camera, your photos or your files. 3. Wait a moment while the receipt is read. 4. Check the date, amount, category and description that were filled in, and correct anything that is wrong. 5. Save or submit the claim as usual. Only empty fields are filled; anything you typed first is left alone. The amount is not filled when the receipt is in a different currency from your organisation's. If a receipt cannot be read, you are told and you enter the details yourself. See [Your expenses](https://czappstudio.com/docs/self-service/expenses). PDF receipts are read when you use Claude, Gemini or OpenAI. Self-hosted models read only JPG and PNG photos and scans; a PDF is still attached to the claim as usual. When the phone is offline, the receipt is attached and the claim is queued as usual, and nothing is filled in. The employee is never blocked. Once the claim syncs, the stored receipt is read so reviewers still get their checks. ## Checks for approvers When a reviewer opens a claim, each item may show **Receipt checks**: | Notice | What it means | | --- | --- | | The receipts add up to one amount, but another is claimed. | The claimed amount differs from the total on the item's receipts. | | The receipt is dated one day, but the expense date is another. | The claim's date differs from the receipt's. | | A receipt is in another currency. | The amount could not be compared. Check it by hand. | | A receipt could not be read. | The photo is unclear or is not a receipt. Check it by hand. | | The same receipt file is attached to another expense claim. | An identical file is on another claim that is not cancelled or rejected. | | Another expense claim has a receipt from the same merchant, on the same date, for the same amount. | A possible duplicate from a different photo of the same receipt. | A notice is a prompt to look, not a decision: a difference can be legitimate, such as a tip that is not on the receipt. The person who made the claim does not see these notices. See [Expense administration](https://czappstudio.com/docs/administration/expenses). ## What is sent The receipt file, your organisation's currency and the names of your expense categories are sent to your AI provider. Nothing about the person making the claim is sent. What was read from each receipt is kept with the receipt so reviewers can see the checks. --- # Ask your HR data Ask plain questions about headcount, leave, attendance and expenses, and check every answer against the records it came from. The **Ask your HR data** add-on gives HR and managers an **Ask your data** page. Type a question such as "Who is on leave next week in Sales?" or "Which department had the most late arrivals last month?" and get an answer with the figures it was worked out from. It only reads records. It never changes anything. It is a paid add-on. It needs an AI provider connected under [Settings → AI](https://czappstudio.com/docs/ai/overview), with a model that passed **Looks up records** in the connection test. ## Turn it on 1. Turn the add-on on from the **Modules** page. 2. Open **AI → Overview** and switch on **Turn on AI**, then open **AI → Features and access** and switch on **Questions about HR data**. 3. On the **Roles** page, give the **Ask questions about HR data** permission to the roles that should use it. Only the System Administrator has it to start with. **Ask your data** then appears in the menu for those people. ## What people can ask about A person only gets figures from records they can already see in the application. | Subject | Who can ask | | --- | --- | | Headcount, and people who joined or left | People who can view employees | | Who is on leave, and leave taken | People who can view all leave, or managers for their own reports | | Attendance: days attended, late days, early leaving, hours and overtime | People who can view all attendance, or managers for their own reports | | Expense claims: counts and totals | People who can view all expenses, or team expenses for their own reports | Someone who can only see their own records is told they do not have access. Questions about their own leave or attendance belong in [Ask HR](https://czappstudio.com/docs/ai/hr-assistant). ## Ask a question 1. Open **Ask your data**. 2. Type your question and select **Ask**. Say the period you mean, such as "last month" or "from 1 to 15 November". 3. Read the answer, then open **Worked out from** under it. It shows each set of records the answer used, with the period and department. You can ask a follow-up, such as "And for Support?". One question covers at most 400 days. For expenses, say which claims you mean. "Sent in" counts every claim that was submitted, "approved" counts approved claims, and "paid" or "paid out" counts only claims already reimbursed. **Worked out from** shows which was used under **Claims counted**. The answer comes in the language you ask in. Names of people, departments and kinds of leave are shown as they are recorded. ## Check the figures The answer is written by an AI model and can be wrong. The tables under **Worked out from** are the actual records it was given, so check a figure against them before you rely on it. If a table says it shows only the first rows, the answer covers only those rows: narrow the question to one department or a shorter period. If the records cannot answer the question, you see "I could not work this out from the records." Ask about headcount, leave, attendance or expenses, or open the matching report. ## What is sent and what is kept - Your question and the figures used to answer it, including employee names where the answer lists people, are sent to the AI provider your administrator chose. With a self-hosted model they stay on your own network. - Only you can see your questions and answers. They are removed after 30 days; select **Clear my questions** to remove them sooner. - Each question counts as one AI request towards the monthly limits under **AI → Overview**. --- # Microsoft 365 setup Connect Open Core HR to a Microsoft Entra application and grant the permissions each feature needs. Open Core HR uses one Microsoft 365 connector and three optional modules: **Microsoft 365 Account Management**, **Outlook Email** and **Outlook Calendar Sync**. The Core calendar is included and needs no Microsoft configuration. Enable the connector and the modules you need in module management. In **Settings → Microsoft 365 connection**, save your tenant ID, application ID and client secret. These values belong in Settings, not `.env`. The application supports the Microsoft public cloud. Preserve the application's encryption key when backing up or restoring the settings database. Use a Microsoft Entra application with application permissions and administrator consent. Grant permissions for the operations you enable and restrict mailbox access in Microsoft administration where applicable: | Feature | Permission guidance | | --- | --- | | Link an existing account | User.Read.All for Microsoft account lookup | | Outlook Email | Mail.ReadWrite and Mail.Send | | Calendar sync | Calendars.ReadWrite | | Create accounts and assign licences | See Microsoft's [create-user](https://learn.microsoft.com/en-us/graph/api/user-post-users?view=graph-rest-1.0) and [assign-licence](https://learn.microsoft.com/en-us/graph/api/user-assignlicense?view=graph-rest-1.0) requirements; licence capacity lookup also needs permission to list subscribed SKUs | | Disable or enable access | User.EnableDisableAccount.All and User.Read.All; User.RevokeSessions.All for session revocation | | Reset or synchronize passwords | See the passwordProfile permission and role requirements in [Update user](https://learn.microsoft.com/en-us/graph/api/user-update?view=graph-rest-1.0) | A successful connection test confirms authentication only. Check the intended operation with a designated test employee before enabling automatic account management. Microsoft permissions, licence availability, usage country and tenant policies can prevent individual operations. Run the queue worker and scheduler described in [Services](https://czappstudio.com/docs/installation/services). Auto provisioning, account-status sync and password sync start off. Calendar sync starts off and also requires each user to opt in from Calendar. The optional system-email sender belongs to the connector. It is used only when **Settings → Mail** is set to **Microsoft 365 (Graph)**; SMTP settings remain independent. Changing the connector does not switch the mail transport. After changing tenants, link users to accounts in the new tenant. Old queued account jobs and calendar connections do not reuse the new tenant. Clearing the client secret stops Microsoft operations until valid credentials are saved again. --- # Microsoft 365 Connector The shared connection that the Microsoft 365 modules use. The shared connector holds one Microsoft tenant connection and links HR users to existing Microsoft accounts. It is the dependency for Account Management, Outlook Email and Outlook Calendar Sync; enable only the optional modules you use. An administrator with **Manage settings** configures tenant ID, application ID and client secret in **Settings → Microsoft 365 connection**. The saved secret is encrypted and never displayed. Leave the secret blank to preserve it, or explicitly clear it. Save before running **Test connection**. The test verifies credentials; it does not prove every module permission or mailbox is ready. To use an existing account, an administrator with **Manage settings** and **Edit employees** opens the employee profile's **Microsoft account** tab and links its Microsoft sign-in name. Unlinking removes the local association and stops features using it; it does not delete or disable the Microsoft account. Changing the tenant requires linking accounts for the new tenant. Old links and sync checkpoints are not reused across tenants. See [Microsoft 365 setup](https://czappstudio.com/docs/microsoft-365/setup) for permissions and operational requirements. --- # Microsoft 365 account management Provision, link, reset, disable and deprovision Microsoft 365 accounts for employees. This optional module creates Microsoft accounts for employees and manages account access. It requires Microsoft365Connector. Existing Microsoft accounts can be linked through the connector without purchasing Account Management. Configure its policies under **Settings → Microsoft 365 accounts**. Auto provisioning, account-status synchronization and password synchronization are off by default. Each is a separate control. The **Microsoft 365 Accounts** overview helps administrators find unlinked employees and inspect recent or disabled accounts. Employee profile actions require **Manage settings** and **Edit employees**; viewing account summaries also requires employee-detail access. For email and calendar access, enable [Outlook Email](https://czappstudio.com/docs/microsoft-365/outlook-email) or [Outlook Calendar Sync](https://czappstudio.com/docs/microsoft-365/outlook-calendar-sync) independently. ## Automatic account provisioning 1. Configure and test the shared Microsoft 365 connection. 2. In **Settings → Microsoft 365 accounts**, set a verified email domain and address format. Set the licence SKU and usage country when assigning a licence. 3. Enable **Auto provision** when newly created active employees should receive an account. 4. Create the employee and review the Microsoft account management tab after the queue worker processes the request. The worker creates a Microsoft identity and assigns the configured licence. Microsoft controls mailbox readiness; licence assignment does not guarantee immediate mailbox availability. Existing unlinked employees can be provisioned manually from their profiles. If licence assignment fails after the identity is created, use **Retry licence assignment**. If creation has an uncertain result, check the Microsoft admin centre and link the existing account rather than creating a duplicate. Resolve missing licence capacity or permissions before retrying. Turning auto provisioning off stops queued automatic provisioning. It does not delete accounts. A deliberate manual provision action remains available. ## Reviewing Microsoft accounts ![Microsoft 365 Accounts: the Unlinked (1), Recently Linked (2) and Disabled (3) tabs.](https://media.czappstudio.com/screens/docs/m365-accounts/light-6e9f9f9894-2880.webp) Administrators can open **Microsoft 365 Accounts** to review active employees without a linked account, accounts linked in the last seven days, and accounts with Microsoft sign-in disabled. Configure connection credentials in **Settings → Microsoft 365 Connection** and provisioning policies in **Settings → Microsoft 365 Accounts**. Automation is off by default. An account link alone does not confirm that a mailbox licence has been assigned. Open an employee profile to link an existing account or use **Microsoft account management** to provision and manage an account. Review pending licence assignments and uncertain creation results there before retrying. ## Employees without a linked account Administrators can use **Microsoft 365 Accounts → Unlinked** to find active employees without a Microsoft account link. Open the employee profile. If a Microsoft account already exists, link it from **Microsoft account**. Otherwise, use **Microsoft account management** to provision one after configuring the account domain and any required licence in Settings. Automatic provisioning applies only when its setting is enabled and an employee becomes active. Enabling it does not create accounts for every existing employee. A linked account still needs a suitable Microsoft licence before Outlook Email or calendar sync can use its mailbox. ## Recently linked accounts The **Recently Linked** tab in **Microsoft 365 Accounts** shows up to twenty accounts linked in the last seven days. This includes existing Microsoft accounts linked by an administrator and newly provisioned accounts. The link date does not confirm licence assignment or mailbox readiness. Check the employee profile's **Microsoft account management** tab for provisioning status and [initial login details](https://czappstudio.com/docs/microsoft-365/account-management#section-7). ## Reviewing disabled Microsoft 365 accounts Use the **Disabled** view in **Microsoft 365 Accounts** to review linked work accounts that cannot sign in. Check the employee's account access and the disable date before restoring access. Disabling an employee account retains the Microsoft 365 account and mailbox; it does not automatically delete them after a grace period. Enable account access from the employee profile only when access should be restored. Employment status and account access are separate. An ended employment record does not itself prove that access has been disabled. See [Pausing and restoring access](https://czappstudio.com/docs/microsoft-365/account-management#section-8). ## Resetting a Microsoft password In an employee's **Microsoft account management** tab, choose the password-reset action and confirm. The result changes the linked Microsoft password only; it does not reset the HR password. The new password is displayed only to authorized administrators and stored encrypted for credential handover. Close the display after use and follow your organization's approved handover process. The separate **Sync password changes** setting mirrors future HR password changes to Microsoft when enabled. It is off by default and does not read existing passwords. A Microsoft failure does not undo a successful HR password change; an administrator must resolve the Microsoft issue. ## Viewing Microsoft credentials Open the employee's **Microsoft account management** tab and choose the credential action when available. Only credentials generated by Open Core HR can be displayed; linking an existing account does not retrieve its password. The password is encrypted in storage and excluded from ordinary API responses. Access requires **Manage settings** and **Edit employees**. Close the display after use and transfer credentials through your organization's approved process. ## Disabling and enabling Microsoft access Use the employee profile's **Microsoft account management** actions to disable or enable the linked Microsoft account. Disabling blocks sign-in and requests session revocation. It retains the account and mailbox and does not end employment. Enable **Sync account status** in module settings only when employee suspension, deletion and restoration should control Microsoft access automatically. The worker checks the employee's current status before applying a queued change. With the setting off, manage Microsoft access explicitly. Deleting an HR record never permanently deletes the Microsoft account. Complete mailbox handover, retention and any permanent deletion through the Microsoft admin centre. ## Microsoft access when employment ends Use the employee profile's **Microsoft account management** actions to disable or enable the linked Microsoft account. Disabling blocks sign-in and requests session revocation. It retains the account and mailbox and does not end employment. Enable **Sync account status** in module settings only when employee suspension, deletion and restoration should control Microsoft access automatically. The worker checks the employee's current status before applying a queued change. With the setting off, manage Microsoft access explicitly. Deleting an HR record never permanently deletes the Microsoft account. Complete mailbox handover, retention and any permanent deletion through the Microsoft admin centre. --- # Outlook Email Read, search, send, reply to and organize your Microsoft 365 mail inside Open Core HR. Outlook Email is an optional module for reading, searching, sending and organizing Microsoft 365 email. Open **Outlook Email** from the menu after your administrator links your Microsoft account. It requires Microsoft365Connector, an Exchange Online mailbox and the appropriate Microsoft Graph permissions. Microsoft 365 Account Management and Outlook Calendar Sync are separate optional modules; neither is required to use an existing mailbox. See [Reading mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-1), [Sending mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-11) and [Searching mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-7). Your [Core calendar](https://czappstudio.com/docs/self-service/calendar) is available independently. ## Reading your mail Open your mailbox to read incoming messages, switch between folders, and mark mail as read or unread. > **Availability:** Email and Calendar work only if your company uses Microsoft 365 and your account is connected to it. Check with your HR or IT team if your account is not connected. ### Steps 1. Choose **Outlook Email** from the sidebar. Your **Inbox** opens with the message list shown. 2. To switch folders, click a folder name in the list on the left — for example **Sent Items**, **Drafts** or **Deleted Items**. The message list updates to show that folder. 3. Click a message in the list to open it in the reading pane on the right. 4. Read the message. You'll see the subject, who it's **From**, who it's **To**, any **CC** recipients, and the **Date**. If the message has attachments, they appear as chips above the message body. 5. If the conversation has earlier messages, a line such as "2 earlier messages in this conversation" appears — click any entry to expand and read it. ### Marking read and unread - Opening an unread message marks it as read automatically. - To change it yourself, use the mail icon in the action bar at the top of the reading pane. The tooltip says **Mark as unread** or **Mark as read** depending on the current state. ### Refreshing The folder list refreshes on its own every minute, so unread counts stay up to date. Switching folders or reopening a message also reloads the latest mail. ### Tips - On a small screen the reading pane replaces the message list. Use **Back to messages** at the top left to return to the list. - Use **Load more** at the bottom of the list to fetch older messages. ### Related pages - [Searching your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-7) - [Replying and forwarding](https://czappstudio.com/docs/microsoft-365/outlook-email#section-16) - [Organizing your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-27) ## Searching your mail There's a search box at the top of the mailbox for finding messages. ### Steps 1. Choose **Outlook Email** from the sidebar to open your mailbox. 2. Select **Search emails...**. 3. Type what you're looking for, such as a sender, subject word or phrase. After a short pause, the message list displays matching results from your mailbox. 4. Select a result to read it. If there are 1,000 matches, refine the query to find a more specific result. ### Tips - Clear the box to go back to the normal folder view. - Search results use the mailbox search service. Clear the query to browse a particular folder instead. ### Related pages - [Reading your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-1) ## Sending a new message Write and send a new email from inside Open Core HR. ### Steps 1. Choose **Outlook Email** from the sidebar. 2. Click the **Compose** button (the **+** button at the top of the folder list). The **New Message** screen opens. 3. In the **To** field, start typing a name or email address and pick a colleague from the list, or type a full email address. Add as many recipients as you need. 4. To copy other people, click **CC** or **BCC** next to the **To** field and add addresses there. 5. Type a **Subject**. 6. Write your message in the body box. Use the toolbar above it to make text bold, italic, strikethrough, add a bullet list or numbered list, or add a link. 7. To attach files, see [Attachments](https://czappstudio.com/docs/microsoft-365/outlook-email#section-33). 8. Click **Send**. ### After you finish After the message is sent you're taken back to your mailbox and an "Email sent" confirmation appears. If you didn't add any recipient, you'll be asked to add at least one. ### Tips - Click **Save Draft** to keep the message without sending it — see [Drafts](https://czappstudio.com/docs/microsoft-365/outlook-email#section-22). - Click **Cancel** to leave without sending. ### Related pages - [Replying and forwarding](https://czappstudio.com/docs/microsoft-365/outlook-email#section-16) - [Attachments](https://czappstudio.com/docs/microsoft-365/outlook-email#section-33) - [Drafts](https://czappstudio.com/docs/microsoft-365/outlook-email#section-22) ## Replying and forwarding When a message is open in the reading pane, you can reply to the sender, reply to everyone, or forward it on. ### Reply to the sender 1. Open the message. 2. In the action bar at the top of the reading pane, click **Reply**. A reply box opens below the message, addressed to the sender. 3. Type your reply in the editor. 4. Click **Send**. You can also click the **Click here to reply...** prompt at the bottom of an open message to start a reply the same way. ### Reply to everyone 1. Open the message. 2. Click **Reply All** in the action bar. The reply box opens addressed to the sender and all other recipients. 3. Type your reply and click **Send**. ### Forward a message 1. Open the message. 2. Click **Forward** in the action bar. The **Forward** screen opens with the original subject (prefixed with "Fwd:") and the original message quoted in the body. 3. Add one or more recipients in the **To** field. 4. Add any note above the quoted message. 5. Click **Forward**. ### Tips - If you start a reply and then click the close (X) button or **Discard**, you'll be asked to confirm before any text you typed is thrown away. - Switching to a different message closes an open reply box. ### Related pages - [Reading your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-1) - [Sending a new message](https://czappstudio.com/docs/microsoft-365/outlook-email#section-11) ## Drafts A draft is a message you've started but haven't sent yet. Drafts are kept in the **Drafts** folder. ### Saving a draft 1. Click **Compose** to start a new message and fill in whatever you have so far — recipients, subject, body. 2. Click **Save Draft**. A "Draft saved" confirmation appears. The message is stored in your **Drafts** folder. ### Opening a draft 1. Choose **Outlook Email** from the sidebar. 2. In the folder list on the left, click **Drafts**. 3. Click the draft to view it in the reading pane. To continue editing and send a saved draft, use Outlook; this web compose screen currently creates new messages and does not reopen an existing draft for editing. ### Discarding a draft To remove a draft you no longer want, open it from the **Drafts** folder and use the delete (trash) button in the action bar. It moves to **Deleted Items**, where you can still recover it if needed. ### Related pages - [Sending a new message](https://czappstudio.com/docs/microsoft-365/outlook-email#section-11) - [Organizing your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-27) ## Organizing your mail You can flag messages that need attention and delete messages you no longer want. ### Flagging a message 1. Open the message in the reading pane. 2. In the action bar, click the flag icon. The flag turns orange to show the message is flagged, and a flag icon appears next to it in the message list. 3. To remove it, click the flag icon again. ### Marking read or unread In the action bar, click the mail icon to switch a message between read and unread. The tooltip shows **Mark as unread** or **Mark as read**. ### Deleting a message 1. Open the message in the reading pane. 2. Click the trash icon in the action bar. 3. Confirm by clicking **Delete**. The message moves to **Deleted Items**, where you can recover it if needed. ### Archiving and returning to Inbox Open a message and click the archive icon in the action bar (**Archive this message**). In the Archive folder, the same control becomes **Move to Inbox**. For other folder moves, use Outlook. ### Related pages - [Reading your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-1) - [Drafts](https://czappstudio.com/docs/microsoft-365/outlook-email#section-22) ## Attachments You can attach files to a new message and download files that arrive on messages you receive. ### Attaching a file when composing 1. Click **Compose** to start a new message. 2. Below the message body, click **Attach Files** (the button with a paperclip icon). 3. Choose one or more files from your device. Each file appears as a chip showing its name. 4. To remove a file you added, click the X on its chip. 5. Finish your message and click **Send**. Attaching files is available on new messages. (Reply and forward don't have an attach-files button.) ### Downloading an attachment you received 1. Open the message in the reading pane. 2. Attachments appear as chips above the message body, each showing the file name and size with a paperclip and a download icon. 3. Click the attachment chip to download the file. ### Tips - A message with attachments shows a paperclip icon next to it in the message list. ### Related pages - [Sending a new message](https://czappstudio.com/docs/microsoft-365/outlook-email#section-11) - [Reading your mail](https://czappstudio.com/docs/microsoft-365/outlook-email#section-1) --- # Outlook Calendar Sync Keep your Core calendar and your Outlook calendar in step. This optional module connects the included Core calendar to Microsoft 365. It requires Microsoft365Connector and a linked active mailbox. It does not require Outlook Email or Account Management. An administrator chooses the organization-wide mode under **Settings → Outlook Calendar Sync**: | Mode | Behavior | | --- | --- | | Off | No Outlook calendar requests. Core remains available. | | Core → Outlook | Publish events you organize in Core and their changes or cancellations. | | Two-way | Also import private Outlook appointments and apply Outlook changes to exported personal Core events. | In the web **Calendar**, enable your own Outlook sync, then use **Sync now** when needed. The background scheduler otherwise checks enabled connections every five minutes. Initial synchronization covers the previous month and the next seven months, and advances monthly. Recurring Core occurrences are published as separate appointments in that window. Imported appointments are read-only in Core and private to you. Module-owned events remain controlled by the originating module. Core RSVP actions are local; handle Outlook invitation responses in Outlook. When both sides change an event, review the conflict in Calendar. **Use Core** publishes the current Core version. **Use Outlook** applies the current Outlook version to a personal event in two-way mode; it is unavailable for module-owned events. Disabling a module stops its sync operations and does not erase remote appointments. For Teams links, the administrator enables Teams meetings and the organizer requests an online meeting on the Core event. The linked Microsoft account must support Teams meetings. A successful sync supplies the join link. If sync fails, check the linked account, saved connection, mailbox and calendar permissions, then retry. Turning sync off preserves local events and existing remote copies. --- # SaaS hosting setup Sell subscriptions to separate company workspaces with the optional SaaS module. The optional **SaaS** module lets you sell subscriptions to separate company workspaces. Each customer has its own users, HR records, settings and files within one shared database. One workspace has one subscription. Without this module, Open Core HR remains a standalone installation. ## Prepare the service 1. Enable SaaS through module management and apply the supplied migrations. Enable **SaaS PayPal** or **SaaS Razorpay** only if you need that payment provider. 2. Configure outgoing email and keep the queue worker and scheduler running as described in [Services](https://czappstudio.com/docs/installation/services). Customers must receive and open their signup verification email. 3. Sign in as the installation super administrator. In **Settings → General**, enter the seller's billing details and currency. Choose the currency before creating plans or orders. Creating the first plan or order locks the currency. For offline payments, configure **Settings → Bank transfer**. 4. Set the payment grace period and your terms and privacy links. Once either link is set, visitors must accept the linked terms to sign up. The acceptance and links are recorded in the customer's billing audit when they verify their email. To protect signup from automated submissions, enable **Workspace signup** under **Settings → Security** (see [Google reCAPTCHA](https://czappstudio.com/docs/installation/configuration#section-3)). Keep public signup disabled until you have checked the complete signup and payment flow. 5. Create and publish plans. Set monthly and/or yearly pricing, trial days, user and storage limits, and included modules. Only installed, enabled modules can be offered; include their dependencies too. Changing a plan does not rewrite accepted subscription terms or old invoices. Archive a plan when it should no longer be offered to new customers. A customer's existing subscription keeps its saved terms. Visitors can compare published offers at `/plans` and choose a billing interval before signing up. With Landing Page enabled, **Pricing** appears in the public navigation, and visitors can return to the published landing sections from pricing or signup. To feature pricing in your landing page’s main call to action, set its destination to `/plans`. The operator edits the landing page, its pages, enquiries and subscribers from **Landing page** in the console menu, and its site settings under **Settings → Landing page**. ## Explore the demo On a local or testing installation with SaaS enabled and migrations applied, populate sample workspaces from `backend/`: ```sh php artisan db:seed --class='Modules\SaaS\Database\Seeders\Demo\SaaSDemoSeeder' ``` Set `APP_DEMO=true` for the demo installation to show **Platform admin demo**, **Customer admin demo** and **Employee demo** on the sign-in page. The buttons select the appropriate workspace and use normal authentication, including CAPTCHA when configured. Keep demo mode off on a real customer deployment. The sample companies cover active monthly and annual subscriptions, a trial, an overdue subscription and a suspension. Review the sample bank transfer, inspect order and refund history, or open Northstar's HR workspace and billing page. These are fictional records; no payment provider is charged. Re-running the seeder preserves existing demo records and your changes. ## Bank transfers In **Settings → Bank transfer**, enter your payment instructions, turn on **Accept bank transfers**, and save. Customers can then create an order, make the transfer outside Open Core HR, and submit a reference and optional proof. To pause new bank transfer orders, turn off **Accept bank transfers** and save. The instructions are kept for when you enable it again. Customers can still submit proof for existing, unexpired orders, and you can review those transfers. Review the actual bank receipt before approving a submission in **Orders**. Approval activates its paid period. Reject incorrect submissions with a reason so the customer can correct them. A bank refund must first be completed outside the application; **Record refund** records the amount and reference in the order history. ## Online payments Gateway configuration is available only to the installation super administrator. Open **Settings → PayPal** or **Settings → Razorpay**, store provider credentials, select the test or live environment, and configure the webhook URL shown there. Each provider appears only when its module is enabled. Preserve the application encryption key in your backup process. PayPal and Razorpay payments use the provider's hosted checkout. An approval or return page alone does not activate a subscription: the server verifies payment through provider events or reconciliation. Test both the checkout and webhook delivery with the provider before accepting live customers. PayPal returns the customer to billing. After Razorpay hosted checkout, customers return to **Subscription** and use **Refresh status**. An online renewal that needs a new mandate starts when the current period ends; bank transfer can be prepaid for the next period. An unpaid online order expires after three days, and its checkout is withdrawn at the provider. If the customer completes that checkout later anyway, the payment is still recorded and applied. If PayPal suspends a subscription after a failed renewal, or Razorpay halts one after its retries, Open Core HR cancels that mandate. The owner can then pay again from billing during the grace period. Overdue reminders wait three days after the period ends while an automatic renewal can still be collected. PayPal supports a coupon on the first paid cycle. Razorpay coupon checkout is currently unavailable; use a supported payment method for discounted orders. Online refunds are initiated in the provider dashboard and reflected in Open Core HR after verification. The scheduler reconciles subscriptions and expiry. For troubleshooting, run `php artisan saas:reconcile` from `backend/` and investigate reported failures. A successful credentials test confirms authentication, not the full recurring-payment flow. ## Customers and limits Use **Dashboard** to compare monthly collections and refunds. The chart covers the current calendar month and the preceding five; a refund appears in the month it was recorded. **Net collections (all time)** subtracts refunds from successful payments in the billing currency. **Monthly recurring revenue** uses the plan price for active and past-due subscriptions, divides annual prices by twelve, and excludes trials. It is an estimate of recurring billings, not a payment balance. The customer owner manages employees and ordinary workspace permissions. Platform administration remains restricted to the installation super administrator. Customers sign in with their workspace identifier; the installation administrator leaves this field blank. User limits count non-system accounts that have not been deleted, including inactive accounts. Storage limits count managed files. Reaching a limit blocks additional users or uploads; existing records are retained. Billing stays available after access expires so the customer can renew. Use a suspension to block ordinary workspace access. Suspending also cancels the customer's automatic payments at PayPal or Razorpay, so the provider stops charging them. After you reactivate the customer, the owner authorizes payment again from billing when the next period is due. Employees using the mobile app in a suspended or expired workspace are told to contact their administrator. A trial extension requires a reason and is recorded. A refund does not automatically cancel a subscription; handle the access decision separately. Do not disable SaaS while subscriptions exist. Gateway modules also prevent disabling while they manage active payment mandates. Cancel or migrate the affected subscriptions first. Back up the entire shared database and managed file storage together; see [Backups & updates](https://czappstudio.com/docs/installation/backups-and-updates). --- # Manage your subscription Start, renew, change or cancel your hosted workspace subscription and review billing records. In a hosted workspace, the workspace owner or a user with billing permission can select the plan at the bottom of the sidebar to open **Subscription & billing**. This page shows trial or renewal dates, user and storage usage, included modules, and orders. ## Start or renew a plan 1. Choose **Subscribe or renew**, select a plan and monthly or yearly billing, and enter a coupon if you have one. 2. Choose an available payment method and review the order total, including discount and tax. 3. For online payment, continue to the provider and complete authorization. Return to **Subscription** and use **Refresh status** if the provider does not return you automatically. Access updates after the server verifies payment. If the provider shows success but the order is still pending, allow time for confirmation and contact your service operator with the order number before paying again. 4. For bank transfer, follow the displayed instructions and use the order number as a reference. Submit the transfer reference, date and optional proof. Access begins after the operator confirms receipt. If rejected, read the review notes and correct the submission. Only one pending order is allowed at a time. Open it to continue payment or cancel it before creating a different order. A pending order does not itself grant paid access. Coupons apply to the first paid period and may be limited by plan, billing interval or expiry. Razorpay cannot currently process a coupon order; choose another supported payment method. ## Change or cancel Open **Change plan** to compare available plans against the column marked **Subscribed**. That column shows your agreed price and billing interval. Switch between monthly and yearly to compare other offers, including their user limits, storage and modules. Choose a plan, review its price and renewal date, then select **Schedule change**. Your current plan covers the rest of the paid period. If you have automatic payments, scheduling a change cancels the existing mandate. Use **Keep current plan** to remove a scheduled change before renewal. If an order is waiting for payment or transfer approval, open **View orders** and resolve it first. If you have prepaid the next period, wait for that period to begin. Plans with limits below your current user count or storage usage show why they cannot be selected. Authorize a replacement online mandate when the current period ends. You can prepay the next period by bank transfer; its plan and limits take effect when that period begins. Cancelling a subscription stops future renewal while preserving the remaining paid access. Review any pending payment separately. Refunds are handled by the service operator and do not automatically cancel the subscription. ## Usage and billing records User usage includes inactive accounts that have not been deleted, but excludes system accounts. At the user limit, you must remove an account you no longer need or renew onto a larger plan before adding another. Storage limits apply to managed uploads; remove unnecessary files or choose a larger allowance before uploading more. Update your billing name, address, email and tax identifier before creating an order. Existing orders retain the details recorded when they were created. Open an order to view its invoice, inspect payment and refund history, or check transfer review notes. Use the invoice's Print button to print it or save it as a PDF through your browser. If an automatic renewal fails and the provider stops retrying, automatic payments end. Open billing and pay again before the grace period ends. When a trial or paid period expires, ordinary work may be restricted, and employees using the mobile app are told to contact their administrator. Billing remains available so that you can renew. Contact the service operator if your workspace has been suspended or a confirmed payment is missing.