Skip to content
Documentation

User guide

Hints, tips and best practices for the usage of ProjectForge

Written by
Table of Contents

1. Introduction

This guide collects hints, tips and best practices for working with ProjectForge®. It doesn’t describe every single field: most pages explain themselves through their labels and tool tips.

Since version 9.0 ProjectForge® comes with a completely reworked user interface. This guide describes the current interface.

  • New to ProjectForge? The Quick start shows how to set up users, groups, structure elements and cost units step by step.

  • Installation, configuration and plugins are described in the Admin guide.

Hint

You only see the menu entries and pages you have access to. Some features also have to be enabled or configured by your administrator first (e. g. plugins, telephony, CardDAV or e-invoices). If something described here is missing, please ask your administrator.

2. Common concepts

The button Menu at the top left opens the main menu (keyboard shortcut Ctrl+K, on macOS Cmd+K). It shows all entries you have access to, grouped into Common, Project management, HR, Finance, Cost, Reporting, Organization, Administration and Miscellaneous.

  • Search the menu: Just start typing. ProjectForge® searches the titles of the menu entries as well as the group names (typing "finance" lists the whole area). Below the menu entries you’ll find matching data records, e. g. addresses or projects. The last row Search "…​" in all data opens the global search. You may navigate the results with the cursor keys and Enter.

  • Recently used: While the search field is empty, your recently used entries are shown on top. They are stored on the server, so they follow you to other devices and browsers.

2.2. Favorites bar and personal menu

Next to the menu button you’ll find your personal favorites bar. It may contain single entries as well as folders. Entries that don’t fit into the bar move into the …​ menu. Some entries show a counter badge, e. g. the number of open leave applications.

To change your favorites, choose Customize my menu in the user menu (top right, showing your name): drag entries from the template on the right to your menu on the left (or simply click them), create, rename and remove groups and save your changes. Reset to Default restores the default menu.

The user menu also contains Send feedback, My account, Two-factor authentication, Leave account (for employees), entries of plugins (e. g. the Personal box of DataTransfer), Appearance and Logout.

Under Common > Search (or via the last row of the menu search) you may search several areas at once: addresses, customers, projects, users, groups, structure elements, books and employees. Only areas you are allowed to read are searched.

  • Tick the area tiles to restrict the search to some areas, Search all areas resets the scope.

  • Show all in …​ opens the list of the area with your search term already entered.

  • The search term is part of the page address, so you may bookmark a search or send it to a colleague.

Most list views have a search field (Search list…​). The search starts while you are typing, Esc clears the field. The search field supports the Lucene query syntax, refer to the Lucene query parser syntax for all details.

The following table shows some commonly used queries.

Expression Function

abc

The search result contains all objects with fields containing words beginning with 'abc'. The search isn’t case-sensitive.

*abc*

The search result contains all objects with fields containing words containing 'abc'. The search isn’t case-sensitive.

meier~

Fuzzy search: words with a similar spelling such as 'mayer' will also be found.

abc def

Searches for objects containing words beginning with 'abc' or 'def'.

+abc -def

Searches for objects containing the word 'abc' but not the word 'def' (no automatic wildcards, see below; +abc* -def* for words beginning with 'abc' but not with 'def').

name:abc def

Searches for all objects where the field 'name' contains the word 'abc' and searches for 'def' in all fields.

2.4.1. Automatic wildcards

Hint

If the search term consists only of letters, digits, spaces and the characters @._-*`, ProjectForge® automatically appends the wildcard character '*' to each word. Words ending with '*', words starting with '' or '-' (Lucene operators) and the keywords AND, OR and NOT are left untouched. A search term starting with '+' or '-' is used as entered, as are all other expressions (e. g. containing ':', '~', '"' or brackets). A word with a separator inside such as `dhl-pop is searched as typed and as its parts: dhl-pop* or both dhl* and pop*.

Start your search term with an apostrophe (') to switch off any modification: the apostrophe is removed and the rest is used exactly as entered.

Expression Modification by ProjectForge

hello

hello*

hello ProjectForge

hello* ProjectForge*

hello AND world

hello* AND world*

name:hello

name:hello
(no substitution because of ':'.)

+hello -world

hello -world + (no substitution because of the leading ''.)

'hello

hello
(no substitution because of the leading apostrophe.)

2.5. Filtering lists

Above each list you’ll find the filter bar:

  • Add filter offers all searchable fields of the list as a filter, All filters shows all active filters at once. Reset and Clear all remove the filters again.

  • Period filters (e. g. Time period of the time sheets) offer quick selections such as week, month or year to date, and arrows for paging to the previous or next period.

  • Modified filters the list by the history of changes: by the user who made a change, by the time of modification (e. g. last 10 minutes, today, since yesterday) or by modified values. This is useful, if you want to find all objects you changed during the last hour.

  • Deleted shows entries marked as deleted, so you may restore them.

Your last filter settings are stored on the server for each list, so they survive a reload and are available on all your devices.

2.5.1. Favorite filters

Use Favorites in the filter bar to save filter settings you need often: New Filter saves the current settings under a name of your choice. An asterisk marks a favorite whose settings were changed, Save modification stores the changes. You may rename and delete favorites at any time.

All pages have stable addresses: you may bookmark them in your browser or send them by e-mail. Edit pages are addressed by the id of the object, list pages accept a search term (?q=…​). Filter settings are not part of the address, use favorite filters for them.

2.6. Multi-selection and mass update

Many lists (e. g. time sheets, invoices, incoming invoices, salaries, projects, cost units and liquidity entries) support the modification of many entries at once:

  1. Click Multi selection in the toolbar of the list.

  2. Select the desired entries: click selects an entry, Ctrl (macOS: Cmd) + click toggles single entries, Shift + click selects a range, the checkbox in the header selects all.

  3. Click Mass update. For each field you may choose whether to set (overwrite) a value, to append text, to search & replace text or to delete the value.

Up to 100 entries can be modified at once. After the update ProjectForge® shows the number of modified entries and offers an Excel file with all modifications. Selected entries may also be deleted or restored at once.

2.7. Export

Lists with export support offer an Export menu in the toolbar. Excel export exports the currently filtered list. Some lists offer further exports, e. g. the cost assignments of invoices, the forecast of the order book or a PDF of time sheets.

2.8. Auto completion

Many fields (e. g. users, structure elements, cost units or customers) suggest entries while you are typing, usually after entering 2 characters. Use the cursor up and down keys and Enter to select an entry without using your mouse. The selection of structure elements additionally offers your recently used structure elements and your own favorites.

2.9. History of changes

Almost all objects keep a complete history of changes. The section History of changes at the bottom of an edit page shows when an object was created and changed, by whom and which fields were modified (old and new value).

For users and groups you may additionally enter a Change comment while saving (e. g. why a right was granted) or add one later via Append comment. These comments are shown in the history.

2.10. Appearance

Choose Appearance in the user menu to switch between the Light and Dark theme or to follow the setting of your operating system (System). The setting is stored for your user and applied on all your devices.

2.11. Stay logged-in

On the login screen you may tick Remember my login on this computer.:

  • ProjectForge® stores a cookie in this browser. It stays valid for 30 days after its last use and is renewed every time you use it.

  • Logout removes the cookie of the current browser only.

  • Changing your password logs out all devices.

  • Under My account you see all devices staying logged in (browser, IP address, last access). Log out in the row of a device logs out this device only, Log out all devices. logs out all of them, including the current one.

2.12. Two-factor authentication

Your administrator may protect sensitive areas (e. g. administration, finance or HR) by a second factor in addition to your password. Configure your factors in the user menu under Two-factor authentication:

  • Authenticator apps: Scan the displayed QR code with an authenticator app on your smartphone (time-based one-time passwords, TOTP).

  • WebAuthn (Fido2 etc.): Register a hardware token such as a YubiKey.

  • SMS configuration: Receive one-time codes by text message (if configured).

  • Codes may also be sent by e-mail, unless your administrator has disabled this.

If a page or an action requires a second factor that is missing or expired, ProjectForge® asks for a code and continues afterwards. Which areas are protected and how long a second factor stays valid is configured by your administrator, see Admin guide: 2FA.

2.13. My account

Under My account you may maintain your personal settings, e. g. your name, time zone, language, date formats, your phone ids for direct calls and your public GPG and SSH keys.

You’ll also find your personal authentication tokens here: for subscribing calendars, for CardDAV and for REST clients. Each token may be renewed: all URLs and clients using the old token stop working immediately, which is what you want if a subscription URL fell into the wrong hands.

3. Calendar

The calendar is one of the most important functionalities of ProjectForge®. You may organize your time sheets and personal events as well as team events in a convenient way.

3.1. Views and navigation

The calendar offers the following views: Month, Week and Day, each month and week also without weekends (Workdays), a week overview (overview) and a list of all entries (agenda).

Use Today, the arrow buttons and Choose date (a month picker with a year selection) for browsing. In the week and day views a line marks the current time. ProjectForge® remembers your last view and date.

3.2. Calendars, colors and favorites

  • Choose the calendars to display: all team calendars you have access to, plus Birthdays (all addresses) and Birthdays (address favorites).

  • Click on a calendar to change its color or to hide it temporarily.

  • The settings dialog (gear icon) contains your Default calendar for new events, the time sheets to show (your own or, if you are allowed to, those of other users), Breaks, the vacation of groups and users (Vacation groups, Vacation users), the grid size, the begin of the day and the colors.

  • Save different combinations as Favorites and switch between them with two clicks.

Holidays and weekends are highlighted.

3.3. Holidays

ProjectForge® supports the German holidays out of the box (in the initial configuration Christmas Eve and New Year’s Eve count as half working days). Your administrator may add own holidays or modify the built-in ones in config.xml.

3.4. Support of different time zones

ProjectForge® supports different time zones at once. Every user may choose his time zone in My account, e. g. while travelling.

3.5. Creating and changing entries

  • Create: Select a time range in the calendar or click + (or press N). If you have chosen a default calendar, a new event is created, otherwise a new time sheet.

  • Move and resize: Drag an entry to another time or change its duration. ProjectForge® opens the edit form with the new times; the change is applied when you save it.

  • Copy: Use Clone in the edit form of a time sheet or an event.

  • Convert: An event may be turned into a time sheet (Switch to time sheet) and vice versa.

  • Breaks: Gaps between your time sheets of a day may be displayed as breaks. Click on a break to book a time sheet for this gap.

3.6. Booking several days

Book several days in the toolbar books a time sheet on every working day of a period, e. g. for a training or a longer stay at a customer:

  1. Choose the period (at most one month), the start time, the hours per day, the structure element, cost unit, location and description (or use one of your templates or recent entries).

  2. Check the Preview: weekends and holidays are skipped. On a day that is already booked, the time sheet is only booked if it doesn’t collide with an existing one (an overlap with a shared cost element is allowed).

  3. Click Book.

With Take over vacation you choose one of your leave applications (approved or in progress, a year back and ahead) and book its days on the vacation cost unit configured by your administrator. If no vacation cost unit is configured, you choose the structure element and cost unit yourself.

3.7. Team calendars

Under Common > List of calendars you manage team calendars. Each calendar has an owner and may be shared with groups and users using three access modes:

  1. Full access
    The assigned groups and users are able to read, insert, update and delete any event of the calendar.

  2. Read-only access
    The assigned groups and users are only able to read all events including the subscription and download.

  3. Minimal access
    The assigned groups and users only see the start and stop times of the events, including the subscription and download. All other properties of events such as title, location, notes etc. are removed.

image

Figure 1:

You may configure the access to any calendar for groups and/or users.

A team calendar may also show the leave of selected users and groups (section Vacation).

3.8. Recurring events

ProjectForge® supports recurring events. If you change a recurring event, you choose under Any modification regards: whether the change applies to Only this event, to All events or to All future events.

Attendees of imported events are displayed, but ProjectForge® doesn’t send invitations.

3.9. Calendar subscriptions (ics)

You may subscribe your ProjectForge® calendars in any calendar application supporting ics subscriptions (e. g. Apple Calendar, Google Calendar, Microsoft Outlook or Thunderbird):

  • More > Subscription in the calendar offers subscriptions for your time sheets (Export timesheets), the holidays (Export holidays) and the calendar weeks (Export week-of-years.).

  • The edit page of each team calendar shows the subscription URL of this calendar, with or without reminders.

The dialogs show the URL to copy and a QR code for your smartphone. The subscriptions are read-only: changes are made in ProjectForge®. (ProjectForge® doesn’t offer a CalDAV server.)

Hint

The subscription URL contains your personal, encrypted calendar token. Keep it secret! If in doubt, renew the Authentication token for calendars under My account. All your previous subscription URLs stop working afterwards.

Single events may be downloaded as ics file as well (Export ics).

image

Figure 2:

An example of subscribed calendars of ProjectForge in Apple’s calendar.

3.10. Subscribing external calendars

A team calendar may subscribe an external calendar (e. g. from Google or Apple iCloud): tick External subscription in the edit page of the team calendar, enter the Calendar URL and choose an Update interval. The events of subscribed calendars are read-only. If the external calendar can’t be read for a long time (default: 90 days), the subscription is switched off automatically and a note is added to the description of the calendar.

3.11. Importing events

More > Import Events in the calendar (or the edit page of a team calendar) imports events from ics files:

  1. Choose the target calendar and drop or choose an .ics file. Files with multiple events are supported.

  2. Check the preview: new and modified events are marked.

  3. Commit the import.

Events are recognized by their unique id (UID): an event already present in the calendar is updated instead of being imported twice.

4. Leave

4.1. Application for leave

Under Common > Application for leave you apply for leave and see the leave applications of your team.

  • Choose the Start date and the End date. The first and last day may be half leave days (Half leave day at first day, Half leave day at last day). ProjectForge® shows the number of workdays and your available vacation days.

  • Choose your Manager who approves the application, and your Substitution (and optionally Other substitutes).

  • Tick Special leave for leave not counting against your leave account. Special leave is approved by the HR staff.

New applications get the status In progress. Your manager sets the status to Approved or Rejected. ProjectForge® remembers the manager and substitute you used last time.

The manager, the substitutes and you are notified by e-mail about new and changed applications (if a mail server is configured).

Rules

  • You can’t apply for more leave days than available (except special leave). Days left over from the previous year may be used until the configured date (by default 31st March).

  • Leave periods of the same employee must not overlap.

  • You may withdraw an application (status Rejected) or delete an approved one, as long as it hasn’t started yet.

  • Leave in the past can only be entered by the HR staff.

Conflicts

ProjectForge® warns you if there is at least one day on which none of your substitutes is available because they are on leave themselves. In this case choose other or further substitutes. The list of leave applications may be filtered by conflicts.

4.2. Leave account

Under Administration > Leave account (visible for employees with annual leave) you’ll find your leave statistics for the previous and the current year: annual leave, leave from the previous year, approved leave and leave in progress, special leave and your available leave days. Corrections by the HR staff are listed as Leave account entries (maintained under HR > Leave account entries).

The leave account also offers a subscription URL for the leave days of employees.

4.3. Automatic booking of vacation

ProjectForge® may book your approved leave (special leave included) automatically as time sheets every night, if your administrator configured the vacation structure element and cost unit and set Book vacation as time sheets (max. days back) to a value greater than 0 (under Administration > Configuration; default 0, i. e. switched off, at most 7):

  • Only past working days up to yesterday are booked, never in advance, and only days without any time sheet.

  • Each day is processed once: a run books the days since the last successful run, but at most the configured number of days back, so nights the job didn’t run are caught up. A vacation time sheet deleted by hand isn’t booked again.

  • The hours per day are derived from your weekly working hours (half leave days get half of the hours). The description is "Vacation".

  • Leave approved after its days have already been processed isn’t booked automatically. Use Book several days with Take over vacation instead.

The Monthly employee report shows working days and vacation days without time sheets separately.

5. HR

  • HR > Employees contains the employee data such as staff number, entry and leaving date and the values with a valid-since date: Annual leave days, Hours per week and Employee Status.

  • HR > Salaries contains the monthly salaries of the employees. They are used for the cost unit accounting.

  • Project management > HR planning gives an overview of the planned working hours of your employees in projects per week.

5.1. Import of salaries

Salaries may be imported from an Excel file (.xlsx or .xls) via Import of salaries. The following columns are required:

  • Abrechnungsmonat: month of the salary in the format yyyy/MM,

  • Pers.Nr. (or Personalnummer): staff number of the employee,

  • Gesamtkosten (or bruttoMitAgAnteil): gross salary including the employer’s share.

Rows with an unknown staff number are marked as faulty and are skipped.

6. Address book

6.1. Address books

Addresses are organized in address books (Common > Addressbooks). Each address book has an owner and may be shared with users and groups with Full access (read and write access to all addresses of this address book) or Read-only access. An address may belong to several address books. Addresses without an address book belong to the global address book.

6.2. Reverse search of phone numbers

ProjectForge® adds every phone number without any special characters and white spaces to the search index. You may enter any part of the phone number to find the address connected to this phone number (if exists).

Hint

Sometimes you may omit the country prefix of the phone number to find the address.

6.3. Personal favorites

Tick Favorite in the edit page of an address to mark it as one of your personal favorites. Your favorites are highlighted in the list (and may be filtered by my favorites).

Favorites are the base for exporting addresses to your personal address book (e. g. Apple contacts) and for synchronizing them with your mobile device:

  • Export vCards in the export menu of the address list downloads all your favorites as vCard file (vcf). A single address may be exported in its edit page via Export vCard.

  • CardDAV (if enabled by your administrator) synchronizes your favorites with your address book application. How to use CardDAV service in the export menu shows the server, path and credentials to use. Removing a contact in your address book application removes it from your favorites; contacts can’t be created or changed via CardDAV.

Hint

Please use UTF-8 as encoding in your address book software!

6.3.1. Hint for Apple contacts

Multiple exports of addresses may result in multiple note entries. The Apple script offered in the menu of the address list (Apple-Script) removes such multiple note entries:

1
2
3
4
5
6
7
8
9

tell application "Address Book"
repeat with thisPerson in every person
if (exists (note of thisPerson)) and ((note of thisPerson) contains "CLASS: WORK") then
log "Name: " & (name of thisPerson)
delete note of thisPerson
end if
end repeat
save
end tell

  1. You may execute this script directly in your Apple-Script editor. (The result 'missing value' is expected.)

  2. Afterwards you should import the ProjectForge® download (vCard) again.

6.4. Export of the list of addresses

You may export the currently displayed list of addresses as Excel file (Excel-Export). For reasons of data protection only your favorite addresses will be exported. Members of the groups PF_Finance or PF_Marketing are able to export all addresses of the list.

6.5. Direct call and text messages

If your company’s telephony system is connected (see Admin guide), you may initiate phone calls directly from ProjectForge® (Common > Direct call): enter the number or start typing a name or organization and choose the address. Phone numbers in the address list are linked to the direct call and enlarged when you move the mouse over them.

Please enter your personal phone ids (comma separated) under My account first.

If an SMS gateway is configured, you may send text messages via Common > Send SMS.

7. Structure elements in ProjectForge (former tasks)

The term 'structure element' is used in a generic way and represents customers, projects, releases, work packages etc. They’re organized hierarchically in the Structure tree (Project management > Structure tree). Access rights may depend on structure elements (and are derived from ancestor structure elements if configured). Time sheets are always booked on structure elements.

image

Figure 3:

Hierarchy of structure elements in ProjectForge®

The following table describes the fields of structure elements:

Field Description

Parent structure element

The structure element is a descendant structure element of the parent structure element. The structure element at the top of the hierarchy is the root node which is the only structure element without a parent structure element.

Title

Reference

Multi purpose field, optional. This field is derived for all descendant structure elements if not overwritten in such structure elements. This is useful for exports etc.

Status

Not opened, opened or closed. Closed structure elements aren’t bookable anymore.

Priority

Short description

Description

Maximum hours

If given, the consumption will be displayed in the structure tree as well as during the booking of a time sheet, see Consumption. If Maximum hours take priority is ticked, the maximum hours are used even if order positions are assigned.

Responsible user

ProjectForge® user for information.

Cost 2 list

All cost 2 values are project specific if a project was assigned to this structure element or any ancestor structure element. The black list defines cost 2 entries which should be excluded from the assigned project. If no project is assigned, cost 2 values are configurable by using a white list.

Time sheet booking

Inherit (default), opened, only leaf nodes, no booking or completely closed, see Booking of time sheets.

Protect time sheets until

If set, only time sheets with start dates after the given date may be inserted and updated, see Protection.

Protection of privacy

If checked, the time sheets of this structure element and any descendant structure elements are invisible for other users (except the members of the financial staff).

Shared cost element

If checked (inherited by all descendant structure elements), time sheets booked here may overlap in time with time sheets of other projects, see Shared cost element. Unlike the other fields of this section, it may be changed by everybody allowed to edit the structure element.

Gantt settings

Start and end date, duration, progress and predecessor for the Gantt chart (Project management > Gantt).

The fields of the section Finance administration (except Shared cost element) may only be changed by the financial staff (cost 2 list and booking status also by the project managers of the assigned project).

7.1. Consumption

Consumption bars are displayed as part of the structure tree as well as during every booking of time sheets. The tool tip shows the booked and the planned person days (1 person day = 8 hours) including all structure sub elements, the percentage and the period of the bookings. Click on a bar to see the booked time sheets.

The planned value is taken from the maximum hours of the structure element or, if order positions are assigned, from the ordered person days.

Consumption Display

No budget given

Booked person days only, no percentage.

0-80%

Green bar.

80%-90%

Yellow bar.

90%-100%

Dark yellow bar.

over 100%

The track of the bar turns red: the budget is exceeded.

For finished (closed) structure elements the bar stays green up to 100%; from 100% to 110% the bar shows a mild over-budget status (red track with a neutral bar), above 110% the normal over-budget status.

7.1.1. Suppressing the status of consumption bars

Enter 0 as maximum hours of a structure element for suppressing the status (planned value and percentage) of a consumption bar, even if order positions are assigned. This is useful for not demotivating a team or if not all orders with budgets are assigned to a structure element.

7.2. Booking of time sheets

Time sheets must be assigned to a structure element. For improving the quality of time sheets, ProjectForge® checks the following rules. If a rule isn’t met, the user can’t book his working time on such a structure element:

  1. The user needs access to this structure element or any ancestor structure element including the right of booking time sheets.

  2. The structure element and its ancestors must not be closed or deleted.

  3. The project of the structure element (the nearest assigned project in the structure tree) must not be ended or deleted.

  4. The structure element or any ancestor structure element may have a time sheet protection. The users aren’t able to modify or add time sheets for a day before the protection date.

  5. The booking status of the structure element (or of the nearest ancestor with a booking status other than 'inherit') must not be 'no booking', and no ancestor may be 'completely closed'.

  6. If the structure element is not a leaf element (has descendants), the booking status must not be 'only leaf nodes'.

  7. No descendant structure element may have an assigned order position. This rule is important, because otherwise ProjectForge® won’t be able to calculate the consumption of budgets defined by orders.

Further checks: a time sheet must have a duration (maximum 14 hours) and must not overlap with another time sheet of the same user, except for a shared cost element (see below).

7.2.1. Shared cost element

Time sheets of the same user may overlap in time, if at least one of the two is booked on a shared cost element and both don’t belong to the same project. A time sheet is booked on a shared cost element if its cost 2 unit has Shared costs set to yes. If the cost 2 unit leaves it empty (As structure element) or there is no cost 2 unit, the checkbox Shared cost element of the structure element (or of an ancestor) decides. A cost 2 unit set to no takes precedence: its time sheets don’t count as shared, even on a shared cost element.

Never allowed, shared or not, are overlaps:

  • on the same cost 2 unit, or on the same structure element if neither time sheet has a cost 2 unit,

  • within the same project,

  • within the same overlap group: the administrator may define groups of cost 2 units under Administration > Configuration (Time sheet overlap groups, e. g. 6 for all cost 2 units 6.*); each group counts like one project.

Overlapping time is counted pro rata in attendance, statistics and the monthly employee report: e. g. 1 hour on project A plus an overlapping hour on project B count 0.5 hours each. For the effort of a project (e. g. invoicing and project exports) every time sheet counts with its full duration.

If a structure element is protected, the user may still modify fields not affecting financial parameters (such as description and location but not times or cost units). The user may therefore correct typos etc. in time sheets.

8. Time sheets

Time sheets are booked in the calendar or under Project management > Time sheets.

8.1. Templates and recent entries

Above the edit form of a time sheet you’ll find your Templates and Recent entries. They fill in what you booked (structure element, cost unit, location, description etc.), not the time. Save time sheets you book often as named templates.

8.2. Protection

You may protect time sheets by date for structure elements (including all descendant structure elements). This protection ensures that no employee is able to modify time sheets with dates before the date where the protection ends (Protect time sheets until).
This is useful if the time sheets are invoiced or taken over by other accounting systems. Time sheets with dates before the date of protection may only be changed by members of the financial staff (regarding times and cost assignments).

8.3. Cost units

  • You may assign projects and/or cost 2 units to a structure element.

  • If a project is assigned, all existing cost 2 units of this project are automatically assigned to this structure element.

  • If there is no project or cost unit assigned to a structure element, all settings of the parent structure element are used. If no such setting is found for the parent element, the grandparent element is used and so on.

  • Only such cost units are used which have no status value or the status value 'active'.

If there is any cost 2 unit associated with a structure element (directly or derived), a user has to select a suitable cost unit while booking time sheets.

Hint

If you are missing cost units you may add them via the project edit page (with status 'active').
If you want to disable cost units you may change the status of such units to 'not active' or 'ended' or you may remove them by using the black or white list of the structure element.

8.4. Monthly employee report

The Monthly employee report (Project management > Monthly employee report) summarizes the time sheets of an employee for a month, as well as the working days and vacation days without time sheets. It is also available as PDF with fields for the signatures of the employee and the project leader.

8.5. My statistics

Project management > My statistics compares your booked hours with your target hours and shows how early you book your time sheets. Early booking of time sheets is essential for a successful project management!

8.6. JIRA support

JIRA issues are supported if configured by your administrator. If JIRA issue keys are contained in the activity report or reference of time sheets, they are displayed as links to the configured JIRA system.

8.7. Cost unit accounting

8.7.1. Fraction of working time

You may configure a fraction for single cost 2 units or cost 2 types (default is 1). Example: if the travelling time should be counted only as half regarding the employee’s working time, you may configure the fraction as 0.5. The monthly employee report takes this fraction into account.

9. Order book

Offers and orders may be managed in the Order book. They may be assigned to project managers having access to their orders and offers. Members of the administrative staff may have access to all orders if they have the right to do so (see user administration of ProjectForge®).

  • Orders contain positions (order type, payment type, person days, net sum, period of performance, structure element etc.) and an optional payment schedule.

  • Only the financial staff may mark positions and payment schedules as completely invoiced.

  • The export menu offers a Forecast of the filtered orders as Excel file. Further statistics such as forecast and contribution margin are available under Finance > Statistics (or Project management > Statistics for users without the finance menu).

9.1. E-mail notification

If you save an order, the contact persons and all users involved in the order (if they have access to it) may be notified by e-mail including a link to the order. Untick Send an e-mail notification? to suppress the notification.

10. Financial administration with ProjectForge®

10.1. Invoices

ProjectForge® supports the management of outgoing and incoming invoices (debitors and creditors):

  • Invoices may contain an unlimited number of positions.

  • If the cost module is configured, you may assign the amount of each position to one or an unlimited number of cost units.

  • Export invoice generates a Word document of a saved invoice based on your company’s invoice template.

10.1.1. Assignment of cost units

It’s recommended to try this feature for a better understanding.
You may assign positions of invoices to cost 1 and cost 2 units (Cost id assignments). An auto completion helps you to find the cost units very fast. You may enter numbers of cost units as well as text (e. g. the description, customer or type of a cost unit).
An unlimited number of assignments is supported. The amount may be given as amount or as percent value (e. g. 10%). ProjectForge® highlights positions whose amount isn’t completely assigned yet (Cost id assignment difference).

Positions and assignments already saved are marked as deleted first and may be restored until you save the invoice.

10.1.2. Clone and cancellation

You may clone existing invoices for a faster process of inserting new invoices:

  • The date is replaced by 'today', the due dates are recalculated from the payment terms.

  • The positions as well as any existing assignment to cost units are copied.

  • The invoice number is assigned when saving. Payment data and attachments aren’t copied.

Create cancellation prepares a cancellation invoice with negated amounts for an outgoing invoice. When saving, the original invoice gets the status canceled.

10.2. E-invoices (XRechnung and ZUGFeRD)

Outgoing invoices may be exported as electronic invoices (if your administrator configured the seller data):

  • Save and XRechnung saves the invoice, validates it and downloads it as XRechnung (XML).

  • Save and ZUGFeRD creates a ZUGFeRD invoice (PDF/A-3 with embedded XML, profile EN16931). The base PDF is the uploaded Invoice PDF or, if none is uploaded, the PDF generated from the Word template.

Missing data (e. g. the address of the customer or the bank account of the seller) is reported before the export. Fill in from account takes over the e-invoice data from the customer’s account.

The E-Invoice Checker (Finance > E-Invoice Checker) displays the content of any ZUGFeRD PDF or XRechnung XML file (seller, buyer, positions, amounts, attachments) and checks the most important mandatory fields. It’s not a replacement for a full official validation.

10.3. Incoming invoices

Incoming invoices may be imported from DATEV CSV exports (Upload of creditor invoices in the list of incoming invoices). The help text on the import page describes the expected DATEV exports. As in all imports of ProjectForge® you check the preview (new, modified, unmodified and faulty entries), select the entries and commit them.

Export bank transfers creates a SEPA transfer file (pain.001) for one or more incoming invoices.

10.4. Bank accounts

Under Finance > Bank accounts you manage your bank accounts and import their transactions from CSV files. The column mapping is configured per bank account (Settings for import of transactions). Transactions already imported are updated, not duplicated, so overlapping periods may be imported again.

10.5. Liquidity planning / forecast

Based on invoices and additional liquidity entries (others than invoices) ProjectForge® gives you the opportunity to manage your cash flow very easily including a forecast (Reporting > Liquidity).

10.5.1. Liquidity entries and series

Liquidity entries have a date of payment, an amount, a subject and a comment. They may be marked as paid automatically after the date of payment has passed.

Recurring payments such as rent or leasing rates are entered once as a series: tick Repeat this entry as a series, enter the interval (Every N months) and optionally the Number of installments (empty means endless).

  • The occurrences of a series are shown automatically, they aren’t stored.

  • If you open and save a single occurrence (e. g. to change its amount or to mark it as paid), or change or delete it by a mass update, it becomes an independent entry (Fixed) which doesn’t follow later changes of the series.

  • If you change a series, you choose whether the change applies to the whole series or from a given date on (Change from a date on). In the latter case earlier occurrences keep their values, and the interval can’t be changed (the continuation keeps the interval of the series).

10.5.2. Forecast

The Liquidity forecast shows the expected account balance for the next days (up to 600) based on a start amount. Choose a base date in the past to compare a former forecast with the actual development. Excel export downloads the forecast including all entries and invoices.

10.5.3. Calculation of expected dates of payments

ProjectForge® uses due dates for forecasting the cash flow and account balance. For invoices ProjectForge® additionally calculates the expected dates of payment based on the paid invoices of the last 12 months of the same:

  1. Project: Do paid invoices already exist for the same project?

  2. Customer number: Do paid invoices already exist for the same customer (grouped by the customer number)?

  3. Account: Do paid invoices already exist for the same account?

  4. Customer text: Do paid invoices already exist for the customer (full text)?

  5. Customer short text: Do paid invoices already exist for the customer (the beginning of the customer text will be used)?

If any paid invoice is found (starting with the project), the mean time of payment of these invoices (weighted by amount) is used for calculating the expected date of payment. The same is done for incoming invoices.

The liquidity planning is a plugin which is activated automatically when ProjectForge® is set up, refer to the Admin guide for managing plugins.

10.6. DATEV import

The accounts (chart of accounts) and the accounting records are imported from the Excel files your tax office provides (Reporting > Datev import). The original Excel file (.xlsx or .xls) may be uploaded unchanged; report sheets such as BWA, SuSa or USt are ignored.

The import page has two tabs:

  • Accounting records: The month sheets ("01", "02", …​, "12") contain the records of the booking month. If the file has no month sheet, the month is taken from the file name (e. g. 2026-07_…​). Records dated in a later month are assigned to the booking month but keep their real date. The calendar year is detected automatically from the dates of the records.

  • Chart of accounts: The sheet "Kontenplan" (also prefixed by the month, e. g. "07_Kontenplan") with the columns "Konto" and "Beschriftung". Only the account names are imported, existing accounts aren’t deleted.

Columns are recognized by their header names, their order doesn’t matter and additional columns are ignored. For the accounting records the following columns are used:

  • "Satz-Nr.", "Betrag", "SH", "Konto", "Gegenkonto", "Datum", "Beleg", "Text", "Menge",

  • "Kostenstelle/-träger" (or "Kst." or "Kost2") is interpreted as cost 2,

  • "Alt.-Kst." (or "Kost1") is interpreted as cost 1,

  • "Bemerkung" (or "Kommentar") is optional and may contain additional information or markers.

image

Figure 4:

Excel format for the DATEV import of accounting records

The import works in the same steps as all imports of ProjectForge®:

  1. Upload the file. Errors (e. g. an invalid number format) are shown with sheet, row and column.

  2. The preview shows the new, modified, unmodified and faulty records (for modified records the former value is shown as well) as well as the resulting business assessment (BWA).

  3. Select the records to take over (or Select all) and Commit them. You may repeat this step until all records are taken over.

Imported accounting records are listed under Reporting > Accounting records, including a business assessment (BWA) of the chosen period.

10.7. Reporting via Report objectives

Under Reporting > Report Objectives you upload (or paste) an XML file describing your report objectives, choose a period and create the report. The XML is kept until you log out. Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<ReportObjective title="Customer ACME" id="ACME" suppressOther="true" suppressDuplicates="true">
  <kost1-include>3.*</kost1-include>
  <kost1-exclude>*.01</kost1-exclude>
  <kost1-exclude>*.12</kost1-exclude>
  <kost2-include>5.*</kost2-include>
  <kost2-exclude>*.02</kost2-exclude>
  <kost2-exclude>*.11</kost2-exclude>
  <ReportObjective title="Project ACME-WEB-Portal" id="ACME-WEB-Portal">
    <kost2-include>5.020.01.*</kost2-include>
  </ReportObjective>
  <ReportObjective title="Project ACME-Java-Migration" id="ACME-Java-Migration">
    <kost2-include>5.020.02.*</kost2-include>
  </ReportObjective>
</ReportObjective>

  1. If an include list is empty, all records will match for this include list (wildcard).

  2. If an include list isn’t empty, at least one entry must match.

  3. For multiple include lists a record must match all include lists (logical 'and').

  4. If a record matches at least one entry of any exclude list, this record will be excluded.

The method String.matches(regExp) is used for evaluating the regular expressions. You may refer to the expression syntax of the Java class java.util.regex.Pattern for a better understanding. For your convenience ProjectForge® modifies the configured expressions automatically before usage: all points ('.') will be escaped and the wildcard character '' is replaced by '.'. You may suppress the automatic modification by prepending an apostrophe, e. g. "'^5\.510.*" will not be modified (only the apostrophe itself is removed before evaluation).
Examples:

  • "3.*" → "3\..*" (matches all strings beginning with "3.").

  • "*.02" → ".*\.02" (matches all strings ending with ".02").

  • "'^5.02.*" → "^5.02.*" (matches all strings starting with "5", any character and "02").

(This strategy of replacement is for convenience purposes because '.' normally means any character and '' means a multiple occurrence of the character before the asterisk: for example "3.1" will match "3x1111" but not "3.120.08.02".)

Hint

A child ReportObjective may only consist of entries of the parent ReportObjective (only a subset)!

The accounting records of each report objective may be opened directly from the report.

11. Scripting in ProjectForge®

You may edit, store and execute scripts in ProjectForge® (Reporting > List of scripts) for generating Excel files out of the database of ProjectForge® as well as charts etc. Scripts are written in Kotlin or Groovy. A script editor with syntax highlighting, the list of available variables and some examples are built in.

  • Scripts may define up to 6 parameters (e. g. numbers, texts, dates, time periods, structure elements or users), which are asked for before execution.

  • You may upload a file (e. g. an Excel master file) to a script for reading or modifying it.

  • Scripts may be shared with users and groups. They find them under Project management > List of my scripts and may execute them without seeing the source code.

11.1. Examples

You may use the predefined example scripts for getting an idea how powerful the scripting in ProjectForge® is.

11.1.1. Example: Easy Excel-file generation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// Simple Kotlin script
val users = userDao.list.filter { it.hasSystemAccess() }
val workbook = ExcelUtils.prepareWorkbook("Userlist.xlsx")
val sheet = workbook.createOrGetSheet("Users")
sheet.registerColumns(
  "Username|20", // Title Username is also property name, length = 20
  "Full name|fullname|30", // Title differs from property name
  "Email|30",
  "Id|10",
  "Description|50",
)
sheet.createRow().fillHeadRow()
users.forEach { user ->
  val row = sheet.createRow()
  ExcelUtils.autoFill(row, user)
}
sheet.setAutoFilter() // optional Excel auto filter
workbook

11.1.2. Example: Usage of ProjectForge® filters

1
2
3
4
5
6

val filter = TimesheetFilter()
filter.startTime = PFDateTime.withDate(2026, Month.JANUARY, 1).utilDate
filter.stopTime = PFDateTime.withDate(2026, Month.JUNE, 30).utilDate
val list = timesheetDao.select(filter)

"Number of found time sheets: ${list.size}"

PFDateTime and PFDay automatically use the time zone of the currently logged-in user as default.

11.2. Access rights (DAOs)

You may access all database entries by using the DAOs (Data Access Objects) of ProjectForge®. The DAOs ensure that only such entities are returned the user has access to. All entities without the user’s access are removed by the DAOs from the result lists.

11.3. Creation of diagrams and charts

You may create charts using JFreeChart.

image

Figure 5:

Example of a script producing a chart

 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import org.jfree.chart.*
import org.jfree.data.general.*
import org.projectforge.export.*

DefaultPieDataset dataset = new DefaultPieDataset()
dataset.setValue("Linux", 15)
dataset.setValue("Mac", 8)
dataset.setValue("Windows", 70)
dataset.setValue("Others", 7)
JFreeChart chart = ChartFactory.createPieChart("Operating systems of our users", dataset, true, true, false)

ExportJFreeChart export = new ExportJFreeChart(chart, 800, 600)
return export

11.4. Creation of zip archives containing multiple files

You may create zip files containing multiple files (Excel sheets and diagrams). Optionally the archive may be encrypted with a password.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// org.projectforge.business.scripting.ExportZipArchive and ExcelUtils are imported by default.
import org.projectforge.export.ExportJFreeChart

val zip = ExportZipArchive("my-first-archive") // File name will be: my-first-archive.zip
val workbook = ExcelUtils.prepareWorkbook("sheet.xlsx")
// ... fill the workbook, see above
zip.add("sheet.xlsx", workbook)
val chart = ExportJFreeChart(...)
zip.add("chart.png", chart)
zip

The optional parameter encryptionPassword (e. g. ExportZipArchive("my-first-archive", encryptionPassword = "…​")) encrypts the archive.

11.5. Nested and indexed properties

You may use bean properties using the commonly used notation:

1
2

sheet.propertyNames = ["user.username", "description", "startTime", "stopTime",
         "kost2.kost2Art.fakturiert"]

Nested and indexed properties are supported as well: users[3].name or result.userList[0].

11.6. Import of Excel files

Figure 6 shows an example file.

image

Figure 6:

Example file for an Excel import

The file uploaded to the script is available as variable file (byte array) and its name as filename. The Groovy example below reads it with ExportWorkbook, which supports the .xls format only.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

import java.text.*
import org.projectforge.business.excel.*
NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.UK)

ExportWorkbook workbook = new ExportWorkbook(file) // The file uploaded to this script.
ExportSheet sheet = workbook.getSheet("Sheet-1") // Gets sheet with the given title.
result = ""
total = 0.0

for (int i = 1; i < sheet.rows.size(); i++) {
  row = sheet.getRow(i)
  no = row.getCell(0).getNumericCellValue()
  name = row.getCell(1).getStringCellValue()
  amount = row.getCell(2).getNumericCellValue()
  total += amount
  result += (int)no + ". The amount of " + name + " is: " + nf.format(amount) + "\n"
}
result += "The total amount is: " + nf.format(total)
return result

The output is:

1
2
3
4
5

1. The amount of Susan is: £50.23
2. The amount of Hugo is: £17.00
3. The amount of Lisa is: £15.00
4. The amount of Mona is: £10.00
The total amount is: £92.23

12. Miscellaneous

12.1. Data transfer

Miscellaneous > Data transfer is the easy way to exchange files with colleagues and external partners:

  • Your personal box is meant for sending files to another single user. Files are deleted after 60 days.

  • Shared areas are accessible for the assigned admins, users and groups. Observers are notified by e-mail about uploads and external downloads.

  • A shared area may be enabled for external downloads and/or uploads: external partners get a link and a password (both may be renewed at any time).

  • Each area has an expiry period (e. g. 7 days) after which files are deleted automatically. You’ll be notified in advance of files being deleted (for longer expiry periods). The maximum file size is configured per area.

  • Download all downloads all files of an area as zip archive.

12.2. Further features

  • Polls (Miscellaneous > Polls): create polls with single choice, multiple choice and text questions, invite attendees and export the results.

  • Merlin Word® templates (Miscellaneous > Merlin Word® templates): generate Word documents such as contracts or letters from templates with variables, also as serial documents from an Excel sheet.

  • Licenses / Hardware (Miscellaneous > Licenses / Hardware): manage software licenses, keys and their usage.

  • Skill matrix (Project management): rate your own skills and interests and see the skills of your colleagues.

13. Data protection

13.1. Passwords

Passwords are stored only as salted and peppered hashes in the database. Directly after usage of passwords (such as in the login screen) all password variables are deleted. Passwords are not part of any log file entry.

13.2. History of changes

All modifications of entities (create, update, delete) are stored with time stamp, the user who caused the modification and the modified fields with the old and new value. The history of changes is displayed at the edit page of an entity. There are single special fields which are not part of this history mechanism.

13.3. Logging

Access violations and actions of users (such as modification of entities) as well as any error message are stored in log files. The log file is important for analyzing errors etc.

13.4. Phone calls and text messages

Phone calls and text messages initiated via ProjectForge® are logged, including the user and the phone numbers involved.

14. Glossary

The developers of ProjectForge® were using the German language for some financial terms. Nowadays English is the main language of the development (for classes, documentation etc.). Here you may find translations and descriptions of commonly used terms.

German English Description

Aufgabe

task

The term task was replaced by 'structure element' because such elements may represent not only tasks, they represent customers, projects, releases, tasks etc.

Auftrag

order

Beleg

receipt

Betrag

amount

Brutto

gross (amount)

Buchungssatz

accounting record

Accounting records are entities which are imported from external financial systems (e. g. DATEV in Germany). The recommended workflow is to organize invoices, salaries of the employees etc. with ProjectForge® and then to import the data in the external financial system. The re-imported accounting records should match the data in ProjectForge®.
ProjectForge® and the scripts also work if you don’t have accounting records, you may use the origin entities such as invoices etc. directly in your scripts.
The plural of accounting record is: Buchungssätze

BWA

business assessment

Term used inside the financial module of ProjectForge®.

DATEV

Software commonly used in Germany for financial administration. ProjectForge® offers import interfaces.

Datum

date

Eingangsrechnung

incoming invoice

Used for incoming invoices (creditors).

fakturiert

invoiced

Fibu

financial administration

Fibu is the abbreviation of the German term 'Finanzbuchhaltung'.

Gegenkonto

contra account

Term used inside the financial module of ProjectForge®.

Kontenplan

chart of accounts

Term used inside the financial module of ProjectForge®.

Konto

account

Term used inside the financial module of ProjectForge®.

Kost

cost

Term used inside the financial module of ProjectForge®. Kost1/Kost2 → cost 1/cost 2 is the short form of 'cost unit'.

Kostenträger

cost unit

Term used inside the financial module of ProjectForge®.

Kostenträgerart

type of cost unit

Term used inside the financial module of ProjectForge®. Examples for types of cost units are: 'Travelling', 'Acquisition', 'Meetings' etc. Types are customizable and used for specifying different types of costs in projects and/or company wide.

Kostenzuweisung

cost assignment

Term used inside the financial module of ProjectForge®. Costs, such as employee salaries, positions of invoices (incoming and outgoing) etc. are assigned to cost units.

Kunde

customer

Menge

quantity

Netto

net (amount)

Projekt

project

Rechnung

invoice

Used for outgoing invoices (debitors).

Sonderurlaub

special leave

Leave not counting against the leave account.

Urlaub

vacation, leave