This is second part of my blog post series on Building a Kentico E-Commerce Chat Bot. Make sure that you have read part 1 of the series before continuing. The goal of this post is to review and setup of the Kentico e-commerce side of the solution.
Kentico 10 provides us two key pieces of the overall solution. We are going to use it's e-commerce features to house all of the order data that we need. Since Kentico gives us the ability to have Orders with status, history, tracking number, why not?
After that we are going to use one of its built-in integration options to interact with our chatbot, the REST Service. The REST Service in Kentico has been around for years. I have used it many times and posted on it before here at my blog including Building a Content Slider with the REST.
The real power of the REST Service is that you can securely query any object, page, or piece of data that you have in your Kentico site via HTTP requests. You can also finely control the response payload to shape the data however you want. Need XML or JSON format? No problem. Need only 3 columns of data instead of all 50? No problem.
The only downside of the REST Service is that if you want to get complex results that join multiple objects together, it is pretty tough to do so without custom code. So it is not always the correct tool based on your requirements. But for this project it does the job just fine.
Mocking the Order Data
First, if you are going to follow along you can simply go download and install Kentico with the Dancing Goat starter site template.
Once you have it installed, the easiest way to generate some e-commerce data to play with is to use one of my favorite features of the demo site, the Generate Sample Data ability. This can be found by navigating to the Pages app. Once there, expand out the Special Pages node of the content tree and click on Generator. This should bring you to page tab of the Generator page and give you the ability to click on the Generate button to generate some on-line marketing and e-commerce data.
Once you click the button it will take a few seconds, but when the process is complete your Kentico demo site will have all the e-commerce orders, customers, and products that you need for this example. It's pretty cool.
Pro Tip: If you need more control over generating test data in your Kentico site, check out my post on How To Generate Realistic Test Data in Kentico.
Configuring the Kentico REST Service
Secondly, we need to configure the REST settings in our Kentico instance to allow for communication to happen. The Kentico documentation on how to enable the REST Service will work just fine here. It mostly involves adding one web.config setting (that also gives you extensionless URLs working). So update the modules line in your web.config file (the one towards the bottom of the file).
Then enabling the correct settings in the Settings app. You will find those Integration -> REST settings tree as the documentation states. During development, you don't have to lock down the service by configuring Allowed object types and Allowed page types, you can pretty much just enable the service and allow read-only Object access. Once your project is complete, you may want to add in only the objects you are working with in the Allowed Object Types setting. If you want to, you can mimic the settings I have shown below.
Pro Tip: Not sure what object types are in Kentico, or need to figure out which one to use? Have no fear. Kentico 10 includes a new feature for viewing Object Types.
However, at this point I always recommend creating a Kentico Role that secures what users can interact with the REST Service, and which modules that those users have access to. Don't be a lazy developer and just use your Global Administration account! I know it is tempting, but trust me. Of course, I then recommend creating a User that your application will use to access the REST Service that is in that role. So let's do just that. Follow the steps below.
- Create a new Role: RESTful
- Create a new User: RestUser
- Give it a password you can remember, set the user as None (Privilege level)
- Make sure you assign the new user to the site, and assign the user to the RESTful role.
- Configure the RESTful role permissions to have read only access to the Kentico E-commerce Module. (check all the checkbox with Read in the permission matrix).
After these steps your permission matrix should look like (click the image to enlarge it and see more):
Query Your Data via REST
Now that the configuration is done, and we have some test data, let's try it all out. The Kentico REST Service has a few very specific syntax parameters on how to interact with it. They are best described on the Getting data using REST documentation. I am not going to re-write all of that. In fact, I am going to make it real easy for you by providing the URLs you need. But first, let's check that the setup is correct.
Navigate to a URL like this on your test site:
It should prompt you for basic authorization credentials. Use the RestUser account we created above to authenticate in the browser. It should authenticate you and bring you an XML result set of all of the customers in your test site.
If this works you are in a good spot. If it doesn't work, chances are something is wrong with your security permissions. Go back and double check the role, user, and permission setup.
Now, XML is pretty old school, and not my favorite way to deal with webservice data. Luckily, with a simple parameter Kentico allows us to return JSON. You can also add more parameters to include a Where clause as the documentation above states. These are the types of URLs that chatbot will work with.
Notice the use of where=, columns=, and format= in the querystring. Now we are actually querying the site by email address to find e-commerce customers, and return the customer object in JSON format while specifying only certain object attributes to be returned (instead of everything possible).
Now that we have the Kentico solution ready to go, part 3 on Building a Kentico E-commerce Chat Bot is going to go into setting up the Chat bot. I'll show you how to log into the Azure Portal and create a Bot Service for the first time. Hopefully Microsoft won't have changed the name of the thing by then either. Look for it coming soon.