Metadata draft pr

[shahmayur001]

Meta Data Release

[WIP] Stuff left to do

• Write a description for meta programming
• API collection for request example
• Fix Coverage
• Add metadata for User, LineItem, refund
• Remove from variant
• Fix test cases

Breaking Changes

This feature breaks sqlite versions predating to December 2023, verify your requirements before migrating.

Introduction

Overview

This PR introduces the concept of metadata fields to solidus. The purpose of metadata fields is to allow customers and admins alike to provide additional information to transactions to either extend the informations contained or allow to insert additional data to correlate transactions with third party systems.

Examples for data can be:

• any transaction itself such as orders, RMAs, payments and stock movements;
• individual items contained inside an order (line items);
• match users with 3rd party systems.

Possible Applications on a very high level are:

• customers that want to add Purchase Order information to an order;
• administrators that want to add a ticket number to an RMA.

The current scope of meta data are following ressources:

• Order
• CustomerReturn
• Payments
• ReturnAuthorization
• Shipments
• StockLocations
• StockMovement
• Users
• Line Items

How is the additional information stored?

for each of the above resources two columns have been created:

• customer_metadata
• admin_metadata

The resources store the information as jsonb.

What is the access model?

Cancancan has been used to allow users to write data with the current scope just extended by the additional fields:

• Users can create / delete / alter metadata on orders only till the payment itself is processed,
• Admins have universal access R/W access to metadata at all stages of transactions.

Testing

Extensive test cases have been added.

Detailed Overview

Types of Meta Data and why we need it

Overview

Meta data can be broken down in three large topics visible in the table below:

	Use Case
Administrative Metadata	Information required to correlate all transactions to 3rd party systems.
Customer Metadata	Information allowing customers to customize orders (eg options to store information like a text string or link to an image) or correlate transactions (such as POs).

Administrative Metadata

We do not believe that solidus is used anywhere as standalone system (edge cases excluded of course). Transactional resources are either by nature integrated with 3rd party systems (eg Payments, Billing in Italy with eInvoicing) or by operational requirement (ERP, CRMs like Salesforce,...). For that purpose I see meta data as a senseful extension on admin site for all transactional ressources (also payments, stock movements (even if we won't use them) and RMAs. Given that more and more countries switch to eInvoicing (Germany is next and US has had testing phases for B2B in 2022) in the coming years I personally (and I might well be alone with that opinion) deem meta data on orders a hard requirement to future proof the system.

Customer Meta Data

Customer meta data allows users to customize a cart (incomplete order) with either administrative (PO numbers,...) or customisation information (eg an URL to a picture to customize a shirt, text strings for incisions or in our case IMEIs to relate to a subscription) allowing to significantly extend the features without changing the underlying model. Fields should be accessible on front-end and backend.

Schema

Meta Data should net a reliable outcome:
"key1" : "value1" should be as applicable as "key2" : "value2", without restriction other than the quantity of storable key value pairs and limitations of the dimension of the value given that json as a format does not pose limits we should do that server side. I think it's a front-end job to render the information correctly for the public.

Scopes & Arrays

Nature of the Values

The system is agnostic to the value contained. A decision has been made to store the data in additional columns in a jsonb which by now is relatively widely supported. Some preexisting installations might have to upgrade DBs, older sqlite versions dating before Jan 2024 are therefor not supported and need to be updated.

"key1" : "value1" should lead to the same behaviour as "key2" : "value2" without requiring modification inside the code. Reasonable provisions should be taken inside the code base to edit the quantities and content size of key value pairs and appropriate errors should be returned where rate or size limits are exceeded.

Administrative Meta Data

Allow appropriate roles to customize resources with private fields not end-user accessible.
R/W = Read and Write Access

	Admin	Use Case
Order	R/W	Add 3rd party system reference fields such as PO-Order or Dropshipping reference
Line Item	R/W	Add information to customize object such as link to an image for customization of a product or relate to a 3rd party system reference
RMA	R/W	Add 3rd party system reference fields such as PO-Order or Dropshipping reference
Payment	R/W	Add 3rd party system reference fields such as PO-Order or Dropshipping reference
Order	R/W	Add 3rd party system reference fields such as PO-Order or Dropshipping reference
Shipment	R/W	Add 3rd party system reference fields such as a delivery note
Payment	R/W	Add 3rd party system reference fields for payment conciliation

Customer Meta Data

Allowing users to customize an incomplete order (or I'd say a cart) and call the information after a completed order. Admins should in an ideal case be allowed to edit those information after purchase, but I feel that can wait if technical limitations are currently in place.

	User	Admin	Use Case
Order	R/W	R/W	Add 3rd party system reference fields such as PO-Order,
Line Item	R/W	R/W	Add information to customize object such as link to an image for customization of a product or relate to a 3rd party system reference
User	R/W	R/W	Add additional User Fields or References