Order Number Generation

This article applies to Active Commerce 3.2+.

 

How are order numbers generated in Active Commerce?

Active Commerce taps into the ID generation capabilities of NHibernate in order to efficiently generate order numbers in a way that scales across multiple servers. Specifically, Active Commerce uses the Hi/Lo ID generation algorithm, which essentially grabs "batches" of IDs from the database to use as order numbers. In a webfarm configuration, each server can grab its own ranges of IDs to use, until it needs more. As a result, you may see order numbers that appear to be out of sequence, or you may experience gaps in order numbers if a server or application pool is recycled. This is to be expected.

 

Tell me more about the Hi/Lo algorithm!

You can find some great explanations of NHibernate Hi/Lo on Stackoverflow and in developer blogs:

• Stackoverflow: What's the Hi/Lo algorithm?
• Code Project: NHibernate HiLo Identity Generator
• Vlad Mihalcea: The Hi/Lo Algorithm

 

Where can I find the "Hi" and "Lo" values?

The current "hi" value can be found in the nhibernate_unique_key table in the Active Commerce database, where the entity is "ActiveCommerce.OrderNumber."

SELECT [next_hi],[entity]
FROM [hibernate_unique_key]
WHERE entity = 'ActiveCommerce.OrderNumber'

The "lo" or increment number is found in the XML configuration setting ActiveCommerce.Orders.OrderNumberBlockSize, and defaults to 10. You can utilize a configuration patch to raise this value, but we only recommend this if you are sure you need to do so for performance reasons. Note that lowering the value after you have begun collecting orders is dangerous and can result in duplicate/overlapping order numbers!

If you really must avoid any gaps in order numbers, you can set the block size value to 0.

 

How can I change the starting order number?

The starting order number will be Hi*Lo+1, so in a vanilla Active Commerce install, the starting order number is 11. If you wish to start your order numbers at a higher number, update the next_hi value in the nhibernate_unique_key table in the Active Commerce database, where the entity is "ActiveCommerce.OrderNumber."

UPDATE [hibernate_unique_key]
SET [next_hi] = 2000
WHERE entity = 'ActiveCommerce.OrderNumber'

The above statement would result in the first order number being 20001.

 

What about adding a prefix or suffix to the order number?

As of Active Commerce 3.3, you can do this by patching the ActiveCommerce.Orders.OrderIdPrefix and ActiveCommerce.Orders.OrderIdSuffix settings. These default to blank values (disabled) and can be found in xActiveCommerce.OrderProcessing.config.

The total Order ID length must not exceed 128 characters. Prefix and suffix values may contain the following character types:

• alphanumerics
• dashes
• underscores