Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Microservices using a Composable Custom Type

Custom Fields are a great way to extend and customize the data model to your business needs. Your microservice can declare the Custom Fields through a custom Type. These fields can then be assigned to resources and be used by, for instance, the Merchant Center or another service.

In our tutorial on Using Custom Types and Custom Fields, we demonstrate how a single service can customize a resource. However, what if you have a microservices-based architecture and would like multiple services to declare fields on the same resource? In this guide, we'll showcase a potential solution using the Composable Custom Type pattern.

Learn more about using Custom Types in our self-paced Extensibility overview module.

Example use case

For our example, we'll assume that two separate services want to add Custom Fields to Line Items. One microservice, the pricing-engine, wants to add some pricing-related information. For instance, a promotional message, like: "Sign up to receive 10% off on this product."

The other microservice, the tax-service, calculates the taxes and wants to save the timestamp of the last tax refresh on the Line Item. Our tax-service is a standard integration that we would like to use out of the box.

To customize the Line Item, the pricing-engine wants to write to a field called priceTips, while the tax-service wants to use a field called taxLastRefreshedAt.

Composing a custom Type

The data on customizable resources can be extended using the custom property, which has a reference to a single Type. Therefore, if both microservices create their own Type, then they couldn't work on the same Line Item. Instead, our services should use a shared custom Type by making the key field of the Type configurable (as opposed to a fixed value).

Using the example of the tax-service, let's look at how a service can add a Type:

  1. Fetch configuration value for Composable Custom Type key, in this case let's use composed-cart-type.
  2. Check if a Type with key composed-cart-type exists in the Composable Commerce Project.
  3. If the Type doesn't already exist, create it.
  4. Add the desired fields (in this case taxLastRefreshedAt) to the Type as optional fields.

For this to work, both microservices must use unique field names. For instance, a field called id has a high chance of not being unique. Especially for standard integration microservices like a tax microservice, consider adding a prefix to the field name. For example, the name of the microservice, tax-service-taxLastRefreshedAt.

Using the custom Type

Now, let's explore how our services can interact with the customizable resource. If a service wants to add a Custom Field, it will first check if the Type already exists on the resource. If not, it will add it. Next, the service proceeds by adding or removing the fields belonging to its own domain. The service will not interfere with fields outside its domain. For instance, the tax-service would only add or remove the field tax-service-taxLastRefreshedAt.

Conclusion

Using the Composable Custom Type pattern, multiple microservices can work with Custom Fields on the same resource. Whether you have a collection of custom microservices or services built as standard integrations, you can extend the data model seamlessly with this approach.