> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-workflow/19.latest/upgrading/version-specific.md).

# Version Specific Upgrade Notes

Version specific documentation for upgrading to new major versions of Umbraco Workflow.

This page covers specific upgrade documentation for when migrating to Umbraco Workflow version 18.

{% hint style="info" %}
If you are upgrading to a new minor or patch version, you can find information about the breaking changes in the [Release Notes](https://docs.umbraco.com/umbraco-workflow/19.latest/release-notes.md) article.
{% endhint %}

## Version Specific Upgrade Notes History

Version 18 of Umbraco Workflow has a minimum dependency on Umbraco CMS core of `18.0.0`. It runs on .NET 10.

## Breaking changes

Version 18 contains a number of breaking changes. The details are listed here.

### Dependencies

* Umbraco CMS dependency was updated to `18.0.0`
* SwaggerGen/Swashbuckle dependency was removed in favor of the built-in `Microsoft.AspNetCore.OpenApi` package

### Database

The `WorkflowUserGroupPermissions` table has been updated: the `NodeId` and `ContentTypeId` columns are consolidated into a single `EntityId` column paired with the existing `EntityType` discriminator.

A new `WorkflowActionConfig` table is added for storing workflow action configurations.

All legacy migrations (pre-v17) have been removed. Sites upgrading from versions earlier than v17 must first upgrade to v17 before upgrading to v18.

### Namespace reorganization

The flat `Umbraco.Workflow.Core.Models` and `Umbraco.Workflow.Core.ViewModels` namespaces have been dissolved into feature-slice namespaces. If you reference any Workflow types directly, update your `using` statements:

The feature-slice namespaces include `Actions`, `ApprovalGroups`, `ContentApprovals`, `ContentReviews`, `Settings`, `Common`, `Email`, `Document`, `Element`, `AlternateVersions`, `Charts`, `HistoryCleanup`, `ReleaseSets`, and `SignalR`.

DTOs were also renamed from `Poco` to `Dto` suffix to remove the implied coupling to NPoco.

### Email templates

The email template models were renamed as part of the namespace reorganization. A template customized for Workflow 17 does not compile in Workflow 18 until its `@model` is updated:

| Workflow 17                                                 | Workflow 18                                                                      |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `Umbraco.Workflow.Core.Email.Models.HtmlEmailModel`         | `Umbraco.Workflow.Core.ContentApprovals.Email.ContentApprovalEmailModel`         |
| `Umbraco.Workflow.Core.Email.Models.HtmlReminderEmailModel` | `Umbraco.Workflow.Core.ContentApprovals.Email.ContentApprovalReminderEmailModel` |
| `Umbraco.Workflow.Core.Email.Models.HtmlReviewEmailModel`   | `Umbraco.Workflow.Core.ContentReviews.Email.ContentReviewEmailModel`             |

When templates are not compiled with the site, which is the default for `BackofficeDevelopment` mode, the build does not catch this. From Workflow 18.2.1, a template on disk that does not compile falls back to the version Workflow ships. The **Email Templates** health check lists it. For more information, see the [Email Templates](https://docs.umbraco.com/umbraco-workflow/19.latest/getting-started/content-approval-settings.md#email-templates) article.

### Code

The list below includes changes raising validation errors `CP0001`, `CP0002` and `CP0006` between versions 17.3.2 and 18.0.0-rc1.

Notable changes include:

* Removal of split config models in favor of unified `ConfigUpdateRequestModel`
* Consolidation of `NodeId`/`ContentTypeId` into `EntityId` on permission models
* Removal of previously obsoleted members on `IWorkflowInstanceResolver`, `IEmailTemplateLocator`, and `IPropertyValueTransformer`.

#### Removed Types

* `Umbraco.Workflow.Core.ContentApprovals.ViewModels.DocumentConfigResponseModel`
* `Umbraco.Workflow.Core.ContentApprovals.ViewModels.DocumentConfigUpdateRequestModel`
* `Umbraco.Workflow.Core.ContentApprovals.ViewModels.DocumentTypeConfigUpdateRequestModel`
* `Umbraco.Workflow.Core.ContentReviews.Models.ContentReviewsNodeQueryResponseModel`
* `Umbraco.Workflow.Core.Models.Enums.IPermissionsModel`
* `Umbraco.Workflow.Web.Api.Configuration.BackOfficeSecurityRequirementsOperationFilter`
* `Umbraco.Workflow.Web.Api.Configuration.GenerateWorkflowSchemaDocumentFilter`
* `Umbraco.Workflow.Web.Api.Configuration.SwaggerParameterAttribute`
* `Umbraco.Workflow.Web.Api.Configuration.SwaggerParameterAttributeFilter`
* `Umbraco.Workflow.Web.Api.Configuration.WorkflowOperationIdHandler`
* `Umbraco.Workflow.Web.Api.Configuration.WorkflowSchemaIdHandler`

#### Removed Members

* `Umbraco.Workflow.Core.ApprovalGroups.Models.ApprovalGroupPermissionsDto.get_NodeId`
* `Umbraco.Workflow.Core.ApprovalGroups.Models.ApprovalGroupPermissionsDto.get_ContentTypeId`
* `Umbraco.Workflow.Core.ContentApprovals.Models.PermissionRequestModel.get_NodeId`
* `Umbraco.Workflow.Core.ContentApprovals.Models.WorkflowSearchFilterModel.get_NodeId`
* `Umbraco.Workflow.Core.ContentApprovals.Processes.IWorkflowInstanceResolver.CompleteForScheduler`
* `Umbraco.Workflow.Core.ContentApprovals.Processes.IWorkflowInstanceResolver.CompleteNow`
* `Umbraco.Workflow.Core.ContentReviews.Models.ContentReviewsScaffoldModel.get_Culture`
* `Umbraco.Workflow.Core.ContentReviews.Models.ContentReviewConfigPoco.SplitPath`
* `Umbraco.Workflow.Core.Email.Interfaces.IEmailTemplateLocator.GetEmailTemplateInfo`
* `Umbraco.Workflow.Core.Email.Interfaces.IEmailTemplateLocator.GetEmailTemplateVirtualPath`
* `Umbraco.Workflow.Core.Email.Interfaces.IEmailTemplateLocator.InstallTemplates`
* `Umbraco.Workflow.Core.Email.Interfaces.IEmailTemplateLocator.GetViewEngineResult`
* `Umbraco.Workflow.Core.AlternateVersions.Services.IPropertyValueTransformer.ForDisplay(IEnumerable<PropertyDataDto>, Guid, Guid)`
* `Umbraco.Workflow.Core.AlternateVersions.Services.IPropertyValueTransformer.ForPersistence(IEnumerable<PropertyDataDto>, Guid, Guid)`
* `Umbraco.Workflow.Core.Settings.ViewModels.WorkflowSettingsPropertiesViewModel.GeneralSettingsViewModel.get_DocumentTypeApprovalFlows`
* `Umbraco.Workflow.Web.Api.Controllers.Email.InstallEmailTemplateController` (removed `install-sync` endpoint)
* `Umbraco.Workflow.Web.Api.Controllers.Information.GetInformationController` (removed obsolete constructor overload)

#### Added Interface Members (Breaking)

* `Umbraco.Workflow.Core.ContentApprovals.Processes.IWorkflowInstanceResolver.CompleteForSchedulerAsync` (default implementation removed, now required)
* `Umbraco.Workflow.Core.ContentApprovals.Processes.IWorkflowInstanceResolver.CompleteNowAsync` (default implementation removed, now required)
* `Umbraco.Workflow.Core.Email.Interfaces.IEmailTemplateLocator.InstallTemplatesAsync` (default implementation removed, now required)
* `Umbraco.Workflow.Core.Email.Interfaces.IEmailTemplateLocator.GetViewPath` (default implementation removed, now required)
* `Umbraco.Workflow.Core.AlternateVersions.Services.IPropertyValueTransformer.ForDisplay(AlternateVersionDto)` (default implementation removed, now required)
* `Umbraco.Workflow.Core.AlternateVersions.Services.IPropertyValueTransformer.ForPersistenceAsync` (default implementation removed, now required)

### Localization

Status localization keys in the `workflow` section have changed from integer-based to camelCase:

| Old Key    | New Key                 |
| ---------- | ----------------------- |
| `status1`  | `approved`              |
| `status2`  | `rejected`              |
| `status3`  | `pendingApproval`       |
| `status4`  | `notRequired`           |
| `status5`  | `cancelled`             |
| `status6`  | `errored`               |
| `status7`  | `resubmitted`           |
| `status8`  | `cancelledByThirdParty` |
| `status9`  | `excluded`              |
| `status10` | `awaitingResubmission`  |

This applies to both the XML language files (server-side) and TypeScript language dictionaries (client-side). Custom email templates or integrations referencing the old `statusN` keys must be updated.

### OpenAPI

SwaggerGen/Swashbuckle has been replaced with `Microsoft.AspNetCore.OpenApi`. The changes in Workflow follow those introduced in the CMS.

### Frontend

* TypeScript enums have been replaced with string-union types. If you reference Workflow enums in custom extensions, update to use the string values directly.
* The `@umbraco-workflow/backoffice` NPM package has been restructured with static imports, reducing chunk count and overall bundle size. Custom extensions importing from the package should verify their import paths are still valid.

### Legacy version specific upgrade notes

You can find the version specific upgrade notes for versions out of support in the [Legacy documentation on GitHub](https://github.com/umbraco/UmbracoDocs/tree/umbraco-eol-versions).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-workflow/19.latest/upgrading/version-specific.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
