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) Too not disrupt customer data, we have documented step by step instructions that can be followed to ensure migration to the new field while maintaining data integrity. Ardoq does not automatically update existing fields when new solution bundles with different definitions are imported due to name conflicts and to avoid potential data loss. This guide explains the manual 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.
Background
When a solution bundle is imported into an Ardoq organization where a field with the same name already exists, the existing field is not overwritten or updated (this is done to prevent potential data loss). This can cause issues if the imported solution contains assets (like Surveys or Reports) expecting the new field definition (e.g., a different field type). These assets may break because they are trying to use a field definition that wasn't imported due to the name conflict.
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 Review Date v2 with the type Date.
Crucially: Assign this temporary field (Review Date v2) to all the same Component Types and Reference Types that the original field (Review Date) is assigned to. You can check the assignments on the original field's configuration page. This ensures you know where the data needs to go.
Migrate Data to Temporary Field:
Copy all existing data from the original field (Review Date) into the temporary field (Review Date v2). You can do this using Ardoq's Excel import/export, or simply copy and pasting from the Grid Editor.
Handle data type conversions during the copy:
Example (Date-Time to Date): When copying Date-Time values to the new Date field, Ardoq usually handles this automatically, dropping the time portion.
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. 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 (Review Date).
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 "Review Date", 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 this error
(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 (Review Date) but with the new, updated definition (e.g., type Date).
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 (Review Date v2) into the newly created final field (Review Date). 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 (Review Date 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.