Sitecore Experience Commerce – XC9 – Getting started with Postman

When you will start working with Sitecore Experience Commerce, one of the most important tool that you will need is Postman to run your API calls for various purposes.

This blog is a walk through about how to set it up and get started with it. The example is based upon Sitecore XC9 initial release. It assumes that you have downloaded and installed Postman on your local environment.

1-Disable SSL verification

The first think that you want to do is disable SSL verification from the File > Settings > SSL certification verification. This settings needs to be turned off.

2-Disable AntiForgery Settings

This settings should always be enabled during the production environment, but for requesting API through Postman tool this setting needs to be disabled.

Navigate to \CommerceAuthoring_Sc9\wwwroot\config.json and set the value for AntiForgeryEnabled to false.

3-Import Postman sample scripts

There are various API scripts that are available within the  \Sitecore.Commerce.Engine.SDK.2.0.1922\postman deploy folder location. All you have to do is import them before so you start playing around with the API calls

1-Click on the top import button

2-Select Import Folder and navigate to Sitecore.Commerce.Engine.SDK.2.0.1922\postman location and start uploading scripts.

After the import of the DevOps folder new set of calls will appear in the left hand panel

3-Import the other folder and the individual files too and you will end up with lots of collection as below:

4-Bootstrap Sitecore Commerce

To bootstrap you first need to get the authentication token

If everything is correct, it will generate a token which can be used in subsequent calls

Then scroll down in the left hand panel and under SitecoreCommerce_DevOps > 1 Environment Bootstrap click on Bootstrap Sitecore Commerce

If everything is correct, the Postman will show a success message like this:

Error: The required antiforgery header value “X-XSRF-TOKEN” is not present.

If you are trying to bootstrap and you get this as 500 error

Check the logs at \CommerceAuthoring_Sc9\wwwroot\logs

If the error message is related to antiforgery as below, then you need navigate to \CommerceAuthoring_Sc9\wwwroot\config.json and set the AntiForgeryEnabled  value to false. Also do an iisreset or recycle the app pool

ERROR Connection id ""0HLBOLTT3AJ84"", Request id ""0HLBOLTT3AJ84:00000001"": An unhandled exception was thrown by the application.
Microsoft.AspNetCore.Antiforgery.AntiforgeryValidationException: The required antiforgery header value "X-XSRF-TOKEN" is not present.
   at Microsoft.AspNetCore.Antiforgery.Internal.DefaultAntiforgery.d__9.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Sitecore.Commerce.Core.CommerceController.d__13.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionFilter.d__4.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.d__14.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.d__22.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResourceExecutedContext context)
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.d__17.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.d__15.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Builder.RouterMiddleware.d__4.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Builder.RouterMiddleware.d__4.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Authentication.AuthenticationMiddleware.d__6.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Cors.Infrastructure.CorsMiddleware.d__7.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Sitecore.Commerce.Core.ClientCertificateValidationMiddleware.d__4.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Diagnostics.StatusCodePagesMiddleware.d__3.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Sitecore.Framework.Diagnostics.DiagnosticMetadataMiddleware.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Sitecore.Framework.Diagnostics.DiagnosticPageMiddleware.d__4.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Server.IISIntegration.IISMiddleware.d__11.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Hosting.Internal.RequestServicesContainerMiddleware.d__3.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http.Frame`1.d__2.MoveNext()


That’s all there is, checkout the other sample API calls and get familiar with them!

Happy Sitecoring!

Naveed

Advertisements

Sitecore Experience Commerce – XC9 – First Look and Feel

Sitecore released their much awaited module – Sitecore Experience Commerce (or XC9 in short) in late January 2018. As an avid Sitecore enthusiast, I was eager to learn more about it. On a free weekend, I decided to install and play with it. This blog is about the first look and feel about the XC9 module and only explores very high level features. The detailed documentation about the module can be found at the official site.

The Storefront

Once the installation is complete, the modules comes with an sample store called the Storefront.

The home page comes with featured carousel and product list components (SXA based)

Clicking on any of the top menu items (for example Appliances) will present the list of products with filtering and sorting options:

Clicking on an individual item will take the user through to the product details page, where the user can add the product in their shopping cart:

The Checkout Process

The checkout process is very user friendly and can be compared with any top of the line commerce stores. For example if the user decides to add a laptop and click on the ‘View Cart‘ link from the top right, the user will be shown the summary of cart:

The user can either click ‘checkout‘ or click ‘continue shopping great products‘. If the user decides to click the ‘checkout‘ button, the next screen asks for delivery details to calculate additional shipping charges:

The user can check ‘Ground’ option and click ‘Continue to billing’. The next screen asks for ‘Billing’ details and also includes shipping charges:

Before the user can continue,  the user must validate credit card details. At the moment, the system is configured to use Braintree sandbox account. The user can enter any of the test credit card details available from the Braintree website and click ‘Validate Payment’:

Once the credit card has been validated, the user can proceed to the final review screen before hitting ‘Confirm Order‘ button:

The final screen will show order confirmation number:

That was an amazing experience for buying a product and as a user, I am very much impressed!

The Business Tools

So that was the customer experience, now lets see what is there in the for the back office administrators. After installing the XC9 module a new icon as ‘Business Tools’ should be available for admin users from the Sitecore Experience Platform dashboard.

The Business Tool dashboard comes with 7 sub-modules to manage the store.

  • Merchandising
  • Inventory
  • Pricing
  • Promotions
  • Orders
  • Customers
  • Relationship Definitions

Since the user has just made a purchased, lets checkout what is in the ‘Order’ module

Clicking on the ‘Order’ link from the dashboard or side link, the admin user can see one order is in the ‘Pending’ state:

Clicking on the pending order link, the admin user can see the details about the order:

This out of the box back office processing system for admin users looks amazing as they can instantly see all the order summaries and details. I will pause the exploring rest of the commerce modules as they require much more detail and perhaps another blog.

The Storefront Content Tree

The Storefront content tree is based upon conventions and structure introduced by SXA module. The SXA modules comes with 80+ components for speeding up the development process.

A new set of commerce components are added in the SXA toolbox library.

All of the pages in the Storefront are developed using SXA or Commerce-SXA components.

Summary

As you can see, Sitecore Experience Commerce 9 is a very rich and extensive module for developing an online store. In this blog, I have only scratched the surface of the module and I am super excited about it. The 40+ commerce SXA components, the 7 back office processing modules, and additional 80+ standard SXA components for rapid website development, all together deliver a knockout punch in the online commerce industry

In my opinion, Sitecore XC9 module will definitely meet the expectations of any business looking for a modern, cloud-ready and secure online store. So, if you manage an online store and looking for replacement options, do evaluate  Sitecore Experience Commerce out before making any decisions.

Thanks

Naveed

Installing Sitecore 9 on Mircosoft Azure Cloud as PaaS : Know your options

Installing Sitecore 9 on Microsoft Azure Cloud as PaaS has never been easier than before. There are 2 main routes that you can take:

  1. Install via Azure Market Place
  2. Install via Sitecore Azure ARM Templates

I have blogged about both options 1 and option 2 previously, but with Sitecore 9 release there are some updates. This blog is just a follow up about the changes since last release and it is based upon Sitecore 9.0 and Sitecore Azure Toolkit 2.0.

Option 1 : Install via Azure Market Place

The Azure Market Place module for Sitecore has been updated with a nice 4 step wizard. The configuration wizard will ask you to choose your Sitecore version, choose your region, add your own credentials, review legal terms and conditions, click the magic button and let Azure do its business.

I believe any non-technical person with an Azure account can do this installation without any help or bugging IT to setup servers for Sitecore 9. Bonus information, you can tick the box for Sitecore Experience Accelerator 1.5 during the installation wizard and SXA will be installed as well for you to play around with 80+ pre-built components like Carousel, Gallery and so on. The following screen shot from the Azure portal is showing different resources that were deployed successfully after I ran the Sitecore installation wizard for Single  (CM & CD combined) size.

Option 2 : Install via Azure ARM Templates

This is slightly more technical option as you will need to manually configure ARM templates (read JSON files) and use Windows Powershell. I have blogged in detail about this earlier so I will not go in details this time. I will only mention what I found was different for Sitecore 9 installation and the issues I ran into during the installation process.

There were 2 changes:

  1. You have to supply a secure certificate’s blob and it’s password within the parameters file.
  2. You have to use ArmTemplateUrl parameter instead of ArmTemplatePath  for the Start-SitecoreAzureDeployment command.

As given on the Sitecore documentation site, you need to generate the self-assigned certificate, export it and get its blob. I have combined the scripts into a single script and added additional code to get the blob so you can easily get the required secure certificate blob by running the following script:

PS C:\azure\sitecore-azure-2.0> .\self-assigned-ssl.ps1

I wanted to deploy the XP topology so I updated the azuredeploy.parameters.json file on my local machine with information as below:

Then I created a xp1install.ps1 file with parameters and raw link to the ArmTemplateUrl from the quick start templates section: (this is optional step, you can enter these values directly in PowerShell too)

From the Windows Powershell command line, navigated to the Sitecore Azure Toolkit 2.0 folder and ran this command

PS C:\azure\sitecore-azure-2.0> .\xp1install.ps1

Waited about an hour or so and the XP installation was up and running on Microsoft Azure Platform.

 

If you look closely in the screen grabs above, 19 resources were deployed during the single type of installation and 31 resources were deployed during the XP installation.

Errors during Azure ARM

I ran into 2 errors during the Azure ARM deployment:

Error 1 – InvalidTemplate Error

Initially, I was using ArmTemplatePath and was providing the full path to the template on my local machine, but it turns out, that I needed to provide ArmTemplateUrl as mentioned in this blog. Supplying the correct parameter with Github’s path resolved this error.

Error 2 – Cannot find certificate

I was supplying the path to the certificate instead of the base64 encoded string. Thanks to the Sitecore Slack community that came to the rescue and I was able to resolve this by generating the secure certificate correctly and supplying it’s blob value.

I hope it is going to help if you are doing Azure ARM deployments with Sitecore 9 in coming days!

Thanks.

Sitecore 9 SIF installation error : ERROR_SCRIPTDOM_NEEDED_FOR_SQL_PROVIDER

Sitecore 9 was announced at the recently held Sitecore Symposium 2017 and it comes with lots of new features and improvements. One of the major change to the platform is the way you install Sitecore on a server or local machine. The standard .exe installer has been replaced with a Windows PowerShell module which is called Sitecore Installation Framework (SIF). The SIF comes with Sitecore related pre-built tasks and configuration files to facilitate installation of Sitecore.

As a Sitecore enthusiast, I wanted to get my hands dirty with this new SIF module. After reading the official guide, I found out there were few pre-requites that were required even before running the SIF module. The 2 main ones were SQL Server 2016 and SOLR 6.6.1. In addition, the Solr instance must be running over https to make sure all the communication is secured.

The details of the installation process is given in the official guide but I will just mention few high level steps for local install:

Step 1: Configure and Install SOLR

So lets install Solr, sounds easy as I have done it few times before and I am sure you would have too. However, installing the secure certificate was bit tricky on localhost, but thanks to the Sitecore community, this SSL script from Kam’s blog worked like a charm and I had Solr 6.6.1 running over https in no time.

Step 2: Install SQL Server 2016

I had multiple versions of SQL Server (2012,2014) running side by side on my machine and installation of SQL Server 2016 Express wasn’t a problem as well. I ran the standard SQL Server 2016 installer and it was installed as expected (or I thought so).

Step 3 : Install Sitecore via SIF

As per the installation guide, I registered the SIF module via PowerShell and ran the following script: (I just added -Verbose at the end of each command so I can see the debug information during install)

I was expecting it to install Sitecore 9, but after the first run I got this error:

The error suggested that I have to install additional SQL server modules for Web Deploy to work, as given on the Microsoft’s website

DacFxNeededForSQLProvider,

ERROR_SCRIPTDOM_NEEDED_FOR_SQL_PROVIDER,
ERROR_SQLCLRTYPES_NEEDED_FOR_SQL_PROVIDER

The group of 3 errors listed above share the following diagnosis and resolution:

Diagnosis: SQL DAC and its dependencies are not installed.

Resolution: Use Web Platform Installer to install:

  1. Microsoft SQL Server 2012 Data-Tier Application Framework
  2. SQL Server 2012 Transact-SQL ScriptDom
  3. SQL Server System CLR Types 11.0

I installed the above dependencies and ran the script. It failed again with the same error message.

I was sure that my SQL server installation is correct and I have installed module related to ScriptDom but what is wrong with Web Deploy ?

Then I found this article on Sitecore KB https://kb.sitecore.net/articles/019579 for Sitecore Azure Toolkit 1.1 which mentioned to add registry values for the Web Deploy for DAC dependencies path.

I was bit skeptical at first but decided to go ahead with this approach. I added the 2 registry values via regedit. For one of the values, I have to point the path to the recently installed SQL Server 2016 SDK folder. For the second registry value, I have to point the path towards VS 2015 DAC folder. I do want to mention here I also had multiple versions of VS (2013, 2015 and 2017) installed on my local machine.

The registry values were:

DacFxDependenciesPath : C:\Program Files (x86)\Microsoft SQL Server\130\SDK\Assemblies

DacFxPath : C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\130

The actual screen shot of the registry values for Web Deploy:

Ran the script again and BOOM! it worked.

So it turns out since I had multiple version of SQL servers and also multiple versions of VS installed on my local machine, the Web Deploy 3.6 was not able to figure out what is the path for the SQL dependency dlls to install the SQL DAC packages for Sitecore 9.

By the way, if you are installing Sitecore 9 for the first time,  Do check out the following posts:
How to Install Sitecore 9 with the Sitecore Install Framework 
Gotchas while installing Sitecore 9 using the Sitecore installation framework

The lazy developer’s way to install Sitecore 9
Introducing SIF-less for Easy Sitecore 9 Installation
Low-effort SOLR Installs 

I hope this blog will help any other developer facing the same error.

Happy Sitecoring 🙂