Variable substitution system

Substitution variables are keywords that can be used in many places in Dolibarr to be replaced later. It is used for example in the templates of emails or configuration text for a text to be personalized when it is displayed or sent for emails.

These variables will be replaced only if the corresponding data exist on the object (for exemple for a third party mail, the online payement URL doesn't exist and will not be replaced)

Substitution variables available

Dolibarr User


Variable	Displayed Value	Note
__USER_SIGNATURE__	My beautiful signature	User signature
__USER_SIGNATURE__	My beautiful signature	User signature
__USER_ID__	1	User ID
__USER_LOGIN__	doli9	User Login
__USER_LASTNAME__	Admin	User last name
__USER_FIRSTNAME__	Super	User first name
__USER_FULLNAME__	SuperAdmin	User full name
__USER_SUPERVISOR_ID__	1	User supervisor ID
__USER_REMOTE_IP__	xxx.xxx.xxx.xxx	User remote IP

My Company


Variable	Displayed Value	Note
__MYCOMPANY_NAME__	My little company	Name of the company
__MYCOMPANY_EMAIL__	contact@mycompany.com	My company contact email
__MYCOMPANY_PHONE__	0123456789	My company phone number
__MYCOMPANY_FAX__	0123456789	My company fax number
__MYCOMPANY_PROFID1__	12345678	Prof Id 1 (TIN)
__MYCOMPANY_PROFID2__	12345678	Prof Id 2 (PAN)
__MYCOMPANY_PROFID3__	12345678	Prof Id 3 (SRVC TAX)
__MYCOMPANY_PROFID4__	12345678	Prof Id 4
__MYCOMPANY_PROFID5__	12345678	Prof Id 5
__MYCOMPANY_PROFID6__	12345678	VAT ID
__MYCOMPANY_CAPITAL__	10000	Capital of the company
__MYCOMPANY_FULLADDRESS__	21 Jump street 75500 MyTown India	Full address of the company
__MYCOMPANY_ADDRESS__	21 Jump street	address of the company
__MYCOMPANY_ZIP__	75500	ZIP code of the company address
__MYCOMPANY_TOWN__	MyTown	Town of the company address
__MYCOMPANY_COUNTRY__	India	Country of the company address
__MYCOMPANY_COUNTRY_ID__	1	Country ID of the company address
__MYCOMPANY_COUNTRY_CODE__	1	Country Code of the company address
__MYCOMPANY_CURRENCY_CODE__	EUR	Main currency

Object

Generic


Variable	Displayed Value	Note	Dolibarr Mini
__ID__	1	ID of the object
__REF__	1234	Reference of the object
__REF_CLIENT__	1234	Customer reference of the object
__REF_SUPPLIER__	1234	Supplier reference of the object
__NOTE_PUBLIC__	My Public note	Object Public Note	V 13
__NOTE_PRIVATE__	My Private note	Object Private Note	V 13
__DATE_DELIVERY__	01/02/2021	Delivery date	V 13

Objects with amounts


Variable	Displayed Value	Note	Dolibarr Mini
__DATE_YMD__	1/1/2020	Object date
__DATE_DUE_YMD__	1/1/2020	Due date
__AMOUNT__	1243.34	Amount
__AMOUNT_TEXT__	One thousand five hundred ...	Amount in words	V13
__AMOUNT_TEXTCURRENCY__	One thousand five hundred ...	Amount in words with currency	V13
__AMOUNT_EXCL_TAX__	1234.45	Amount without taxes
__AMOUNT_VAT__	123.4	VAT amount
__AMOUNT_VAT_TEXT__	One thousand five hundred ...	VAT Amount in words	V13
__AMOUNT_VAT_TEXTCURRENCY__	One thousand five hundred ...	VAT Amount in words with currency	V13
__AMOUNT_TAX2__	123.4	TAX2 amount
__AMOUNT_TAX3__	123.4	TAX3 amount
__AMOUNT_FORMATED__	1243.34 €	Amount formated
__AMOUNT_EXCL_TAX_FORMATED__	1234.45 €	Amount without taxes formated
__AMOUNT_VAT_FORMATED__	123.4 €	VAT amount formated
__AMOUNT_TAX2_FORMATED__	123.4 €	TAX2 amount formated	V13
__AMOUNT_TAX3_FORMATED__	123.4 €	TAX3 amount formated	V13
__AMOUNT_MULTICURRENCY__	1234.45 $	Amount in Multicurrency	V13
__AMOUNT_MULTICURRENCY_TEXT__	One thousan five hundred ...	Amount in Multicurrency in words	V13
__AMOUNT_MULTICURRENCY_TEXTCURRENCY__	One thousan five hundred ...	Amount in Multicurrency in words with currency	V13

Member


Variable	Displayed Value	Note	Dolibarr Mini
__MEMBER_ID__	123	Member ID	V 13
__MEMBER_CIVILITY__			V 13
__MEMBER_FIRSTNAME__			V 13
__MEMBER_LASTNAME__			V 13
__MEMBER_FULLNAME__			V 13
__MEMBER_COMPANY__			V 13
__MEMBER_ADDRESS__			V 13
__MEMBER_ZIP__			V 13
__MEMBER_TOWN__			V 13
__MEMBER_COUNTRY__			V 13
__MEMBER_EMAIL__			V 13
__MEMBER_BIRTH__			V 13
__MEMBER_PHOTO__			V 13
__MEMBER_LOGIN__			V 13
__MEMBER_PASSWORD__			V 13
__MEMBER_PHONE__			V 13
__MEMBER_PHONEPRO__			V 13
__MEMBER_PHONEMOBILE__			V 13
__MEMBER_TYPE__	Member	Type of member	V 13
__MEMBER_FIRST_SUBSCRIPTION_DATE__			V 13
__MEMBER_FIRST_SUBSCRIPTION_DATE_START__			V 13
__MEMBER_FIRST_SUBSCRIPTION_DATE_END__			V 13
__MEMBER_LAST_SUBSCRIPTION_DATE__			V 13
__MEMBER_LAST_SUBSCRIPTION_DATE_START__			V 13
__MEMBER_LAST_SUBSCRIPTION_DATE_END__			V 13

Thirdparty


Variable	Displayed Value	Note	Dolibarr Mini
__THIRDPARTY_ID__	1	Third party ID of the object
__THIRDPARTY_NAME__	MyCustomer	Third party name of the object
__THIRDPARTY_NAME_ALIAS__	MyC	Third party name alias of the object
__THIRDPARTY_CODE_CLIENT__			V13
__THIRDPARTY_CODE_FOURNISSEUR__			V13
__THIRDPARTY_EMAIL__	contact@mycustomer.com	Third party email of the object
__THIRDPARTY_PHONE__			V13
__THIRDPARTY_FAX__			V13
__THIRDPARTY_ADDRESS__			V13
__THIRDPARTY_ZIP__			V13
__THIRDPARTY_TOWN__			V13
__THIRDPARTY_COUNTRY_ID__			V13
__THIRDPARTY_COUNTRY_CODE__			V13
__THIRDPARTY_IDPROF1__			V13
__THIRDPARTY_IDPROF2__			V13
__THIRDPARTY_IDPROF3__			V13
__THIRDPARTY_IDPROF4__			V13
__THIRDPARTY_IDPROF5__			V13
__THIRDPARTY_IDPROF6__			V13
__THIRDPARTY_TVAINTRA__			V13
__THIRDPARTY_NOTE_PUBLIC__			V13
__THIRDPARTY_NOTE_PRIVATE__			V13

Candidate


Variable	Displayed Value	Note	Dolibarr Mini
__CANDIDATE_FULLNAME__			V13
__CANDIDATE_FIRSTNAME__			V13
__CANDIDATE_LASTNAME__			V13

Project


Variable	Displayed Value	Note
__PROJECT_ID__	1	Project ID of the object
__PROJECT_REF__	1	Project reference of the object
__PROJECT_NAME__	1	Project name of the object

Shipment


Variable	Displayed Value	Note	Dolibarr Mini
__SHIPPINGTRACKNUM__	XXXXX	Shipping tacking number
__SHIPPINGTRACKNUMURL__	http://trackingcompagny.com/XXXXX	Shipping tracking url

Reception


Variable	Displayed Value	Note	Dolibarr Mini
__RECEPTIONTRACKNUM__	XXXXX	Shipping tacking number	V13
__RECEPTIONTRACKNUMURL__	http://trackingcompagny.com/XXXXX	Shipping tracking url	V13

Contract


Variable	Displayed Value	Note
__CONTRACT_HIGHEST_PLANNED_START_DATE__	1/1/2020	Highest date planned for a service start
__CONTRACT_HIGHEST_PLANNED_START_DATETIME__	1/1/2020 1PM	Highest date and hour planned for service start
__CONTRACT_LOWEST_EXPIRATION_DATE__	1/1/2020	Lowest date for planned expiration of service
__CONTRACT_LOWEST_EXPIRATION_DATETIME__	1/1/2020 1PM	Lowest date and hour for planned expiration of service

Extrafield

Generic Rule


Variable	Displayed Value	Note	Dolibarr Mini
__EXTRAFIELD_XXX__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code)

Date Extrafield


Variable	Displayed Value	Note	Dolibarr Mini
__EXTRAFIELD_XXX__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code)
__EXTRAFIELD_XXX_LOCALE__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code) in locale
__EXTRAFIELD_XXX_RFC__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code) in RFC

Datetime Extrafield


Variable	Displayed Value	Note	Dolibarr Mini
__EXTRAFIELD_XXX__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code)
__EXTRAFIELD_XXX_LOCALE__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code) in locale
__EXTRAFIELD_XXX_DAY_LOCALE__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code) only the day in locale
__EXTRAFIELD_XXX_RFC__		Object Extrafield (XXX need to be replace by the Extrafield Attribute code) in RFC

Online Payment


Variable	Displayed Value	Note	Dolibarr Mini
__ONLINE_PAYMENT_URL__	http://mydoli.com/payment	Address of the Online payement if applicable
__ONLINE_PAYMENT_TEXT_AND_URL__	Click to pay	Text and Url to pay online if applicable

Online Proposal Signature


Variable	Displayed Value	Note	Dolibarr Mini
__ONLINE_SIGN_URL__	http://mydoli.com/public/onlinesign	Address of the Online Signature for proposal	15

Online Intervention Signature


Variable	Displayed Value	Note	Dolibarr Mini
__ONLINE_SIGN_FICHINTER_URL__	http://mydoli.com/public/onlinesign	Address of the Online Signature for intervention

Document download


Variable	Displayed Value	Note
__DIRECTDOWNLOAD_URL_PROPOSAL__	http://mydoli.com/proposal.pdf	Direct download url of a proposal
__DIRECTDOWNLOAD_URL_ORDER__	http://mydoli.com/order.pdf	Direct download url of an order
__DIRECTDOWNLOAD_URL_INVOICE__	http://mydoli.com/invoice.pdf	Direct download url of an invoice. This needs that the setup INVOICE_ALLOW_EXTERNAL_DOWNLOAD is set to allow to generate the link.
__DIRECTDOWNLOAD_URL_FICHINTER__	http://mydoli.com/fichinter.pdf	Direct download url of an intervention. This needs that the setup FICHINTER_ALLOW_EXTERNAL_DOWNLOAD is set to allow to generate the link.
__URL_PROPOSAL__	http://mydoli.com/comm/propal/card.php?id=xxx
__URL_ORDER__	http://mydoli.com/commande/card.php?id=xxxx
__URL_INVOICE__	http://mydoli.com/compta/facture/card.php?id=xxx
__URL_FICHINTER__

Event


Variable	Displayed Value	Note	Dolibarr Mini
__EVENT_LABEL__			V13
__EVENT_DATE__			V13
__EVENT_TIME__			V13

Dates


Variable	Displayed Value	Note
__DAY__	12	actual day
__DAY_TEXT__	Monday	Actual day in text
__DAY_TEXT_SHORT__	Mo	Actual day in short text
__DAY_TEXT_MIN__	M	Actual day in minimum text
__MONTH__	3	Actual month
__MONTH_TEXT__	March	Actual month in text
__MONTH_TEXT_SHORT__	March	Actual month in short text
__MONTH_TEXT_MIN__	M	Actual month in minimum text
__YEAR__	2020	Actual year
__PREVIOUS_DAY__	11	Previous day
__PREVIOUS_MONTH__	2	Previous month
__PREVIOUS_YEAR__	2019	Previous Year
__NEXT_DAY__	13	Next day
__NEXT_MONTH__	4	Next month
__NEXT_YEAR__	2021	next year

Multicompany


Variable	Displayed Value	Note	Dolibarr Mini
__ENTITY_ID__			V13

System


Variable	Displayed Value	Note	Dolibarr Mini
__DOL_MAIN_URL_ROOT__	http://mondolibarr/htdocs	Root URL of Dolibarr
__(AnyTranslationKey)__	Translation	Any translation Key
__(AnyTranslationKey\|langfile)__	Translation	Any translation Key (load also language file before)	V13
__[AnyConstantKey]__	1	Value of a constant key

For Emails


Variable	Displayed Value	Note	Dolibarr Mini
__CONTACT_NAME_XXX__	Mister T	XXX is the contact type defined on Setup->Dictionaries->Contact/Address types (exemple : __CONTACT_NAME_BILLING__ for the billing contact). The output will be LastName + First Name	V14
__CONTACT_LASTNAME_XXX__	T	XXX is the contact type defined on Setup->Dictionaries->Contact/Address types (exemple : __CONTACT_NAME_BILLING__ for the billing contact).	V14
__CONTACT_FIRSTNAME_XXX__	Mister	XXX is the contact type defined on Setup->Dictionaries->Contact/Address types (exemple : __CONTACT_NAME_BILLING__ for the billing contact).	V14
__CONTACT_TITLE_XXX__	Mr	XXX is the contact type defined on Setup->Dictionaries->Contact/Address types (exemple : __CONTACT_NAME_BILLING__ for the billing contact).	V14
__CHECK_READ__		Insert a blank image with a callback URL to Dolibarr (/public/emailing/mailing-read.php?tag=)

Substitution variables provide by external module

Custom substitution variables can be added by external modules. For this, the external module must embed a file called mymodule/core/substitutions/functions_mymodules.lib.php and set the

$this->module_parts['substitutions'] = 1

into the module descriptor.

How it work

The array to define all substitution variables is defined in code by calling the method $substitutionarray = getCommonSubstitutionArray(). This method receive the $object in parameter, so it can define the content of the substitution array using properties of this object. No database access and no IO are allowed to set the substitution array.

Then the array will be used by calling the make_substitutions() this way: $textcompleted = make_substitutions($textwithsubtitutionkeys, $substitutionarray)

However, sometimes to value to use is not available into the $object, neither into the environment, and it needs a database access to get the value. In such a case, the substitution is not done by the getCommonSubstitutionArray(). The getCommonSubstitutionArray() will just add an entry into the array of substitution with the information to explain how to get the value like for this entry: $substitutionarray['__PROJECT_NAME__@lazyload'] = '/projet/class/project.class.php:Project:fetchAndSetSubstitution:'.$object->id The substitution will be done by the make_substitutions() and only it is required by calling the method defined (here fetchAndSetSubstitution with the param $object->id of the object Project defined into file /projet/class/project.class.php). Thus, the heavy database access is done only if required.