Spryker Documentation

Migrate from OpenSearch 1.3 to 3.5

Wed, 26 Aug 2026 12:12:26 +0000

This document describes how to migrate an OpenSearch cluster used by a Spryker project from version 1.3 to 3.5. Between major OpenSearch versions, an index or a cluster setting can become incompatible with the target version, for example because of an outdated Lucene index format, a deprecated setting, or a breaking plugin change. OpenSearch does not support skipping major versions and cannot be upgraded in place while such incompatibilities exist, so the upgrade is blocked until you resolve them. To resolve this, you upgrade the cluster incrementally, from 1.3 to 2.19, and then from 2.19 to 3.5, fixing every incompatibility before each upgrade. {% info_block warningBox "Verification" %} Before you start, test the migration in a non-production environment. Blocking writes to an index makes it read-only until the reindexing is complete, so plan the migration for a maintenance window. {% endinfo_block %} ## 1. Update the required modules You only need to update the packages for the features used in your project. Check the following table and update the packages that are installed in your project to at least the specified versions: | Package | Minimum version | | --- | --- | | `spryker/sales-return-search` | 1.4.1 | | `spryker/merchant-search` | 1.3.1 | | `spryker/product-review` | 2.15.1 | | `spryker/search-elasticsearch` | 1.23.1 | | `spryker/service-point-search` | 1.4.1 | | `spryker-feature/self-service-portal` | 20.9.1 | Update the packages installed in your project using Composer: ```bash composer update spryker/merchant-search:"^1.3.1" spryker/product-review:"^2.15.1" spryker/sales-return-search:"^1.4.1" spryker/search-elasticsearch:"^1.23.1" spryker/service-point-search:"^1.4.1" spryker-feature/self-service-portal:"^20.9.1" ``` If your project overrides the search schema of these modules, apply the equivalent changes to your project-level search schema as well. ## 2. Check the upgrade eligibility Consult the breaking changes and deprecation notices for OpenSearch 2.19, and check your indexes and cluster settings against them to determine whether the cluster is eligible for the upgrade. - If the cluster is eligible, upgrade it to 2.19 and continue to [4. Check the upgrade eligibility for 3.5](#4-check-the-upgrade-eligibility-for-35). - If the cluster is not eligible, one or more incompatibilities block the upgrade. - For an index with an incompatible index format, unblock the upgrade by reindexing it as described in the following section. - For any other incompatibility, for example a deprecated index setting or a breaking plugin change, fix it first. Only continue with the upgrade after all the incompatibilities are resolved. ## 3. Reindex an index to unblock the upgrade Repeat the following steps for every index with an incompatible index format. Replace `` with the name of the index you are migrating. ### 3.1. Block writes to the index To prevent data from changing while the index is being cloned, block write operations: ```json PUT //_settings { "settings": { "index.blocks.write": true } } ``` ### 3.2. Clone the index Clone the index into a temporary index: ```json PUT //_clone/_tmp ``` ### 3.3. Verify the document count Compare the document count of `` and `_tmp`. The counts must match before you continue. ### 3.4. Delete the original index ```json DELETE / ``` ### 3.5. Re-create the index and its schema Re-create the index and install its schema using the following console command: ```bash console search:setup:sources ``` ### 3.6. Reindex the documents Reindex the documents from the temporary index back into the newly created ``: ```json POST /_reindex?slices=2&wait_for_completion=false { "source": { "index": "_tmp" }, "dest": { "index": "" } } ``` ### 3.7. Verify the document count again Compare the document count of `` and `_tmp` again. The counts must match before you continue. ### 3.8. Delete the temporary index ```json DELETE /_tmp ``` After you reindex all the blocking indexes, upgrade the cluster to version 2.19. ## 4. Check the upgrade eligibility for 3.5 Consult the breaking changes and deprecation notices for OpenSearch 3.5, and check your indexes and cluster settings on version 2.19 against them to determine whether the cluster is eligible for the upgrade. - If the cluster is eligible, upgrade it to 3.5. - If the cluster is not eligible, incompatibilities again block the upgrade. Resolve them the same way as in step 2: reindex every index with an incompatible index format by repeating the steps in [3. Reindex an index to unblock the upgrade](#3-reindex-an-index-to-unblock-the-upgrade), and fix any other incompatibility. Then upgrade the cluster to 3.5.

Upgrade the PurchasingControl module

Tue, 25 Aug 2026 08:40:54 +0000

{% include pbc/all/upgrade-modules/upgrade-the-purchasingcontrol-module.md %}

Purchasing Control feature overview

Tue, 25 Aug 2026 08:40:54 +0000

The *Purchasing Control* feature lets B2B companies track and control procurement spending by assigning orders to cost centers and enforcing configurable budget rules. It extends the existing [Approval Process](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html) with a second dimension of spending governance: per-department or per-project budget limits that work alongside the existing per-person permission limits. Buyers assign a cost center and a budget to a cart at checkout or to a quote request, and agents can do the same on a customer's behalf. {% info_block infoBox "Info" %} This feature is available in the Back Office and on the Storefront. {% endinfo_block %} ## Cost centers A *cost center* is an organizational unit within a company that incurs costs but does not directly generate revenue. Companies use cost centers to track and control spending by department, project, location, or function. **Common examples:** - **Departmental:** Marketing, Engineering, HR, Facilities - **Project-based:** Office Renovation Q2 2026, Trade Show Berlin - **Location-based:** Warehouse Berlin, Office London Every purchase a buyer makes is charged to a cost center so the company can track where money is being spent. In ERP systems such as SAP, Oracle, and Microsoft Dynamics, cost centers are a foundational accounting concept - orders flow into the ERP tagged with a cost center code, enabling financial reporting and cost allocation. ### Deactivated cost centers and budgets A cost center or budget can be deactivated instead of deleted, which preserves the history of the orders already charged to it. Deactivated records are not offered in the cost center and budget selectors, and a deactivated cost center is no longer shown where the assignment of a cart or quote is displayed. If every cost center available to a buyer is deactivated, or if the selected cost center has no active budget left, no choices are rendered and the buyer cannot assign one until an active record is available again. ## Budgets A *budget* is a spending limit assigned to a cost center for a defined period - monthly, quarterly, or annually. It represents the maximum amount that a department or project is authorized to spend in that period. **Example:** The Marketing department has a quarterly procurement budget of €50,000 for office supplies and event materials. Once that budget is consumed, further purchases are either blocked, flagged for review, or escalated for approval. ### Budget enforcement rules Each budget is configured with one of three enforcement rules: | RULE | DESCRIPTION | | --- | --- | | Block | The order is rejected outright when the budget is exceeded. The buyer cannot proceed to checkout. | | Warn | A warning is displayed to the buyer, but they can proceed. | | Require Approval | The order is sent for approval when the budget is exceeded. The buyer cannot complete checkout until an approver accepts the order. | ### Budgets in recurring orders With the [Recurring Orders feature](/docs/pbc/all/order-experience-management/latest/base-shop/feature-overviews/recurring-orders-feature-overview.html) installed, a recurring order carries a cost center and a budget, selected on the recurring order forms and changeable when the buyer edits the schedule or approves a review. Budgets with the **Require Approval** enforcement rule cannot be used for a recurring order. A recurring order places its follow-up orders unattended, so no approver can accept them at placement time. The restriction applies in two places: - Such budgets are not offered in the recurring order budget selector. - Checkout is blocked if a quote being set up as a recurring order carries one. This check applies regardless of the quote grand total and of the remaining budget amount, so the budget does not have to be exceeded for the block to take effect. Regular, non-recurring checkouts are not affected—there, the **Require Approval** rule behaves as described above. ## Relationship to the Approval Process Spryker's existing Approval Process triggers a workflow when a buyer's order exceeds their *Buy up to grand total* permission. The Purchasing Control feature adds a parallel check: an order might be within a buyer's personal permission limit but still exceed the cost center's remaining budget. Both checks run independently at checkout. If either the permission limit or the budget rule is triggered, the configured action - block, warn, or require approval - is applied. This gives companies layered spending governance: per-person limits *and* per-department or per-project limits. {% info_block infoBox "Permissions required for the Require Approval enforcement rule" %} To use budgets with the **Require Approval** enforcement rule, the following [Approval Process](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html) permissions must be assigned to the relevant company roles: | PERMISSION | REQUIRES | | --- | --- | | Buy up to grand total | Send cart for approval | | Send cart for approval | Buy up to grand total | | Approve up to grand total | None | {% endinfo_block %} {% info_block warningBox "Approvals within a business unit" %} Approvers can only approve orders of employees within their own business unit. This constraint applies to both permission-based and budget-based approval requests. {% endinfo_block %} ## Cost centers and budgets in the procurement workflow The typical B2B procurement flow involving cost centers and budgets: 1. **Finance sets budgets.** At the start of a fiscal period, finance allocates budgets to each cost center. 2. **Buyers are assigned to cost centers.** Buyers are linked to one or more cost centers they are authorized to purchase against. Cost centers are linked to company business units, so all users in a business unit are automatically assigned to the corresponding cost centers. 3. **Orders are tagged.** At checkout, the buyer selects the cost center the purchase is charged to and the budget it is drawn from. Both fields are saved together in a single step: - The budget dropdown offers the budgets of every cost center available to the buyer, narrowed to the selected cost center. - Changing the cost center narrows the budget list immediately, without reloading the page. If the previously selected budget does not belong to the new cost center, the budget field is cleared. - If the selected cost center has no active budgets, the budget field is hidden and a message states that no budgets are available. - A budget that is selected must belong to the selected cost center. The pairing is validated on the server, so a mismatched combination is rejected even when the browser-side filtering is bypassed. - The selector form does not enforce a budget selection by itself, but the field is marked as required in the browser whenever the selected cost center has active budgets. An order cannot be placed without an active budget: if the buyer's business unit has active cost centers and no active budget is resolved, checkout fails and the buyer is asked to select a cost center and a budget. 4. **Budget is validated.** The system checks whether the order total fits within the remaining budget for the selected cost center. 5. **Enforcement rules apply.** Based on the configured rule, the order is blocked, a warning is shown, or approval is required. 6. **Budget is consumed.** Once the order is confirmed, the budget balance is reduced by the order amount. 7. **Budget is restored.** If the order is cancelled or refunded, the budget balance is restored by the amount corresponding to the cancelled or refunded items. For partial cancellations or refunds, only the amounts of the affected items are restored. ## Checkout validation outcomes | SCENARIO | OUTCOME | | --- | --- | | Within budget and within permission limit | Buyer completes checkout without additional steps. | | Exceeds budget - Warn rule | A warning is displayed; the buyer can proceed to checkout. | | Exceeds budget - Require Approval rule | The order is sent for approval; the buyer cannot complete checkout until approved. | | Exceeds Buy up to grand total permission limit | The order is sent for approval, same as the standard Approval Process. | | Exceeds budget - Block rule | Checkout is blocked; no approval option is available. | | Recurring order with a Require Approval budget | Checkout is blocked, whether or not the budget is exceeded. The buyer must select a budget bound to the Block or Warn rule. | | No active budget resolved while the business unit has active cost centers | Checkout fails; the buyer must select a cost center and a budget before placing the order. | ## Quote lock When an order is sent for approval - whether triggered by a budget rule or a permission limit - the quote is locked to preserve the order state during the approval review. Neither the buyer nor the approver can modify the quote while it is pending approval. For details, see [Quote lock functionality](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html#quote-lock-functionality). ## Cost centers and budgets on quote requests Buyers do not have to wait until checkout to attribute spending. The same cost center and budget selection is available on quote requests, so a purchase is assigned to a cost center while it is still being negotiated. {% info_block infoBox "Info" %} Cost center selection on quote requests requires the [Quotation Process](/docs/pbc/all/request-for-quote/latest/install-and-upgrade/install-features/install-the-quotation-process-feature.html) feature. {% endinfo_block %} | CONTEXT | WHERE THE SELECTION IS AVAILABLE | | --- | --- | | Buyer (Storefront) | Quote request details page and quote request edit page in the company area. | | Agent (Storefront) | Agent quote request details page and agent quote request edit page. | ### Cost centers follow the quote request owner Cost centers are scoped per company business unit. On a quote request, the applicable cost centers are those of the business unit that owns the request - the business unit of the company user who created it - and not those of the person currently viewing it. An agent working on a customer's quote request therefore sees the customer's cost centers rather than their own. Buyers can only change the cost center on their own quote requests. A quote request reference that belongs to another company user is treated as not found, so an unauthorized reference is indistinguishable from a reference that does not exist. ### Editability On a quote request, selecting a budget is optional: there is no checkout to pass, so a quote request is saved with a cost center and no budget. A budget that is selected must still belong to the selected cost center. A cost center and a budget can be changed only while the quote request is in an editable status. The status check runs on the server, so a quote request that is no longer editable is rejected even when the form is submitted directly. Quote requests that are not editable still display the assigned cost center and budget as read-only. ## Roles and capabilities | ROLE | CAPABILITIES | | --- | --- | | Site Operator (Back Office) | Create, update, activate, and deactivate cost centers. Assign cost centers to business units. Create and manage budgets with amount, period, currency, and enforcement rule. View the **Cost Center** column in the orders table. Filter and search orders by cost center and budget. View spend-vs-budget reports. Export reports to CSV. Review the audit log. Import cost centers, budgets, and business unit assignments in bulk using data import. | | Cost Center Manager (Storefront) | Create, update, activate, and deactivate cost centers and budgets from the company area. Requires the **Manage Cost Centers** permission assigned to their company role. | | Buyer (Storefront) | Select a cost center and budget at checkout. Assign a cost center and budget to their own quote requests. View the remaining budget for the selected cost center. Submit orders for approval when required. Filter order history by cost center and budget. View the assigned cost center and budget on order detail pages. | | Approver (Storefront) | Review locked quotes pending approval. Approve or reject orders, including those triggered by budget rules. | | Agent (Storefront) | Assign a cost center and budget to a customer's quote request on the customer's behalf, using the cost centers of the quote request owner's business unit. | ## Related Developer documents | INSTALLATION GUIDES | | --- | | [Install the Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature.html) | | MIGRATION GUIDES | | --- | | [Upgrade the PurchasingControl module](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/upgrade-modules/upgrade-the-purchasingcontrol-module.html) |

Install the Purchasing Control feature

Tue, 25 Aug 2026 08:40:54 +0000

This document describes how to install the [Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview.html). ## Install feature core Follow the steps below to install the Purchasing Control feature core. ### Prerequisites To start feature integration, review and install the necessary features: | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Company Account | {{page.release_tag}} | [Install the Company Account feature](/docs/pbc/all/customer-relationship-management/latest/base-shop/install-and-upgrade/install-features/install-the-company-account-feature.html) | | Checkout | {{page.release_tag}} | [Install the Checkout feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-checkout-feature.html) | | Approval Process | {{page.release_tag}} | [Install the Approval Process feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html) | | Quotation Process | {{page.release_tag}} | [Install the Quotation Process feature](/docs/pbc/all/request-for-quote/latest/install-and-upgrade/install-features/install-the-quotation-process-feature.html) | {% info_block infoBox "Quotation Process" %} The Quotation Process feature is required only if you want buyers and agents to assign cost centers and budgets to quote requests. The `spryker/quote-request` and `spryker/quote-request-agent` modules are installed as dependencies of `spryker-feature/purchasing-control` in either case, but the Storefront quote request pages are only available with the Quotation Process feature installed. If you do not need this part of the feature, skip [Integrate cost centers with quote requests](#integrate-cost-centers-with-quote-requests). {% endinfo_block %} ### 1) Install the required modules ```bash composer require spryker-feature/purchasing-control:"^2.0.0" spryker/sales:"^11.83.0" spryker/sales-extension:"^1.15.0" spryker-shop/checkout-page:"^3.40.0" spryker-shop/company-page:"^2.36.0" spryker-shop/customer-page:"^2.77.0" spryker-shop/shop-ui:"^1.108.0" --update-with-dependencies --ignore-platform-req=ext-grpc ``` ### 2) Set up database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_cost_center | table | created | | spy_cost_center_to_company_business_unit | table | created | | spy_budget | table | created | | spy_budget_consumption | table | created | | spy_quote.fk_cost_center | column | created | | spy_quote.fk_budget | column | created | | spy_sales_order.fk_cost_center | column | created | | spy_sales_order.fk_budget | column | created | Make sure the following changes have been applied in transfer objects: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | CostCenter | class | created | src/Generated/Shared/Transfer/CostCenterTransfer.php | | CostCenterCollection | class | created | src/Generated/Shared/Transfer/CostCenterCollectionTransfer.php | | CostCenterCriteria | class | created | src/Generated/Shared/Transfer/CostCenterCriteriaTransfer.php | | CostCenterConditions | class | created | src/Generated/Shared/Transfer/CostCenterConditionsTransfer.php | | CostCenterCollectionRequest | class | created | src/Generated/Shared/Transfer/CostCenterCollectionRequestTransfer.php | | CostCenterCollectionResponse | class | created | src/Generated/Shared/Transfer/CostCenterCollectionResponseTransfer.php | | CostCenterResponse | class | created | src/Generated/Shared/Transfer/CostCenterResponseTransfer.php | | CostCenterQuoteUpdateRequest | class | created | src/Generated/Shared/Transfer/CostCenterQuoteUpdateRequestTransfer.php | | CostCenterQuoteUpdateResponse | class | created | src/Generated/Shared/Transfer/CostCenterQuoteUpdateResponseTransfer.php | | Budget | class | created | src/Generated/Shared/Transfer/BudgetTransfer.php | | BudgetCollection | class | created | src/Generated/Shared/Transfer/BudgetCollectionTransfer.php | | BudgetCriteria | class | created | src/Generated/Shared/Transfer/BudgetCriteriaTransfer.php | | BudgetConditions | class | created | src/Generated/Shared/Transfer/BudgetConditionsTransfer.php | | BudgetCollectionRequest | class | created | src/Generated/Shared/Transfer/BudgetCollectionRequestTransfer.php | | BudgetCollectionResponse | class | created | src/Generated/Shared/Transfer/BudgetCollectionResponseTransfer.php | | BudgetResponse | class | created | src/Generated/Shared/Transfer/BudgetResponseTransfer.php | | BudgetConsumption | class | created | src/Generated/Shared/Transfer/BudgetConsumptionTransfer.php | | BudgetConsumptionCollection | class | created | src/Generated/Shared/Transfer/BudgetConsumptionCollectionTransfer.php | | BudgetConsumptionCriteria | class | created | src/Generated/Shared/Transfer/BudgetConsumptionCriteriaTransfer.php | | BudgetConsumptionConditions | class | created | src/Generated/Shared/Transfer/BudgetConsumptionConditionsTransfer.php | | Quote.idCostCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.idBudget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.costCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.budget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Order.fkCostCenter | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | Order.fkBudget | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | Order.costCenter | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | Order.budget | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | OrderTableCriteria.costCenterIds | property | created | src/Generated/Shared/Transfer/OrderTableCriteriaTransfer.php | | OrderTableCriteria.budgetIds | property | created | src/Generated/Shared/Transfer/OrderTableCriteriaTransfer.php | {% endinfo_block %} ### 3) Set up data import Register the following data import plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterDataImportPlugin | Imports cost centers from `cost_center.csv`. Creates or updates cost centers by key, name, description, and active status. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\DataImport | | BudgetDataImportPlugin | Imports budgets from `budget.csv`. Resolves the cost center by key and creates or updates budgets by cost center and name. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\DataImport | | CostCenterToCompanyBusinessUnitDataImportPlugin | Imports cost center to company business unit relations from `cost_center_company_business_unit.csv`. Skips already existing relations. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\DataImport | **src/Pyz/Zed/DataImport/DataImportDependencyProvider.php** ```php */ protected function getDataImporterPlugins(): array { return [ // ... new CostCenterDataImportPlugin(), #PurchasingControlFeature new BudgetDataImportPlugin(), #PurchasingControlFeature new CostCenterToCompanyBusinessUnitDataImportPlugin(), #PurchasingControlFeature ]; } } ``` Create the CSV import files: **data/import/common/common/cost_center.csv** ```csv key,name,description,is_active cc-marketing,Marketing,Marketing and communications expenses,1 cc-it,IT & Operations,IT infrastructure and software licenses,1 ``` **data/import/common/common/budget.csv** ```csv cost_center_key,name,amount,currency_iso_code,starts_at,ends_at,enforcement_rule,is_active cc-marketing,Marketing Q2 2026,50000,EUR,2026-04-01,2026-06-30,warn,1 cc-it,IT Software Licenses 2026,100000,EUR,2026-01-01,2026-12-31,block,1 cc-it,IT Hardware Approvals 2026,200000,EUR,2026-01-01,2026-12-31,require_approval,1 ``` **data/import/common/common/cost_center_company_business_unit.csv** ```csv cost_center_key,business_unit_key cc-marketing,spryker_systems_berlin cc-it,spryker_systems_berlin ``` Import the data: ```bash console data:import purchasing-control-cost-center console data:import purchasing-control-budget console data:import purchasing-control-cost-center-to-company-business-unit ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers > Cost Centers**, make sure the imported cost centers and budgets are displayed. Make sure the cost centers are assigned to the expected business units. {% endinfo_block %} ### 4) Set up behavior Enable the following behaviors by registering the plugins. #### Set up Zed plugins | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ManageCostCentersPermissionPlugin | Grants permission to create, update, and manage cost centers. Assign this permission to company roles that should have access to Purchasing Control management pages. | None | SprykerFeature\Shared\PurchasingControl\Plugin\Permission | | BudgetCheckoutPreConditionPlugin | Validates the cart grand total against the remaining budget before checkout proceeds. Blocks checkout or triggers the approval flow depending on the budget enforcement rule. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterOrderSaverPlugin | Saves the selected cost center and budget references to the sales order during checkout. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | ConsumeBudgetCheckoutPostSavePlugin | Records budget consumption immediately after the order is saved so the remaining budget balance is accurate for concurrent buyers. Does nothing when no budget is selected on the quote. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterQuoteExpanderPlugin | Expands the quote with the default cost center assigned to the buyer's business unit when no cost center is already set. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | CostCenterQuoteFieldsAllowedForSavingProviderPlugin | Adds `idCostCenter` and `idBudget` to the list of quote fields persisted to the database. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | RestoreBudgetOnCancelOmsCommandPlugin | Restores the budget balance by deducting the amount of the canceled order items. Also deducts the shipment group total if all items in the group are canceled. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | | RestoreBudgetOnRefundOmsCommandPlugin | Restores the budget balance by deducting the refundable amount of the refunded order items. When refund with shipment is enabled, also deducts the shipment group expense refundable amount if all items in the group are refunded. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | | CostCenterOrderExpanderPlugin | Expands `OrderTransfer` with the assigned cost center and company name, and with the assigned budget when present. Does nothing when no cost center is assigned to the order. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterSearchOrderExpanderPlugin | Expands each `OrderTransfer` in a list with `CostCenterTransfer` and `BudgetTransfer` when assigned. Used for order search results. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrderSearchQueryExpanderPlugin | Expands `QueryJoinCollectionTransfer` with `WHERE` conditions for `fk_cost_center` and `fk_budget` when filter fields of type `costCenter` or `budget` are present. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableQueryExpanderPlugin | Adds a `LEFT JOIN` from `spy_sales_order.fk_cost_center` to `spy_cost_center.id_cost_center` and exposes `cost_center_name` as a virtual column on the Back Office orders table query. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableHeaderExpanderPlugin | Inserts a **Cost Center** column before the **Actions** column in the Back Office orders table. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableFilterFormExpanderPlugin | Adds cost center and budget multi-select filter fields to the Back Office orders table filter form. Budget choices are loaded via AJAX filtered by the selected cost centers. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableCriteriaFilterExpanderPlugin | Filters the Back Office orders table by `costCenterIds` and `budgetIds` when present on `OrderTableCriteriaTransfer`. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterSalesTablePlugin | Normalizes the `cost_center_name` column to `-` for orders that have no cost center assigned. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | #### Set up permissions **src/Pyz/Zed/Permission/PermissionDependencyProvider.php** ```php */ protected function getPermissionPlugins(): array { return [ // ... new ManageCostCentersPermissionPlugin(), #PurchasingControlFeature ]; } } ``` **src/Pyz/Client/Permission/PermissionDependencyProvider.php** ```php */ protected function getPermissionPlugins(): array { return [ // ... new ManageCostCentersPermissionPlugin(), #PurchasingControlFeature ]; } } ``` Sync the permission plugins to the database: ```bash console sync:data permission ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers > Company Roles**, assign the **ManageCostCentersPermissionPlugin** permission to a company role. Make sure company users with that role can access the cost center management pages on the Storefront. {% endinfo_block %} {% info_block infoBox "Require Approval enforcement rule" %} If you configure budgets with the **Require Approval** enforcement rule, the following [Approval Process](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html) permissions must be registered and assigned to company roles for the approval workflow to function: | PERMISSION | REQUIRES | | --- | --- | | Buy up to grand total (`PlaceOrderPermissionPlugin`) | Send cart for approval | | Send cart for approval (`RequestQuoteApprovalPermissionPlugin`) | Buy up to grand total | | Approve up to grand total (`ApproveQuotePermissionPlugin`) | None | For plugin registration details, see [Install the Approval Process feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html). {% endinfo_block %} #### Set up Checkout plugins **src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php** ```php */ protected function getCheckoutPreConditions(Container $container): array { return [ // ... new BudgetCheckoutPreConditionPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\Checkout\Dependency\Plugin\CheckoutSaveOrderInterface|\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutDoSaveOrderInterface> */ protected function getCheckoutOrderSavers(Container $container): array { return [ // ... new CostCenterOrderSaverPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutPostSaveInterface> */ protected function getCheckoutPostHooks(Container $container): array { return [ // ... new ConsumeBudgetCheckoutPostSavePlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer places an order with a budget selected, verify the following: - Checkout is blocked when the order exceeds a budget with the **Block** enforcement rule. - An approval request is triggered when the order exceeds a budget with the **Require Approval** rule. - A warning is displayed when the order exceeds a budget with the **Warn** rule. - A `spy_budget_consumption` record is created after the order is successfully placed. - The cost center and budget IDs are saved on the `spy_sales_order` record. {% endinfo_block %} #### Set up Quote plugins **src/Pyz/Zed/Quote/QuoteDependencyProvider.php** ```php */ protected function getQuoteExpanderPlugins(): array { return [ // ... new CostCenterQuoteExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\QuoteExtension\Dependency\Plugin\QuoteFieldsAllowedForSavingProviderPluginInterface> */ protected function getQuoteFieldsAllowedForSavingProviderPlugins(): array { return [ // ... new CostCenterQuoteFieldsAllowedForSavingProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer with an assigned business unit opens a cart, make sure the quote is automatically expanded with the default cost center of their business unit. Make sure `idCostCenter` and `idBudget` are persisted to the `spy_quote` table when the quote is saved. {% endinfo_block %} #### Set up Sales plugins **src/Pyz/Zed/Sales/SalesDependencyProvider.php** ```php */ protected function getOrderHydrationPlugins(): array { return [ // ... new CostCenterOrderExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SearchOrderExpanderPluginInterface> */ protected function getSearchOrderExpanderPlugins(): array { return [ // ... new CostCenterSearchOrderExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SearchOrderQueryExpanderPluginInterface> */ protected function getOrderSearchQueryExpanderPlugins(): array { return [ // ... new CostCenterOrderSearchQueryExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableQueryExpanderPluginInterface> */ protected function getOrdersTableQueryExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableQueryExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableHeaderExpanderPluginInterface> */ protected function getOrdersTableHeaderExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableHeaderExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableFilterFormExpanderPluginInterface> */ protected function getOrdersTableFilterFormExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableFilterFormExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableCriteriaFilterExpanderPluginInterface> */ protected function getOrdersTableCriteriaFilterExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableCriteriaFilterExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SalesTablePluginInterface> */ protected function getSalesTablePlugins(): array { return [ // ... new CostCenterSalesTablePlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} - In the Back Office, open **Sales > Orders**. Make sure the **Cost Center** column is displayed in the orders table. - Make sure the orders table filter form includes cost center and budget multi-select fields. - Open an individual order. Make sure the cost center and budget names are displayed on the order detail page. - In the storefront, open **My Account > Orders**. Make sure the cost center and budget data appear on completed orders. {% endinfo_block %} #### Set up Recurring Orders plugins {% info_block infoBox "Recurring Orders feature" %} This step is only required if your project uses the [Recurring Orders feature](/docs/pbc/all/order-experience-management/latest/base-shop/feature-overviews/recurring-orders-feature-overview.html). The plugins belong to the Purchasing Control module but register in the `OrderExperienceManagement` dependency providers. {% endinfo_block %} | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | BudgetApprovalRuleRecurringOrderCheckoutValidatorPlugin | Blocks checkout when a quote being set up as a recurring order carries a budget with the `require_approval` enforcement rule. Applies regardless of the quote grand total and the remaining budget amount. Passes when no budget is selected or the budget uses another enforcement rule. | Recurring Orders feature | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\OrderExperienceManagement | | CostCenterRecurringOrderApproveFormExpanderPlugin | Adds cost center and budget dropdowns to the recurring order review approve form and validates the selected pair server-side. | Recurring Orders feature | SprykerFeature\Yves\PurchasingControl\Plugin\OrderExperienceManagement | | CostCenterRecurringScheduleEditFormExpanderPlugin | Adds cost center and budget dropdowns to the recurring schedule edit form and validates the selected pair server-side. | Recurring Orders feature | SprykerFeature\Yves\PurchasingControl\Plugin\OrderExperienceManagement | **src/Pyz/Zed/OrderExperienceManagement/OrderExperienceManagementDependencyProvider.php** ```php */ protected function getRecurringOrderCheckoutValidatorPlugins(): array { return [ new BudgetApprovalRuleRecurringOrderCheckoutValidatorPlugin(), #PurchasingControlFeature ]; } } ``` For the two Yves form expander plugins and the budget enforcement rules that can be selected on the recurring order forms, see [Install the Recurring Orders feature](/docs/pbc/all/order-experience-management/latest/base-shop/install-and-upgrade/install-features/install-the-recurring-orders-feature.html). {% info_block warningBox "Verification" %} Set a budget's enforcement rule to **Require approval**, assign it to a cart, and set up that cart as a recurring order at checkout. Make sure checkout is blocked with a message stating that the selected budget requires approval and cannot be used for a recurring order. {% endinfo_block %} ### 5) Configure Back Office navigation Add the Purchasing Control section to the Back Office navigation: **config/Zed/navigation.xml** ```xml ... ... Cost Centers Cost Centers purchasing-control cost-center index ``` Rebuild the navigation cache: ```bash console navigation:build-cache ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers**, make sure the **Cost Centers** menu item is displayed and links to the cost center list page. {% endinfo_block %} ### 6) Configure the OMS process Register the OMS command plugins and configure the OMS process XML. #### Register OMS command plugins **src/Pyz/Zed/Oms/OmsDependencyProvider.php** ```php extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... $commandCollection->add(new RestoreBudgetOnCancelOmsCommandPlugin(), 'CostCenter/RestoreBudgetOnCancel'); #PurchasingControlFeature $commandCollection->add(new RestoreBudgetOnRefundOmsCommandPlugin(), 'CostCenter/RestoreBudgetOnRefund'); #PurchasingControlFeature return $commandCollection; }); return $container; } } ``` #### Configure the OMS process XML Add the `CostCenter/RestoreBudgetOnCancel` and `CostCenter/RestoreBudgetOnRefund` commands to the relevant events in your OMS process XML. The following example uses `DummyPayment01`: **config/Zed/oms/DummyPayment01.xml** ```xml ... ... ``` #### Configure budget restoration behavior By default, shipment costs are not included when restoring the budget on refund. To include shipment costs, override `isRefundWithShipmentEnabled()` in your project config: **src/Pyz/Zed/PurchasingControl/PurchasingControlConfig.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... CostCenterMenuItemWidget::class, #PurchasingControlFeature PurchasingControlSummaryWidget::class, #PurchasingControlFeature CostCenterSelectorWidget::class, #PurchasingControlFeature CostCenterDetailWidget::class, #PurchasingControlFeature CostCenterOrderDetailWidget::class, #PurchasingControlFeature CostCenterBudgetFilterWidget::class, #PurchasingControlFeature ]; } } ``` {% info_block infoBox "Where CostCenterDetailWidget is rendered" %} Unlike the other widgets in this table, no Purchasing Control template calls `CostCenterDetailWidget`. It renders only where another template calls it explicitly. In the demo shop, its single caller is the recurring order detail sidebar of the [Recurring Orders feature](/docs/pbc/all/order-experience-management/latest/base-shop/feature-overviews/recurring-orders-feature-overview.html). To display the assigned cost center and budget elsewhere—on the cart page or a quote detail page, for example—call the widget from that template: ```twig {% raw %}{% widget 'CostCenterDetailWidget' args [data.quote] only %}{% endwidget %}{% endraw %} ``` Pass a second argument to add a budget usage summary—the total, used, and remaining amounts, plus a used-percentage bar—below the cost center and budget names: ```twig {% raw %}{% widget 'CostCenterDetailWidget' args [data.quote, true] only %}{% endwidget %}{% endraw %} ``` The summary is rendered by the `recurring-order-budget-summary` molecule the module ships. It is omitted when the argument is `false` or not passed, and also when the quote carries no budget or no currency. {% endinfo_block %} {% info_block warningBox "Verification" %} - Make sure all six widgets are available in Twig templates. - On the storefront company dashboard, make sure the **Purchasing Control** summary widget displays cost center and budget data. - On the checkout summary page, make sure the cost center and budget selector is displayed. - On the order detail page, make sure the assigned cost center and budget names are displayed. - On the order history page, make sure the cost center and budget filter controls are displayed. - Call `CostCenterDetailWidget` from a template with a quote that has a cost center assigned, and make sure the cost center and budget names are displayed. Deactivate that cost center and make sure the names are no longer displayed. {% endinfo_block %} ### 3) Extend the ShopUi select component Extend the ShopUi `select` atom to render HTML attributes for the cost center and budget selectors: **src/Pyz/Yves/ShopUi/Theme/default/components/atoms/select/select.twig** ```twig {% raw %}{% block attributes %} {%- for attrname, attrvalue in attr | default({}) -%} {%- if attrvalue is same as(true) -%} {{ attrname }}="{{ attrname }}" {%- elseif attrvalue is not same as(false) -%} {{ attrname }}="{{ attrvalue }}" {%- endif -%} {%- endfor -%} {% endblock %}{% endraw %} ``` {% info_block warningBox "Verification" %} Make sure the cost center and budget dropdowns correctly disable unavailable options. Select a cost center and make sure the budget dropdown offers only the budgets of that cost center, and that budgets of other cost centers are both hidden and disabled. {% endinfo_block %} ### 4) Extend the checkout summary template Add the `CostCenterSelectorWidget` to the checkout summary page, placing it directly above the `QuoteApprovalWidget` call: **src/SprykerShop/CheckoutPage/src/SprykerShop/Yves/CheckoutPage/Theme/default/views/summary/summary.twig** ```twig

{% raw %}{% widget 'CostCenterSelectorWidget' args [data.cart] only %}{% endwidget %}{% endraw %} {% raw %}{% widget 'QuoteApprovalWidget' args [data.cart] only %}{% endwidget %}{% endraw %}

``` {% info_block warningBox "Verification" %} On the checkout summary page, make sure the cost center and budget selector is displayed above the approval widget. {% endinfo_block %} ### 5) Set up routes Register the following route provider plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterRouteProviderPlugin | Adds storefront routes for cost center list, create, update, and quote update actions. Also adds the POST-only routes that update the cost center and budget of a quote request in the customer and agent contexts. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | | BudgetRouteProviderPlugin | Adds storefront routes for budget list, create, and update actions. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new CostCenterRouteProviderPlugin(), #PurchasingControlFeature new BudgetRouteProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} - Make sure the cost center list, create, and update pages are accessible under `/company/cost-center`. - Make sure submitting the cost center selector form in the cart updates the quote with the selected cost center and budget. - Make sure the budget list, create, and update pages are accessible. {% endinfo_block %} ### 6) Extend the order search form Register the following plugins to add cost center and budget filter fields to the storefront order history search form: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterOrderSearchFormExpanderPlugin | Adds cost center and budget filter dropdowns to the order history search form. Only adds fields when the current customer is a company user. | None | SprykerFeature\Yves\PurchasingControl\Plugin\CustomerPage | | CostCenterOrderSearchFormHandlerPlugin | Maps selected cost center and budget IDs from the filter form to `FilterFieldTransfer` entries on `OrderListTransfer`. | None | SprykerFeature\Yves\PurchasingControl\Plugin\CustomerPage | **src/Pyz/Yves/CustomerPage/CustomerPageDependencyProvider.php** ```php */ protected function getOrderSearchFormExpanderPlugins(): array { return [ // ... new CostCenterOrderSearchFormExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\SprykerShop\Yves\CustomerPageExtension\Dependency\Plugin\OrderSearchFormHandlerPluginInterface> */ protected function getOrderSearchFormHandlerPlugins(): array { return [ // ... new CostCenterOrderSearchFormHandlerPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} On the storefront **My Account > Orders** page, make sure company users see cost center and budget filter dropdowns. Make sure filtering by cost center or budget returns the expected orders. {% endinfo_block %} ## Integrate cost centers with quote requests Follow the steps below to let buyers and agents assign a cost center and a budget to a quote request. Skip this section if you do not use quote requests. {% info_block infoBox "Prerequisites" %} This part of the feature requires the [Quotation Process](/docs/pbc/all/request-for-quote/latest/install-and-upgrade/install-features/install-the-quotation-process-feature.html) feature. {% endinfo_block %} ### 1) Install the required modules ```bash composer require spryker-shop/quote-request-page:"^3.8.0" spryker-shop/quote-request-agent-page:"^3.7.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules are installed at the specified versions or higher: | MODULE | EXPECTED VERSION | | --- | --- | | QuoteRequestPage | 3.8.0 | | QuoteRequestAgentPage | 3.7.0 | {% endinfo_block %} ### 2) Allow the cost center and budget quote fields for saving Add `ID_COST_CENTER` and `ID_BUDGET` to the quote fields that are persisted with a quote request version. Without this configuration, both fields are stripped when the quote request version is saved: the update appears to succeed, but the selection is lost. **src/Pyz/Zed/QuoteRequest/QuoteRequestConfig.php** ```php */ public function getQuoteFieldsAllowedForSaving(): array { return array_merge(parent::getQuoteFieldsAllowedForSaving(), [ // ... QuoteTransfer::ID_COST_CENTER, #PurchasingControlFeature QuoteTransfer::ID_BUDGET, #PurchasingControlFeature ]); } } ``` {% info_block warningBox "Verification" %} Assign a cost center and a budget to a quote request, then reload the quote request details page. Make sure the selection is still displayed. In the database, make sure `spy_quote_request_version.quote` contains the `idCostCenter` and `idBudget` values. {% endinfo_block %} ### 3) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | QuoteRequestCostCenterSelectorWidget | Renders the cost center and budget selection UI on the quote request details and quote request edit pages. Takes a `QuoteRequestTransfer` and an optional form action route name. When the route name is omitted, the form posts to `company/cost-center/update-quote-request`. | SprykerFeature\Yves\PurchasingControl\Widget | | QuoteRequestAgentCostCenterSelectorWidget | Renders the same selection UI on the agent quote request details and agent quote request edit pages. Takes the same two arguments. When the route name is omitted, the form posts to `agent/quote-request/cost-center/update`. | SprykerFeature\Yves\PurchasingControl\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... QuoteRequestCostCenterSelectorWidget::class, #PurchasingControlFeature QuoteRequestAgentCostCenterSelectorWidget::class, #PurchasingControlFeature ]; } } ``` Both widgets are rendered from a `costCenter` block in the `quote-request-details.twig` and `quote-request-edit.twig` templates of the `QuoteRequestPage` and `QuoteRequestAgentPage` modules. In a project that uses these templates as they are shipped, no template changes are required. To change or remove the placement, override the `costCenter` block. {% info_block warningBox "Template overrides" %} If your project overrides any of the four templates, the widget is not rendered on the affected pages, because your override replaces the module template that contains the `costCenter` block. Re-base your overrides against the new module templates, or add the `costCenter` block to them. {% endinfo_block %} The second argument controls where the form returns to after saving. The details pages omit it, so the widget falls back to the details route. The edit pages pass it explicitly: the `QuoteRequestPage` edit template passes `company/cost-center/update-quote-request-from-edit`, and the `QuoteRequestAgentPage` edit template passes `agent/quote-request/cost-center/update-from-edit`. Pass a route name of your own only if you also register a route that returns to your page. {% info_block infoBox "Info" %} The widgets suppress themselves when there is nothing to show. An editable quote request renders the selection form only if at least one cost center is available to the owner's business unit. A quote request that is not editable displays the assigned cost center and budget as read-only. {% endinfo_block %} {% info_block warningBox "Verification" %} - On the Storefront, open a quote request in an editable status and make sure the cost center and budget selection is displayed on both the details page and the edit page. - Select a cost center and a budget, then submit the form. Make sure a success message is displayed and the page returns to the details page or the edit page, depending on where you started. - Open a quote request that is not editable and make sure the assigned cost center and budget are displayed as read-only, without a submit button. - As an agent, open a customer's quote request and make sure the cost center dropdown lists the cost centers of the customer's business unit, not your own. {% endinfo_block %} ### 4) Review the quote request routes The `CostCenterRouteProviderPlugin` that you registered in [Set up routes](#5-set-up-routes) adds the following routes. All of them accept `POST` requests only, and each one determines its own return page, so the redirect target cannot be supplied by the request. | ROUTE NAME | PATH | RETURNS TO | | --- | --- | --- | | `company/cost-center/update-quote-request` | `/company/cost-center/update-quote-request/{quoteRequestReference}` | Quote request details page | | `company/cost-center/update-quote-request-from-edit` | `/company/cost-center/update-quote-request-from-edit/{quoteRequestReference}` | Quote request edit page | | `agent/quote-request/cost-center/update` | `/agent/quote-request/cost-center/update/{quoteRequestReference}` | Agent quote request details page | | `agent/quote-request/cost-center/update-from-edit` | `/agent/quote-request/cost-center/update-from-edit/{quoteRequestReference}` | Agent quote request edit page | The two `-from-edit` routes are reached only when a widget receives a form action route name as its second argument. For details, see [Set up widgets](#3-set-up-widgets). The two agent routes are deliberately placed under `/agent/` so that they are covered by the agent firewall. {% info_block warningBox "Verification" %} - Make sure a `GET` request to any of the four paths is rejected. - Make sure a buyer cannot update the cost center of a quote request that belongs to another company user: the request must return `404`, the same response as for a quote request reference that does not exist. - Make sure an anonymous request to either agent path is rejected by the agent firewall. {% endinfo_block %}

Install the Configuration Management feature

Tue, 25 Aug 2026 07:19:33 +0000

This document describes how to install the Configuration Management feature. ## Prerequisites Update the required modules: | NAME | VERSION | |----|---------| | Kernel | ^3.82 | | Store | ^1.36 | | Translator | ^1.15 | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/configuration:"^1.0.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | | --- | --- | | Configuration | vendor/spryker/configuration | {% endinfo_block %} ### 2) Set up configuration Add the following configuration to extend scope support with store-level configuration: | CONFIGURATION | SPECIFICATION | NAMESPACE | | --- | --- | --- | | ConfigurationConfig | Adds `store` scope to available scopes and defines scope hierarchy (store inherits from global). | Pyz\Shared\Configuration | **src/Pyz/Shared/Configuration/ConfigurationConfig.php** ```php ' SPRYKER_CONFIGURATION_ENCRYPTION_INIT_VECTOR: '' ``` In Cloud, add environment variables using [Parameter Store](/docs/ca/dev/add-variables-in-the-parameter-store). To generate new keys, run: ```bash openssl rand -hex 32 # generates SPRYKER_CONFIGURATION_ENCRYPTION_KEY openssl rand -hex 16 # generates SPRYKER_CONFIGURATION_ENCRYPTION_INIT_VECTOR ``` {% info_block warningBox "Verification" %} 1. Create a setting with `secret: true` in a YAML schema and run `configuration:sync`. 2. Set a value for the secret setting in the Back Office. 3. Check the `spy_configuration_value` table — the stored value must be encrypted (not plain text). 4. Read the value back in the Back Office — it must be decrypted and displayed correctly. {% endinfo_block %} ### 3) Set up the database schema and transfer objects #### 3.1) Set up database schema extension Add event behavior to the `spy_configuration_value` table to enable Publish & Synchronize: **src/Pyz/Zed/Configuration/Persistence/Propel/Schema/spy_configuration.schema.xml** ```xml

``` #### 3.2) Apply database changes and generate transfers ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied by checking your database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_configuration_value | table | created | | spy_configuration_storage | table | created | {% endinfo_block %} {% info_block warningBox "Verification" %} Make sure the following changes in transfer objects have been applied: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | ConfigurationSetting | class | created | src/Generated/Shared/Transfer/ConfigurationSettingTransfer | | ConfigurationValue | class | created | src/Generated/Shared/Transfer/ConfigurationValueTransfer | | ConfigurationScope | class | created | src/Generated/Shared/Transfer/ConfigurationScopeTransfer | | ConfigurationFeature | class | created | src/Generated/Shared/Transfer/ConfigurationFeatureTransfer | | ConfigurationTab | class | created | src/Generated/Shared/Transfer/ConfigurationTabTransfer | | ConfigurationGroup | class | created | src/Generated/Shared/Transfer/ConfigurationGroupTransfer | | ConfigurationConstraint | class | created | src/Generated/Shared/Transfer/ConfigurationConstraintTransfer | | ConfigurationDependency | class | created | src/Generated/Shared/Transfer/ConfigurationDependencyTransfer | | ConfigurationSyncResponse | class | created | src/Generated/Shared/Transfer/ConfigurationSyncResponseTransfer | | ConfigurationSettingCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingCollectionTransfer | | ConfigurationScopeCollection | class | created | src/Generated/Shared/Transfer/ConfigurationScopeCollectionTransfer | | ConfigurationValueRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueRequestTransfer | | ConfigurationValueResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueResponseTransfer | | ConfigurationValidationRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValidationRequestTransfer | | ConfigurationValidationResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValidationResponseTransfer | | ConfigurationError | class | created | src/Generated/Shared/Transfer/ConfigurationErrorTransfer | | ConfigurationValueCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionRequestTransfer | | ConfigurationValueDeletion | class | created | src/Generated/Shared/Transfer/ConfigurationValueDeletionTransfer | | ConfigurationValueCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionResponseTransfer | | ConfigurationSettingValuesCriteria | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValuesCriteriaTransfer | | ConfigurationSettingValueCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValueCollectionTransfer | | ConfigurationStorage | class | created | src/Generated/Shared/Transfer/ConfigurationStorageTransfer | | ConfigurationFileUpload | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadTransfer | | ConfigurationFileUploadCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadCollectionRequestTransfer | | ConfigurationFileUploadCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadCollectionResponseTransfer | {% endinfo_block %} ### 4) Add translations Regenerate the Zed translator cache to pick up the Configuration Management Back Office UI translations: ```bash console translator:generate-cache ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Verify that all UI labels, buttons, and messages are displayed in the correct locale. 3. Switch to German locale and verify the German translations appear. {% endinfo_block %} ### 5) Configure navigation Add the Configuration Management entry to `config/Zed/navigation.xml`: ```xml Configuration Configuration Management settings configuration manage index 1 ``` Execute the following command to clear the navigation cache: ```bash console navigation:cache:remove ``` {% info_block warningBox "Verification" %} Log in to the Back Office and verify that the **Configuration** menu item appears in the main navigation sidebar. {% endinfo_block %} ### 6) Set up behavior #### 6.1) Register console commands and application plugin Register the configuration sync console command and the application plugin that exposes the Configuration facade as an application service for direct Zed access from the Client layer: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationSyncConsole | Synchronizes configuration schemas from YAML files and generates the merged schema and settings map. | None | Spryker\Zed\Configuration\Communication\Console | | ConfigurationApplicationPlugin | Registers the Configuration facade as an application service for direct access in Zed applications. | None | Spryker\Zed\Configuration\Communication\Plugin\Application | **src/Pyz/Zed/Console/ConsoleDependencyProvider.php** Add the import statements: ```php use Spryker\Zed\Configuration\Communication\Console\ConfigurationSyncConsole; use Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin; ``` Register the console command in `getConsoleCommands()`: ```php protected function getConsoleCommands(Container $container): array { $commands = [ // ... new ConfigurationSyncConsole(), // ... ]; } ``` Register the application plugin in `getApplicationPlugins()`: ```php protected function getApplicationPlugins(Container $container): array { $applicationPlugins = parent::getApplicationPlugins($container); // ... $applicationPlugins[] = new ConfigurationApplicationPlugin(); return $applicationPlugins; } ``` **src/Pyz/Zed/Application/ApplicationDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin; ``` Register the application plugin in each Zed application context (`getBackofficeApplicationPlugins()`, `getBackendGatewayApplicationPlugins()`, `getBackendApiApplicationPlugins()`): ```php protected function getBackofficeApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } protected function getBackendGatewayApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } protected function getBackendApiApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Run `console configuration:sync` and verify that it outputs the number of processed settings. 2. Verify that configuration values can be read in Zed context via the Client layer without going through storage. {% endinfo_block %} #### 6.2) Set up queue configuration Register the Configuration storage synchronization queue in both message broker implementations. **src/Pyz/Client/RabbitMq/RabbitMqConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` **src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` {% info_block warningBox "Verification" %} Run `console queue:setup` and verify that the `sync.storage.configuration` queue is created in RabbitMQ. {% endinfo_block %} #### 6.3) Register queue message processor Register the synchronization storage queue message processor for the Configuration sync queue: **src/Pyz/Zed/Queue/QueueDependencyProvider.php** Add the import statements: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the processor to `getProcessorMessagePlugins()`: ```php protected function getProcessorMessagePlugins(Container $container): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION => new SynchronizationStorageQueueMessageProcessorPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Run `console queue:worker:start --stop-when-empty`. 3. Verify that the `sync.storage.configuration` queue is processed without errors. {% endinfo_block %} #### 6.4) Register publisher plugins Enable Publish & Synchronize for configuration values by registering the publisher plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationValueWritePublisherPlugin | Publishes storefront-visible, non-secret configuration values to `spy_configuration_storage` when `spy_configuration_value` entities are created, updated, or deleted. | None | Spryker\Zed\Configuration\Communication\Plugin\Publisher | **src/Pyz/Zed/Publisher/PublisherDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Publisher\ConfigurationValueWritePublisherPlugin; ``` Register the plugin group in `getPublisherPlugins()`: ```php protected function getPublisherPlugins(): array { return array_merge( // ... $this->getConfigurationStoragePlugins(), ); } ``` Add the new method: ```php /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherPluginInterface> */ protected function getConfigurationStoragePlugins(): array { return [ new ConfigurationValueWritePublisherPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Check that the `spy_configuration_storage` table contains the published value. 3. Verify that secret settings are NOT published to storage. {% endinfo_block %} #### 6.5) Register scope identifier provider plugins Register the store scope identifier provider to resolve the current store name as the scope identifier: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreConfigurationScopeIdentifierProviderPlugin | Provides the current store name as the scope identifier for the `store` scope. | Store module installed | Spryker\Zed\Store\Communication\Plugin\Configuration | **src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php** ```php */ protected function getScopeIdentifierProviderPlugins(): array { return [ new StoreConfigurationScopeIdentifierProviderPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Switch the scope selector to a specific store. 3. Verify that the scope identifier resolves to the store name (for example `DE`, `AT`). {% endinfo_block %} #### 6.6) Register Client-level request expander plugins Register the store scope expander to attach the current store scope to configuration value requests: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreScopeConfigurationValueRequestExpanderPlugin | Expands the configuration value request with the current store scope and store name as scope identifier. | Store module installed | Spryker\Client\Store\Plugin\Configuration | **src/Pyz/Client/Configuration/ConfigurationDependencyProvider.php** ```php

Workflows, Skills, and Agents

Mon, 24 Aug 2026 13:00:28 +0000

Overview

The AI Dev SDK ships five ready-made workflows, more than 30 skills, and six agents that codify common Spryker practice — from turning a demoshop clone into a customer project, to building features, fixing bugs, and upgrading releases. Instead of teaching your AI assistant Spryker’s conventions prompt by prompt, you install workflows that already know them.

The skills and agents reach your project in two ways:

Via the ai-dev:setup console command — copies the skills and agents into your project’s AI-tool directories (.claude/skills/ + .claude/agents/, .windsurf/skills/ + .windsurf/agents/, and so on) for every AI tool listed under Generated files per AI tool. Codex CLI has no agents directory, so agents are skipped for that tool.
Via the Claude Code plugin — for Claude Code users, the Claude Code plugin installs the same skills and agents through the official marketplace, no console command required.

Both delivery paths read from the same source files — the plugin just packages them for marketplace installation.

What’s the difference between a skill and an agent?

Skills load into the active chat on demand. Use them when you want the assistant to follow a specific workflow (write a product requirement document, refresh caches, run QA).
Agents are isolated sub-conversations the assistant delegates to. Use them when you want focused, single-purpose work done in its own context window (verify a behavior, diagnose a failure).

You do not need to remember the names — the assistant picks the right skill or agent from your prompt. The tables below explain what each one does so you know what to expect.

Available workflows and wizards

Five shipped workflows cover the work most projects need on day one, so you get value before you write anything of your own. Each has its own page, listed under this one in the sidebar:

Workflow	Skill	What it does
Project Starter Wizard	`project-starter-wizard`	Turns a fresh demoshop clone into your project
Customization Workflow	`spryker-customization`	Builds a feature from a product requirement document to a committed branch
Bugfix Workflow	`spryker-bugfix`	Drives a bug to a validated, QA-accepted fix
Upgrade Workflow	`spryker-upgrade`	Upgrades a customized project to a newer Spryker release
Profiler Workflow	`spryker-profiler`	Reads the Spryker WebProfiler as hard performance numbers

The first four are orchestrators: they own a full workflow and delegate each stage to the specialist skills and agents listed below. Alongside them, product-requirement-document turns a feature idea into a research-grounded spec, so you can go from idea to specification to implementation without leaving your assistant.

Composable by design

Each skill covers one stage of work and nothing more — research a feature, seed test data, run static validation, drive the running app, capture screenshots. Nothing is bundled into a single monolithic assistant, so you compose the stages into whatever long-running workflow your team actually runs.

This is how the orchestrator skills themselves are built. spryker-bugfix does not reimplement testing or validation — it calls codecept-functional, static-validation, code-review, and spryker-qa-coverage in sequence, and delegates isolated work to the agents. Your own workflows compose the same building blocks the same way.

Adapt the shipped workflows to your process. The four orchestrators are a baseline, not a prescription. Every team runs a different process — different review gates, different definition of done, different tracker. Because the stages are separate, you can reorder them, skip the ones you do not need, or drop your own stage in between. Ask for the workflow you want in your own words and the assistant assembles it from the installed skills.

Use the shipped skills as a template for your own. Every skill is plain Markdown with frontmatter, and every one ships a README documenting its flow, design decisions, and limits — linked in the Reference column of the tables below. Read the skill closest to what you need, then write your own the same way: your team’s release checklist, your onboarding walkthrough, your project-specific conventions. The result is AI-assisted development shaped by how your team works rather than by a fixed set of commands.

How to invoke

In most cases you do not need to call a skill or agent by name. Describe what you want — “build this feature”, “verify the new fee shows on the cart”, “write a product requirement document for…” — and the assistant matches your wording to the right skill or agent from the set installed in your project.

If you want to invoke one explicitly:

Claude Code plugin — every skill is also available as a slash command. Type /spryker-ai-dev-sdk:<skill-name> (for example /spryker-ai-dev-sdk:spryker-customization) and the skill loads into the current chat. The command naming rule is on the Claude Code page.
Other AI tools — invocation follows the tool’s own convention for skills and agents. In Cursor, Windsurf, Copilot, OpenCode, and Codex CLI, the skills and agents land in the tool-specific directories (.cursor/, .windsurf/, etc.) and are picked up automatically by your assistant. Generated files per AI tool lists the output paths per tool.
Agents (subagents) are not invoked by the user directly — they are spawned by the assistant or by a parent skill when the work calls for an isolated context. You can suggest one by name in your prompt (“use the spryker-verifier to…”), but the assistant decides when to spawn.

Skills

Skills are delivered through ai-dev:setup (all supported AI tools) or the Claude Code plugin.

Every skill ships a README in its own directory in the plugin repository, covering its full flow, design decisions, and known limits. The Reference column links to it — use it when the summary here is not enough.

Orchestrator skills

These skills own a full workflow and delegate each stage to the specialist skills and agents below. Each has its own page.

Skill	Purpose	Benefits	Reference
`project-starter-wizard`	Turn a fresh clone of a demoshop into the customer’s project	One developer interview up front, then nine orchestrated steps to a verified running shop; a resumable state file survives interruptions	README
`spryker-customization`	Walk a product requirement document or set of acceptance criteria through to a committed branch	One workflow drives the full build; quality bar (PoC or MVP) chosen up-front; never auto-commits	README
`spryker-bugfix`	Drive a bug from an optional tracker ticket or a plain description through to a committed, validated, QA-accepted fix	Orchestrates reproduce, root cause, minimal fix, functional test, static validation, review, QA, and final verification; a shared attempt budget loops back on any failed gate; Autonomous mode adds a pushed draft PR with a remote CI watch loop	README
`spryker-upgrade`	Upgrade the project’s modules and features to a newer Spryker release	Checks first whether the customizations are covered by tests at all, resolves the constraint blockers that stop a release-group bump, then detects the silent damage a heavily customized project would otherwise ship	README

Project setup skills

The project-starter-wizard runs these as its steps, and each also works standalone on an existing project.

Skill	Purpose	Benefits	Reference
`project-ci-generator`	Transform an inherited product-style CI setup into a single, lean project CI pipeline	Reads the CI that actually exists rather than applying a template; proposes a keep/drop plan for approval before deleting anything; ports the same jobs to GitLab or Bitbucket	README
`configure-codebase`	Register a custom namespace instead of `Pyz` and wire autoload, frontend build, and Codeception to resolve it	One pass covers every place the namespace must be declared, so the project builds, lints, and tests under its own name	README
`brand-project`	Apply or change the project’s brand identity — name, development domain, Docker namespace, palette, and logo	Repeatable any time, not only at project start; works pre- or post-boot	README
`configure-services`	Change what infrastructure the project runs on, or build a new environment deploy file	Surgical edits to the keys it owns; neighboring deploy-file blocks stay untouched	README
`define-stores`	Create or redefine a DMS project’s stores and region before the first boot	Clears the hardcoded store and locale literals that otherwise abort the boot	README
`project-data`	Populate, reshape, reduce, clean up, or remove the project’s import data	One skill for every `data/import` change — adapt the demo shop to your stores, generate a catalog from images, or start with no demo data at all	README
`spryker-import-tools`	Read, filter, edit, and validate data import CSV files and manifests	Reliable where shell tools corrupt multi-line quoted fields; static validation catches boot-aborting data in seconds	README
`boot-and-verify`	Take a transformed project from “files written” to “verified running”	Per-store verification of storefront, Back Office, search, and queues; an independent verifier agent gives the verdict	README
`curate-golive-data`	Make the data the project keeps production-safe before go-live	Resolves the go-live warnings the data and boot steps surface — placeholder tax rates, Spryker CDN imagery, demo accounts	README
`translate-content`	Translate storefront content into a project locale	Strictly per-locale and opt-in; covers glossary as well as catalog, CMS, navigation, and labels	README

Development skills

Skill	Purpose	Benefits	Reference
`ai-dev-setup`	Generate rules, an agents/context file, and skills for the project and the chosen AI tool	One command sets up consistent AI tooling for the whole team; also refreshes the rules and context file from the latest upstream content	README
`code-review`	Review staged or PR changes against Spryker coding standards	Catches Spryker-specific issues before they reach a pull request	README
`propel-schema`	Create and modify Propel ORM schema files	Follows Spryker schema conventions automatically	README
`data-import`	Create and modify data import CSV files and importers	Generates importers that fit Spryker’s data-import path	README
`static-validation`	Run static analysis over only the code that changed against a base branch — PHP and frontend	Validates the diff rather than the whole project; groups PHP by changed file or by whole changed module	README
`payment-template`	Scaffold payment method integration	Follows Spryker payment module patterns end-to-end	README
`yves-atomic-frontend`	Create atomic design components for the Yves storefront	Components match the project’s atomic conventions	README
`product-requirement-document`	Turn a feature idea into a research-grounded product requirement document before any code is written	Spec-before-code; assigns a real Spryker actor to every story; cuts ambiguity before implementation	README
`spryker-refresher`	Run the right post-change console and composer commands after edits	Owns the file-to-command mapping (codegen, caches, frontend builds, class-resolver); no missed cache rebuilds	README
`spryker-docs-research`	Look up the right answer in official Spryker documentation	Grounds AI work in documented behavior rather than the model’s memory; falls back gracefully when MCP tools are unavailable	README
`spryker-runtime`	Drive the running Spryker application — Yves, Back Office, Merchant Portal, console, HTTP	Real authenticated sessions; read-only DB, Redis, and queue inspection; reusable building block for higher-level skills and agents	README
`ai-runtime-debugging`	Inspect Spryker runtime state safely from an AI session	`[AI-DEBUG]` tagged-log pattern plus optional XDebug step-debug; built-in cleanup of debug instrumentation before commit	README

Testing and performance skills

Skill	Purpose	Benefits	Reference
`codecept-functional`	Generate Codeception functional tests	Tests follow Spryker test patterns out of the box	README
`cypress-tests`	Create, run, review, and validate Cypress end-to-end tests	Day-to-day E2E work against your project’s own suite — storefront, Back Office, Merchant Portal, and Glue API	README
`cypress-migration`	Replace Spryker’s demoshop test suites with a project-owned Cypress baseline	One-time migration; vendors in a proven reference implementation, wires up CI, and generates the companion `cypress-tests` skill for the project	README
`spryker-qa-coverage`	Turn acceptance criteria into a four-bucket test plan executed against the live app	Coverage goes beyond literal acceptance criteria — happy, negative, authorization, and corner cases; reports pass/fail with real evidence	README
`spryker-profiler`	Read and configure the Spryker WebProfiler — every metric it recorded about a request	Real measurements instead of guesses; finds N+1 duplicates, Redis and search call counts, and the heaviest request; also fixes a profiler that shows no data	README

Agents

Agents are delivered through ai-dev:setup (every supported AI tool with an agents directory) or the Claude Code plugin.

Each agent does one narrowly defined job in its own context and reports back — the “never” boundaries in the table are what make the results trustworthy.

Agent	Purpose	Benefits
`spryker-code-reviewer`	Review code against Spryker’s coding standards and architectural rules	Deeper, Spryker-aware review than a generic linter; catches layer-architecture and module-convention issues
`spryker-feature-expert`	Answer “how does feature X work in this project / in Spryker”	Pushes back when the user’s framing reinvents an existing primitive; surfaces canonical patterns first; never edits code
`spryker-verifier`	Verify that a specific behavior holds in the running Spryker environment	Returns PASS / FAIL / BLOCKED per acceptance criterion with raw evidence; never lies green; never tries to fix
`spryker-issue-diagnoser`	Investigate why something failed and return a root cause	Reads logs, DB state, queue, search, browser console — returns a suggested direction; never attempts the fix itself
`spryker-data-seeder`	Create small additive test data through Spryker’s existing import path	Safe and incremental — CSV + `data:import` only; never edits code, never writes directly to the database
`spryker-screenshot-collector`	Capture screenshots and GIFs of pages and flows for demos and documentation	Pure capture — never asserts whether something works, never investigates failures, never edits

Upgrade Workflow

Mon, 24 Aug 2026 13:00:28 +0000

Availability

The spryker-upgrade skill is available from spryker-sdk/ai-dev version 0.6.4, which ships version 0.4.0 of the spryker-ai-dev-sdk Claude Code plugin.

To update the Claude Code plugin, run /plugin in Claude Code and update spryker-ai-dev-sdk from the spryker-plugins-official marketplace to version 0.4.0 or later. For installation instructions, see Claude Code.

What the skill does

spryker-upgrade upgrades your project’s modules and features to a newer Spryker release. It is built for projects with heavy src/Pyz customization, where the dangerous part of an upgrade is not the code that stops compiling but the code that keeps running while doing nothing.

The skill combines an orchestrated workflow with a set of deterministic detector scripts. Each script is a standalone CLI that runs on host PHP using reflection or static parsing only, with no Spryker bootstrap — so they also work in CI.

Invoke it with “upgrade the project”, “update to the latest release”, or any request to bump spryker-feature/* or spryker/* packages.

Why silent damage is the real problem

Everything a Spryker project overrides fails quietly when core moves. A dead override still loads, a replaced plugin stack still boots, and a stale template still renders. Nothing errors — the customization simply stops taking effect.

The workflow therefore starts with a different question than “which modules changed”. It asks which of your customizations would notice if they stopped working, and whether the upgrade can be verified at all.

The phases

Coverage check — measures your override surface against the tests that cover it, and offers to write characterization tests for the gaps. These must be written before the upgrade; written afterwards they pin the upgraded behavior and can no longer detect that it changed.
Preflight and baselines — records snapshots of overrides and shadowed frontend files, checks for constraint styles that block resolution, and captures pre-existing damage so it is not misattributed to the upgrade.
Constraint resolution — relaxes patch-locked constraints, then resolves conflicts iteratively. Conflicts arrive in waves, each root bump revealing the next transitive layer.
Detection — after Composer completes, runs the detectors that find the silent damage.
Resolution — merges shadowed files, rewires replaced plugin stacks, fixes broken configuration references, and requires a migration guide for every major module bump.

What the detectors find

Detector	Damage it catches
`check-test-coverage.php`	Customizations with no test over them, ranked by risk, with the test type that would catch each gap
`check-vendor-class-replacement.php`	Project files that declare a vendor namespace and replace a core class outright, so the vendor implementation never loads
`check-constraint-style.php`	Patch-locked or exactly pinned constraints that make a feature bump unresolvable
`check-typed-members.php`	Untyped overrides of constants and properties that core has since typed — a fatal on class load that aborts the console itself
`check-dead-overrides.php`	Project methods overriding a vendor method that the new version deleted, so the project logic stops being called
`twig-shadow-map.php`	Shadowed Twig, SCSS, and TypeScript files whose vendor counterparts changed upstream
`merge-shadowed-files.php`	Runs a three-way merge for every shadowed file and sorts the outcomes into clean, identical, conflicted, and removed
`check-plugin-usage.php`	Vendor plugins that are missing or deprecated after the upgrade, and project plugins implementing a removed interface
`check-config-constants.php`	Configuration referencing a vendor constants interface or constant that no longer exists, which breaks bootstrap of every application
`list-major-bumps.php`	Every major module bump, with a documentation search URL, changelog URL, and compare URL per package
`resolve-constraints.php`	Runs Composer, parses root conflicts, raises the constraints the tree demands, and repeats
`unpin-feature-driven-modules.php`	Breaks a cohort deadlock, where a group of modules sharing a dependency must move together

The detectors keep their snapshots and reports in .spryker-upgrade/state/ inside the project, created self-gitignoring on first use.

Order matters

The dependency between the detectors is real. The skill runs them in the correct order — coverage and replacement checks first, then baselines and constraint preflight, then resolution, then post-Composer detection. Running them out of order wastes time on phantom findings.

Run the detectors in CI

Two detectors are cheap enough to gate every pull request, and both catch damage that is otherwise invisible until runtime:

php $UP/check-typed-members.php     # fatals on class load
php $UP/check-plugin-usage.php      # missing plugins

Neither needs a snapshot, a database, or a search backend — only an installed vendor/ directory. Failing the build on exit code 1 turns “the Back Office returns 500 after deploy” into a red pipeline.

For dependency-bumping pull requests, also wrap the change in a snapshot and verify pair for check-dead-overrides.php and twig-shadow-map.php, because those compare against pre-upgrade state and cannot work from a single point in time.

You can also gate check-test-coverage.php in CI, but gate it on a ratchet rather than on zero: fail when a pull request increases the number of untested overrides. New customization then arrives with a test, instead of the project needing a coverage project before anyone can merge.

Known limits

No detector covers Propel schema merges, glossary keys, ACL and navigation for new Back Office routes, or pure behavioral change. Those remain process gates and tests, and the skill marks them as such.

Published migration guides are also sometimes stale or absent, so the skill treats the tag diff, not the guide, as the source of truth.

Requirements

A Spryker project with Composer installed, and host PHP available to run the detector scripts
An AI tool with the SDK’s skills loaded — either through the Claude Code plugin or via ai-dev:setup for another supported tool

spryker-upgrade README — the skill’s own reference in the plugin repository
Workflows, Skills, and Agents — the full reference of every skill and agent
Upgrade and migrate — the manual upgrade and migration guides
Installation — install the SDK and generate your project’s rules, context file, and skills

Project Starter Wizard

Mon, 24 Aug 2026 13:00:28 +0000

Every Spryker project starts from a demoshop — a complete, working reference shop that you reshape into your customer’s project. Doing that by hand means changes across CI configuration, namespaces, deploy files, stores, and demo data, in an order that is easy to get wrong. The project-starter-wizard skill handles it for you: one developer interview, then a single orchestrated run that ends in a booted shop, verified store by store.

What the skill does

project-starter-wizard turns a fresh, un-booted clone of the Spryker B2B Marketplace demoshop into your customer project. It collects everything once up front — in a developer interview, or from a setup questionnaire you fill instead. Either way, the answers land in a resumable state file, and the wizard then drives nine specialist skills in the one order that works.

The wizard owns the conversation and the flow — it writes almost nothing itself. Each step delegates to a sibling skill that does the transformation work.

It is also the resume entry point — if a previous run left a state file, invoking the skill again skips the interview and continues from the first unfinished step.

Before you start

The wizard needs the SDK’s skills loaded into your AI tool. If you have not done that yet, install the AI Dev SDK first.

For this wizard, use the Claude Code plugin: it installs into Claude Code itself and needs nothing from the project, so your tooling is ready on a fresh clone. The ai-dev:setup console command is the alternative for other assistants, but it requires an installed project — which a fresh clone is not yet.

The wizard requires plugin version 0.4.0 or later. If the plugin is already installed, run /plugin and update it.

Verify the installation

Type /spryker-ai-dev-sdk:project-starter-wizard in Claude Code. The command autocompletes when the plugin is loaded; if it does not appear, run /reload-plugins and check the plugin with /plugin.

Choose a demo-data strategy

Before starting the wizard, think about which strategy best fits your goal — the choice determines what you need to prepare in advance:

Generate demo data. Prepare product images and a logo before you start; this is optional, but highly recommended because the wizard can use the logo colors in the project theme.
Adapt the existing demo data to the new store structure. For example, existing products receive new prices and store relations.
Clean the demo data so that everything is removed except the minimum required for the project setup.

The wizard does everything itself, except one thing: in generate mode, you supply the images and the logo — the wizard never fabricates them.

Time and tokens

Adapt and clean are the smoothest options: one boot and a handful of confirmations. Data generation is the most resource-intensive option and requires a significant number of tokens. Real localization — including glossary and catalog translations rather than English stubs — is also resource-intensive and time-consuming. These options are worthwhile when needed, but choose them deliberately.

Start the wizard

Clone the Marketplace B2B Demo Shop and start Claude Code in the clone, without booting or installing the project first:

git clone https://github.com/spryker-shop/b2b-demo-marketplace.git my-project
cd my-project
claude

Then describe your project. For example:

We need to set up a project.
Ostrem sells marine hardware to boatyards and refit shops: brass compasses, brass handrails, brass cleats and ropes.
The logo is supplied as SVG in more than one color, with several variants: an icon, a horizontal lock-up with wordmark, a dark app tile, and a simplified favicon.
The images and logo are inside the ostrem-images folder.

A shorter prompt such as “We need to set up a project.” is also sufficient — you can provide the remaining details during the interview.

The interview

The wizard asks nine short questions and needs no further configuration decisions after them. Each question shows the demo’s current default; accept it with one click or override it. Accepting every default is valid.

Project identity — project name, local development domain, one or two brand colors, and an optional logo.
Code area (namespace) — keep the demo’s Pyz namespace or choose your own private area to keep your code safe from Spryker updates. The wizard proposes a valid name.
Services and applications — everything is enabled by default. Choose what to turn off or replace, including headless mode, the Merchant Portal, Storybook, the Storefront API, and the Backend API. Keep the infrastructure defaults unless your hosting requires otherwise.
Stores and region — describe your stores, including languages, currencies, countries, and timezone. The wizard proposes one region for confirmation; a multi-region setup requires manual follow-up.
Demo-data strategy — confirm the strategy you chose earlier. Adapt asks for a currency exchange-rate table, clean asks nothing extra, and generate asks for your theme, products, categories, prices, image folders, and content language.
Catalog scope (adapt only) — choose the entire demo catalog or a subset.
Localization — off by default, with each language starting as an English copy. Enable it only when you need real translation.
Automatic quality checks (CI) — set up a lightweight check for every change, skip it, or let a developer tune it later.
Run mode — choose autonomous or supervised; see Run modes.

The wizard summarizes the configuration and asks for confirmation before making any changes. After you confirm, the setup runs without further configuration questions.

The nine steps

Steps 1 to 7 run before the first boot, because each one changes files the boot reads.

Step	Skill	What it does
1	`project-ci-generator`	Rebuilds the inherited product CI into a single lean project pipeline
2	`configure-codebase`	Registers the custom namespace and wires autoload, frontend build, and Codeception. Skipped when the project keeps `Pyz`
3	`brand-project`	Applies the project identity — name, domain, Docker namespace
4	`configure-services`	Writes the chosen engines, development services, and applications into `deploy.dev.yml`
5	`define-stores`	Creates the region and store definitions. Skipped when the data mode is `leave`
6	`project-data`	Adapts, cleans, generates, or leaves the import data
7	`cypress-migration`	Replaces the demoshop test suites with a project-owned Cypress baseline
8	`boot-and-verify`	First boot and per-store verification, including applying the theme
9	`translate-content`	Translates storefront content. Runs only when you selected locales to localize

Run modes

You choose the run mode in the interview, and the wizard honors it again on resume:

Autonomous — steps 1 to 9 run as one continuous pass. At a reversible decision point the wizard picks the best option and records it in a decision log.
Supervised — the wizard reports a one-line result and asks “Continue to the next step?” at each step boundary. A good choice for your first run.

When the wizard stops for you

Neither run mode relaxes the hard stops. During the run, the wizard may print ⚠ ACTION NEEDED and wait for something only you can do:

Start Docker or OrbStack — the wizard cannot start it for you.
Update /etc/hosts — this requires sudo. If you skip it, the setup still completes, but browser checks are marked as blocked.
Approve destructive actions — the wizard shows exactly what will be removed and waits for your confirmation.
Supply your own images and logo in generate mode.
Point Git at your repository and commit when ready — the wizard stages files but never commits or pushes.

Any step failure also returns control to you, in both modes.

Run artifacts

The run writes three files into the clone’s own tree under .ai-dev/:

File	Role
`project-setup.md`	The state — interview answers and a step table with per-step status. Resume reads this file
`run.log`	The timeline — step boundaries, conditional skips with their reason, hard stops, and every resume
`decision-log.md`	The rationale — each autonomous decision with its evidence and how to reverse it

What you get at the end

A transformed clone with:

The project identity and branding applied
A registered custom namespace
The services and stores you chose
Project-shaped import data
A lean, project-owned CI pipeline
A vendored Cypress test suite

All of it booted and verified per store by an independent verifier agent, with all changes staged but never committed — you review everything before it enters the project’s history.

The closing summary flags what still needs a human before go-live, such as a git remote that still points at the demoshop upstream, a still-shipped Spryker logo, or translation debt from locales left as English copies.

Troubleshooting

The wizard has stopped and appears to be waiting. Look for a line beginning ⚠ ACTION NEEDED. The wizard is waiting for an action only you can perform, such as starting Docker or OrbStack, adding the /etc/hosts entry, or approving a destructive action. Complete the requested action and the wizard continues.
The boot fails or the shop does not start. Check that Docker or OrbStack is running, ports 80 and 443 are available, and your disk has enough free space. A GitHub rate limit may also have interrupted the installation. Follow the wizard’s message, fix the issue on your machine, and ask Claude Code to retry. Do not edit project files to force the boot; the wizard is designed to handle this.
Data from a previous project appears, or a name or volume collision is reported. Another project on your machine may already use the same name. Choose a different project name, or remove the previous project’s leftover Docker volumes using the safe options provided by the wizard.
The storefront does not open in the browser, although the checks passed. The /etc/hosts entry is probably missing. Add the exact entry provided by the wizard, or accept the browser-check limitation. The setup itself has still completed.
I selected the wrong stores or demo-data strategy. Before the boot starts, tell Claude Code what to change. On a fresh clone, the wizard can undo and rerun the configuration from the appropriate point. After the boot, changing stores or the catalog requires the data to be wiped and reloaded; the wizard explains what will be removed before asking for approval.
The session closed, or I interrupted the run. Reopen Claude Code in the same project directory and say “Continue the project setup.” The wizard reads the completed work and resumes from where it stopped; it does not start over.
The setup is slow or uses many tokens. This is expected in generate mode or with real translation enabled. If you do not need these options, adapt or clean is considerably lighter.
The wizard will not start: “not a fresh clone” or “wrong shop”. It runs only on an untouched, un-booted B2B Marketplace demoshop. Start with a clean clone, or ask Claude Code to guide you through restoring the project to a fresh state.
A step has failed. The wizard stops at the failed step and records what happened; it never continues past a failure. Share the exact message with Claude Code so it can check the known issues before attempting a fix.

Requirements

A fresh, un-booted clone of the Spryker B2B Marketplace demoshop
An AI tool with the SDK’s skills loaded — see Before you start

project-starter-wizard README — the skill’s own reference in the plugin repository
Workflows, Skills, and Agents — the full reference of every skill and agent this wizard composes
Customization Workflow — build features on the project once it runs
Installation — install the SDK and generate your project’s rules, context file, and skills

Profiler Workflow

Mon, 24 Aug 2026 13:00:28 +0000

Availability

The spryker-profiler skill is available from spryker-sdk/ai-dev version 0.6.4, which ships version 0.4.0 of the spryker-ai-dev-sdk Claude Code plugin.

What the skill does

spryker-profiler turns the Spryker and Symfony WebProfiler into performance numbers you can act on, and explains how to switch profiling on when there is nothing to read.

Spryker records every web request automatically. That history is the cheapest source of truth for performance work: instead of guessing which code is slow, the skill reads what actually ran. It reduces a stored profile to the metrics that matter and prints JSON, so nobody has to scrape the profiler’s HTML or open a browser.

Invoke it when you ask why a page, endpoint, or Back Office screen is slow, want the heaviest request, suspect an N+1 query, need before-and-after evidence that a performance fix worked, or want to know what a request logged, threw, or which controller handled it. It also covers profiler setup — a missing toolbar, a collector showing no data, or enabling profiling for a specific application.

What it can tell you

The I/O counters say how much work a request did:

Metric	Answers
`queries` / `unique` / `duplicates`	How many SQL statements a request ran, and how many were repeats
`redis`	Key-value operations per request
`elasticsearch`	Search calls per request
`zed_requests`	Yves-to-Zed calls — the architecture boundary check
`external_http`	Third-party calls blocking the response
`duration_ms` / `memory_mb`	Wall time and peak memory
`segments`	Queries attributed to a named code path you wrapped

These say why, and whether the numbers are comparable between runs:

Metric	Answers
`logs`	Errors, warnings, and deprecations logged during the request
`audit_log`	Security and compliance events by channel — a separate stream from `logs`
`exception`	What was thrown, with message and status code
`twig`	Template count and render time
`events`	Listeners called synchronously, plus Spryker application events
`http`	Which controller and route handled the request, and where a 3xx redirected to
`session`	Session payload size
`runtime`	Debug mode and Xdebug flags — check these before comparing any timing

A Spryker request records 20 collectors. The skill reads every one that carries request data and maps it onto the fields above. The three it does not read hold no per-request measurements — they are toolbar plumbing and a dump of resolved configuration.

One user action is many profiles

The mistake that most often produces a wrong answer is treating a profile as a user action. A profile is one HTTP request. Clicking Login on the storefront creates six profiles across two applications and two storage directories — and the storefront profile itself reports zero queries, because Yves has no SQL collector by design.

The skill reconstructs the full tree instead. Yves-to-Zed links are exact, because the callee returns its own debug token, which the caller stores. Browser-issued AJAX and ESI sub-requests carry no such link, so those are grouped by time window and flagged as the heuristic they are.

The workflow

If you do not know which page is slow, rank the recorded profiles by a metric to find the outlier.
Reproduce the request, then read the profile and check that its age is seconds — profiles accumulate for days, and without checking you may analyze last week’s request.
If a collector is absent or there are no profiles at all, the skill walks the setup layers that must be enabled.
For a page or user action, read the full trace rather than the entry request alone.
Read the counts, not the milliseconds. Local wall time swings widely for identical work, while I/O counts are stable and are what scales badly in production.
If the counts are high, profile a small and a large entity to see whether the count scales with the data.

An absent collector is not zero

collector: "absent" means the metric was never measured for that application — Yves has no SQL collector, and the Back Office has no Redis collector. Reporting zero queries from an absent collector is a false conclusion. collector: "incompatible" means the collector is recording but an upgrade renamed part of its API, so the data is still available in the browser panel.

Going deeper than counts

Segmented SQL attributes queries to a named code path, turning “this page runs 261 queries” into “the calculator stack runs 180 of them”. Wrap the suspect code and the reader reports it under database.segments:

use Spryker\Shared\Propel\Logger\PropelInMemoryLogger;

PropelInMemoryLogger::startSegment('order-validation');
try {
    $this->validateOrder($orderTransfer);
} finally {
    PropelInMemoryLogger::endSegment();
}

Always use try/finally. The logger is static, so an unclosed segment swallows every later query in the request. Remove segments once you have the answer — they are debugging scaffolding.

A stored profile holds far more than the reader prints, including full SQL text, headers, routing, events, and logger entries. When a question needs something the reader does not expose, the skill extends the script rather than stopping at the available options.

Things that will confuse you

Timings are only comparable at equal runtime. Xdebug inflates wall time several-fold and debug mode disables caches, so a “regression” can be nothing more than a differently configured container.
Each application writes to its own directory. Yves and Glue write to one directory; Zed, the Back Office, the Backend Gateway, and the Merchant Portal write to another. The reader picks the most recently written one, which is often not the one you want.
The index outlives the data. Stored profiles are deleted after two days, but the index is never trimmed, so it can list thousands of requests when only a few dozen files survive. The skill reports how many profiles a ranking actually covered.
external_http: 0 may mean “not instrumented”. External calls appear only if the calling code uses the external HTTP logger trait, so a zero is never proof that a request makes no outbound calls.
Login walls profile the redirect. An unauthenticated request to the Back Office or Merchant Portal records the redirect to the login form, which says nothing about the page you wanted. Reproduce with an authenticated session.
Back Office tables are two requests. The page renders an empty grid and loads its rows through a separate table route, which is usually where the real cost sits. Profile both.
Console commands, queue workers, and cron jobs are never profiled. The WebProfiler is request-scoped. Use Xdebug profiling or explicit timing for those.

When there is no data

Three independent layers must all be in place, and the skill checks each one:

The web profiler is enabled in the project configuration.
The web profiler application plugin is registered for the application you are profiling. Zed alone has four separate stacks — Zed, Back Office, Backend Gateway, and Backend API.
A collector plugin for the metric you want is registered in that application’s WebProfilerDependencyProvider.

After changing any of these, empty the cache and reproduce the request.

Requirements

A running Spryker project (Docker SDK up) with the web profiler enabled
An AI tool with the SDK’s skills loaded — either through the Claude Code plugin or via ai-dev:setup for another supported tool

WebProfiler — why the profiler matters and how to integrate it per application
spryker-profiler README — the skill’s own reference in the plugin repository
Workflows, Skills, and Agents — the full reference of every skill and agent
Installation — install the SDK and generate your project’s rules, context file, and skills

AI Dev MCP Server

Mon, 24 Aug 2026 13:00:28 +0000

The AiDev module ships an MCP server that gives AI assistants live access to your running Spryker application: transfer objects, module interfaces, order management system (OMS) state machines, CSV data, and read-only database queries. This page describes what the server exposes, how to extend it, and how to debug it.

Install first

The ai-dev:mcp-server command exists only after the spryker-sdk/ai-dev module is installed in your project and its console commands are registered. To install the module and register the server in your assistant, see Installation.

About Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems. For Spryker developers, MCP allows AI assistants like Claude or Copilot to understand your project, improving the quality of AI-generated code and recommendations.

Learn more about MCP at modelcontextprotocol.io.

How the server runs

The module provides the server through the ai-dev:mcp-server console command, which runs inside your project’s Docker container over the MCP stdio transport:

docker/sdk console ai-dev:mcp-server -q

The command starts the server, registers all configured MCP tool plugins, and listens for requests from AI assistants. You do not usually run it by hand — your assistant starts it. For the registration steps per assistant, see Register the MCP server.

Available MCP tools

The AiDev module provides the following built-in tools that AI assistants can use:

Tool name	Description
`getTransferStructureByName`	Retrieves the structure of a Spryker transfer object by its name. Returns all properties with their types and metadata.
`getTransferStructureByNamespace`	Retrieves the structure of a Spryker transfer object by its fully qualified namespace.
`getInterfaceMethodsByNamespace`	Retrieves all method signatures, parameters, return types, and PHPDoc for a given interface FQN (Fully Qualified Name).
`getOmsTransitionsByState`	Retrieves OMS state machine transitions for a specific state. Returns all transitions that start from the given state, optionally filtered by process name.
`getOrderOmsTransitions`	Retrieves OMS state machine transitions for a specified order from the order’s current state. Helps identify the current state and possible transitions.
`executeQuery`	Executes read-only database queries (SELECT, SHOW, DESCRIBE, EXPLAIN) for accessing project data without modification capabilities.
`getSprykerModules`	Lists all available Spryker modules from project and vendor directories.
`getSprykerModuleMap`	Retrieves detailed module metadata including class paths, method signatures, and extension points.
`searchAlgoliaDocumentation`	Enables keyword-based Spryker documentation search through Algolia integration.
`analyzeCsvFile`	Analyzes CSV file structure without loading full content. Returns headers, row count, and sample rows. Supports optional column analysis with unique values and null counts.
`transformCsv`	Transforms and modifies CSV files with three operation modes: APPEND (add new rows), REPLACE (overwrite target), and UPDATE (modify existing rows in-place). Supports column mappings, row filters, value transformations, default values, and automatic backup creation.
`deleteCsvRows`	Deletes rows from CSV files based on filter criteria with multiple operators (equals, not_equals, in, not_in, contains, not_contains, starts_with, ends_with, empty, not_empty). Includes safety checks and automatic backup creation.
`splitOdsToCsv`	Splits ODS (OpenDocument Spreadsheet) files into separate CSV files per sheet. Skips empty sheets and returns details about created files. Useful for converting Google Sheets exports to Spryker-compatible CSVs.

AI assistants can automatically discover and use these tools when connected to the MCP server.

Extension points

The AiDev module provides plugin interfaces for extending the MCP server with custom functionality.

AiDevMcpToolPluginInterface

Implement this interface to add custom MCP tools that AI assistants can use to query or interact with your application.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface

Integration: Register your tool plugins in AiDevDependencyProvider::getMcpToolPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpToolPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface>
     */
    protected function getMcpToolPlugins(): array
    {
        return array_merge(parent::getMcpToolPlugins(), [
            new CustomAiDevMcpToolPlugin(),
        ]);
    }
}

Configuration

You can configure the AiDev module through the AiDevConfig class. Refer to the module’s configuration class for the available options and their default values.

Debug the MCP server

Before you connect the MCP server to an AI assistant, you can test and debug it with the MCP Inspector. The inspector provides a web interface to interact with your MCP server, test tools, and verify that everything works correctly.

Go to your Spryker project directory and run:

npx @modelcontextprotocol/inspector docker/sdk console ai-dev:mcp-server -q

This command:

Starts the MCP Inspector in your browser
Connects to your local MCP server
Displays all available tools
Lets you test tool calls interactively

To run the inspector with Xdebug:

npx @modelcontextprotocol/inspector docker/sdk cli -x console ai-dev:mcp-server

Node.js required

The MCP Inspector requires Node.js on your system. The npx command automatically downloads and runs the inspector without a global installation.

Installation — install the module and register the server in your assistant
AI Dev SDK — what the SDK is and what it ships
Workflows, Skills, and Agents — the workflows that consume these tools