Sitecore XC 9.0.2 – Create your custom order IDs

I was already asked a few times, if it is possible to set your own order confirmation ids in Sitecore Commerce Engine. The answer was always, that this is of course possible. Within this article I would like to tell you, how easy it is, to achieve that.

First of all we have to find the place, where we have to hook in to change the standard order confirmation id creation. As you can see in the screen below, I had a look into the node settings configuration file and especially had a look at the ICreateOrderPipeline.

2018-11-01 16_29_37-logs

This Pipeline includes a bunch of different blocks, as well as a bunch of other Pipelines, which are triggered. For our task, we have a closer look at the IOrderPlacedPipeline, cause it includes the block we need to change, the OrderPlacedAssignConfirmationIdBlock. As the name already tells us, this block is responsible for setting the order confirmation id after the order was created.

Now that we know, where the confirmation id is generated and set, we now have to find out, how we can do that on our own. Therefore we can have a look at the existing implementation via dotPeek, or some other tool.2018-11-01 16_03_27-Customer.Sample.Solution - Microsoft Visual Studio

In the screenshot above, you can see the implementation of the mentioned block. In the highlighted part you can see, that the generation of a confirmation id is done by a custom processor called GenerateUniqueCodeCommand. So what we can do now within our block is just to use a custom command, which generated a unique code the way we want to have it. In the screen below you can see the example implementation of our custom pipeline block.2018-11-01 16_05_15-Customer.Sample.Solution - Microsoft Visual Studio

You can see, that is looks very similar to the standard one, except the part, that we call a custom command for generating the code.

Within the next screens you can see the implementation of that custom processor and how the code generation is done.

2018-11-01 16_49_36-Customer.Sample.Solution - Microsoft Visual Studio.png

In the screen above you see the basic structure of the command with properties and the entry point. The more interesting part is the helper function CalculateOrderConfirmationId. What I implemented within this little show case is the following functionality

Every order id has a

  • prefix
  • suffix
  • and a numeric portion, which is incremented from order to order

Of course you can implemented here any logic, your business case needs. You only have to take, that every generated id is unique. Otherwise the pipeline would fail and the order would not be created.

To be as flexible as possible, we use a custom policy to make some general settings. In the screen below you see the UniqueCodePolicy with its properties

  • Prefix (The prefix of every order ID)
  • Suffix (The suffix of every order ID)
  • ShopNameAsSuffix (Possiblility to use the shop name as prefix of the order)
  • ShopNameAsPrefix (Possiblity to use the shop name as suffix of the order
  • DigitsFormat (The format of the numeric portion of the order ID, especially the number of digits to us)
  • ShopNameAsUpper (Flag to determine if the shop name should be upper case, in case the shop name is used as prefix or suffix)

2018-11-01 16_07_16-Customer.Sample.Solution - Microsoft Visual Studio

For my show case I set the following values for our newly created policy. Every order should use the shop name as prefix in upper letters and use the word SITECORE as suffix. The format of the digits portion in between should be 5 digits.

2018-11-01 16_07_30-C__Code_DemoCommerceEngine_src_Sitecore.Commerce.Engine_wwwroot_data_Environment

Now lets investigate the logic of our code generator. At first we extract all the values of our policy and use them to correctly set our prefix, suffix and digits format.

2018-11-01 16_07_56-Customer.Sample.Solution - Microsoft Visual Studio

You can see, that with the given prefix and suffix we try to grab the order with the highest numeric portion in between to increment that for our current order. In case we do not get a valid number, we fallback to the standard code generation command, so the order creation process is not interrupted.

2018-11-01 16_08_20-Customer.Sample.Solution - Microsoft Visual Studio

In the screen above you see the implementation details of the GetLatestUsedId, which returns the highest numeric portion of an order, which matches the given prefix and suffix. This ensures, that e.g. for the case, we use the shop name as prefix or suffix, we have different counter for the different shops. For example we then cover cases like B2C0001SITECORE and B2B00001SITECORE for orders of the shops B2B and B2C. If we do not use the shop name within the order confirmation id generation, we only have one counter, which is always incremented. And of course this is only an example implementation, of how it could be done. How you do it within our own implementation is highly depended on the given business needs. But this implementation gives you everything and especially inspiration to build your own custom command.

After we implemented our own block and command, we finally have to patch the commerce pipelines in the right way. The next screen shows, how to do that.2018-11-01 16_08_38-Customer.Sample.Solution - Microsoft Visual Studio

We simply remove the existing block and insert our own one at the same position. The result is seen in the extraction of the node settings after the changes are made.2018-11-01 16_02_30-NodeConfiguration_Deployment01_6e5dc404637c411cb225b423b1fcb3c1.log - Editor

If we now create some new orders, we can see, that the order confirmation id ib s now generated the way we want to have it. The following two screens show the the first two orders I created after implementing the custom block.2018-11-01 16_09_12-Postman

Note: The first order was created with the Setting ShopNameAsUpper = false and the second one with ShopNameAsUpper = true. Therefore the prefixes look different although they were created by the same shop.2018-11-01 16_09_33-Postman

We can see that as prefix we get the current shop name of the shop from which the order is generated. In our case it is CommerceEngineDefaultStorefront in upper letters. The suffix is simply the word SITECORE. And in between we have a numeric portion with 5 digits which is incremented with every order automatically.

So within this article you learned how easy it is to interfere with the default order confirmation id creation in patching the exiting pipeline with your own block and command. Within that command you are totally free in how you create the order confirmation id, but here you already got some inspiration in how it can be done for some specific business needs.

If you want to have a closer look at the complete implementation, the whole source code is uploaded to my git repository and is available under

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s