5.8. Placeholders reference

This is a reference section that shows all the fields that can be used in an invoice template. These fields can be used to include information about:

  • your business

  • your client's business

  • the actual invoice content

Some fields contain an additional description to properly describe their meaning.

5.8.1. Business

The following table shows the fields that can be used to include information about your business in an invoice.

Table 5.4. Business Properties

Property Version Meaning

1. General

business.name 1.0 self-explained
business.code 2.3 A short code that identifies your business.
business.businessNumber 2.3 The number assigned to your business when it was created.
business.otherNumber 2.3 A number that could be used as the trade register number.
business.taxNumber 1.4 The tax number assigned by the government to your business. In many countries, businesses must include their VAT number on their invoices. In such cases, the tax number is the VAT number.

2. Taxes

business.taxLiable 1.5

Indicates whether the business pays taxes or not. A business pays taxes if they are enabled.

If you want to do something when the business pays taxes:

[#if business.taxLiable]
...
[/#if]

If you want to do something when the business doesn't pay taxes:

[#if !business.taxLiable]
...
[/#if]

3. Contact

business.attention 1.0 self-explained
business.address 1.0 self-explained
business.city 1.0 self-explained
business.state 1.0 self-explained
business.zip 1.0 self-explained
business.country 1.0 self-explained
business.phone 1.0 self-explained
business.fax 1.0 self-explained
business.mobile 2.1 self-explained
business.other 2.1 self-explained
business.email 1.0 self-explained
business.website 1.8 self-explained

5.8.2. Client

The following table shows the fields that can be used to include information about your client's business in an invoice.

Table 5.5. Client Properties

Property Version Meaning
1. General
client.name 1.0 The client name that is visible in the application.
client.code 1.5 The client code is especially useful if you want to number invoices automatically and to include the client code in the invoice number.
client.legalName 3.3 The legal name that can be displayed on invoices.
client.businessNumber 2.3 The number assigned to the business when it was created.
client.otherNumber 2.3 A number that could be used as the trade register number.
client.taxNumber 1.4 The tax number assigned by the government to your client's business. In many countries, invoices must include the client's VAT number. In such cases, the tax number is the VAT number.
client.invoices 2.0

A list with all the invoices of a client. This is useful if you want to create a statement. To access an invoice from the list use the following Freemarker code:

[#list client.invoices as invoice]
...
[/#list]
client.balance 2.0 How much money the client has to pay for all open (unpaid) invoices. Balance is the difference between the total of all invoices and the total of all payments.
client.deposits 3.1

A list with all the deposits of a client. To access a deposit from the list use the following Freemarker code:

[#list client.deposits as deposit]
...
[/#list]
client.depositsBalance 3.1 How much money the client has in its deposits account. The balance increases with each new deposit and decreases with each withdrawal.

2. Contact

client.attention 1.0 self-explained
client.address 1.0 self-explained
client.city 1.0 self-explained
client.state 1.0 self-explained
client.zip 1.0 self-explained
client.country 1.0 self-explained
client.phone 1.0 self-explained
client.fax 1.0 self-explained
client.mobile 2.1 self-explained
client.other 2.1 self-explained
client.email 1.0 self-explained
client.website 1.8 self-explained

5.8.3. Invoice

The following table shows the fields that can be used to include information about the actual invoice.

Table 5.6. Invoice Properties

Property Version Meaning
1. General
invoice.number 1.0 self-explained
invoice.reference 1.9, 2.1, 3.1

A reference number like the purchase order number.

Note: This field was known as contract.reference before version 3.1 and as contract.clientNumber before version 2.1

invoice.notes 2.0 self-explained
invoice.date 1.0 Use ${invoice.date?date} to access the value of the invoice date.
invoice.period 2.3 Indicates the date or period when the invoiced services were provided.
invoice.dueDate 1.5 Use ${invoice.dueDate?date} to access the date when an invoice is due.
invoice.dueDays 1.5 When the invoice must be paid (in days since the invoice date).
invoice.overdue 2.1.2 Indicates whether an invoice is overdue or not.
2. Payments
invoice.ageInDays 2.0 The number of days since an invoice was created until it was paid.
invoice.balance 2.0 How much money the client has to pay. Balance is the difference between the invoice total and payments total.
invoice.paymentsTotal 2.0 self-explained
invoice.payments 2.0

A list with all the payments of an invoice. To access a payment from the list use the following Freemarker code:

[#list invoice.payments as payment]
...
[/#list]
invoice.paid 2.0 Indicates whether an invoice is paid (completely) or not.
invoice.paymentDate 2.0 Use ${invoice.paymentDate?date} to access the value of the date when the invoice was paid completely.

3. Contents

The contents of an invoice may be accessed either by project or directly by referencing its items.

invoice.items 1.4, 2.0

A list with all the items of an invoice. To access an item from the list use the following Freemarker code:

[#list invoice.items as item]
...
[/#list]

Since version 2.0, this placeholder has a new meaning. The list contains all items, including products and expenses. Previously, it contained only services.

Instead of accessing the entire list of items, one can access the service items, the mileage items, the expense items and the product items separately using the invoice.serviceItems, invoice.expenseItems, invoice.mileageItems and invoice.productItems placeholders.

invoice.regularItems 3.0, 3.1

A list with all the regular (non-project) items of an invoice. If you don't invoice projects then ${invoice.regularItems} is the same as ${invoice.items}. To access an item from this list use the following Freemarker code:

[#list invoice.regularItems as item]
...
[/#list]

Note: invoice.regularItems replaces invoice.nonProjectItems which was used in version 3.0.

invoice.serviceItems 2.0, 2.7

A list with all the service items of an invoice. To access a service item from the list use the following Freemarker code:

[#list invoice.serviceItems as item]
...
[/#list]

Note: invoice.serviceItems replaces invoice.services which was used up until version 2.6.

invoice.expenseItems 1.4, 2.7

A list with all the expense items of an invoice. To access an expense item from the list use the following Freemarker code:

[#list invoice.expenseItems as item]
...
[/#list]

Note: invoice.expenseItems replaces invoice.expenses which was used up until version 2.6.

invoice.mileageItems 3.0

A list with all the mileage items of an invoice. To access a mileage item from the list use the following Freemarker code:

[#list invoice.mileageItems as item]
...
[/#list]
invoice.productItems 2.5, 2.7

A list with all the product items of an invoice. To access a product item from the list use the following Freemarker code:

[#list invoice.productItems as item]
...
[/#list]

Note: invoice.productItems replaces invoice.products which was used up until version 2.6.

invoice.projects 1.0

A list with all the projects whose items belong to this invoice. The list of projects is useful if you invoice multiple projects.

To access a project from the list use the following Freemarker code:

[#list invoice.projects as project]
...
[/#list]
4. Totals
invoice.serviceItemsSubtotal 2.0, 2.7

The total amount of money due for all the service items from the invoice.

Note: invoice.serviceItemsSubtotal replaces invoice.servicesSubtotal which was used up until version 2.6.

invoice.expenseItemsSubtotal 1.0, 2.7

The total amount of money due for all the expense items from the invoice.

Note: invoice.expenseItemsSubtotal replaces invoice.expensesSubtotal which was used up until version 2.6.

invoice.mileageItemsSubtotal 3.0

The total amount of money due for all the mileage items from the invoice.

invoice.productItemsSubtotal 2.5, 2.7

The total amount of money due for all the product items from the invoice.

Note: invoice.productItemsSubtotal replaces invoice.productsSubtotal which was used up until version 2.6.

invoice.total 1.0 The total amount of money (no taxes included).
invoice.grandTotal 1.4 The total amount of money (all taxes included).
invoice.profit 3.1 The invoice profit is calculated as the difference between the invoice total and the total amount of all invoice expenses.
invoice.exchangeRates 2.0

A list with all the exchange rates of an invoice if it uses multiple currencies. To access exchange rates from the list use the following Freemarker code:

[#list invoice.exchangeRates as exchangeRate]
...
${exchangeRate.source}
${exchangeRate.target}
${exchangeRate.rate}
...
[/#list]
5. Taxes
invoice.taxable 1.8

Indicates whether the invoice has taxes or not. If you want to do something when the invoice has taxes:

[#if invoice.taxable]
...
[/#if]

If you want to do something when the invoice doesn't have taxes:

[#if !invoice.taxable]
...
[/#if]
invoice.taxes 1.4

A list with all the taxes of an invoice. To access a tax from the list use the following Freemarker code:

[#list invoice.taxes as tax]
...
[/#list]
invoice.getTaxTotal(tax) 1.4, 3.3

This is a function that gives you the total amount for a certain tax.

The most common situation when this function is used is at the end of the invoice to display the total for each tax of the invoice. If the invoice has more than one tax.

Note: invoice.getTaxTotal replaces invoice.taxTotal which was used up until version 3.2.

invoice.taxesTotal 1.4 The taxes due for the invoice.
6. Discounts
invoice.regularTotal 1.8

If the total of an invoice is discounted, this field indicates the total before the discount. You may want to use this field like this:

[#if item.totalDiscounted]
    ${item.regularTotal}
[/#if]

The regular total is accessed only when the total is discounted.

invoice.rawTotal 1.8

If an invoice has discounts for both its items and its total value, this field represents the value of the invoice without any discount.

It's how much you would make if no discount is applied.

invoice.totalDiscount 1.8 If the total value of an invoice is discounted, this field indicates the discount. It can be used to display the actual discount.
invoice.totalDiscounted 1.8 Indicates if the total of an invoice is discounted. See the item.regularPrice field above.
7. Time
invoice.billableTimeAsHour 1.5, 3.1, 3.3

The total invoiced time in hour format. For instance 1 hour and 30 minutes is represented as 1:30.

Note: invoice.billedTimeAsHour was used instead of invoice.billableTimeAsHour in versions 3.1 and 3.2.

invoice.billableTimeAsDecimal 1.5, 3.1, 3.3

The total invoiced time in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.

Note: invoice.billedTimeAsDecimal was used instead of invoice.billableTimeAsDecimal in versions 3.1 and 3.2.

8. Time Reporting

The following placeholders are useful if you need to create invoice templates that group time entries by date.

These placeholders are used by the invoice template editor (File » Template Editor) if time is displayed and time entris are grouped by date. It uses ${invoice.groupDatesByDate(item.timeEntries)} to determine the dates when time was recorded for a service item.

invoice.timeEntries 3.1

A list with all the time entries that belong to the service items of an invoice.

This list is useful if you want to determine the dates when the invoiced time was recorded (see invoice.groupDatesByDate).

If you need to access the date of the first and last time entry, you can use the following expressions:

  • ${invoice.timeEntries?sort_by("date")?first.date?date} for the first date

  • ${invoice.timeEntries?sort_by("date")?last.date?date} for the last date

invoice.groupDatesByDate(timeEntries) 3.1

A list with the dates when the specified time entries were recorded.

[#list invoice.groupDatesByDate(invoice.timeEntries)?sort as date]
...
[/#list]

Use ${date.toDate()?date} to print each date and ${date.toInterval()} to create an interval for a date.

invoice.filterByDate(timeEntries, interval) 3.1 Finds the subset of the specified time entries that were recorded in the specified interval. (their Date field belongs to the interval)
invoice.calculateBillableTimeAsHour(timeEntries) 3.1, 3.3

The total billable time in hour format for the specified list of time entries.

Note: invoice.calculateRoundedElapsedTimeAsHour was used instead of invoice.calculateBillableTimeAsHour in versions 3.1 and 3.2.

invoice.calculateBillableTimeAsDecimal(timeEntries) 3.1, 3.3

The total billable time in decimal format for the specified list of time entries.

Note: invoice.calculateRoundedElapsedTimeAsDecimal was used instead of invoice.calculateBillableTimeAsDecimal in versions 3.1 and 3.2.

invoice.calculateElapsedTimeAsHour(timeEntries) 3.1 The total elapsed time in hour format for the specified list of time entries.
invoice.calculateElapsedTimeAsDecimal(timeEntries) 3.1 The total elapsed time in decimal format for the specified list of time entries.

5.8.4. Item

The following table shows the fields of an item from an invoice. An item cannot be accessed directly. You can either access it from the list of items of an invoice (invoice.items or invoice.serviceItems, invoice.productItems and invoice.expenseItems) or from the list of items of an invoice project (project.items or project.serviceItems, project.productItems and project.expenseItems).

Table 5.7. Item Properties

Property Version Meaning

1. General

The general fields are used to describe an item.

item.name 1.0 self-explained
item.description 1.0 self-explained
item.date 2.0, 3.0

This placeholder is deprecated starting with version 3.0. Items don't actually have a date field.

  • for service items

    • with at least one time entry, the date represents the date of the oldest time entry

    • with no time entries, the date represents the start date of the task

  • for expense items the date represents the date when the expense was made

  • for mileage items the date represents the invoice date

  • for product items the date represents the date when the product was made

Use ${item.date?date} to access the value of the item date.

item.catalogItem 1.0, 2.0, 2.5

self-explained

${item.catalogItem!"-"}

Note: item.catalogItem replaces item.itemCategory (introduced in version 2.0) and item.service (used before version 2.0).

item.regularItem 3.1

Indicates whether this item is a regular item or not. All items that are added directly to an invoice (i.e. they don't invoice a project) are regular items. The following code prints a plus character if the item is a regular item.

[#if item.regularItem]
    +
[/#if]

To access the regular items of an invoice, see the invoice.regularItems placeholder.

item.serviceItem 2.0, 2.7

Indicates whether this item is a service item or not. The following code prints a plus character if the item is a service item.

[#if item.serviceItem]
    +
[/#if]

To access the list of service item of an invoice project see the project.serviceItems placeholder. For an invoice, see invoice.serviceItems.

Note: item.serviceItem replaces item.service (used before version 2.7).

item.expenseItem 2.0, 2.7

Indicates whether this item is an expense item or not. The following code prints a plus character if the item is an expense item.

[#if item.expenseItem]
    +
[/#if]

To access the list of expense items of a project see the project.expenseItems placeholder. For an invoice, see invoice.expenseItems.

Note: item.expenseItem replaces item.expense (used before version 2.7).

item.mileageItem 3.0

Indicates whether this item is a mileage item or not. The following code prints a plus character if the item is a mileage item.

[#if item.mileageItem]
    +
[/#if]

To access the list of mileage items of a project see the project.mileageItems placeholder. For an invoice, see invoice.mileageItems.

item.productItem 2.5, 2.7

Indicates whether this item is a product item or not. The following code prints a plus character if the item is a product item.

[#if item.productItem]
    +
[/#if]

To access the list of product items of a project see the project.productItems placeholder. For an invoice, see invoice.productItems.

Note: item.productItem replaces item.product (used before version 2.7).

2. Billing

The billing fields are used to show billing information (price, quantity, total) about the item. If an item is discounted, you may also want to use the fields that show the regular (before any discount is applied) values.

More information about discounts and when they are available is provided in the discount section below.

item.taxable 2.0, 3.3

Indicates whether this item is taxable or not. The following code prints a plus character if the item is non-taxable.

[#if !item.taxable]
    +
[/#if]

Note: item.taxable replaces item.taxExempt which was used up until version 3.3.

item.price 1.0, 2.0

The price used to bill the item. If the item is discounted, it indicates the price after the discount.

Note: item.price replaces item.rate which was used up until version 1.11.

item.quantity 1.0, 2.0

The quantity used to bill the item. If the item is discounted, it indicates the quantity after the discount.

If the item is billed in hours, this field indicates the number of hours in decimal format. Otherwise it indicates the number of units.

Note: item.quantity replaces item.units which was used up until version 1.11.

item.quantityType 2.0

Indicates whether a service item is billed in units or hours. Expense and product items are always billed in units.

[#if item.quantityType.id == 0]
    units
[/#if]

[#if item.quantityType.id == 1]
    hours
[/#if]
item.unitOfMeasure 2.3 self-explained
item.total 1.0, 2.0

The amount of money that is charged for the item. If the item is discounted, it indicates the amount after all discounts.

Note: item.total replaces item.amount which was used up until version 1.11.

item.regularPrice 1.8, 2.0

If the price of an item is discounted, this field indicates the price before the discount. You may want to use this field like this:

[#if item.priceDiscounted]
    ${item.regularPrice}
[/#if]

The regular price is accessed only when the price is discounted.

Note: item.regularPrice replaces item.regularRate which was used up until version 1.11.

item.regularQuantity 1.8, 2.0

If the quantity of an item is discounted, this field indicates the quantity before the discount. You may want to use this field like this:

[#if item.quantityDiscounted]
    ${item.regularQuantity}
[/#if]

The regular quantity is accessed only when it is discounted.

Note: item.regularQuantity replaces item.regularUnits which was used up until version 1.11.

item.regularTotal 1.8, 2.0

If an item is discounted, this field indicates the total amount for the item before any discount is applied to it. You may want to use this field like this:

[#if item.discounted]
    ${item.regularTotal}
[/#if]

The regular total is accessed only when it is discounted.

Note: item.regularTotal replaces item.regularAmount which was used up until version 1.11.

3. Discount

The discount fields can be used to determine the discounts for the price or quantity of an item. There are also a few fields that can be used to determine if a discount has been applied to an item or not.

item.priceDiscount 1.8, 2.0

If an item is discounted by price, this field indicates the discount. It can be used to display the actual discount.

Note: item.priceDiscount replaces item.rateDiscount which was used up until version 1.11.

item.quantityDiscount 1.8, 2.0

If an item is discounted by quantity, this field indicates the discount. It can be used to display the actual discount.

Note: item.quantityDiscount replaces item.unitsDiscount which was used up until version 1.11.

item.priceDiscounted 1.8, 2.0

Indicates if the price of an item is discounted. See the item.regularPrice field above.

Note: item.priceDiscounted replaces item.rateDiscounted which was used up until version 1.11.

item.quantityDiscounted 1.8, 2.0

Indicates if the quantity of an item is discounted. See the item.regularQuantity field above.

Note: item.quantityDiscounted replaces item.unitsDiscounted which was used up until version 1.11.

item.discounted 1.8

Indicates if an item is discounted (either by rate or number of units). See the item.regularAmount field above.

4. Time

The time fields can be used to get more detailed information about the time recorded for a service item.

item.timeEntries 1.5

A list with all the time entries recorded for a service item. This list is useful if you want to create a very detailed invoice that shows a breakdown for each invoiced item.

To access a time entry from the list use the following Freemarker code:

[#list item.timeEntries as timeEntry]
...
[/#list]
item.elapsedTimeAsHour 1.5 The total time recorded for a service item in hour format. For instance 1 hour and 30 minutes is represented as 1:30.
item.elapsedTimeAsDecimal 1.5 The total time recorded for a service item in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.
item.billableTimeAsHour 1.5, 3.1, 3.3

The total billable time of a service item in hour format. For instance 1 hour and 30 minutes is represented as 1:30.

Note: item.billedTimeAsHour was used instead of item.billableTimeAsHour in versions 3.1 and 3.2.

item.billableTimeAsDecimal 1.5, 3.1, 3.3

The total billable time of a service item in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.

Note: item.billedTimeAsDecimal was used instead of item.billableTimeAsDecimal in versions 3.1 and 3.2.

5. Trips

The trip fields can be used to get more detailed information about the trips recorded for a mileage item.

item.trips 3.0

A list with all the trips recorded for a mileage item. This list is useful if you want to create a very detailed invoice that shows a breakdown for each invoiced item.

To access a trip from the list use the following Freemarker code:

[#list item.trips as trip]
...
[/#list]

5.8.5. Payment

The following table shows the fields of a payment made to an invoice. A payment cannot be accessed directly. You can only access it from the list of payments of an invoice (invoice.payments).

Table 5.8. Payment Properties

Property Version Meaning
payment.date 2.0 self-explained
payment.notes 2.0 self-explained
payment.amount 2.0 self-explained
payment.reference 2.0 self-explained


5.8.6. Deposit

The following table shows the fields of a deposit transaction. A deposit cannot be accessed directly. You can only access it from the list of deposits of a client (client.deposits).

Table 5.9. Deposit Properties

Property Version Meaning
deposit.date 3.1 self-explained
deposit.notes 3.1 self-explained
deposit.amount 3.1 The amount deposited in or withdrawn from the deposits account. Positive amounts are deposited while negative amounts are withdrawn.
deposit.reference 3.1 self-explained
deposit.invoiceDeposit 3.1

Indicates whether this deposit was used to pay an invoice. The following code prints the number of the invoice paid by this deposit.

[#if deposit.invoiceDeposit]
    ${deposit.invoiceNumber}
[/#if]

To access the list of deposits of a client see the client.deposits placeholder.

deposit.invoiceNumber 3.1 See deposit.invoiceDeposit.


5.8.7. Tax

The following table shows the fields of a tax from an invoice. A tax cannot be accessed directly. You can only access it from the list of taxes of an invoice (invoice.taxes).

Table 5.10. Tax Properties

Property Version Meaning
tax.name 1.4 self-explained

5.8.8. Invoice Project

The following table shows the fields of an invoice project. A project cannot be accessed directly. You have to access it from the list of projects of an invoice (invoice.projects).

Usually, you don't need to work with invoice projects. They are useful only if the invoice is for multiple projects.

Table 5.11. Project Properties

Property Version Meaning

1. General

project.name 1.0 self-explained
project.number 2.6 self-explained
project.reference 2.6 self-explained
project.description 2.5 self-explained
project.notes 1.8 self-explained
project.location 3.3 self-explained
project.startDate 3.3 self-explained
project.dueDate 3.3 self-explained
project.finishedDate 3.3 self-explained

2. Contents

An invoice project contains items that can be service, expense, mileage or product items. The following fields let you access them.

project.items 1.0, 2.0

A list with all the items of an invoice project. To access an item from the list use the following Freemarker code:

[#list project.items as item]
...
[/#list]

Since version 2.0, this placeholder has a new meaning. The list contains all items, including expense items. Previously, it contained only services.

Instead of accessing the entire list of items, one can access the services and the expenses separately using the project.serviceItems, project.productItems and the project.expenseItems placeholders.

project.serviceItems 2.0, 2.7

A list with all the service items of an invoice project. To access a service item from the list use the following Freemarker code:

[#list project.serviceItems as item]
...
[/#list]

Note: project.serviceItems replaces project.services which was used up until version 2.6.

project.expenseItems 1.0, 2.7

A list with all the expense items of an invoice project. To access an expense item from the list use the following Freemarker code:

[#list project.expenseItems as item]
...
[/#list]

Note: project.expenseItems replaces project.expenses which was used up until version 2.6.

project.mileageItems 3.0

A list with all the mileage items of an invoice project. To access a mileage item from the list use the following Freemarker code:

[#list project.mileageItems as item]
...
[/#list]
project.productItems 2.5, 2.7

A list with all the product items of an invoice project. To access a product item from the list use the following Freemarker code:

[#list project.productItems as item]
...
[/#list]

Note: project.productItems replaces project.products which was used up until version 2.6.

3. Totals

project.serviceItemsSubtotal 2.0, 2.7

The total amount of money due for all the service items from this project.

Note: project.serviceItemsSubtotal replaces project.servicesSubtotal which was used up until version 2.6.

project.expenseItemsSubtotal 1.0, 2.7

The total amount of money due for all the expense items from this project.

Note: project.expenseItemsSubtotal replaces project.expensesSubtotal which was used up until version 2.6.

project.mileageItemsSubtotal 3.0

The total amount of money due for all the mileage items from this project.

project.productItemsSubtotal 2.5, 2.7

The total amount of money due for all the product items from this project.

Note: project.productItemsSubtotal replaces project.productsSubtotal which was used up until version 2.6.

project.total 1.0 The total project amount of money (no taxes included).

4. Time

project.billableTimeAsHour 1.5, 3.1, 3.3

The total time invoiced for a project in hour format. For instance 1 hour and 30 minutes is represented as 1:30.

Note: project.billedTimeAsHour was used instead of project.billableTimeAsHour in versions 3.1 and 3.2.

project.billableTimeAsDecimal 1.5, 3.1, 3.3

The total time invoiced for a project in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.

Note: project.billedTimeAsDecimal was used instead of project.billableTimeAsDecimal in versions 3.1 and 3.2.


5.8.9. Time Entry

The following table shows the fields of a time entry. A time entry cannot be accessed directly. You have to access it from the list of time entries of a project item (item.timeEntries).

Usually, you don't need to work with time entries. They are useful only if you need to create a very detailed invoice that breaks down the time spent on each item.

Table 5.12. Time Entry Properties

Property Version Meaning
timeEntry.date 1.5 Use ${timeEntry.date?time} to access the exact time when time has been recorded for the item.
timeEntry.endDate 1.5 Use ${timeEntry.endDate?time} to access the exact time recording has stopped.
timeEntry.description 1.5 self-explained
timeEntry.elapsedTimeAsHour 1.5 The total recorded time in hour format. For instance 1 hour and 30 minutes is represented as 1:30.
timeEntry.elapsedTimeAsDecimal 1.5 The total recorded time in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.
timeEntry.pausedTimeAsHour 1.8 The pause associated with this time entry in hour format. For instance 1 hour and 30 minutes is represented as 1:30.
timeEntry.pausedTimeAsDecimal 1.8 The pause associated with this time entry in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.
timeEntry.billableTimeAsHour 3.1, 3.3

The total billable time in hour format. For instance 1 hour and 30 minutes is represented as 1:30.

Note: timeEntry.billableTimeAsHour replaces timeEntry.roundedElapsedTimeAsHour which was used up until version 3.2.

timeEntry.billableTimeAsDecimal 3.1, 3.3

The total billable time recorded in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.

Note: timeEntry.billableTimeAsDecimal replaces timeEntry.roundedElapsedTimeAsDecimal which was used up until version 3.2.

timeEntry.units 3.3

self-explained

Here's how to use it in order to display the number of units as an integer:

${timeEntry.units?string.number}
timeEntry.unitsPerHour 3.3

self-explained

The calculated value can be null if the time is zero (00:00:00). The following example shows the best way to use this placeholder:

${timeEntry.unitsPerHour!"N/A"}
timeEntry.timePerUnitAsHour 3.3

self-explained

The calculated value can be null if the number of units is zero. The following example shows the best way to use this placeholder:

${timeEntry.timePerUnitAsHour!"N/A"}
timeEntry.total 3.3 The total value of a time entry. Billable time entries recorded on tasks billed in hours have a non-zero value while non-billable time entries or time entries recorded on tasks billed in units have a zero value.

5.8.10. Task

The following table shows the fields of a task. A task cannot be accessed directly. You have to access it from a project service item (item.task).

Usually, you don't need to work with tasks. They are useful only if you need to create a very detailed invoice that includes details not available in a service item (eg the task reference number).

Table 5.13. Task Properties

Property Version Meaning

1. General

task.name 3.0

self-explained

task.reference 3.0 self-explained
task.category 3.0 self-explained
task.description 3.0

self-explained

task.notes 3.0

self-explained

task.tags 3.0

self-explained

2. Planning

task.startDate 3.0 self-explained
task.dueDate 3.0 self-explained
task.completedDate 3.0 self-explained
task.completed 3.0

Indicates whether the task is completed or not. If you want to do something when the task is completed:

[#if task.completed]
...
[/#if]

If you want to do something when the task isn't completed:

[#if !task.completed]
...
[/#if]
task.overdue 3.0

Indicates whether the task is overdue or not. If you want to do something when the task is overdue:

[#if task.overdue]
...
[/#if]

If you want to do something when the task isn't overdue:

[#if !task.overdue]
...
[/#if]

3. Time tracking

task.timeEntries 3.0

A list with all the time entries of a task. To access a time entry from the list use the following Freemarker code:

[#list task.timeEntries as timeEntry]
...
[/#list]
task.elapsedTimeAsHour 3.0 The total time recorded in hour format. For instance 1 hour and 30 minutes is represented as 1:30.
task.estimatedTimeAsHour 3.0 The total estimated time in hour format. For instance 1 hour and 30 minutes is represented as 1:30.
task.remainingTimeAsHour 3.0 The total remaining time in hour format. For instance 1 hour and 30 minutes is represented as 1:30.

5.8.11. Expense

The following table shows the fields of an expense. An expense cannot be accessed directly. You have to access it from a project expense item (item.expense).

Usually, you don't need to work with expenses. They are useful only if you need to create a very detailed invoice that includes details not available in an expense item (eg the expense reference number).

Table 5.14. Expense Properties

Property Version Meaning
expense.reference 3.0 self-explained
expense.category 3.0 self-explained
expense.description 3.0

self-explained

expense.notes 3.0

self-explained

expense.date 3.0 self-explained
expense.amount 3.0 self-explained
expense.taxAmountsBag 3.3 self-explained

5.8.12. Trip

The following table shows the fields of a trip. A trip cannot be accessed directly. You have to access it from the list of trips of a project item (item.trips).

Usually, you don't need to work with trips. They are useful only if you need to create a very detailed invoice that shows all the trips of each mileage item.

Table 5.15. Trip Properties

Property Version Meaning
trip.startTime 3.0

Use ${trip.startTime?time} to access the time when the trip started.

If you are only interested in the date, use ${trip.startTime?date}.

trip.endTime 3.0

Use ${trip.endTime?time} to access the time when the trip ended.

trip.durationAsHour 3.0 The duration of the trip in hour format. For instance 1 hour and 30 minutes is represented as 1:30.
trip.durationAsDecimal 3.0 The duration of the trip in decimal format. For instance 1 hour and 30 minutes is represented as 1.50.
trip.distance 3.0

The distance recorded by the trip. ${trip.distance} represents distance as value followed by unit (eg 30 km).

If you need to access each field separately then you should use ${trip.distance.value} and ${trip.distance.unit}.

trip.startLocation 3.0

self-explained

trip.endLocation 3.0

self-explained

trip.description 3.0 self-explained
trip.tags 3.0

self-explained


5.8.13. Projects Report

The following table shows the placeholders that can be used to create projects reports. Besides these placeholders you can also use business placeholders to print information about your business in a projects report.

Table 5.16. Projects Report Properties

Property Version Meaning

1. Parameters

The date interval used to build the report can be accessed from the template.

Each interval may or may not have a start date and an end date. If a date interval is defined only by its start date then the end date will not be defined and projectsreport.dateIntervalEnd?? will return false. The folowing code can be used to cover all situations, whether these fields are defined or not.

	[#if projectsreport.dateIntervalStart??]
		[#if projectsreport.dateIntervalEnd??]
	${projectsreport.dateIntervalStart?date} - ${projectsreport.dateIntervalEnd?date}
		[#else]
	After ${projectsreport.dateIntervalStart?date}
		[/#if]
	[#else]
		[#if projectsreport.dateIntervalEnd??]
	Before ${projectsreport.dateIntervalEnd?date}
		[#else]
	All dates
		[/#if]
	[/#if]
projectsreport.dateIntervalStart 3.1

self-explained

projectsreport.dateIntervalEnd 3.1

self-explained

2. Projects

The report allows you to obtain a list with all its projects and project elements (tasks, expenses, trips and products).

projectsreport.projects 3.1

A list with all the projects included in the report. This is probably most important placeholder because almost all reports need to use it.

projectsreport.getTimeEntries(task) 3.1 A list with all the time entries of a task that belong to the reporting period.
projectsreport.getTasks(project) 3.1 A list with all the tasks of a project that belong to the reporting period.
projectsreport.getTrips(project) 3.1 A list with all the trips of a project that belong to the reporting period.
projectsreport.getExpenses(project) 3.1 A list with all the expenses of a project that belong to the reporting period.
projectsreport.getProducts(project) 3.1 A list with all the products of a project that belong to the reporting period.
projectsreport.filterWithActivity(projects) 3.1

Finds the subset of the specified projects that have elements (tasks, time, expenses, trips or products) in the reporting period.

This filter is useful if you don't want to deal with projects that were active during the reporting period but nothing was recorded on them.

projectsreport.filterByClient(projects, client) 3.1

Finds the subset of the specified projects that belong to the specified client.

3. Grouping

Fields like clients can be extracted as separate groups from a list of projects.

projectsreport.groupClients(projects) 3.1

A list with all the clients.

[#list projectssreport.groupClients(projectsreport.projects)?sort as client]
...
[/#list]

4. Totals

The report can calculate totals for a list of projects. The list of projects can either be projectsreport.projects (all the projects included in the report) or a partial list determined by one of the filter functions.

projectsreport.calculateTaskTotal(task) 3.1 The total for the specified task.
projectsreport.calculateElapsedTimeAsHour(task) 3.1 The total elapsed time in hour format for the specified task.
projectsreport.calculateElapsedTimeAsHour(project) 3.1 The total elapsed time in hour format for the specified project.
projectsreport.calculateElapsedTimeAsHour(projects) 3.1 The total elapsed time in hour format for the specified list of projects.
projectsreport.calculateBillableTimeAsDecimal(task) 3.3 The total billable time in decimal format for the specified task.
projectsreport.calculateBillableTimeAsDecimal(project) 3.3 The total billable time in decimal format for the specified project.
projectsreport.calculateBillableTimeAsDecimal(projects) 3.3 The total billable time in decimal format for the specified list of projects.
projectsreport.calculateExpensesAmount(project) 3.1

The total expenses amount for the specified project.

projectsreport.calculateExpensesAmount(projects) 3.1 The total expenses amount for the specified list of projects.
projectsreport.calculateTripsDistance(project) 3.1

The total distance for the specified project.

projectsreport.calculateTripsDistance(projects) 3.1 The total distance for the specified list of projects.
projectsreport.calculateTotal(project) 3.1

The total for the specified project.

projectsreport.calculateTotal(projects) 3.1 The total for the specified list of projects.
projectsreport.calculateTasksTotal(project) 3.1

The tasks subtotal for the specified project.

projectsreport.calculateExpensesTotal(project) 3.1

The expenses subtotal for the specified project.

projectsreport.calculateTripsTotal(project) 3.1

The trips subtotal for the specified project.

projectsreport.calculateProductsTotal(project) 3.1

The products subtotal for the specified project.


5.8.14. Time Report

The following table shows the placeholders that can be used to create time reports. Besides these placeholders you can also use business placeholders to print information about your business in a time report.

Here's an example that shows how to calculate totals by date. It groups time entries by date and then it calculates the total elapsed time for each date.

[!-- Determine the dates when time was recorded. --]
[#assign dates=timereport.groupDatesByDate(timereport.timeEntries)]

[#list dates?sort as date]

  [!-- Use timereport.filterByDate to find time entries recorded on a specific date. --]
  [#assign dateTimeEntries=timereport.filterByDate(timereport.timeEntries, date.toInterval())]

  [!-- Print the date and the total elapsed time for this date. --]
  ${date.toDate()?date}: ${timereport.calculateElapsedTimeAsHour(dateTimeEntries)}

[/#list]

[!-- Calculate the total elapsed time for all the time entries included in the report --]
Total: ${timereport.calculateElapsedTimeAsHour(timereport.timeEntries)}

Table 5.17. Time Report Properties

Property Version Meaning

1. Parameters

The date interval used to build the report can be accessed from the template.

Each interval may or may not have a start date and an end date. If a date interval is defined only by its start date then the end date will not be defined and timereport.dateIntervalEnd?? will return false. The folowing code can be used to cover all situations, whether these fields are defined or not.

	[#if timereport.dateIntervalStart??]
		[#if timereport.dateIntervalEnd??]
	${timereport.dateIntervalStart?date} - ${timereport.dateIntervalEnd?date}
		[#else]
	After ${timereport.dateIntervalStart?date}
		[/#if]
	[#else]
		[#if timereport.dateIntervalEnd??]
	Before ${timereport.dateIntervalEnd?date}
		[#else]
	All dates
		[/#if]
	[/#if]
timereport.dateIntervalStart 3.0

self-explained

timereport.dateIntervalEnd 3.0

self-explained

2. Time entries

The report allows you to obtain a list with all its time entries or partial lists (for instance time entries that were recorded in a certain month).

timereport.timeEntries 3.0

A list with all the time entries included in the report. This is probably most important placeholder because almost all reports need to use it.

timereport.filterByDate(timeEntries, interval) 3.0 Finds the subset of the specified time entries that were recorded in the specified interval. (their Date field belongs to the interval)
timereport.filterByTask(timeEntries, task) 3.0

Finds the subset of the specified time entries that belong to the specified task.

timereport.filterByTaskCategory(timeEntries, taskCategory) 3.2

Finds the subset of the specified time entries recorded on tasks that have the specified task category.

timereport.filterByTaskCategoryNone(timeEntries) 3.2

Finds the subset of the specified time entries recorded on tasks that don't have a task category.

timereport.filterByProject(timeEntries, project) 3.0

Finds the subset of the specified time entries that belong to the specified project.

timereport.filterByClient(timeEntries, client) 3.0

Finds the subset of the specified time entries that belong to the specified client.

3. Grouping

Fields like clients or dates can be extracted as separate groups from a list of time entries.

timereport.groupClients(timeEntries) 3.0

A list with all the clients.

[#list timereport.groupClients(timereport.timeEntries)?sort as client]
...
[/#list]
timereport.groupProjects(timeEntries) 3.0

A list with all the projects.

[#list timereport.groupProjects(timereport.timeEntries)?sort as project]
...
[/#list]
timereport.groupTasks(timeEntries) 3.0

A list with all the tasks.

[#list timereport.groupTasks(timereport.timeEntries)?sort as task]
...
[/#list]
timereport.groupTaskCategories(timeEntries) 3.2

A list with all the task categories.

[#list timereport.groupTaskCategories(timereport.timeEntries)?sort as category]
...
[/#list]
timereport.groupDatesByDate(timeEntries) 3.0

A list with the dates when the time entries included in the report were recorded.

[#list timereport.groupDatesByDate(timereport.timeEntries)?sort as date]
...
[/#list]

Use ${date.toDate()?date} to print each date and ${date.toInterval()} to create an interval for a date.

timereport.groupDatesByWeek(timeEntries) 3.0

A list with the weeks when the time entries included in the report were recorded.

[#list timereport.groupDatesByWeek(timereport.timeEntries)?sort as week]
...
[/#list]

Use ${week.toString("yyyy-ww")} to print each week and ${week.toInterval()} to create an interval for a week.

timereport.groupDatesByMonth(timeEntries) 3.0

A list with the months when the time entries included in the report were recorded.

[#list timereport.groupDatesByMonth(timereport.timeEntries)?sort as month]
...
[/#list]

Use ${month.toString("MMM yyyy")} to print each month and ${month.toInterval()} to create an interval for a month.

timereport.groupDatesByYear(timeEntries) 3.0

A list with the years when the time entries included in the report were recorded.

[#list timereport.groupDatesByYear(timereport.timeEntries)?sort as year]
...
[/#list]

Use ${year} to print each year and ${year.toInterval()} to create an interval for an year.

4. Totals

The report can calculate totals for a list of time entries. The list of time entries can either be timereport.timeEntries (all the time entries included in the report) or a partial list determined by one of the filter functions.

timereport.calculateElapsedTimeAsHour(timeEntries) 3.0 The total elapsed time in hour format for the specified list of time entries.
timereport.calculatePausedTimeAsHour(timeEntries) 3.0 The total pause time in hour format for the specified list of time entries.
timereport.calculateBillableTimeAsHour(timeEntries) 3.1, 3.3

The total billable time in hour format for the specified list of time entries.

Note: timereport.calculateBillableTimeAsHour replaces timereport.calculateRoundedElapsedTimeAsHour which was used up until version 3.3.

timereport.calculateUnits(timeEntries) 3.3 The total units for the specified list of time entries.
timereport.calculateUnitsPerHour(timeEntries) 3.3

The total units per hour for the specified list of time entries.

The calculated value can be null if the total time is zero (00:00:00). The following example shows the best way to use this placeholder:

${timereport.calculateUnitsPerHour(timereport.timeEntries)!"N/A"}
timereport.calculateTimePerUnitAsHour(timeEntries) 3.3

The time per unit for the specified list of time entries.

The calculated value can be null if the number of units is zero. The following example shows the best way to use this placeholder:

${timereport.calculateTimePerUnitAsHour(timereport.timeEntries)!"N/A"}
timereport.calculateElapsedTimeAsDecimal(timeEntries) 3.0 The total elapsed time in decimal format for the specified list of time entries.
timereport.calculatePausedTimeAsDecimal(timeEntries) 3.0 The total pause time in decimal format for the specified list of time entries.
timereport.calculateBillableTimeAsDecimal(timeEntries) 3.1, 3.3

The total billable time in decimal format for the specified list of time entries.

Note: timereport.calculateBillableTimeAsDecimal replaces timereport.calculateRoundedElapsedTimeAsDecimal which was used up until version 3.3.

timereport.calculateTotal(timeEntries) 3.3 The total value for the specified list of time entries.

5.8.15. Tasks Report

The following table shows the placeholders that can be used to create tasks reports. Besides these placeholders you can also use business placeholders to print information about your business in a tasks report.

Table 5.18. Tasks Report Properties

Property Version Meaning

1. Parameters

The date interval used to build the report can be accessed from the template.

Each interval may or may not have a start date and an end date. If a date interval is defined only by its start date then the end date will not be defined and tasksreport.dateIntervalEnd?? will return false. The folowing code can be used to cover all situations, whether these fields are defined or not.

	[#if tasksreport.dateIntervalStart??]
		[#if tasksreport.dateIntervalEnd??]
	${tasksreport.dateIntervalStart?date} - ${tasksreport.dateIntervalEnd?date}
		[#else]
	After ${tasksreport.dateIntervalStart?date}
		[/#if]
	[#else]
		[#if tasksreport.dateIntervalEnd??]
	Before ${tasksreport.dateIntervalEnd?date}
		[#else]
	All dates
		[/#if]
	[/#if]
tasksreport.dateIntervalStart 3.0

self-explained

tasksreport.dateIntervalEnd 3.0

self-explained

2. Tasks

The report allows you to obtain a list with all its tasks or partial lists (for instance tasks that were recorded for a certain project).

tasksreport.tasks 3.0

A list with all the tasks included in the report. This is probably most important placeholder because almost all reports need to use it.

tasksreport.getTimeEntries(task) 3.0 A list with all the time entries of task that belong to the reporting period.
tasksreport.filterWithTimeOrMoney(tasks) 3.0

Finds the subset of the specified tasks that have time or money in the reporting period.

This filter is useful if you don't want to deal with tasks that were active during the reporting period but nothing was recorded on them.

tasksreport.filterByProject(tasks, project) 3.0

Finds the subset of the specified tasks that belong to the specified project.

tasksreport.filterByClient(tasks, client) 3.0

Finds the subset of the specified tasks that belong to the specified client.

3. Grouping

Fields like clients or projects can be extracted as separate groups from a list of tasks.

tasksreport.groupClients(tasks) 3.0

A list with all the clients.

[#list tasksreport.groupClients(tasksreport.tasks)?sort as client]
...
[/#list]
tasksreport.groupProjects(tasks) 3.0

A list with all the projects.

[#list tasksreport.groupProjects(tasksreport.tasks)?sort as project]
...
[/#list]

4. Totals

The report can calculate totals for a list of tasks. The list of tasks can either be tasksreport.tasks (all the tasks included in the report) or a partial list determined by one of the filter functions.

tasksreport.calculateEstimatedTimeAsHour(tasks) 3.1 The total estimated time in hour format for the specified list of tasks.
tasksreport.calculateEstimatedTimeAsDecimal(tasks) 3.2 The total estimated time in decimal format for the specified list of tasks.
tasksreport.calculateRemainingTimeAsHour(tasks) 3.1 The total remaining time in hour format for the specified list of tasks.
tasksreport.calculateRemainingTimeAsDecimal(tasks) 3.2 The total remaining time in decimal format for the specified list of tasks.
tasksreport.calculateElapsedTimeAsHour(task) 3.0 The total elapsed time in hour format for the specified task.
tasksreport.calculateElapsedTimeAsHour(tasks) 3.0 The total elapsed time in hour format for the specified list of tasks.
tasksreport.calculateElapsedTimeAsDecimal(tasks) 3.2 The total elapsed time in decimal format for the specified list of tasks.
tasksreport.calculateBillableTimeAsDecimal(task) 3.3 The total billable time in decimal format for the specified task.
tasksreport.calculateBillableTimeAsDecimal(tasks) 3.3 The total billable time in decimal format for the specified list of tasks.
tasksreport.calculateUninvoicedTotal(task) 3.0, 3.3

The uninvoiced total for the specified task.

How much money could be invoiced for the task in the reporting period.

Note: tasksreport.calculateUninvoicedTotal replaces tasksreport.calculateBillableTotal which was used up until version 3.3.

tasksreport.calculateUninvoicedTotal(tasks) 3.0, 3.3

The uninvoiced total for the specified list of tasks.

How much money could be invoiced for the list of tasks in the reporting period.

Note: tasksreport.calculateUninvoicedTotal replaces tasksreport.calculateBillableTotal which was used up until version 3.3.

tasksreport.calculateInvoicedTotal(task) 3.0, 3.3

The invoiced total for the specified task.

How much money was invoiced for the task in the reporting period.

For instance, if a task started on January 1st and it was invoiced on February 10th for the whole month of January for $100 then the invoiced total for January will be $100.

Note: tasksreport.calculateInvoicedTotal replaces tasksreport.calculateBilledTotal which was used up until version 3.3.

tasksreport.calculateInvoicedTotal(tasks) 3.0, 3.3

The invoiced total for the specified list of tasks.

How much money was invoiced for the list of tasks in the reporting period.

Note: tasksreport.calculateInvoicedTotal replaces tasksreport.calculateBilledTotal which was used up until version 3.3.

tasksreport.calculateTotal(task) 3.0

The total (uninvoiced + invoiced) for the specified task.

How much money is the task worth in the reporting period.

tasksreport.calculateTotal(tasks) 3.0

The total (uninvoiced + invoiced) for the specified list of tasks.

How much money is the list of tasks worth in the reporting period.


5.8.16. Expenses Report

The following table shows the placeholders that can be used to create expenses reports. Besides these placeholders you can also use business placeholders to print information about your business in an expenses report.

Table 5.19. Expenses Report Properties

Property Version Meaning

1. Parameters

The date interval used to build the report can be accessed from the template.

Each interval may or may not have a start date and an end date. If a date interval is defined only by its start date then the end date will not be defined and expensesreport.dateIntervalEnd?? will return false. The folowing code can be used to cover all situations, whether these fields are defined or not.

	[#if expensesreport.dateIntervalStart??]
		[#if expensesreport.dateIntervalEnd??]
	${expensesreport.dateIntervalStart?date} - ${expensesreport.dateIntervalEnd?date}
		[#else]
	After ${expensesreport.dateIntervalStart?date}
		[/#if]
	[#else]
		[#if expensesreport.dateIntervalEnd??]
	Before ${expensesreport.dateIntervalEnd?date}
		[#else]
	All dates
		[/#if]
	[/#if]
expensesreport.dateIntervalStart 3.1

self-explained

expensesreport.dateIntervalEnd 3.1

self-explained

2. Expenses

The report allows you to obtain a list with all its expenses or partial lists (for instance expenses that were recorded for a certain project).

expensesreport.expenses 3.1

A list with all the expenses included in the report. This is probably most important placeholder because almost all reports need to use it.

expensesreport.filterByDate(expenses, interval) 3.2 Finds the subset of the specified expenses that were recorded in the specified interval. (their Date field belongs to the interval)
expensesreport.filterByProject(expenses, project) 3.1

Finds the subset of the specified expenses that belong to the specified project.

expensesreport.filterByClient(expenses, client) 3.1

Finds the subset of the specified expenses that belong to the specified client.

3. Grouping

Fields like clients or projects can be extracted as separate groups from a list of expenses.

expensesreport.groupClients(expenses) 3.1

A list with all the clients.

[#list expensesreport.groupClients(expensesreport.expenses)?sort as client]
...
[/#list]
expensesreport.groupProjects(expenses) 3.1

A list with all the projects.

[#list expensesreport.groupProjects(expensesreport.expenses)?sort as project]
...
[/#list]
expensesreport.groupDatesByDate(expenses) 3.2

A list with the dates when the expenses included in the report were recorded.

[#list expensesreport.groupDatesByDate(expensesreport.expenses)?sort as date]
...
[/#list]

Use ${date.toDate()?date} to print each date and ${date.toInterval()} to create an interval for a date.

expensesreport.groupDatesByWeek(expenses) 3.2

A list with the weeks when the expenses included in the report were recorded.

[#list expensesreport.groupDatesByWeek(expensesreport.expenses)?sort as week]
...
[/#list]

Use ${week.toString("yyyy-ww")} to print each week and ${week.toInterval()} to create an interval for a week.

expensesreport.groupDatesByMonth(expenses) 3.2

A list with the months when the expenses included in the report were recorded.

[#list expensesreport.groupDatesByMonth(expensesreport.expenses)?sort as month]
...
[/#list]

Use ${month.toString("MMM yyyy")} to print each month and ${month.toInterval()} to create an interval for a month.

expensesreport.groupDatesByYear(expenses) 3.2

A list with the years when the expenses included in the report were recorded.

[#list expensesreport.groupDatesByYear(expensesreport.expenses)?sort as year]
...
[/#list]

Use ${year} to print each year and ${year.toInterval()} to create an interval for an year.

expensesreport.groupTaxAmountsTaxes(expenses) 3.3

A list with the years when the expenses included in the report were recorded.

[#list expensesreport.groupTaxAmountsTaxes(expensesreport.expenses)?sort as tax]
...
[/#list]

Use ${tax.name} to print the tax name and ${tax.defaultRate} to print the tax rate.

4. Totals

The report can calculate totals for a list of expenses. The list of expenses can either be expensesreport.expenses (all the expenses included in the report) or a partial list determined by one of the filter functions.

expensesreport.calculateAmount(expenses) 3.1

The total amount for the specified list of expenses.

Amount specifies the total amount of money spent.

expensesreport.calculateTaxAmountsBag(expenses) 3.3

The total tax amount for the specified list of expenses. The following code display tax amounts by tax:

[#assign taxes = expensesreport.groupTaxAmountsTaxes(expensesreport.expenses)]
[#assign allTaxAmountsBag = expensesreport.calculateTaxAmountsBag(expensesreport.expenses)]

[#list taxes?sort as tax]
${allTaxAmountsBag.getAmount(tax)!""}
[/#list]

Use .getAmount(tax) to get the amount for a specific tax.

expensesreport.calculateTotal(expenses) 3.1

The total for the specified list of expenses.

Total specifies the total amount of money billed if the expense is billable.


5.8.17. Trips Report

The following table shows the placeholders that can be used to create trips reports. Besides these placeholders you can also use business placeholders to print information about your business in a trips report.

Table 5.20. Trips Report Properties

Property Version Meaning

1. Parameters

The date interval used to build the report can be accessed from the template.

Each interval may or may not have a start date and an end date. If a date interval is defined only by its start date then the end date will not be defined and tripssreport.dateIntervalEnd?? will return false. The folowing code can be used to cover all situations, whether these fields are defined or not.

	[#if tripsreport.dateIntervalStart??]
		[#if tripsreport.dateIntervalEnd??]
	${tripsreport.dateIntervalStart?date} - ${tripsreport.dateIntervalEnd?date}
		[#else]
	After ${tripsreport.dateIntervalStart?date}
		[/#if]
	[#else]
		[#if tripsreport.dateIntervalEnd??]
	Before ${tripsreport.dateIntervalEnd?date}
		[#else]
	All dates
		[/#if]
	[/#if]
tripsreport.dateIntervalStart 3.1

self-explained

tripsreport.dateIntervalEnd 3.1

self-explained

2. Trips

The report allows you to obtain a list with all its trips or partial lists (for instance trips that were recorded for a certain project).

tripsreport.trips 3.1

A list with all the trips included in the report. This is probably most important placeholder because almost all reports need to use it.

tripsreport.filterByStartTime(trips, interval) 3.2 Finds the subset of the specified trips that were recorded in the specified interval. (their Start Time field belongs to the interval)
tripsreport.filterByProject(trips, project) 3.1

Finds the subset of the specified trips that belong to the specified project.

tripsreport.filterByClient(trips, client) 3.1

Finds the subset of the specified trips that belong to the specified client.

3. Grouping

Fields like clients or projects can be extracted as separate groups from a list of trips.

tripsreport.groupClients(trips) 3.1

A list with all the clients.

[#list tripsreport.groupClients(tripsreport.trips)?sort as client]
...
[/#list]
tripsreport.groupProjects(trips) 3.1

A list with all the projects.

[#list tripsreport.groupProjects(tripsreport.trips)?sort as project]
...
[/#list]
tripsreport.groupStartTimesByDate(trips) 3.2

A list with the dates when the trips included in the report were recorded.

[#list tripsreport.groupStartTimesByDate(tripsreport.trips)?sort as date]
...
[/#list]

Use ${date.toDate()?date} to print each date and ${date.toInterval()} to create an interval for a date.

tripsreport.groupStartTimesByWeek(trips) 3.2

A list with the weeks when the trips included in the report were recorded.

[#list tripsreport.groupStartTimesByWeek(tripsreport.trips)?sort as week]
...
[/#list]

Use ${week.toString("yyyy-ww")} to print each week and ${week.toInterval()} to create an interval for a week.

tripsreport.groupStartTimesByMonth(trips) 3.2

A list with the months when the trips included in the report were recorded.

[#list tripsreport.groupStartTimesByMonth(tripsreport.trips)?sort as month]
...
[/#list]

Use ${month.toString("MMM yyyy")} to print each month and ${month.toInterval()} to create an interval for a month.

tripsreport.groupStartTimesByYear(trips) 3.2

A list with the years when the trips included in the report were recorded.

[#list tripsreport.groupStartTimesByYear(tripsreport.trips)?sort as year]
...
[/#list]

Use ${year} to print each year and ${year.toInterval()} to create an interval for an year.

expensesreport.groupTaxAmountsTaxes(expenses) 3.3

A list with the years when the expenses included in the report were recorded.

[#list expensesreport.groupTaxAmountsTaxes(expensesreport.expenses)?sort as tax]
...
[/#list]

Use ${tax.name} to print the tax name and ${tax.defaultRate} to print the tax rate.

4. Totals

The report can calculate totals for a list of trips. The list of trips can either be tripsreport.trips (all the trips included in the report) or a partial list determined by one of the filter functions.

tripsreport.calculateDistance(trips) 3.1

The total distance for the specified list of trips.

tripsreport.calculateTotal(trips) 3.1

The total for the specified list of trips.


5.8.18. Sales Report

The following table shows the placeholders that can be used to create sales reports. Besides these placeholders you can also use business placeholders to print information about your business in a sales report.

Here's an example that shows how to calculate totals by month. It groups invoices by month and then it calculates the total for each month.

[!-- Determine the months when invoices where issued. --]
[#assign months=salesreport.groupDatesByMonth(salesreport.invoices)]

[#list months?sort as month]

  [!-- Use salesreport.filterByDate to find invoices issued on a specific month. --]
  [#assign monthInvoices=salesreport.filterByDate(salesreport.invoices, month.toInterval())]

  [!-- Print the month and calculate the total for the invoices issued on that month --]
  ${month.toString("MMM yyyy")}: ${salesreport.calculateTotal(monthInvoices)}

[/#list]

[!-- Calculate the total for all the invoices included in the report --]
Total: ${salesreport.calculateTotal(salesreport.invoices)}

Table 5.21. Sales Report Properties

Property Version Meaning

1. Parameters

The date and paid date intervals used to build the report can be accessed from the template.

Each interval may or may not have a start date and an end date. If a date interval is defined only by its start date then the end date will not be defined and salesreport.dateIntervalEnd?? will return false. The folowing code can be used to cover all situations, whether these fields are defined or not.

	[#if salesreport.dateIntervalStart??]
		[#if salesreport.dateIntervalEnd??]
	${salesreport.dateIntervalStart?date} - ${salesreport.dateIntervalEnd?date}
		[#else]
	After ${salesreport.dateIntervalStart?date}
		[/#if]
	[#else]
		[#if salesreport.dateIntervalEnd??]
	Before ${salesreport.dateIntervalEnd?date}
		[#else]
	All dates
		[/#if]
	[/#if]
salesreport.dateIntervalStart 3.0

self-explained

salesreport.dateIntervalEnd 3.0

self-explained

salesreport.paidDateIntervalStart 3.0

self-explained

salesreport.paidDateIntervalEnd 3.0

self-explained

2. Invoices

The report allows you to obtain a list with all its invoices or partial lists (for instance invoices that were issued in a certain month).

salesreport.invoices 3.0

A list with all the invoices included in the report. This is probably most important placeholder because almost all reports need to use it.

salesreport.paidInvoices 3.0 A list with all the paid invoices included in the report.
salesreport.filterByDate(invoices, interval) 3.0 Finds the subset of the specified invoices that were issued in the specified interval. (their Date field belongs to the interval)
salesreport.filterByPaidDate(invoices, interval) 3.0 Finds the subset of the specified invoices that were paid in the specified interval. (their Paid Date field belongs to the interval)
salesreport.filterByClient(invoices, client) 3.0

Finds the subset of the specified invoices that belong to the specified client.

3. Grouping

Fields like clients or dates can be extracted as separate groups from a list of invoices. Dates can be grouped by month or year.

salesreport.groupClients(invoices) 3.0

A list with all the invoiced clients.

[#list salesreport.groupClients(salesreport.invoices)?sort as client]
...
[/#list]
salesreport.groupTaxes(invoices) 3.3

A list with all the taxes.

[#list salesreport.groupTaxes(salesreport.invoices)?sort as tax]
...
[/#list]
salesreport.groupDatesByMonth(invoices) 3.0

A list with the months when the invoices included in the report were issued.

[#list salesreport.groupDatesByMonth(salesreport.invoices)?sort as month]
...
[/#list]

Use ${month.toString("MMM yyyy")} to print each month and ${month.toInterval()} to create an interval for a month.

salesreport.groupDatesByYear(invoices) 3.0

A list with the years when the invoices included in the report were issued.

[#list salesreport.groupDatesByYear(salesreport.invoices)?sort as year]
...
[/#list]

Use ${year} to print each year and ${year.toInterval()} to create an interval for an year.

salesreport.groupPaidDatesByMonth(invoices) 3.0

A list with the months when the invoices included in the report were paid.

salesreport.groupPaidDatesByYear(invoices) 3.0

A list with the years when the invoices included in the report were paid.

4. Totals

The report can calculate totals for a list of invoices. The list of invoices can either be salesreport.invoices (all the invoices included in the report) or a partial list determined by one of the filter functions.

salesreport.calculateTaxTotal(invoices, tax) 3.3 The total for the specified list of invoices and tax.
salesreport.calculateBalance(invoices) 3.0 The balance for the specified list of invoices.
salesreport.calculatePaymentsTotal(invoices) 3.2 The total amount paid for the specified list of invoices.
salesreport.calculateTotal(invoices) 3.0 The total for the specified list of invoices.
salesreport.calculateGrandTotal(invoices) 3.0 The grand total for the specified list of invoices.
salesreport.calculateTaxesTotal(invoices) 3.0 The taxes total for the specified list of invoices.