Skip to content

Complete the 4.0 removals list and document the Chat UI conversion #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stu-greenshoots merged 1 commit into from
Sep 3, 2026
Merged

Complete the 4.0 removals list and document the Chat UI conversion #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions MIGRATION-NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2228,3 +2228,63 @@ CI's silently prunes optional cross-platform entries. The durable fix is still w
2026-07-29 entry asked for and never got — pin the local toolchain to `.node-version` so both
sides run npm 11.16.0. Until then, after any `npm install`, check that
`node_modules/@emnapi/core` is still in the lock before committing.

---

## 2026-09-03 — 4.0 deprecation list corrected against the product registry

The August 2026 "Deprecations and removals" block, as first published in PR #20, did not match
`config/opendialog/deprecations.php` on `origin/4.x` — the registry the platform actually reads
to render the deprecation warning on a scenario card. That warning links straight at
`https://docs.opendialog.ai/release-notes/release-notes` (hardcoded in
`resources/opendialog-design-system/components/Scenarios/Scenario.vue`), so **every component id
in that registry has to be explained on this page** or a customer follows the warning to a page
that does not mention what they were warned about.

Three divergences, all verified against the code rather than the ticket prose:

| | published | registry / code |
|---|---|---|
| Azure Custom QA (`interpreter.core.qa`) | deprecated, removed next major | **removed in 4.0** — `AzureCustomQAInterpreter.php` is absent from `origin/4.x` |
| Conversation Analysis (`interpreter.core.conversation_analysis`) | absent | **removed in 4.0** — `ConversationAnalysisInterpreter.php` is absent from `origin/4.x` |
| OpenAI Language Processor (`language_processor.core.open_ai`) | absent | deprecated, `removed_in` 5.0, `frozen` |

Verified by diffing `packages/core/src/InterpreterEngine/Interpreters/` between `origin/3.x` and
`origin/4.x`: seven interpreters are gone (Luis, QnA, Rasa, Lex, Dialogflow, AzureCustomQA,
ConversationAnalysis), and `LanguageModelEngine/Component/PaLMLanguageModel.php` with them.

One registry entry is deliberately **not** on the page: a single-customer action renamed to
`action.core.question_count` and frozen. Its component id embeds the customer's name, and this
repo and the rendered page are both public, so it is not named here either. The id is not
customer-visible — the deprecation warning renders the registry `label`, which is generic — so
the omission costs that customer nothing. Any future entry whose id embeds a customer name
needs the same treatment, or a relabelled id.

`frozen` was not a concept on the page at all. It is load-bearing and customer-visible: a frozen
component keeps working and stays editable, but refuses *new* configurations — which includes
importing or duplicating a scenario that carries one. That behaviour change is deliberate
(ODP-3364 C3) and worth stating rather than letting people discover it via a failed import.

### The delivery acknowledgement endpoint

`POST /acknowledge` (old webchat `AsyncController@acknowledge`) dies with the legacy webchat.
The Chat UI has no equivalent. The one `/acknowledge/chatApi` reference in the shipped Chat UI
bundle has never routed and already 404s in production, so nothing regresses — but the endpoint
was public surface, so its removal is stated.

### Chat UI conversion how-to

Sourced from the implementation, not from the plan docs, because the plan's earlier revisions
describe a copy-based conversion that was later reversed to in-place:

- `ConvertWebchatScenarioService` (`packages/webchat-package/src/Services/`) rewrites the
scenario's platform configuration rows in place — uid, app key, aliases and publish state all
survive. Only the embed script src changes.
- The `comments` section is dropped unconditionally; unrecognised keys are retained but inert;
the report returns the original payload.
- `ConvertWebchat.vue` sends the customer to the scenario's Interface settings page for the new
snippet, so the page links there.

The screenshot at `~/assets/convert-to-chat-ui.png` is the scenario card with its dot menu
open. It deliberately shows both affordances at once: the "Convert to Chat UI" item, and the
deprecation warning icon on the card footer that the surrounding prose describes.
Binary file added src/assets/convert-to-chat-ui.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 30 additions & 8 deletions src/content/docs/release-notes/release-notes/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,39 @@ OpenDialog 4.0 is here! This is our first release under a new, regular major-ver

#### <mark style={{ color: 'purple' }}>Deprecations and removals</mark>

As part of 4.0 we are clearing out long-deprecated components. The following components are being removed in 4.0:
As part of 4.0 we are clearing out long-deprecated components. The following are removed in 4.0:

* The legacy webchat — new scenarios have used the new webchat for some time, and we will be in touch with owners of remaining legacy-webchat scenarios about migration
* The Voice/Alexa module, including the Alexa platform, the Alexa interpreter and skill synchronisation
* The legacy NLU interpreters: Microsoft LUIS, Microsoft QnA Maker, Rasa, Amazon Lex and Google Dialogflow
* The Google PaLM language model, which has been discontinued by Google
* **The legacy webchat.** New scenarios have used the new webchat for some time. If you still have a scenario on the legacy webchat you can move it yourself — see [Converting a scenario to the Chat UI](#converting-a-scenario-to-the-chat-ui) below. The legacy message delivery acknowledgement endpoint (`POST /acknowledge`) goes with it; the Chat UI has no equivalent and does not need one.
* **The Voice/Alexa module**, including the Alexa platform, the Alexa interpreter and skill synchronisation.
* **The legacy NLU interpreters**: Microsoft LUIS, Microsoft QnA Maker, Rasa, Amazon Lex and Google Dialogflow.
* **The Azure Custom QA interpreter.**
* **The Conversation Analysis interpreter.**
* **The Google PaLM language model**, which has been discontinued by Google.

In addition, the following components are deprecated in 4.0 and will be removed in the next major release:
The following are deprecated in 4.0 and will be removed in 5.0:

* The legacy direct OpenAI client interpreter — replaced by [Language Services](/opendialog-platform/interpreters-and-natural-language-understanding/language-services) backed by language model configurations
* The Azure Custom QA interpreter
* **The OpenAI interpreter** — replaced by [Language Services](/opendialog-platform/interpreters-and-natural-language-understanding/language-services) backed by language model configurations.
* **The OpenAI language processor** — likewise replaced by Language Services.

Deprecated components are *frozen*: existing configurations keep working and stay editable, but you can no longer create new ones. This includes importing or duplicating a scenario that carries one, which will now fail.

Any scenario using a component on either list shows a warning icon on its card in the scenario list. Hover the icon to see which components are affected and which release removes them.

#### <mark style={{ color: 'purple' }}>Converting a scenario to the Chat UI</mark>

Scenarios still on the legacy webchat can be moved to the Chat UI from the scenario list. Open the scenario's **⋮** menu and choose **Convert to Chat UI** — the option only appears on scenarios that are still using the legacy webchat.

![](~/assets/convert-to-chat-ui.png)

The scenario is converted in place. It keeps its ID, app key, aliases and publish state, and your existing settings are carried over wherever the Chat UI supports them. There is no need to recreate the scenario or re-point anything that refers to it by ID.

When the conversion finishes you are shown a short report covering:

* Any settings sections that were removed because the Chat UI does not support them. The **Comments** section is removed for every conversion.
* Any settings the Chat UI does not recognise. These are kept but no longer have any effect.
* Your original settings, which you can expand and copy for your records.

**One step is left to do yourself:** update the embed code on your site so it loads the Chat UI script. Your scenario ID and app key have not changed, so only the script source needs to change. You can copy the new snippet from the scenario's [Interface settings](/opendialog-platform/conversation-designer/webchat-interface-design/webchat-interface-settings) page.

If you have any questions about migrating away from a deprecated component, you can get help via our support form - [https://opendialog.ai/support](https://opendialog.ai/support/).

Expand Down
Loading