Repository: umbraco/UmbracoDocs
Pull request #7006: Umbraco UI Builder release notes and details on entity identifier type converters
Author: login: acoumb
Labels: name: category/umbraco-ui-builder
Created: 2025-04-04T11:52:28Z | Merged: 2025-04-07T08:25:31Z

## Description

* Updated release notes for Umbraco UI Builder 13.2.3 and 15.1.2
* Details on `EntityIdentifierTypeConverters`

## Type of suggestion

* [ ] Typo/grammar fix
* [ ] Updated outdated content
* [x] New content
* [x] Updates related to a new version
* [ ] Other

## Product & version (if relevant)

Umbraco UI Builder 13.2.3 and 15.1.2

## Deadline (if relevant)

When possible.



Diff:
diff --git a/13/umbraco-ui-builder/SUMMARY.md b/13/umbraco-ui-builder/SUMMARY.md
index 3423f807237..6cda5d6211b 100644
--- a/13/umbraco-ui-builder/SUMMARY.md
+++ b/13/umbraco-ui-builder/SUMMARY.md
@@ -46,6 +46,7 @@
   * [Child Collection Groups](collections/child-collection-groups.md)
   * [Retrieve Child Collections](collections/retrieve-child-collections.md)
 * [Related Collections](collections/related-collections.md)
+* [Entity Identifier Converters](collections/entity-identifier-converters.md)
 
 ## Searching
 
diff --git a/13/umbraco-ui-builder/collections/entity-identifier-converters.md b/13/umbraco-ui-builder/collections/entity-identifier-converters.md
new file mode 100644
index 00000000000..a1cb38c5447
--- /dev/null
+++ b/13/umbraco-ui-builder/collections/entity-identifier-converters.md
@@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to reference an Umbraco object in your model and retrieve its `Integer` or `Guid` value, you must convert the `UDI` value.
+
+Use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter`. Add it as a `[TypeConverterAttribute]` to your model's foreign key property.
+
+An entity that references an Umbraco object would look like this:
+
+```csharp
+    [TableName(TableName)]
+    [PrimaryKey("Id")]
+    public class MemberReview
+    {
+        public const string TableName = "MemberReview";
+
+        [PrimaryKeyColumn]
+        public int Id { get; set; }
+
+        public string Title { get; set; }
+
+        public string Content { get; set; }
+
+        [TypeConverter(typeof(EntityIdentifierToIntTypeConverter))]
+        public int MemberId { get; set; }
+    }
+```
+
+You can also create a custom type converter. UI Builder will handle data persistence automatically.
diff --git a/13/umbraco-ui-builder/release-notes.md b/13/umbraco-ui-builder/release-notes.md
index 3cf738d41f2..b9601525c0b 100644
--- a/13/umbraco-ui-builder/release-notes.md
+++ b/13/umbraco-ui-builder/release-notes.md
@@ -18,6 +18,10 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 This section contains the release notes for Umbraco UI Builder 13 including all changes for this version.
 
+#### [**13.2.3**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.2.3) **(April 4th 2025)**
+
+* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144) and introduced new [Entity Identifier Converters](./collections/entity-identifier-converters.md).
+
 #### [**13.2.2**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.2.2) **(March 21st 2025)**
 
 * Fixed an issue for bulk actions that disabled the actions row on cancel [#130](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/130)
diff --git a/15/umbraco-ui-builder/SUMMARY.md b/15/umbraco-ui-builder/SUMMARY.md
index d7d8f48bef3..f52e3e3a763 100644
--- a/15/umbraco-ui-builder/SUMMARY.md
+++ b/15/umbraco-ui-builder/SUMMARY.md
@@ -43,6 +43,7 @@
   * [Child Collection Groups](collections/child-collection-groups.md)
   * [Retrieve Child Collections](collections/retrieve-child-collections.md)
 * [Related Collections](collections/related-collections.md)
+* [Entity Identifier Converters](collections/entity-identifier-converters.md)
 
 ## Searching
 
diff --git a/15/umbraco-ui-builder/collections/entity-identifier-converters.md b/15/umbraco-ui-builder/collections/entity-identifier-converters.md
new file mode 100644
index 00000000000..a1cb38c5447
--- /dev/null
+++ b/15/umbraco-ui-builder/collections/entity-identifier-converters.md
@@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to reference an Umbraco object in your model and retrieve its `Integer` or `Guid` value, you must convert the `UDI` value.
+
+Use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter`. Add it as a `[TypeConverterAttribute]` to your model's foreign key property.
+
+An entity that references an Umbraco object would look like this:
+
+```csharp
+    [TableName(TableName)]
+    [PrimaryKey("Id")]
+    public class MemberReview
+    {
+        public const string TableName = "MemberReview";
+
+        [PrimaryKeyColumn]
+        public int Id { get; set; }
+
+        public string Title { get; set; }
+
+        public string Content { get; set; }
+
+        [TypeConverter(typeof(EntityIdentifierToIntTypeConverter))]
+        public int MemberId { get; set; }
+    }
+```
+
+You can also create a custom type converter. UI Builder will handle data persistence automatically.
diff --git a/15/umbraco-ui-builder/release-notes.md b/15/umbraco-ui-builder/release-notes.md
index 5ecef9e54a7..dc416a01410 100644
--- a/15/umbraco-ui-builder/release-notes.md
+++ b/15/umbraco-ui-builder/release-notes.md
@@ -18,6 +18,15 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 Below are the release notes for Umbraco UI Builder 15, detailing all changes in this version.
 
+#### [**15.1.2**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F15.1.2) **(April 4th 2025)**
+
+* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144), [#136](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/136), and introduced new [Entity Identifier Converters](./collections/entity-identifier-converters.md).
+* Fixed `Create` action button [#137](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/137).
+* Added collection list view refresh feature following an entity action [#139](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/139).
+* Fixed collection visibility [#134](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/134).
+* Enabled rendering of sidebar properties.
+* Fixed an issue that prevented the creation of multiple sections.
+
 #### [**15.1.1**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F15.1.1) **(March 21st 2025)**
 
 * Extended `UdiConverter` with options to convert to `GUID` [#108](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/108)


Reviews:
user: login: eshanrnh
body: The PR looks great, @acoumb 🙌I've added a couple of suggestions to shorten long sentences (Vale errors) and apply some general style guide fixes.

Do you want me to incorporate these kinds of suggestions myself going forward, or will you take care of them?
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-07T07:34:56Z
user: login: eshanrnh
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-07T08:24:33Z
user: login: eshanrnh
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-07T08:25:22Z

Review comments:
diff_hunk: @@ -18,6 +18,15 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 Below are the release notes for Umbraco UI Builder 15, detailing all changes in this version.
 
+#### [**15.1.2**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F15.1.2) **(April 4th 2025)**
+
+* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144), [#136](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/136) and introduce new [Entity Identifier Converters](./collections/entity-identifier-converters.md) .
path: 15/umbraco-ui-builder/release-notes.md
user: login: eshanrnh
body: ```suggestion
* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144), [#136](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/136), and introduced new [Entity Identifier Converters](./collections/entity-identifier-converters.md).
```
created_at: 2025-04-07T07:22:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -18,6 +18,15 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 Below are the release notes for Umbraco UI Builder 15, detailing all changes in this version.
 
+#### [**15.1.2**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F15.1.2) **(April 4th 2025)**
+
+* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144), [#136](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/136) and introduce new [Entity Identifier Converters](./collections/entity-identifier-converters.md) .
+* Fixed `Create` action button [#137](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/137)
+* Add collection list view refresh feature following an entity action [#139](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/139)
+* Fixed collection visibility [#134](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/134)
+* Enable rendering of sidebar properties.
+* Fixed an issue that prevented the creation of multiple sections.
path: 15/umbraco-ui-builder/release-notes.md
user: login: eshanrnh
body: ```suggestion
* Fixed `Create` action button [#137](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/137).
* Added collection list view refresh feature following an entity action [#139](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/139).
* Fixed collection visibility [#134](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/134).
* Enabled rendering of sidebar properties.
* Fixed an issue that prevented the creation of multiple sections.
```
created_at: 2025-04-07T07:23:44Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to use in your model a reference to an Umbraco object and retrieve the `Integer` or `Guid` value of it, you would need to apply a conversion process to the `UDI` value.
path: 13/umbraco-ui-builder/collections/entity-identifier-converters.md
user: login: eshanrnh
body: ```suggestion
If you want to reference an Umbraco object in your model and retrieve its `Integer` or `Guid` value, you must convert the `UDI` value.
```
created_at: 2025-04-07T07:28:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to use in your model a reference to an Umbraco object and retrieve the `Integer` or `Guid` value of it, you would need to apply a conversion process to the `UDI` value.
+
+To achieve that you will need to use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter` - and add it as a `[TypeConverterAttribute]` to your model's foreign key property.
path: 13/umbraco-ui-builder/collections/entity-identifier-converters.md
user: login: eshanrnh
body: ```suggestion
Use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter`. Add it as a `[TypeConverterAttribute]` to your model's foreign key property.
```
created_at: 2025-04-07T07:28:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to use in your model a reference to an Umbraco object and retrieve the `Integer` or `Guid` value of it, you would need to apply a conversion process to the `UDI` value.
+
+To achieve that you will need to use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter` - and add it as a `[TypeConverterAttribute]` to your model's foreign key property.
+
+An entity that references an Umbraco object would look like this:
+
+```csharp
+    [TableName(TableName)]
+    [PrimaryKey("Id")]
+    public class MemberReview
+    {
+        public const string TableName = "MemberReview";
+
+        [PrimaryKeyColumn]
+        public int Id { get; set; }
+
+        public string Title { get; set; }
+
+        public string Content { get; set; }
+
+        [TypeConverter(typeof(EntityIdentifierToIntTypeConverter))]
+        public int MemberId { get; set; }
+    }
+```
+
+You can also define and use your own custom type converter and UI Builder will take care of the data persistence.
path: 13/umbraco-ui-builder/collections/entity-identifier-converters.md
user: login: eshanrnh
body: ```suggestion
You can also create a custom type converter. UI Builder will handle data persistence automatically.
```
created_at: 2025-04-07T07:29:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -18,6 +18,10 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 This section contains the release notes for Umbraco UI Builder 13 including all changes for this version.
 
+#### [**13.2.3**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.2.3) **(April 4th 2025)**
+
+* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144) and introduce new [Entity Identifier Converters](./collections/entity-identifier-converters.md) .
path: 13/umbraco-ui-builder/release-notes.md
user: login: eshanrnh
body: ```suggestion
* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144) and introduced new [Entity Identifier Converters](./collections/entity-identifier-converters.md) .
```
created_at: 2025-04-07T07:30:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to use in your model a reference to an Umbraco object and retrieve the `Integer` or `Guid` value of it, you would need to apply a conversion process to the `UDI` value.
path: 15/umbraco-ui-builder/collections/entity-identifier-converters.md
user: login: eshanrnh
body: ```suggestion
If you want to reference an Umbraco object in your model and retrieve its `Integer` or `Guid` value, you must convert the `UDI` value.
```
created_at: 2025-04-07T07:30:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to use in your model a reference to an Umbraco object and retrieve the `Integer` or `Guid` value of it, you would need to apply a conversion process to the `UDI` value.
+
+To achieve that you will need to use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter` - and add it as a `[TypeConverterAttribute]` to your model's foreign key property.
path: 15/umbraco-ui-builder/collections/entity-identifier-converters.md
user: login: eshanrnh
body: ```suggestion
Use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter`. Add it as a `[TypeConverterAttribute]` to your model's foreign key property.
```
created_at: 2025-04-07T07:31:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,36 @@
+---
+description: Using Umbraco entities as reference with an UI Builder collection
+---
+
+# Entity Identifier Converters
+
+Umbraco stores identifiers in UDI format for most Umbraco object types.
+
+You can read more about them in the [UDI Identifiers](../../umbraco-cms/reference/querying/udi-identifiers.md) section of the documentation.
+
+If you want to use in your model a reference to an Umbraco object and retrieve the `Integer` or `Guid` value of it, you would need to apply a conversion process to the `UDI` value.
+
+To achieve that you will need to use one of UI Builder's converters - `EntityIdentifierToIntTypeConverter` or `EntityIdentifierToGuidTypeConverter` - and add it as a `[TypeConverterAttribute]` to your model's foreign key property.
+
+An entity that references an Umbraco object would look like this:
+
+```csharp
+    [TableName(TableName)]
+    [PrimaryKey("Id")]
+    public class MemberReview
+    {
+        public const string TableName = "MemberReview";
+
+        [PrimaryKeyColumn]
+        public int Id { get; set; }
+
+        public string Title { get; set; }
+
+        public string Content { get; set; }
+
+        [TypeConverter(typeof(EntityIdentifierToIntTypeConverter))]
+        public int MemberId { get; set; }
+    }
+```
+
+You can also define and use your own custom type converter and UI Builder will take care of the data persistence.
path: 15/umbraco-ui-builder/collections/entity-identifier-converters.md
user: login: eshanrnh
body: ```suggestion
You can also create a custom type converter. UI Builder will handle data persistence automatically.
```
created_at: 2025-04-07T07:31:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -18,6 +18,10 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 This section contains the release notes for Umbraco UI Builder 13 including all changes for this version.
 
+#### [**13.2.3**](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.2.3) **(April 4th 2025)**
+
+* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144) and introduced new [Entity Identifier Converters](./collections/entity-identifier-converters.md) .
path: 13/umbraco-ui-builder/release-notes.md
user: login: eshanrnh
body: ```suggestion
* Removed global registration of `UDI` converters [#144](https://github.com/umbraco/Umbraco.UIBuilder.Issues/issues/144) and introduced new [Entity Identifier Converters](./collections/entity-identifier-converters.md).
```
created_at: 2025-04-07T08:24:32Z
author_association: CONTRIBUTOR

PR comments:
user: login: eshanrnh
created_at: 2025-04-04T12:06:26Z
body: Thanks for the PR, @acoumb 🙌 We will look at it as soon as we can.
author_association: CONTRIBUTOR
user: login: eshanrnh
created_at: 2025-04-07T07:09:20Z
body: Hey @acoumb 👋,

Can you please add the **entity-identifier-converters.md** article to the **SUMMARY.md** file so that it appears in the navigation pane?
author_association: CONTRIBUTOR
user: login: acoumb
created_at: 2025-04-07T07:19:00Z
body: @eshanrnh Updated. Thanks
author_association: CONTRIBUTOR
user: login: acoumb
created_at: 2025-04-07T08:18:12Z
body: If you're already working with the PR, it's fine with me for you to take care of them.

Thank you for the assistance.
author_association: CONTRIBUTOR