Znode planning / Migration
Znode 9 to 10 migration: give every customization a plan.
A Znode 9 to Znode 10 transition is a chance to review how the business works and where its custom behavior belongs. Start with the workflows people depend on, then choose the right implementation for the target platform.
Preserve the reason the customization exists.
An account selector might look like a small control, but it can determine catalogs, prices, addresses, payment options, and the active cart. A custom order service may also carry customer identifiers, units, tax decisions, and recovery rules. The important migration requirement is the behavior that these pieces support.
Inventory each customization with its users, inputs, outputs, permissions, external dependencies, and side effects. Ask what should stay, what the target release can provide through configuration, and what is no longer needed. This gives the business a say before engineering commits to rebuilding familiar code.
Make the runtime and extension changes explicit.
Znode 9 uses .NET Framework 4.8 in the legacy application stack discussed in GCG's guides. Znode 10 uses ASP.NET Core and modern .NET for Custom API development, with a React and Next.js storefront and Page Builder development model. The exact SDK and package versions should be recorded for the target release.
That distinction affects application lifecycle, dependency registration, storefront composition, deployment, and extension boundaries. A Razor or jQuery customization needs an intentional frontend design. A legacy service override needs a supported target extension. Treat those as engineering decisions rather than a series of syntax substitutions.
Choose the target approach.
Use the same decision frame for every customization. The right outcome follows the business behavior, target platform boundary, and evidence needed to confirm the result.
| Decision outcome | When it fits | Target approach | What to validate |
|---|---|---|---|
| Configure or retain | The target release provides the required behavior through supported configuration. | Record the configuration, data owner, permissions, and release dependency. | Demonstrate the buyer workflow and operating behavior in the target environment. |
| Rebuild a server-side capability | A business rule needs a defined contract beyond supported configuration. | Use the supported Znode 10 API or a separate service with an authenticated boundary. | Verify inputs, authorization, external dependencies, errors, and recovery ownership. |
| Rebuild storefront behavior | A buyer-facing workflow was previously expressed through Razor or jQuery customization. | Design the Next.js route, component, or Page Builder extension for the target workflow. | Verify account context, responsive behavior, acceptance criteria, and release dependencies. |
| Retire or consolidate | The behavior is no longer required, duplicates another capability, or can be simplified. | Record the replacement process, data transition, and owner decision. | Confirm affected users, integrations, reporting, and support procedures no longer depend on it. |
Choose a home for the data and the rules.
Separate Znode-owned entities from project-owned information and external-system records. A supported entity attribute may be enough for a value owned by an account or product. Small reference data may fit a supported custom-table capability. Relational project data may need its own database and authenticated API.
For a Znode-hosted target, plan to access Znode-owned data through the supported APIs and clients. Keep project database access behind server-side services. A browser, storefront component, or Page Builder widget should receive a defined contract, with authorization enforced at the server boundary.
| Legacy dependency | Planning question |
|---|---|
| Direct core-database query | Which supported API or entity capability provides the required behavior? |
| Custom relational tables | Who owns the data, its schema, its API, and its deployment? |
| Razor or jQuery interface | Which Next.js route, component, or Page Builder extension serves the workflow? |
| ERP job or order mapping | Does a supported connector fit, or does the workflow require a separate service? |
A customization inventory should describe the behavior, not just the file.
A spreadsheet that lists controllers and stored procedures is useful to engineering. A migration decision needs another layer: who uses the feature, why it exists, which account or store it belongs to, and what happens when it fails.
Start with one business capability per row. Link the related source files and database objects in your private working copy. Record the inputs, outputs, permissions, data owner, external dependencies and acceptance check.
The example inventory below uses common customization shapes rather than client code. Replace each row with your implementation and assign a business owner alongside the engineering owner.
| Capability | Legacy shape | Candidate target | Acceptance evidence |
|---|---|---|---|
| Account selection | MVC/session or impersonation-based selection across Framework services and browser code. | Server-authorized account context plus a focused Next.js/React selector; keep true impersonation separate. | Only eligible accounts are listed; denied selection fails; account-specific cart and price follow the agreed policy. |
| Imported account pricing | Legacy import or direct SQL procedure materializes pricing. | Native price-list import and supported account association, with explicit precedence and readback. | Representative account sees intended PDP/cart price; imported row and account association persist. |
| Live price or availability | Legacy ERP override mixes request mapping and remote calls. | Supported ERP connector/common-model touchpoint or a bounded authenticated service when the contract needs it. | Correct account/store mapping, bounded timeout, clear failure and agreed freshness behavior. |
| Quantity rules | Webstore TypeScript feedback plus Framework cart/order service logic. | React feedback plus the supported server-side extension or service for the same rule. | Invalid and valid quantities behave consistently at entry, cart and final server acceptance. |
Keep the three target decisions separate.
First, decide where the interaction belongs. Legacy Znode 9 webstore customizations in these guides use .NET Framework 4.8, ASP.NET MVC/Razor and associated browser code. Znode 10 storefront and Page Builder development use React and Next.js SDKs. Rebuild the interaction for that model instead of assuming the old controller or jQuery event handler can be carried over.
Second, decide where the server-side rule belongs. Znode 10 Custom API development uses ASP.NET Core on modern .NET. GCG's current Custom API examples target .NET 8; record the actual target framework and package versions in your installed SDK for the chosen release.
Third, decide who owns the data. For a hosted Znode 10 target, use supported APIs and clients for Znode-owned information. Keep project-owned relational data behind an authenticated server API. A browser component or Page Builder widget should receive the defined result, not a database connection.
A worked example: account notes need more than a new endpoint.
Imagine a legacy account-notes screen. A service writes a note into a custom relational table; the UI lists it under an account. The requirement is not merely create and list notes. It may also need to preserve the author, account permission, edit history, ordering and protection against two people overwriting the same edit.
For a hosted target, the notes are project-owned relational records. Keep them in a project-owned database behind authenticated Custom API operations. Store the Znode account identifier as a reference and enforce the caller's account authorization at the server boundary.
The Next.js screen displays a purpose-built response and submits a defined request. It does not choose a table or send an arbitrary SQL fragment. The server checks the account, required fields and edit version before writing.
Compare the old and target behavior with fictional fixtures: a permitted user creates a note, a user from another account is denied, a stale edit is rejected, and the note appears with the intended author and order. Those checks preserve the feature's meaning while changing its implementation.
Use the inventory to choose the migration sequence.
Give each row a Configure, Rebuild, Replace, Retire or Decide outcome. Record the proposed extension and the evidence needed to accept it. A file count does not establish implementation effort; data transition, identity, external dependencies and workflow complexity do.
Prove one vertical slice before expanding. Choose a feature that crosses the important boundaries without pulling in the entire catalog or every account. Record which data, API and storefront releases have to arrive together.
Separate the business decision from the release status. A feature can be approved for rebuilding while its data migration or external interface is still an open dependency. The tracker keeps those two conversations visible.
Avoid preserving accidental dependencies.
- Copying a direct core-database dependency into a hosted target. Identify the supported API or native entity capability for Znode-owned data. Keep project relational data in its own server-owned storage.
- Choosing custom storage before identifying the data owner. An entity-owned scalar value may fit a native attribute. Small stable reference data may fit the Custom Tables API. Mutable relational project data needs its own deliberate design.
- Keeping a browser-only authorization check. The UI can guide the user, but the server must authorize each protected read and write against the effective account and store context.
- Using a build as the complete acceptance result. Follow the actual workflow through configuration, persisted data, API and storefront. Include an allowed case, a denied case and a meaningful failure.
Give every retained behavior an owner and an acceptance check.
Download the customization inventory, replace the examples, and link your private source references. Mark each item complete when its owner has reviewed the target behavior and the recorded evidence.
Bring the inventory, target hosting model and biggest dependencies into a migration discussion. GCG can help identify a first slice, supported boundaries and a release sequence that your engineering and business teams can follow.
Interactive planning checklist
Check a task after you have reviewed its completion evidence. Download your progress to assign owners, dates and notes in Excel.
- ZM-01 / Account selection: Map and decide the account selection capability.Complete when: Only eligible accounts are listed; denied selection fails; account-specific cart and price follow the agreed policy.Suggested owner: Ecommerce / IT
- ZM-02 / Imported account pricing: Map and decide the imported account pricing capability.Complete when: Representative account sees intended PDP/cart price; imported row and account association persist.Suggested owner: Sales / integration
- ZM-03 / Live price or availability: Map and decide the live price or availability capability.Complete when: Correct account/store mapping, bounded timeout, clear failure and agreed freshness behavior.Suggested owner: Integration / operations
- ZM-04 / Quantity rules: Map and decide the quantity rules capability.Complete when: Invalid and valid quantities behave consistently at entry, cart and final server acceptance.Suggested owner: Ecommerce / engineering
- ZM-05 / Content widget: Map and decide the content widget capability.Complete when: Edit, preview and published storefront show the same intended fields and links.Suggested owner: Marketing / UX / engineering
- ZM-06 / Entity attribute: Map and decide the entity attribute capability.Complete when: Required value persists on the intended entity; other entity values and permissions remain correct.Suggested owner: IT / data owner
- ZM-07 / Small reference map: Map and decide the small reference map capability.Complete when: Deterministic lookup handles missing/duplicate keys and never accepts an arbitrary table or endpoint.Suggested owner: Integration / engineering
- ZM-08 / Account notes: Map and decide the account notes capability.Complete when: Allowed/denied account checks, stale-edit response, author and ordering are correct.Suggested owner: Customer service / IT
- ZM-09 / Background import: Map and decide the background import capability.Complete when: Representative update persists; replay/checkpoint handling avoids duplicate effects; failures are actionable.Suggested owner: Product data / integration
- ZM-10 / Publish and search extension: Map and decide the publish and search extension capability.Complete when: Published assortment, intended URL and buyer-visible discovery result agree after the release sequence.Suggested owner: Marketing / engineering
Review one complete slice before expanding.
Choose a small but representative workflow that crosses the important boundaries. An account-specific purchase can exercise identity, account selection, catalog access, pricing, quantity rules, and the order handoff. Define expected results with sanitized examples that can be compared across implementations.
Plan the sequence around data readiness, integrations, configuration, storefront behavior, and operational procedures. Include logging, reconciliation, and a recovery route for exceptions. Keep rollback responsibilities and any data-transition constraints explicit so a release decision is based on the complete workflow.
Build the migration brief around decisions.
A useful roadmap states what the business will gain, which current behaviors remain necessary, and how the target architecture supports them. It should also identify the work needed to keep the existing environment dependable during the transition.
- Record the current Znode patch, application surfaces, jobs, integrations, and custom data stores.
- Map each customization to the business behavior and permissions it must preserve.
- Agree retain, rebuild, or retire decisions with the responsible business owners.
- Record the target SDK, hosting model, supported extension, and data owner for each retained behavior.
- Define representative acceptance scenarios, transition dependencies, and operational recovery responsibilities.
Go deeper into the implementation.
Follow the version-specific technical guides and complete recipes behind these planning decisions.
Keep planning.
Discuss your Znode migration roadmap.
Bring the workflow, the systems involved, and the change you want to make. We can establish a useful starting scope together.
Discuss your Znode migration roadmap