After installation in Joomla's extension manager, you need to configure the plugin. It is automatically enabled, but by default, does not change the order and invoice numbers! You have to manually configure the plugin in the Joomla plugin manager (NOT inside VirtueMart!) first:
When a new order is submitted, a new invoice is created or a new user is created, this plugin immediately creates the corresponding order/invoice/customer number before VirtueMart uses its default algorithm. VirtueMart then stores this number in the database and does not create its own numbers. This plugin does not override the general order or invoice handling, but only hooks in at that one point where the number is initially created.
As a consequence, this plugin is not able to change the numbers of existing orders, invoices and customers.
The format strings are simple texts, where the following variables will be replaced. Everything that does not match one of these is taken verbatim into the invoice/order/customer numbers and order password.
|#||Running counter (either global or per format-value); Not applicable to the order password!||X||-||X||X|
|Date and Time:|
|[year], [year2]||Current year (4 or 2 digits)||X||X||X||X|
|[month]||Current month (2 digits); leading zeros if necessary||X||X||X||X|
|[day]||Current day (2 digits); leading zeros if necessary||X||X||X||X|
|[hour], [hour12]||Current hour in 24-hour and 12-hour format; leading zeros if necessary||X||X||X||X|
|[ampm]||Current am-pm (for 12-hour format) in lower-case||X||X||X||X|
|[minute]||Current minute; leading zeros if necessary||X||X||X||X|
|[second]||Current second; leading zeros if necessary||X||X||X||X|
|[decisecond], [centisecond], [millisecond]||Current decisecond (10th of a second), centisecond (100th) and millisecond (1000th)||X||X||X||X|
|Random Numbers and Strings:|
|[randomDigit[n]]||Random sequences of n decimal digits (n=1 if not given).||X||X||X||X|
|[randomHex[n]]||Random sequences of n hexadecimal digits (n=1 if not given).||X||X||X||X|
|[randomLetter[n]]||Random sequences of n (upper- and lowercase) letters (n=1 if not given).||X||X||X||X|
|[randomULetter[n]]||Random sequences of n uppercase letters (n=1 if not given).||X||X||X||X|
|[randomLLetter[n]]||Random sequences of n lowercase letters (n=1 if not given).||X||X||X||X|
|[randomAlphanum[n]]||Random sequences of n general alphanumeric characters (A-Z, a-z, 0-9) (n=1 if not given).||X||X||X||X|
|Billing Address information:|
|Lastname||Last name of the shopper (billing address)||-||-||X||-|
|Firstname, Middlename||First name of the shopper (billing address)||-||-||X||-|
|Company||Company of the shopper (billing address)||-||-||X||-|
|City||City of the shopper (billing address)||-||-||X||-|
|zip, postcode||ZIP of the shopper (billing address)||-||-||X||-|
|country||Full county name (billing address)||-||-||X||-|
|countrycode2||2-letter country code (billing address)||-||-||X||-|
|countrycode3||3-letter country code (billing address)||-||-||X||-|
|E-Mail address of the customer||-||-||X||-|
|Order and Invoice details:|
|orderNumber||Order number, for which the invoice is created||-||-||X||-|
|orderStatus||Status of the order (abbreviations: S, R, X, C, U, P)||X||X||X||-|
|orderTotal, amount||Total order amount (in the currency of the order). Useful only in custom variable conditions||X||X||X||-|
|orderSubTotal||The order subtotal (before shipment and payment fees)||X||X||X||-|
|orderShipment, orderPayment||The shipment and payment fee of the order||X||X||X||-|
|orderDiscount||The order discount||X||X||X||-|
|Articles||The number of articles in the order (each product counted with its quantity)||X||X||X||-|
|Products||The number of different products in the order (ignoring their quantity)||X||X||X||-|
|List-valued variables, available only in custom variable conditions (see below):|
|skus||List of the SKUs (not product IDs!) of all products in the order||X||X||X||-|
|categories||List of all category IDs (not category names!) of all products in the order||X||X||X||-|
|manufacturers||List of all manufacturer IDs (not manufacturer names!) of all products in the order||X||X||X||-|
|vendors||List of all vendor IDs of all products in the order (only for multi-vendor shops!)||X||X||X||-|
|Internal Variables (use strongly discouraged, except in custom variable conditions):|
|vendorID||(Internal) VirtueMart Vendor ID||X||X||X||X|
|userID||(Internal) VirtueMart User ID||X||X||X||X|
|orderID||(Internal) Order ID, for which the invoice is created||-||-||X||-|
|CountryID||(Internal) Country ID of the shopper's country||-||-||X||-|
|StateID||(Internal) State ID of the shopper's state inside the country||-||-||X||-|
|IPaddress||IP-Address of the shopper's computer||X||X||X||X|
As a general rule of thumb, whenever any of the variables included in the format changes, the counter will be reset to 1.
For example, with a format "[year]-[month]-[day]/#", the counter will be reset each day. With a format "[year][month][day][hour][minute]-#", the counter will be reset each minute. So by default it is NOT possible to have e.g. a format "[year][month][day]/#" and have the counter reset only yearly.
It's actually a bit more complicated: The plugin does not have one counter, that is reset at the beginning of a new year/month.
Rather is has multiple concurrent counters. When generating the order number, the plugin will first replace all [...] parts with the variable values. Then the resulting string is used as the name for the counter. The counter is looked up in the database (if not found, a value of 0 is used) and then incremented, stored back to the database and inserted for the # in the format.
This approach is best understood at an example:
Number format [year][month][day]-#:
FIRST ORDER on Aug 18, 2014:
NEXT ORDER on Aug 18, 2014:
FIRST ORDER on Aug 19, 2014:
As you can see, with a format-specific counter, whenever any of the variables in the format changes, a new counter is created and it starts from 1.
If you want one global counter that does not reset, simply select "Global counter" in the plugin configuration.
So, in effect it appears as if the counter is reset daily, while in fact a new counter is used for each day. This approach has the advantage that you can have e.g. different counters for orders to different countries. If you use the format "[year]-[countrycode2]-#", each country will have its own counter and you have order numbers like "2014-AT-1", "2014-DE-1", "2014-AT-2", "2014-AT-3", "2014-CH-1", "2014-DE-2", etc. (Notice that the orders for AT have one counter, while the DE have another independent countet).
This approach is very generic (and very simple, yet really powerful), but unfortunately it also means that having a format of "[year][month]#" where the counter is reset only each year is NOT possible by default, since the format value will change each month and the format value will be used as the counter name...
To solve the problem described in the previous paragraph, version 1.12 of the plugin adds the possibility to use custom counter names that are different from the actual number format. These counter formats are appended to the number format after a |. Notice that this is needed only in exceptional cases and certainly not intended for a normal installation. If you think that you really need this feature in your shop, it is probably best to ask in the support forum, because this feature has a lot of potential to cause havoc.
A typical example is a number format like "[year][month]/#" where the shop owner wants the counter to be running inside the year. By default, a new counter will be used each month (since the month variable changes each month...). Starting with plugin version 1.12, the shop owner can now use a number format "[year][month]/#", but let the plugin use a counter name of "[year]/#", which will cause the counter to be reset only at the beginning of each year. The proper format string in this case is:
This gives the shop owner even more flexibility, but is quite hard to understand with all consequences. In particular, a wrong counter format can cause orders with duplicate numbers, in which case VirtueMart will append the current timestamp to the number (leading to ugly numbers like "201410/1_2014-10-16T15:10:12". To prevent this, the counter format should ONLY use variables that are also in the number format string. Everything else will lead to duplicate numbers.
For each counter, its current value is stored in the database and read from there when the plugin creates a new number. Directly after installation, each counter will start from 1 (its current value is 0). If your shop has been running for a while, you might want it to start from some other value.
The easiest way to achieve this is to set up the plugin, make one test order so that the plugin creates the counter, and then adjust its name in the plugin configuration in the Joomla Backend:
To modify a counter, simply click on the pencil icon on the right and enter the desired new value (remember the value stored on the server is the value of the previous order). The change is immediately sent to the server, i.e. you do not have to press "Save" in the plugin config page.
If you are using a global counter, modify the "Global counter" row, otherwise find the corresponding counter and modify that.
If you don't want to create a test order and the counter you want to modify does not exist yet, you can manually create a counter with the + icon in the last row of the table. Your browser will ask you for the counter name and then send the request to your server to create a counter with that name and initial value 0. To create the global counter, simply leave the field completely empty.
Please read the section on format-specific counters to determine the correct counter name for your format. In particular, the counter name will be the format string where all variables like [year] etc. have been replaced with their corresponding value at the time an order is made. Only the counter (the #) is left unchanged.
In addition to the pre-defined variables, it is possible to define custom variables for use in the number formats in the "Custom Variables" tab of the plugin configuration:
customer_number_formatto change the corresponding number format only for special conditions. In the above example, free orders use an invoice format "Free-[#####]" (first table row), which overrides the configuration of the invoice number format only for those specific orders.
Starting with version 5.99, this plugin uses the Joomla 3.x updater to install new versions. For this to work, you need to enter your updater credentials (order number and password of the purchase at open-tools.net) in the plugin configuration page:
The updater will then access the download at open-tools.net with these credentials, which unlock download access. If you enter invalid credentials, then the plugin will work just fine, only updates are not available:
Please note that the automatic update feature for paid plugins (that need some kind of password to unlock the download) is NOT available in Joomla 2.5!
This plugin is licenced unter the GNU GPLv3. However, you have to pay for the download (all updates are free to our customers). After that, you have all the right and duties that the GPL gives you.
2016-05-03: Version 4.0.2 (Bug fix for old php version 5.3)
2016-04-28: Version 4.0.1 (Add onVmOrdernumberPostprocessNumber trigger to allow other plugins to post-process the generated number)
2016-04-10: Version 4.0 (Automatic updates through the Joomla updater; code factorization into a library)
2015-12-12: Version 3.6 (Fix manual invoice creation for old orders)
2015-12-03: Version 3.5 (Fix automatic invoice creation)
2015-11-16: Version 3.4 (Fix JS call; Fix SQL update script erasing counters)
2015-11-15: Version 3.3 (Workaround for changed VM invoice creation)
2015-06-12: Version 3.2 (Fix counter editing)
2015-05-15: Version 3.1 (Fix bug with global counter)
2015-04-24: Version 3.0 (Added custom variable definitions; some more variables; counter properties directly in the number formats)
2015-03-08: Version 2.2 (Fix jQuery on VM3 / Joomla 2.5)
2015-02-08: Version 2.1 (Add hooks to allow other plugins to extend the ordernumber plugin)
2014-12-02: Version 2.0 (Counter values can be changed in the plugin configuration)
2014-10-05: Version 1.13 (Fixed a small packaging glitch, no changed functionality)
2014-10-04: Version 1.12 (Add possibility to give custom counter names; VERY ADVANCED feature, Not meant for an average installation)
2014-10-01: Version 1.11 (Fix issue with invoice numbers in certain configurations)
2014-09-06: Version 1.10 (Fix some minor issues with Joomla 3.0)
2014-08-16: Version 1.9 (update for Joomla 3.x and VirtueMart 3.x compatibility; drop Joomla 1.5 support)
2013-02-26: Version 1.8 (add backward support for the outdated Joomla 1.5)
2013-01-22: Version 1.7 (implement country variables)
2013-01-11: Version 1.6a (fix some update problems from 1.5 to 1.6)
2013-01-09: Version 1.6 (customer numbers can also be customized)
2012-11-16: Version 1.5 (implement padding the counter with zeros)
2012-11-23: Version 1.4 (fix random elements in the formats)
2012-11-17: Version 1.3 (fix python 5.2 for real; fix German translation)
2012-11-15: Version 1.2 (fix for phython 5.2; only create invoice number when neccessary)
2012-11-14: Version 1.1 (implement variables derived from user data)
2012-11-12: Version 1.0 (initial release for Joomla 2.5)