FI List of Placeholder variables for templates

The following list of variables are useful when adapting the finance document template.  These variables can be included into templates and represent varying values of financial data. This is not the complete list, but generally speaking these are the most frequent ones. 

Other variables can be inserted into templates using a line like:
<H1><%= %variable_name% ></H1>
You can also make function calls from templates and set your own template specific variables:
<% set rate [im_exchange_rate $invoice_date EUR USD] %>
or
<%=[lc_time_fmt $calculated_due_date "%e. %B %Y" en_EN]%>

If the resulting string contains XML special characters, you want to make sure that you escape them.

Please note that in the lists below that invoice is meant to refer to all financial documents. Variables are presented alphabetically by variable name.  

General Variables 

  • default_currency - defines the "DefaultCurrency" parameter   
  • internal_contact_email - email of user_id
  • internal_contact_name - name of user_id
  • total_due - Subtotal + VAT + TAX
  • total_due_pretty - formatted total_due
  • locale - The locale of this invoice, determined by the name of the invoice template. For example "invoice.en_US.adp" will lead to an "en_US" locale for this financial document.  The "locale" determines the language of static texts and the formatting of numbers.
  • page_title - The HTML title of the invoice. Just for the browser header (usually not printed)
  • rounding_precision - Constant set to "2". Determines the number of digits of rounding precision for subtotals etc.
  • subtotal_pretty - formatted subtotal
  • subtotal - subtotal (sum of invoice items)
  • user_id - the ID of the current user (currently looking at the page)
  • user_locale - The default locale of the current user is, in general, different from  locale. This locale serves as a fallback value in case that there is no locale defined for the invoice.

Related Projects

These variables are useful if you want to refer one or more projects that are related to the given invoice. Please note that you can have 0, 1 or multiple projects related to a single invoice (0 for a "stand-alone" invoice without project, 1 for the standard case of one project per invoice and multiple projects if you choose to do "cumulative invoicing", where you include several (small) projects in a single invoice).

  • num_related_projects - Number of related projects, e.g.: 0, 1 or more.
  • related_customer_project_nrs - TCL list of the customer's project references to the related projects.
  • related_projects -  Project ID's of related projects.
  • related_project_names - Project Names of related projects.
  • related_project_nrs - The TCL list of the "numbers" of related projects. Please use <%= [join $related_project_nrs ", "] %> to use this field in the template, so that multiple projects are displayed correctly with a ", " in between.

Customer and Provider

A Financial Document is usually between the "internal company" (please see above) and either a Provider or a Customer, depending on the type of financial document. "Company" in this context refers to this 2nd party, independently of whether it's a customer or a provider.

  • accounting_contact_id - ID of the company's accounting contact person.
  • company_id - ID of the customer or provider
  • company_name - (Long name)
  • company_path - Path  (short name)
  • company_status_id - Status of the company. Use select im_category_from_id (company_status_id) to get a human readable status
  • company_type_id - Type of company. See company_status_id above for formatting.
  • crm_status_id - Information about the CRM acquisition process.
  • deleted_p - The company may already have been deleted…
  • primary_contact_id - ID of the company's main contact person. Please use select im_name_from_user_id (:primary_contact_id) to obtain the name and select im_email_from_user_id(:primary_contact_id) to obtain the contact's email.
  • vat_number - The VAT number of company 

The following fields contain information about the preferences/default values for the company's payment conditions and templates for different invoice types. 

  • default_bill_template_id
  • default_delnote_template_id
  • default_invoice_template_id
  • default_payment_days
  • default_payment_method_id
  • default_po_template_id
  • default_vat

Information about the company's "Office" selected for this invoice. Please note that there can be several Offices per company, so this one refers to the particular office defined in the invoice.

  • address_city
  • address_country_code - Two digit code for the country
  • address_line1 - first of two address lines
  • address_line2 - second of two address lines
  • address_postal_code - ZIP
  • address_state - May only be useful for US American addresses.
  • country_name - English name of the country (can be localized)
  • fax
  • office_id - ID
  • office_name - Name of the Office. Can be used to designate a company's sub organization (department, …) if suitably maintained in the customer's file
  • office_path - Short name of the office
  • office_status_id - Status (as usual)
  • office_type_id - Type (as usual)

Financial Items

  • calculated_due_date - due date (effective date + payment days)company_contact_email - Email of company_contact_id
  • calculated_due_date_pretty - due date formatted according to locale
  • effective_date - effective date of invoice
  • company_contact_id - ID of the Customer's/Provider's contact person to who we want to send or direct the financial document
  • company_contact_name - Name of company_contact_id
  • cost_center_id - Cost Center/Department
  • cost_center_name - Long name CC/Dept
  • cost_note - Note (prominent field in InvoiceListPage and Template)
  • cost_status - Status (human readable)
  • cost_status_id - Status (ID)
  • cost_type - human readable ID
  • cost_type_id - Type (ID)
  • customer_id - Customer, either the "internal" company for a bill/po or customer company for an invoice/quote/delivery note.
  • provider_id - Provider, either the "internal" company for an invoice/quote or the provider company for a bill/po.
  • invoice_date - same as effective date
  • invoice_date_pretty - effective date formatted
  • invoice_office_id - company's office ID
  • invoice_or_bill_p - True ("1") if financial item is a customer invoice or a provider bill. Both types are "hard costs" and require certain fields such as payment conditions.
  • invoice_or_quote_p - True ("1") if the document is related to a Customer (as opposed to Provider). Also true for "Delivery Note".
  • invoice_payment_method - short human readable text for payment method such as "Bank ABC"
  • invoice_payment_method_id - same as payment_method_id
  • invoice_payment_method_desc - Long description text for payment method detailing the how the money should be paid, typically including the bank name, SWIFT code, IBAN, account number, etc.
  • invoice_status_id - same as cost_status_id
  • invoice_template_id - Rendering template for the cost item.
  • item_currency - Currency of invoice items
  • paid_amount - registered payments for this cost item, converted into paid_currency
  • paid_currency - currency of payments, usually identical with default_currency
  • payment_days - number of days for payment, difference between effective_date and calculated_due_date
  • payment_method_id - ID that determines payment details
  • tax - TAX (percentage). This field can accommodate applicable tact, for example Spanish IRPF, or sales tax
  • tax_amount - TAX (percentage x invoice amount)
  • tax_amount_pretty - TAX (percentage x invoice amount) formatted
  • vat - VAT (percentage)
  • vat_amount - VAT (percentage x invoice amount)
  • vat_amount_pretty - VAT (percentage x invoice amount) formatted

Currency and Date Formatting

These formats are used on the SQL level to format variables. The format depends on the locale parameter (see above). For further customization (modifying the decimal and thousand separators for a particular locale) you can modify the language definition files in the "catalog" folder of the acs-lang package. Please see the OpenACS documentation for more details.

  • cur_format
  • tax_format
  • vat_format

Pre-formatted Pieces of HTML

These are pieces of HTML are already formatted to be included in the InvoiceViewPage and the template.  You can customize these elements by using a StyleSheet.

  • item_html
  • item_list_html
  • invoice_item_html
  • payment_list_html - List of related payments formatted for the ViewPage (not for the Preview)
  • payment_method_html
  • payment_terms_html - Formatted "payment conditions" section. Usually only applicable for "hard costs" where invoice_or_bill_p == true (see below).
  • note_html
    Preformatted (<pre>...</pre>) invoice "note" field
  • render_template_id
    ID of the display template to be used for rendering. Refers to the category_id field in the im_categories table where you find the actual name of the template in the "category" field.
  • subtotal_item_html
    The formatted piece of HTML representing the "subtotal" section with subtotal, VAT, TAX and grand total.


Examples 

Area

Variable

Explanation

Type

Example

Available since Version

Internal information

internal_name

Company name

Text

Foo Company

3.4.0.7.x

 

internal_address_line1

First address line

Text

Foo street 1

 

 

internal_address_line2

Second address line

Text

14th floor

 

 

internal_postal_code

Postal code

Text

D-82008

 

 

internal_city

City

Text

Munich

 

 

internal_country_code

Country code

Text

D

 

 

internal_phone

Phone no.

Text

+12 123 12345678

 

 

internal_fax

Fax no.

Text

+12 123 12345679

 

 

internal_primary_contact_email

E-Mail address of your primary contact

 

Foo.barfoobar.com

 

 

internal_vat_number

VAT ID-Number

 

DE1234567890

 

Customer information

company_name

Company name

Text

Big Customer Inc.

 

 

salutation

Salutation for contact person

 

Mr.

 

 

company_contact_name

Contact person’s name

 

Peter Jung

 

 

user_position

Contact person’s position

 

Manager

 

 

address_line1

Address line 1

 

Rich Avenue 1

 

 

address_line2

Address line 2

 

1st – 3rd floor

 

 

address_postal_code

Postal code

 

1500-RICH

 

 

address_city

City

 

Richmond

 

 

company_path

Customer no.

 

12345

 

Finance doc information

invoice_date_pretty

Invoice date (localized format)

 

2010-12-31

 

 

invoice_nr

Invoice No.

 

I2010_0001

 

 

ctr

Counter for invoiced positions

 

1

 

 

item_units_pretty

No. of units (localized format)
Note: This is a MANDATORY field *

 

1.000

 

 

item_uom

Unit of measurement

 

Lines, Words, Hours, etc.

 


item_currency
Currency of invoice items

EUR, GBP, USD, etc.

 

item_name

Item name

 

Translation

 

 

price_per_unit

Price for one unit (localized format, no currency symbol added)
Note: This is a MANDATORY field *

 

10,50

 

 

amount_pretty

Summed amount for this line (localized format, no currency symbol added)

 

10500,00

 

 

vat_perc_pretty

VAT percentage rate (without %-symbol)

 

19

 

 

vat_amount_pretty

VAT amount (localized format, no currency symbol)

 

1.995,00

 

 

total_due_pretty;

Grand total of invoice (localized format, no currency symbol)

 

12.495,00

 


* These fields are mandatory. If they are not part of the template, you'll receive either error messages or incorrect variable substitution. You can prevent their appearance by choosing a white font color. 

References

  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

08902 Hospitalet de Llobregat (Barcelona)

Spain

 Tel Europe: +34 609 953 751
 Tel US: +1 415 200 2465
 Mail: info@project-open.com