Purpose
As Ardoq evolves to meet customer needs, there are situations where a field needs to change it's type (ex.list field to multi-select field, date time field to date field). To avoid disrupting customer data, we have documented step-by-step instructions to ensure a smooth migration to the new field type while maintaining data integrity. Ardoq does not automatically update existing fields when importing new solutions with different definitions, due to name conflicts and to avoid potential data loss.
When attempting to import a solution from the Ardoq Solutions module, you may encounter a field type conflict error that prevents the solution from being installed:
What this error means: The solution you're trying to import contains field definitions that conflict with existing fields in your organization. The fields share the same name but have different types.
This guide explains the process required to update an existing field's type in an Ardoq organization that already contains data and assets using that field. Following this process ensures data is preserved and assets are correctly reconnected to the updated field.
Note: This process involves temporarily breaking assets that use the field.
Before You Begin: Important Features
Before starting the manual refactoring process described below, please review these two powerful features. They can significantly simplify your workflow.
1. The One-Click Field Type Conversion: ONLY Date or DateRange:
If your goal is simply to convert a field from the DateTime to Date OR DateTimeRange to DateRange, you no longer need to follow the full manual process. You can now do this directly in the UI.
Navigate to the Fields Overview Page (My Organization -> Admin -> Fields)
If any outdated DateTime or DateTImeRange fields exist in your org, you will see this banner at the top:
Select "See convertible fields" and you will get a list of all relevant fields in the pop up window.
Click the "Convert" button under the Actions column, for each field.
After closing out the window, refresh your page to allow for the changes to reflect in your Ardoq instance.
2. Auditing: See Where a Field is Used Before You Change It:
Before you modify or archive any field, it is critical to understand which reports, surveys, or other assets depend on it.
Navigate to the Fields Overview Page (My Organization -> Admin -> Fields)
Select the field you want to investigate, a side panel will appear on the right.
You can see which assets, components and references this field is used in under the "Field Usage" section of the side bar.
You can click on asset types (e.g., "Surveys," "Reports"), Workspaces, components, references or types to see a detailed list and navigate directly to them.
Background
With the exception of the new one-click DateTime to Date conversion feature, it is generally not possible to directly change the type of an existing field in Ardoq. For instance, changing a Text field to a Checkbox would have no logical data mapping. This constraint exists to protect against accidental data loss or corruption.
Therefore, for most format changes, a manual migration process is required. This becomes especially relevant when importing a solution bundle. When a solution is imported into an Ardoq organization where a field with the same name already exists, Ardoq performs a compatibility check:
Field types match: Import proceeds normally. The existing field is preserved (not overwritten), and the solution's assets work correctly with the existing field.
Field types conflict: Import is blocked with an error message listing all conflicting fields.
Why the error protection is necessary: In previous versions of Ardoq, when field types conflicted, the import would proceed but the existing field would not be overwritten (to prevent data loss). This created a silent failure scenario where:
The solution would appear to install successfully
But solution assets (Surveys, Reports, Dashboards, Viewpoints) would break immediately
These assets expected the new field definition from the solution bundle
Instead they encountered the old field definition that remained in the organization
The error message now prevents this silent failure by blocking the import upfront and clearly identifying which fields need to be refactored before the solution can be installed.
Refactoring Steps
Follow these steps carefully to update an existing field while preserving data and reconnecting assets. We'll use the example of updating a "Review Date" field from Date-Time type to Date type.
Create a Temporary Field:
Manually create a new field in the organization that matches the updated definition/type.
Give it a temporary, distinct name. A good practice is adding a suffix like "v2".
Example: Create a new field named Lifecycle Phase v2 with the type List.
Crucially: Assign this temporary field (Lifecycle Phase v2) to all the same Component Types and Reference Types that the original field (Lifecycle Phase) is assigned to. You can check the assignments using the Field Usage Feature mentioned before.
Migrate Data to Temporary Field:
Copy all existing data from the original field (Lifecycle Phase) into the temporary field (Lifecycle Phase v2). You can do this using Ardoq's Excel import/export, or simply copy and pasting from Grid Editor/Inventory Mode.
Handle data type conversions during the copy:
Example (Select Multiple List to List): You must identify which list item you want to proceed with, since List only supports one item.
Example (Text to List): If changing from Text to List, you must map the existing text values to the corresponding predefined options in the new List field. Ensure all text values have a valid mapping.
Verify that the data has been copied correctly into the temporary field.
Assess Usage of the Original Field:
Before deleting the original field, investigate where it's currently used. Using the Field Usage Feature mentioned before, check key assets like:
Reports: Look for reports that use the field in filters or columns.
Surveys: Identify surveys that include the field as a question.
Viewpoints: Check viewpoints that use the field for conditional formatting, labels, or filtering.
Calculated Fields: See if any calculated fields depend on the original field.
Note down the assets identified. This helps with validation later.
Note: DO NOT CHANGE anything in the assets, the linkage with the existing field is needed when we re-add the field of the same name. All Gremlin queries will continue to reference the original field name, and will continue to work as expected once field is added back.
Delete the Original Field:
Go to Fields in the Metamodel Editor and delete the original field (Lifecycle Phase).
Warning: Any assets (Reports, Surveys, etc.) currently using this field will break at this point. This is expected. They however, still maintain a reference to the name "Lifecycle Phase", even though the field is gone.
Note: Before deleting a field in the metamodel editor, a message will prompt asking you to confirm the deletion. In that prompt, it will show you all the assets it can affect. This is a good second check on any assets/components/references that will temporarily break.
After deletion the assets will show the error below
(Image shows advanced search query error in a Report):
(Image shows error in a Survey question):
5. Create the Final Updated Field:
Immediately create a brand new field using the exact original name (Lifecycle Phase) but with the new, updated definition (e.g., type List).
Assign this new field to all the Component and Reference Types it should apply to (referencing the list from Step 1).
6. Transfer Data to Final Field:
Copy the data you preserved in the temporary field (Lifecycle Phase v2) into the newly created final field (Lifecycle Phase). Again, use Excel or Grid Editor.
Verify the data is correctly transferred.
Once you confirm the data is safe in the final field, you can delete the temporary field (Lifecycle Phase v2).
7. Validate Assets:
Check the assets you identified in Step 3 (Reports, Surveys, Viewpoints, Dashboards etc.).
Because the new field has the same name as the deleted one, Ardoq should automatically reconnect the assets.
Verify that these assets are now working correctly with the new field definition and data. You may need to manually refresh or slightly adjust some assets (like report columns or viewpoint perspectives) if the type change significantly alters how the data should be displayed.