In this tutorial, you will learn how to write code that will save data using Episerver Commerce. Trying to create, update and save objects in commerce can cause quite a lot of confusion as there are lots of APIs that do similar things. It is really frustrating when you use the wrong API and it doesn't do what you hoped it to. If you want to avoid this frustration, this is the article for you 🔥🔥🔥
Episerver Commerce has three main API's for saving data into the database, IContentRepository, business foundation objects and metadata plus. Each API has a specific purpose. When writing data, you will mainly want to update three main areas:
- Working with products/variants within the catalogue
- Working with the built-in Episerver Objects
- Working with custom objects
Updating products/varients in the Commerce catalogue
To update products and varients, you will use the IContentRepositoryAPI (read this to learn more). You can use IContentRepository to write data back to the CMS for products and variants using the Save():
To update product data you will first need to define some products and varients. Defining content in Commerce follows the same process as the CMS. Create a new class that inherits from a Commerce base class. Decorate the class with the [CatalogContentType]. Add the standard things like Name, Description, and GUID to add related meta-data.
Working with the built-in Episerver Objects
If you look in Commerce Manager in the Administration section, you see these two folders:
These folders represent the default Episerver objects that you can query and update. The screenshot above is a good visual example of where within Commerce manage the different APIs store data. MetaDataPlus is the original API that shipped with Commerce to access these items. Meta Data Plus will allow you to extend the default Commerce objects, known as Meta Class by adding on extra properties, known as Meta Fields.
From Episerver Commerce 7.5 forwards, I would not recommend using Meta Data Plus for updating products from the catalogue. Meta Data Plus should only be used if you want to extend the out-of-the-box catalogue/order metaclasses.
In this example, metaClassName would represent the Contact class. Contact is a default Commerce object, that lives in the [cls_Contact] database table. The classes you can access and update via Meta Data Plus, include Contact, ContactNote, Address and Organization.
Business Foundation Objects
If you want to create your own custom objects within Episerver commerce, the Business Foundation Framework is your friend. Business Foundation Framework was created a few versions after Meta Data Plus. Business Foundation objects allow you to create new Meta Classes. You can then add custom properties within these objects.
When you create a new class using Business Foundation, Episerver will create a corresponding database entry in the Commerce database. Business Foundation Objects and the Meta Data Plus API have very similar and overlapping features. Personally, I think it can be a little confusing to know when you should use each one, so be warned. The snippet below shows you how to query a business object called, Contact and then add a custom property called MiddleName onto it:
To access your business foundation objects, you can use the following MetaModel instance, to get access to all the business foundation objects in the system. This can be done using the following snippet:
If you are still unsure about the two different APIs, hopefully this will make it clearer:
There are two different MetaClass tables within the Commerce databse. If you use a Meta Data Plus object the data definition will be created in one table. Items like Contact, Organization, and Address live in the [mcmd_MetaClass] table.
If you use business foundation objects the data definition will be created in the other. In the [MetaClass] table things like OrderForm, LineItem, and all your custom catalogue definitions can be found.
If you find yourself scratching your head why you can't access some data, the first thing you should do is to make sure you are using the correct API! You can check the database tables to see where the data has been created.
IContentRepository, business foundation objects and meta data plus are the three APIs to save content within Episrver Commerce. You should now know what to use each one. Happy Coding 🤘
