Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Record what a record is called in other systems
Damian Legawiec9e9402ec8d12
diff --git a/spree/core/app/models/concerns/spree/has_external_references.rb b/spree/core/app/models/concerns/spree/has_external_references.rbnew file mode 100644index 0000000000..873cf5f829--- /dev/null+++ b/spree/core/app/models/concerns/spree/has_external_references.rb@@ -0,0 +1,121 @@+module Spree+ # Gives a model identities in external systems (ERP, PIM, DAM, CRM) through+ # {Spree::ExternalReference}. Opt-in per resource rather than on+ # {Spree::Base}: only records a connector actually syncs need the association.+ module HasExternalReferences+ extend ActiveSupport::Concern++ included do+ has_many :external_references, class_name: 'Spree::ExternalReference', as: :resource, dependent: :destroy++ # Scope-friendly so controllers can chain it onto an already store-scoped+ # relation: `current_store.products.with_external_id('erp', 'MAT-100')`.+ # Scoping the lookup to the store is the caller's job, exactly as with any+ # other id coming off a request.+ scope :with_external_id, lambda { |system, external_id|+ joins(:external_references).where(+ spree_external_references: {+ system: system.to_s.strip.downcase,+ external_id: external_id.to_s.strip+ }+ )+ }++ scope :with_external_system, lambda { |system|+ joins(:external_references).where(spree_external_references: { system: system.to_s.strip.downcase })+ }+ end++ class_methods do+ # @param system [String, Symbol] the external system's key+ # @param external_id [String] the identifier that system knows the record by+ # @return [Spree::Base, nil] the record, or nil when no reference matches+ def find_by_external_id(system, external_id)+ with_external_id(system, external_id).first+ end++ # @raise [ActiveRecord::RecordNotFound] when no reference matches+ # @return [Spree::Base]+ def find_by_external_id!(system, external_id)+ find_by_external_id(system, external_id) ||+ raise(ActiveRecord::RecordNotFound,+ "Couldn't find #{name} with external_id #{external_id.inspect} in system #{system.to_s.inspect}")+ end+ end++ # @param system [String, Symbol] the external system's key+ # @return [String, nil] the identifier that system knows this record by+ def external_id_for(system)+ key = system.to_s.strip.downcase++ if external_references.loaded?+ external_references.detect { |reference| reference.system == key }&.external_id+ else+ external_references.for_system(key).pick(:external_id)+ end+ end++ # Creates or updates this record's identity in one external system.+ #+ # @param system [String, Symbol] the external system's key+ # @param external_id [String, nil] blank removes the reference+ # @param metadata [Hash, nil] connector bookkeeping (version, etag, synced at)+ # @return [Spree::ExternalReference, nil] nil when the reference was removed+ def set_external_id(system, external_id, metadata: nil)+ key = system.to_s.strip.downcase+ reference = external_references.for_system(key).first++ if external_id.to_s.strip.blank?+ reference&.destroy+ external_references.reload if external_references.loaded?+ return nil+ end++ reference ||= external_references.build(system: key)+ reference.external_id = external_id+ reference.metadata = metadata if metadata.present?+ reference.store ||= external_reference_store+ reference.save!+ external_references.reload if external_references.loaded?+ reference+ end++ # Writes several references at once, leaving systems the payload does not+ # mention untouched — a connector states its own key without disturbing+ # another system's. Accepts the `{ system => external_id }` map the admin+ # serializers render, or a list of `{ system:, external_id: }` entries.+ #+ # @param references [Hash{String,Symbol=>String}, Array<Hash>]+ # @return [void]+ def assign_external_references(references)+ entries =+ if references.is_a?(Hash) && !references.key?(:system) && !references.key?('system')+ references.map { |system, external_id| { system: system, external_id: external_id } }+ else+ Array(references)+ end++ entries.each do |reference|+ reference = reference.to_h.symbolize_keys+ next if reference[:system].blank?++ set_external_id(reference[:system], reference[:external_id], metadata: reference[:metadata])+ end+ end++ private++ # A reference belongs to the same store as the record it identifies.+ #+ # Store-owning models answer directly (and CompanyLocation delegates).+ # Variants and stock items carry no store of their own and reach it+ # through the product; anything else falls back to the request's store the+ # way {Spree::SingleStoreResource} does.+ def external_reference_store+ return store if respond_to?(:store) && store.present?+ return product.store if respond_to?(:product) && product&.store.present?++ Spree::Current.store+ end+ end+enddiff --git a/spree/core/app/models/spree/category.rb b/spree/core/app/models/spree/category.rbindex 432bc0f1e2..417a763081 100644--- a/spree/core/app/models/spree/category.rb+++ b/spree/core/app/models/spree/category.rb@@ -16,6 +16,7 @@ module Spreeinclude Spree::TranslatableResourceSluginclude Spree::HasCustomFieldsinclude Spree::Metadata+ include Spree::HasExternalReferencesinclude Spree::MemoizedDatainclude Spree::SanitizableRichTextinclude Spree::HasLibraryMediadiff --git a/spree/core/app/models/spree/company.rb b/spree/core/app/models/spree/company.rbindex b26240752b..564c84964e 100644--- a/spree/core/app/models/spree/company.rb+++ b/spree/core/app/models/spree/company.rb@@ -13,6 +13,7 @@ module Spreeinclude Spree::SingleStoreResourceinclude Spree::HasCustomFieldsinclude Spree::Metadata+ include Spree::HasExternalReferencespublishes_lifecycle_events@@ -27,13 +28,9 @@ module Spreedependent: :destroy, inverse_of: :companyvalidates :name, presence: true- # Paired with the partial unique index, per the convention — without it a- # duplicate reference reaches the database and surfaces as a 500 rather- # than a validation error. Nil is exempt on both sides.- validates :external_id, uniqueness: { scope: [:store_id, *spree_base_uniqueness_scope] }, allow_nil: true- self.whitelisted_ransackable_attributes = %w[name external_id]- self.whitelisted_ransackable_associations = %w[company_locations]+ self.whitelisted_ransackable_attributes = %w[name]+ self.whitelisted_ransackable_associations = %w[company_locations external_references]def event_serializer_class'Spree::Api::V3::CompanySerializer'.safe_constantizediff --git a/spree/core/app/models/spree/company_location.rb b/spree/core/app/models/spree/company_location.rbindex 4244c725c1..f231f4250b 100644--- a/spree/core/app/models/spree/company_location.rb+++ b/spree/core/app/models/spree/company_location.rb@@ -10,6 +10,7 @@ module Spreeinclude Spree::HasCustomFieldsinclude Spree::Metadata+ include Spree::HasExternalReferencesbelongs_to :company, class_name: 'Spree::Company', inverse_of: :company_locationsbelongs_to :billing_address, class_name: 'Spree::Address', optional: true, dependent: :destroy@@ -36,6 +37,7 @@ module Spreedelegate :store, :store_id, to: :company- self.whitelisted_ransackable_attributes = %w[name external_id]+ self.whitelisted_ransackable_attributes = %w[name]+ self.whitelisted_ransackable_associations = %w[external_references]endenddiff --git a/spree/core/app/models/spree/external_reference.rb b/spree/core/app/models/spree/external_reference.rbnew file mode 100644index 0000000000..606f7a5395--- /dev/null+++ b/spree/core/app/models/spree/external_reference.rb@@ -0,0 +1,42 @@+module Spree+ # Maps a Spree record to its identity in an external system — the key an ERP,+ # PIM, DAM or CRM knows it by. A record can carry one reference per system, so+ # a product known to both a PIM and an ERP under different keys needs no+ # per-system column.+ #+ # +system+ is a plain string key rather than a foreign key to+ # {Spree::Integration}: data arrives from systems that have no live connector+ # (a nightly CSV from a legacy PIM), and those still need somewhere to record+ # their identity. Where a connector does exist the convention is to reuse its+ # integration's +api_type+, so connector, references and settings page agree+ # on the name.+ class ExternalReference < Spree.base_class+ has_prefix_id :extref++ include Spree::SingleStoreResource+ include Spree::Metadata++ belongs_to :store, class_name: 'Spree::Store', inverse_of: :external_references+ belongs_to :resource, polymorphic: true++ normalizes :system, with: ->(value) { value.to_s.strip.downcase }+ normalizes :external_id, with: ->(value) { value.to_s.strip }++ validates :system, :external_id, presence: true+ validates :system,+ format: { with: /\A[a-z0-9_]+\z/, message: :invalid_system_key },+ allow_blank: true+ # Both directions, each backed by a unique index: one reference per system+ # per record, and one record per external id.+ validates :resource_id,+ uniqueness: { scope: [:store_id, :system, :resource_type, *spree_base_uniqueness_scope] },+ allow_blank: true+ validates :external_id,+ uniqueness: { scope: [:store_id, :system, :resource_type, *spree_base_uniqueness_scope] },+ allow_blank: true++ self.whitelisted_ransackable_attributes = %w[system external_id resource_type]++ scope :for_system, ->(system) { where(system: system.to_s.strip.downcase) }+ end+enddiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex a682836f75..fa476a9ba8 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -46,6 +46,7 @@ module Spreepublishes_lifecycle_eventsinclude Spree::HasCustomFieldsinclude Spree::Metadata+ include Spree::HasExternalReferencesinclude Spree::Searchableif defined?(Spree::Security::Orders)include Spree::Security::Ordersdiff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rbindex cdac950ef8..0b69bede77 100644--- a/spree/core/app/models/spree/product.rb+++ b/spree/core/app/models/spree/product.rb@@ -28,6 +28,7 @@ module Spreeinclude Spree::HasCustomFieldsinclude Spree::CustomFieldFilterableinclude Spree::Metadata+ include Spree::HasExternalReferencesinclude Spree::Searchableinclude Spree::Product::Slugsinclude Spree::Product::Channelsdiff --git a/spree/core/app/models/spree/stock_level.rb b/spree/core/app/models/spree/stock_level.rbindex ebd6a89bad..32b4e0db47 100644--- a/spree/core/app/models/spree/stock_level.rb+++ b/spree/core/app/models/spree/stock_level.rb@@ -6,6 +6,7 @@ module Spreeinclude Spree::HasCustomFieldsinclude Spree::Metadata+ include Spree::HasExternalReferences# Dual-emits the pre-rename `stock_item.*` names for one release.include Spree::StockLevel::CustomEventsdiff --git a/spree/core/app/models/spree/stock_location.rb b/spree/core/app/models/spree/stock_location.rbindex 772273229a..0038b394fe 100644--- a/spree/core/app/models/spree/stock_location.rb+++ b/spree/core/app/models/spree/stock_location.rb@@ -12,6 +12,7 @@ module SpreePICKUP_STOCK_POLICIES = %w[local any].freezeinclude Spree::SingleStoreResource+ include Spree::HasExternalReferencesinclude Spree::UniqueNameif defined?(Spree::Security::StockLocations)include Spree::Security::StockLocationsdiff --git a/spree/core/db/migrate/20260818000001_create_spree_external_references.rb b/spree/core/db/migrate/20260818000001_create_spree_external_references.rbnew file mode 100644index 0000000000..06a1b8e978--- /dev/null+++ b/spree/core/db/migrate/20260818000001_create_spree_external_references.rb@@ -0,0 +1,38 @@+class CreateSpreeExternalReferences < ActiveRecord::Migration[8.1]+ def change+ create_table :spree_external_references do |t|+ t.references :store, null: false, index: false+ t.string :system, null: false+ t.references :resource, polymorphic: true, null: false, index: false+ t.string :external_id, null: false+ if t.respond_to?(:jsonb)+ t.jsonb :metadata+ else+ t.json :metadata+ end+ t.timestamps+ end++ # One reference per system per record.+ add_index :spree_external_references,+ [:store_id, :system, :resource_type, :resource_id],+ unique: true, name: 'idx_external_references_on_resource'++ # An external id maps to exactly one record — what makes upsert-by-external-id safe.+ add_index :spree_external_references,+ [:store_id, :system, :resource_type, :external_id],+ unique: true, name: 'idx_external_references_on_external_id'++ # Reverse lookup for the resource-side association (resource → its references).+ add_index :spree_external_references, [:resource_type, :resource_id],+ name: 'idx_external_references_on_resource_lookup'++ # Company and location external ids move to the new table. Unreleased+ # (6.0-dev only), so no data carry-over: dev databases re-key from their+ # feed. Options given in full so the migration reverses cleanly.+ remove_index :spree_companies, [:store_id, :external_id], unique: true,+ where: 'external_id IS NOT NULL', name: 'idx_companies_external_id'+ remove_column :spree_companies, :external_id, :string+ remove_column :spree_company_locations, :external_id, :string+ end+enddiff --git a/spree/core/lib/spree/testing_support/factories/external_reference_factory.rb b/spree/core/lib/spree/testing_support/factories/external_reference_factory.rbnew file mode 100644index 0000000000..985dfcd87a--- /dev/null+++ b/spree/core/lib/spree/testing_support/factories/external_reference_factory.rb@@ -0,0 +1,8 @@+FactoryBot.define do+ factory :external_reference, class: Spree::ExternalReference do+ store { Spree::Store.default || create(:store) }+ resource { create(:product, store: store) }+ system { 'erp' }+ sequence(:external_id) { |n| "EXT-#{n}" }+ end+enddiff --git a/spree/core/spec/models/concerns/spree/has_external_references_spec.rb b/spree/core/spec/models/concerns/spree/has_external_references_spec.rbnew file mode 100644index 0000000000..2de81a00ac--- /dev/null+++ b/spree/core/spec/models/concerns/spree/has_external_references_spec.rb@@ -0,0 +1,136 @@+require 'spec_helper'++RSpec.describe Spree::HasExternalReferences do+ let(:store) { @default_store }+ let(:product) { create(:product, store: store) }++ describe '#set_external_id' do+ it 'creates a reference carrying the record store' do+ reference = product.set_external_id('erp', 'MAT-100')++ expect(reference).to be_persisted+ expect(reference.store).to eq(store)+ expect(product.external_id_for('erp')).to eq('MAT-100')+ end++ it 'updates the existing reference for that system rather than adding a second' do+ product.set_external_id('erp', 'MAT-100')++ expect { product.set_external_id('erp', 'MAT-200') }.not_to change { product.external_references.count }+ expect(product.external_id_for('erp')).to eq('MAT-200')+ end++ it 'keeps one record identifiable in several systems at once' do+ product.set_external_id('erp', 'MAT-100')+ product.set_external_id('pim', 'SKU-1')++ expect(product.external_id_for('erp')).to eq('MAT-100')+ expect(product.external_id_for('pim')).to eq('SKU-1')+ end++ it 'removes the reference when given a blank id' do+ product.set_external_id('erp', 'MAT-100')++ expect { product.set_external_id('erp', '') }.to change { product.external_references.count }.by(-1)+ expect(product.external_id_for('erp')).to be_nil+ end++ it 'stores connector bookkeeping in metadata' do+ reference = product.set_external_id('erp', 'MAT-100', metadata: { 'etag' => 'abc' })++ expect(reference.metadata['etag']).to eq('abc')+ end+ end++ describe '#external_id_for' do+ it 'reads through a loaded association without a further query' do+ product.set_external_id('erp', 'MAT-100')+ loaded = Spree::Product.includes(:external_references).find(product.id)++ queries = 0+ counter = ->(*, payload) { queries += 1 unless payload[:name].to_s.in?(['SCHEMA', 'TRANSACTION']) }++ result = ActiveSupport::Notifications.subscribed(counter, 'sql.active_record') do+ loaded.external_id_for('erp')+ end++ expect(queries).to eq(0)+ expect(result).to eq('MAT-100')+ end++ it 'matches case-insensitively on the system key' do+ product.set_external_id('erp', 'MAT-100')++ expect(product.external_id_for('ERP')).to eq('MAT-100')+ end+ end++ describe '.find_by_external_id' do+ it 'finds the record the external system knows' do+ product.set_external_id('erp', 'MAT-100')++ expect(Spree::Product.find_by_external_id('erp', 'MAT-100')).to eq(product)+ end++ it 'returns nil when no reference matches' do+ expect(Spree::Product.find_by_external_id('erp', 'NOPE')).to be_nil+ end++ it 'honours the scope it is chained onto, so another store is invisible' do+ other_store = create(:store)+ other_product = create(:product, store: other_store)+ other_product.set_external_id('erp', 'MAT-100')++ expect(store.products.find_by_external_id('erp', 'MAT-100')).to be_nil+ expect(other_store.products.find_by_external_id('erp', 'MAT-100')).to eq(other_product)+ end+ end++ describe '#assign_external_references' do+ it 'writes the systems named and leaves the others alone' do+ product.set_external_id('pim', 'SKU-1')++ product.assign_external_references([{ system: 'erp', external_id: 'MAT-100' }])++ expect(product.external_id_for('erp')).to eq('MAT-100')+ expect(product.external_id_for('pim')).to eq('SKU-1')+ end++ # The same map shape the admin serializers render, so a caller can hand+ # back exactly what it read.+ it 'accepts a system => id map as well as a list' do+ product.assign_external_references(erp: 'MAT-100', pim: 'SKU-1')++ expect(product.external_id_for('erp')).to eq('MAT-100')+ expect(product.external_id_for('pim')).to eq('SKU-1')+ end++ it 'ignores entries without a system' do+ expect { product.assign_external_references([{ external_id: 'MAT-100' }]) }.+ not_to change { product.external_references.count }+ end+ end++ describe 'store resolution for records that reach the store through a parent' do+ it 'uses the product store for a variant' do+ variant = create(:variant, product: product)++ expect(variant.set_external_id('erp', 'V-1').store).to eq(store)+ end++ it 'uses the company store for a company location' do+ company = create(:company, store: store)+ location = create(:company_location, company: company)++ expect(location.set_external_id('erp', 'LOC-1').store).to eq(store)+ end+ end++ describe 'lifecycle' do+ it 'destroys the references with the record' do+ product.set_external_id('erp', 'MAT-100')++ expect { product.destroy }.to change { Spree::ExternalReference.count }.by(-1)+ end+ end+enddiff --git a/spree/core/spec/models/spree/company_spec.rb b/spree/core/spec/models/spree/company_spec.rbindex 89fbeff00e..8db16479ae 100644--- a/spree/core/spec/models/spree/company_spec.rb+++ b/spree/core/spec/models/spree/company_spec.rb@@ -22,23 +22,36 @@ describe Spree::Company, type: :model doendend- describe 'external_id' do- it 'is unique per store' do- create(:company, store: store, external_id: 'ACME')-- expect(build(:company, store: store, external_id: 'ACME')).not_to be_valid+ # The former external_id column moved to Spree::ExternalReference so a company+ # can be known to an ERP and a CRM at once (docs/plans/6.0-third-party-pricing-inventory.md).+ describe 'external references' do+ it 'is unique per store and system' do+ create(:company, store: store).set_external_id('erp', 'ACME')+ duplicate = create(:company, store: store)++ expect { duplicate.set_external_id('erp', 'ACME') }.to raise_error(ActiveRecord::RecordInvalid)endit 'allows the same reference in another store' do- create(:company, store: store, external_id: 'ACME')+ create(:company, store: store).set_external_id('erp', 'ACME')+ elsewhere = create(:company, store: create(:store))- expect(build(:company, store: create(:store), external_id: 'ACME')).to be_valid+ expect(elsewhere.set_external_id('erp', 'ACME')).to be_persistedendit 'lets several companies carry no reference' do- create(:company, store: store, external_id: nil)+ create(:company, store: store)++ expect(build(:company, store: store)).to be_valid+ end++ it 'carries one identity per external system' do+ company = create(:company, store: store)+ company.set_external_id('erp', 'ACME')+ company.set_external_id('crm', 'CUST-1')- expect(build(:company, store: store, external_id: nil)).to be_valid+ expect(company.external_id_for('erp')).to eq('ACME')+ expect(company.external_id_for('crm')).to eq('CUST-1')endenddiff --git a/spree/core/spec/models/spree/external_reference_spec.rb b/spree/core/spec/models/spree/external_reference_spec.rbnew file mode 100644index 0000000000..c7d577e90a--- /dev/null+++ b/spree/core/spec/models/spree/external_reference_spec.rb@@ -0,0 +1,87 @@+require 'spec_helper'++RSpec.describe Spree::ExternalReference, type: :model do+ let(:store) { @default_store }+ let(:product) { create(:product, store: store) }++ describe 'normalization' do+ it 'downcases and strips the system key' do+ reference = create(:external_reference, resource: product, store: store, system: ' ERP ')++ expect(reference.system).to eq('erp')+ end++ it 'strips the external id' do+ reference = create(:external_reference, resource: product, store: store, external_id: ' MAT-100 ')++ expect(reference.external_id).to eq('MAT-100')+ end+ end++ describe 'validation' do+ it 'rejects a system key that is not a plain lowercase token' do+ reference = build(:external_reference, resource: product, store: store, system: 'my system!')++ expect(reference).not_to be_valid+ expect(reference.errors[:system]).to be_present+ end++ it 'allows one reference per system for the same record' do+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ pim = build(:external_reference, resource: product, store: store, system: 'pim', external_id: 'SKU-1')++ expect(pim).to be_valid+ end++ it 'rejects a second reference for the same record and system' do+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ duplicate = build(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-200')++ expect(duplicate).not_to be_valid+ expect(duplicate.errors[:resource_id]).to be_present+ end++ it 'rejects the same external id pointing at two records in one system' do+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ other = build(:external_reference, resource: create(:product, store: store), store: store,+ system: 'erp', external_id: 'MAT-100')++ expect(other).not_to be_valid+ expect(other.errors[:external_id]).to be_present+ end++ it 'allows the same external id in two different systems' do+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ pim = build(:external_reference, resource: create(:product, store: store), store: store,+ system: 'pim', external_id: 'MAT-100')++ expect(pim).to be_valid+ end++ it 'allows the same external id in another store' do+ other_store = create(:store)+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ elsewhere = build(:external_reference, resource: create(:product, store: other_store), store: other_store,+ system: 'erp', external_id: 'MAT-100')++ expect(elsewhere).to be_valid+ end+ end++ describe 'database constraints' do+ it 'refuses a duplicate (store, system, resource) at the database level' do+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ duplicate = build(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-200')++ expect { duplicate.save(validate: false) }.to raise_error(ActiveRecord::RecordNotUnique)+ end++ it 'refuses a duplicate (store, system, external_id) at the database level' do+ create(:external_reference, resource: product, store: store, system: 'erp', external_id: 'MAT-100')+ duplicate = build(:external_reference, resource: create(:product, store: store), store: store,+ system: 'erp', external_id: 'MAT-100')++ expect { duplicate.save(validate: false) }.to raise_error(ActiveRecord::RecordNotUnique)+ end+ end+end