Upgrade guide: 1.3.x → 1.4.0

Plan §20 item 18, §26. Only the upgrade from an installed 1.3.5 on Magento 2.4.7-p4 has been measured (module-verify.sh, local stack); upgrades from earlier 1.3.x releases and on other Magento versions have not.

Before you upgrade

• Conviro's backend must already support 1.4.0. A backend that predates it rejects the new registration (oauth field). Conviro releases the backend first; the in-admin "update available" notice appears only after 1.4.0 is published. If you upgrade by hand before that notice, check with Conviro.
• Security minimum is 1.3.5. Every release before 1.3.5 rendered the logged-in shopper's name, e-mail and order history into full-page-cached HTML, where the next shopper in the same customer group could be served it. Stores below 1.3.5 see SECURITY UPDATE REQUIRED; upgrade straight to 1.4.0.
• Magento cron must run: 1.4.0 delivers everything through it.
• Take your usual backup; the upgrade adds tables and config rows (below).

Commands

From the Magento root, as the owner of the Magento files, never root (e.g. sudo -u www-data -s first), production mode shown:

bin/magento maintenance:enable
composer require 'conviro/module-aichat:^1.4'
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f en_US <your store locales, e.g. tr_TR>
bin/magento cache:flush
bin/magento maintenance:disable

• Maintenance mode from the first step to the last: between Composer replacing the code and the compile and static deploy finishing, the store would serve errors. If a step fails the store stays in maintenance until you finish the remaining steps.
• A plain setup:upgrade here — not --keep-generated, which would run the new data patches against the old compiled code (it belongs to the release-directory method only). The generated code and static files it clears are rebuilt by the next two steps while the store is in maintenance.
• setup:di:compile and the static deploy are required in production mode: 1.4 changed class constructors, and a store that skips the compile fails with "class does not exist" errors until it runs. Name every store-view locale and en_US.
• Developer mode: composer, setup:upgrade and cache:flush are enough; default mode also needs the static deploy.

Each step, the release-directory method and rollback: Installation › Upgrading. Your API key, settings and the Magento integration are kept.

What changes on upgrade

Schema and data

setup:upgrade (declarative schema, replacing the old InstallSchema):

• adds conviro_event_outbox, conviro_sync_job, conviro_inbound_event;
• adds the columns direction and hits to the existing conviro_webhook_log (the table keeps its 1.3.5 columns unchanged);
• runs data patches, once each: HoldCartEventsUntilConfirmed, ScheduleOauthMigration and RefreshIntegrationAccess (below) and RequireSignedWebhooks (Require Signed Webhooks = Yes). None calls Conviro.
• adds the ACL resources Conviro_AiChat::api_* (the Conviro read API) and the REST routes /V1/conviro/....

Held cart and payment events

If Abandoned Cart Recovery or Payment Failure Assistance was switched on in 1.3.x (at any scope), nothing is sent after the upgrade until you confirm it — with the link in the admin message (a page that confirms only the ticked features and starts no sync, 1.4.1), in the setup wizard (step 5) or with Confirm cart / payment data sharing = Yes. In 1.3.x these switches never actually sent data (read at default scope only; the payment hook was not called by the default checkout), so confirming starts something new. From 1.4.1 on, an admin system message on every admin page says what is held and links to the wizard step until you decide. Details: Cart recovery and payment assist.

Automatic OAuth migration

A store upgraded with an API key already saved is moved from the legacy bearer token to Magento OAuth 1.0a by itself: the patch marks it pending, and the cron job conviro_connection_maintenance runs the same registration as Save Config within minutes — the least-privilege integration is repaired and its OAuth credentials sent to Conviro. It never runs during setup:upgrade or in a storefront request. Retries back off (1 min, 5 min, 15 min, 1 h, then every 6 h) on network errors, 5xx and anything that is not an answer of the Conviro API itself — including a challenge page of the network protection in front of it; only a 401/403 from the Conviro API stops it (you need to act), and so does a 409 store_disconnected (the store was disconnected — it reconnects only through the wizard's Reconnect). 1.4.0 also stopped on a challenge page and gave up after 7 days; 1.4.1 keeps retrying, and its upgrade resumes a migration that 1.4.0 stopped for such a reason (data patch ResumeOauthMigration). Clicking Save Config yourself does the same at once. Follow it in the setup wizard and on the Integration Health Authentication row. If OAuth is refused (typically HTTPS terminated by a proxy), the store stays on the bearer token and the row tells you what to fix. Measured on the local stack (setup-wizard.sh).

The upgrade also re-registers every store that has an API key once, even one already on OAuth 1.0a (data patch RefreshIntegrationAccess, same cron job and backoff): the "Conviro AI Chat" integration moves to the least-privilege Conviro read API (Permissions). Until Conviro confirms it reads through the new routes, the integration keeps the Magento resources it had, so nothing stops working in between; the Authentication row shows a Warning while they are still held. Requires the backend to be deployed first (release order).

Store-wide bearer mode: switch it back off yourself. 1.3.x turned on Stores › Configuration › Services › OAuth › Consumer Settings › Allow OAuth Access Tokens to be used as standalone Bearer tokens on every Save Config, which lets the access token of every integration on the store work without an OAuth signature. 1.4.0 never writes this setting, so the upgrade leaves it as 1.3.x left it (measured on 2.4.9: still Yes after the upgrade). Conviro does not need it: once the Authentication row shows OAuth 1.0a, set it to No, unless another integration of yours authenticates with a bearer token. The Integration Health card shows a Store-wide bearer tokens warning while it is on, with a Turn off store-wide bearer tokens button that does exactly that after a confirmation (Integration Health); the module never switches it off on its own.

Custom admin roles

1.4.0 adds the admin resource Conviro_AiChat::setup ("Conviro Setup (connect, key, AI actions, sync)"), a child of Conviro_AiChat::config. It guards Stores › Settings › Conviro Setup and every wizard action, and — new against 1.3.x, where Conviro_AiChat::config was enough — pasting the API key, the AI capability switches (order actions among them), Require Signed Webhooks, the cart / payment data-sharing confirmations and the health card's Retry failed / Re-sync / Import / Repair buttons (Permissions). A role with only Conviro AI Chat now sees those settings read-only. Administrators with All resources have it. For custom roles: open System › Permissions › User Roles › (role) › Role Resources, confirm Conviro Setup Wizard is ticked for the roles that should connect / disconnect the store (or unticked for those that should not), and save the role. Roles saved before the upgrade have no rule of their own for the new resource; how Magento resolves that for your roles was not measured on the test stack, so check and save them explicitly.

Settings that moved to default scope

The API key, Require Signed Webhooks, tenant and chatbot ids and the whole AI Capabilities group are now shown and read at default scope only. Values you saved per website or store view in 1.3.x stay in the database and are ignored (Configuration reference). Sync toggles are now really read per website (1.3.x read them at default scope).

Behaviour changes to expect

• Events are queued locally and delivered by cron every minute instead of being posted during the request — storefront, checkout and admin saves no longer wait on Conviro.
• order.placed is sent when the order is created (quote submission), not from the checkout success page.
• Disabled products are sent (as disabled) and removed from the assistant's knowledge at once.
• Save Config no longer regenerates the integration's access token — and it now really re-registers the store with Conviro (in 1.3.x the observer listened to an event Magento never dispatches, so a save sent nothing).
• order.placed no longer carries the billing name and phone, the line items or the customer id; the widget receives the logged-in customer's id as id.
• Disconnect takes the chat widget and lead form off the storefront unless you tick Keep the chat widget on my storefront.
• conviro_webhook_log rows older than 30 days and finished sync jobs older than 90 days are purged daily.
• Deleting a customer sends customer.deleted (when customer data is shared) and drops their undelivered events.
• The Integration Health card replaces the old connection and delivery cards.
• In Conviro: every AI action is off until enabled; flows using the Magento cancel / RMA / quote nodes stop writing until the matching action is switched on (AI action policy).

After upgrading

1. Open Stores › Settings › Conviro Setup and walk through the wizard: it resumes where your store stands. At minimum check step 4 (store views — all are selected by default) and step 5 (data sync; run the initial sync if you want your catalog, stock and order history in Conviro now).
2. On the Integration Health card: every row Pass or an understood Warning; Authentication shows OAuth 1.0a.
3. Require Signed Webhooks is Yes after the upgrade (1.4.0 always signs; the upgrade's data patch RequireSignedWebhooks turned a saved No into Yes, and the automatic re-registration tells Conviro). Leave it on.
4. Decide on the cart / payment confirmation if the card shows the held row.
5. Store-wide bearer mode: switch it back to No unless another integration needs it (above) — the health card's Store-wide bearer tokens row has a button for it.
6. View the source of a storefront page: the widget is a <script type="application/json" id="conviro-widget-config"> block plus Conviro_AiChat/js/widget-loader.js. An inline script containing __conviroMagentoWidgetLoaded is 1.3.x's markup served from the full-page cache. On Magento 2.4.9 with the built-in file cache we measured one page cached by 1.3.5 that bin/magento cache:flush did not remove (2026-09-26, version matrix; not seen on 2.4.4-p13); rm -rf var/page_cache/* did. With Varnish, purge it.