Export/Import Object Types with UUID Retention

[joeridiederen]

Thema / Theme

Objecten API

Omschrijving / Description

We propose adding an export/import feature to the Object Type API that allows a complete Object Type definition to be transferred between environments without changing its UUID. In practice, this means an administrator could export an object type from one environment (e.g. a test or staging setup) and import it into another (e.g. production) while preserving the same unique identifiers. The scope covers the entire object type configuration – such as its schema/fields, labels, and any relevant metadata – ensuring the imported type is an exact replica of the original.

Toegevoegde waarde / Added value

This feature enables process definitions and workflows that are tightly coupled to specific object types to be migrated across environments without breaking. For example, in TAP-straat scenarios (Test, Acceptance, Production), a process that stores zaakdetails in a custom object type can be moved from a test environment to production confidently, since the required object type (and its UUID) will be identical on each environment.

It ensures configuration consistency between environments. Administrators won’t need to manually re-create object types by hand (which is time-consuming and error-prone).

Preserving UUIDs is critical for interoperability in a microservice landscape. Many systems refer to object types by their UUID. By retaining the same identifiers, we maintain integrity of links and references between the Objects API and other components (or process engines) in different environments.

Aanvullende opmerkingen / Additional context

In the context of TAP-straat migrations, organizations often have multiple environments (for testing, acceptance, and production) through which configurations progress. Currently, if one wants to duplicate an object type from one environment to another, there is no straightforward supported method to do so while keeping the same UUID. This poses challenges for TAP-straat implementations where a business process defined in a test environment expects certain object types (with specific IDs) to exist in the production environment. Without an export/import feature, teams resort to manual recreation of object types or direct database scripts – methods that are prone to mistakes and do not guarantee the same identifiers.

Notably, a similar challenge has been addressed in the case management domain by Open Zaak. In a recent update, Open Zaak introduced an option to preserve UUIDs when importing zaaktypen (case type definitions) via the admin interface​.

[alextreme]

Discussed with Team Bron: what do you do when importing a objecttype with a uuid that already exists? Would this update the existing objecttype? Assumption: always override if there's an existing objecttype uuid

We don't have django-import-export in the objecttypes API, this is a custom import/exporter built around sharing-configs which will be removed in the next release. So our assumption is to also ensure objecttypes can easily be exported and imported like with Open Formulieren and Open Zaak.

Question: how is JoeriD currently importing ObjectTypes, via the URL importer or otherwise?

Estimation: 3 days

[alextreme]

@janmasGDH ter info

[joeridiederen]

Discussed with Team Bron: what do you do when importing a objecttype with a uuid that already exists? Would this update the existing objecttype? Assumption: always override if there's an existing objecttype uuid

We don't have django-import-export in the objecttypes API, this is a custom import/exporter built around sharing-configs which will be removed in the next release. So our assumption is to also ensure objecttypes can easily be exported and imported like with Open Formulieren and Open Zaak.

Question: how is JoeriD currently importing ObjectTypes, via the URL importer or otherwise?

Estimation: 3 days

Why the current approach will no longer work
We currently promote Object Types through the TAP street (test → acceptance → production) by firing a one-off POST request from Postman, which lets us set a fixed uuid so it stays identical in every environment. While that satisfies our integrity requirements, Postman is deemed too technical for our municipal functional administrators, who need a simple import-export button in the admin UI.

New acceptance criterion: keep all the versions, including version indicator
Besides retaining the uuid, the migration must also keep the version indicator (objectTypeVersion). The current objecttype_create endpoint automatically creates version 1 and ignores any explicit version value in the payload, so true version history is lost.

Why this is important
Leaving the version number and its history out of an objectType breaks the contract that components rely on. Both Open Forms and the Generiek Zaakafhandelcomponent (GZAC) explicitly look up or store data against a specific object-type version. If that reference disappears, existing forms or zaakdetails suddenly point at an incompatible schema, causing validation errors, orphaned data and even stalled workflows.

Requested enhancement

• Export and import a complete Object Type (metadata, JSON schema, labels and every published version) in a portable file.
• Preserve both the uuid and the original version numbers, and versions, on import.
• Expose the feature in the admin UI so non-technical staff can use it without external tools.

This is similar to the “keep UUID” option recently added to Open Zaak for migrating zaaktypen, which has proven its value in practice.

-- Off topic — apologies for the delayed response. If you tag me next time, I can respond more quickly.

[StefSchots1993]

https://dimpact.atlassian.net/browse/PF-222

[StefSchots1993]

@alextreme - I just have send an e-mail to you and your to check which dev-team will be able to pick this up for development or further refinement. I just got asked about this feature by Rotterdam as stakeholders of Open Forms who wants this in their usecase with Open Forms to eSuite and GZAC. I'm wondering with whom I need to talk to so this feature can get on the right roadmap.

Technically Rotterdam told me they might have financial coverige for this feature true dedicaded Open Forms budgets.
So just want to discuss abouts whats possible.

[alextreme]

We'll discuss this issue next monday with Team Bron, sorry I'll tag you next time Joeri!