How to Use Collections in Kontent
Introduction
Kentico Kontent includes a fantastic feature for organizing and producing a content model / content inventory. This feature is called Collections in Kontent. It allows departments and teams to manage their content in logical groups, campaigns, global regions, enterprise business units, or any other way you can think of. Let's take a look at how to use Collections in Kontent and I'll explain why I think it adds value to any large content operation.
The Issue Collections in Kontent Solves
When it comes to organizing large content operations that have global regions or multiple product catalogs across many different websites, most content management systems have the ability to categorize content in a hierarchical way. That means a region or major product grouping can be setup as folders inside of folders to divide out say North American vs. European content items or Automotive vs Healthcare industry targeted products. This approach can work fine, but it starts to get more complicated the larger your solution becomes, and it starts tying your content tightly into that one project or instance of the website you may be building.
This means that different content teams or editors that are based per location or business unit may need to all access the same "content tree" to be able to add, edit, or manage the content that they need. This starts to become interesting when you need different levels of permissions, or content approval workflow based on the different regions or product groupings. What if the North American team needs to have add and edit permissions but can't publish the content because the European team has the ultimate last say in what gets to the live website channel? On top of that does that mean you have one project or installation of the CMS in the EU? Would be slow for the NA team to access it? These are all issues that a great headless cms like Kontent attacks with its Collections feature.
The Setup of Collections
Getting started with Collections in Kontent it is pretty easy. As long as you have the feature available to your project (which is based on your Kontent subscription). For the rest of this post I am assuming that you have access to Collections in your subscription. You begin by logging into Kontent, then choose the project you are working on, and select the Project Settings main navigation menu item in the app. Once inside of Project Settings you click on the Collections. One optional step is to check which Environment you are using in your Kontent Project. It's best to create this first in a non production environment.
You will notice that by default, there is already one Collection in your project. The system does this at the time of the initial project creation. It's what all newly created Content Types and Content Items will be assigned to, and you must have at least one Collection in your project marked as the Default Collection at all times.
Create your first new Collection by clicking the very obvious Create New Collection button. Simply give it a new name and click save. You are now on your way, seriously that is all it takes to start using the feature. In my example, I want to actually model a large enterprise organization that sells products in different regions around the world. So I have created multiple Collections in my Kontent project that represent my organization's global regions that are broken out as my organization is shaped. I have set the North American (NA) collection to the Default collection by simply renaming the original "Default" Collection to "North America (NA)" as it's new name. The results of my Collections are show below.
If you are not sure on how name or setup your collections, the Kontent docs have a few more examples of how to divide up your project in Kontent.
Using Collections from an Editor's Standpoint
Now that you have setup some Collections, let's talk about using them. From an Editor's standpoint you pretty much are always working in one Collection. With Collections enabled the main Content Inventory screen will show you your content items with a new column of Collection. This allows editors to see at all times which Collection the content is stored within.
As you can see below, my organization has different Content Items, the various chairs, of the Content Type, Product, that I am now representing in the different Collections of NA, EU, LATAM, MEA and APAC.
The filter system of the Kontent UI now has a new facet of filter by Collection that allows you to narrow down your content into the Collection that you want to work on. Below I am showing an example of filtering by the Content Type of Product and Collection of North American (NA).
If you are a seasoned Kontent user, you may notice that I am actually using a Saved Filter of the Content Inventory screen to remember my filter choices. You can see this again in the screen shot above for where I have "Globo NA Product View" selected under the Your saved filters area near the top of the screen. This saved filter saves me the time and effort of constantly clicking the filter choices if I bounce between screens in the Kontent app (which I do all the time!).
Pro Tip: Share your Saved Filters! You can share your saved filters with other editors to save them time as well. This feature is pretty killer when you combine it with Collections and have multiple team members working on the same content.
The second aspect of working with Collections is creating Content Items. Click on the Create New button to create a new Content Item and you can see the screen changes to ask you what Collection you would like to create the new Content Item in.
After that choice the normal create Content Item process continues to ask you which type of item you would like to create and the system behaves normally from there.
The last set of differences is around the security of working with content in Collections. When it comes to users and roles, the system shines. Now we can divide up our other team members into all of the Collections on the project, or lock them down to just a single Collection. Here I am giving my good friend and fellow Kontent MVP, Michael Kinkaid access to any Collection in the project. I could actually designate a different role in the NA collection vs. the EU collection if I want to as well. Which is very fitting for Michael as he splits his time between Canada and Ireland... or at least he used to before this whole global pandemic thing. If you are reading this Michael: Cheers mate!
Using Collections from a Developer's Standpoint
For those in my technical audience I'm sure you are interested in how to inject content from the Delivery or Preview APIs that use Collections in your apps. Well it's very simple. Nothing much changes in your code and that is a benefit in my opinion. There is simply a new System filter that you use to pass in the code name of the Collection into the API call.
Even though it sounds simple, it actually took me a second or two to figure out how to do this. The documentation explains what to do, but doesn't actually show the full example. So I'm going to show it here. The key is to use the system.collection querystring parameter if you are using the REST API or EqualsFilter if you are in C# land via the .NET Kontent Delivery SDK.
https://deliver.kontent.ai/<project id>/items?system.type=product&system.collection=europe__eu_
This will get you a nice result set of your content. In my example from up above it gets me this:
The value of the system.collection is from the codename of the Collection item itself in the UI.
Also below is a C# snippet of using the EqualsFilter.
IDeliveryItemListingResponse<Product> response = await client.GetItemsAsync<Product>(
new LanguageParameter("en-US"),
new EqualsFilter("system.collection", "europe__eu_"),
new EqualsFilter("system.type", "product"),
);
IList<Product> items = response.Items;
Watch Me and the Kontent Team Present
If you want to actually watch me demo and talk more on Collections and even hear from the Kontent team themselves on the subject, you can check out the recording of the last North American Kontent User Group on Youtube at my channel or embedded below:
What Collections Can't Yet Do
There is one large limitation of Collections that I feel is fair to bring up. That is the Asset management feature of Kontent, the storage, management, and delivery of images, files, and pdfs has no concept yet of Collections. There is still just the simple folders of Assets that Kontent gives you. I'm hoping that the Kontent team adds in the ability to segment out assets by Collections over time. There is a simple workaround to build more folder structures in the Asset manager, that mimic your Collections, but as you can tell, I'm not a huge fan of nested folders within folders for dealing with content or assets.
Conclusion
I hope that after reading this blog post you can tell that Collections in Kentico Kontent are a critical factor for success for large content operations. I recommend using them in your Kontent project. The feature is definitely more than just a folder. If you are already using them in your project, let me know on twitter at @mcbeev.
