---
title: "Power Database Fields migration process"
canonical: "https://support.appfire.com/space/PSJ/2116747393/Power%20Database%20Fields%20migration%20process"
format: markdown
---
> Macro (aura-html)

---

## Migration process overview

The migration process involves several steps:

|  |  |
| --- | --- |
| **[Assessment](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Step-1%3A-Assessment)** | Evaluate your current field configurations. |
| **[Field conversion](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Step-2%3A-Field-conversion)** | Convert legacy fields to next-generation fields using the Migration Wizard or manual configuration. |
| **[Convert child field relationships](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Convert-child-field-relationships)** | Redesign legacy child fields using next-generation approaches. |
| **[Field values migration](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Field-values-migration)** | Migrate existing field data (if needed). |
| **[Testing and validation](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Testing-and-Validation)** | Verify functionality in a test environment.<br>> ✅ Migration complexity varies significantly based on your current implementation. Allow adequate time for testing and validation before deploying to production. |
| **Production deployment** | Apply changes to production after successful testing. |
| **[Post-migration cleanup](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Post-migration-tasks)** | Update references and remove old fields. |

---

## Step 1: Assessment

Before migrating, categorize your legacy fields by complexity:

| **For…** | **Recommended migration approach…** |
| --- | --- |
| ### Simple configurations<br>- Basic SQL queries without complex joins
- Single table data sources
- Standard autocomplete or select list formats
- No custom scripts or complex dependencies | - Use [Migration Wizard](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Method-1%3A-Using-the-Migration-Wizard) |
| ### Complex Configurations<br>- Advanced SQL queries with joins, subqueries, or complex WHERE clauses
- Multiple data source dependencies
- Custom SIL scripts
- Child field relationships
- Complex parameter passing | - [Manual migration](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/2116747393/Power+Database+Fields+migration+process#Method-2%3A-Manual-migration)
- Migration Wizard with manual adjustments |

---

## Step 2: Field conversion

Once you've completed the prerequisites and assessed your field configurations, you can proceed with the actual migration. Power Database Fields provides two approaches for converting legacy fields to next-generation fields, each suited to different complexity levels and technical requirements.

### Method 1: Using the Migration Wizard

The Migration Wizard automates the conversion process for simple field configurations. The Migration Wizard:

- Creates an exact copy of your legacy field configuration.
- Converts settings to next-generation field format.
- Attempts to transfer existing field values automatically.
- Leaves the original legacy field intact during migration.

> ℹ️ **Migration Wizard limitations:**
> ℹ️ 
> ℹ️ - Might not parse complex SQL queries correctly.
> ℹ️ - Cannot handle advanced scripting configurations.
> ℹ️ - Might fail to migrate values for complicated field relationships.

#### **Procedure**

To access the Migration Wizard:

1. Navigate to **Administration** > **Power Apps Config.**
2. Click **Tools** > **Migrate Old DBCF.**
3. Follow the wizard’s instructions.
4. After migration completes:
  1. Review the migrated field configuration.
  2. Thoroughly test field functionality.
  3. Perform manual adjustments if needed.

### Method 2: Manual migration

For complex configurations or when the Migration Wizard fails to produce correct results, manual migration is required.

#### **Procedure**

1. Create a new Advanced Database Row Field. To do this:
  - Go to **Administration** > **Custom Fields** > **Add Custom Field**
  - Select **Advanced Database Row Field**.
2. Configure the new custom field using the Configuration Wizard or Advanced Configuration.
  - Use the [Configuration Wizard ](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15482085)for guided setup (requires primary key in database table).
  - Use [Advanced Configuration](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15482103) for full manual control.
3. Set up the required [scripts](https://appfire.atlassian.net/wiki/spaces/PSJ/pages/15482071):
  - **GET script**: Retrieves field values (uses primary key as parameter).
  - **SEARCH script**: Provides selectable options.
  - **DEFAULT script** - Sets default values (optional).
4. Configure external parameters (if needed).
  - Set up dependencies on other fields.
  - Configure dynamic parameter passing.
5. Test field functionality.
  - Verify queries execute correctly
  - Test field behavior in Create/Edit screens
  - Validate parameter dependencies

---

## Step 3: Convert child field relationships

Legacy child fields don't exist in next-generation fields. Use these alternatives:

| ### Option 1: Multi-column Advanced Row Field (recommended) | ### Option 2: Dynamic parameter relationships |
| --- | --- |
| Convert parent-child relationships into a single Advanced Row Field with multiple columns:<br>- The main value becomes the primary column.
- Child data becomes additional columns.
- All related data appears in one field. | To create separate Advanced Row Fields connected through dynamic parameters:<br>1. Create the parent field:
  1. Add a new Advanced Database Row Field for the parent data (for example, Countries).
  2. Configure with standard GET and SEARCH scripts.
2. Create the dependent field:
  1. Add a second Advanced Database Row Field for the dependent data (for example, Capitals).
  2. Configure the GET script normally.
  3. Configure the SEARCH script to reference the parent field using parameter syntax:
3. Configure external parameters:
  1. In the dependent field's configuration, navigate to the external parameters section and add the parent field's custom field ID as an external parameter.
  2. Choose parameter type:
    - Use `screen:customfield_ID` for real-time updates during editing
    - Use `issue:customfield_ID` for saved values
4. To test the relationship:
  1. Create or edit an issue and select a value in the parent field.
  2. Verify that the dependent field updates with filtered options.
5. (Optional) Enable auto-bind:
  1. In the dependent field's **Advanced Configuration** > **General** tab, enable the **Auto-bind **toggle. The field will automatically populate when only one option is available<br>**Result:** When users select a value in the parent field, the dependent field will show only the relevant options based on that selection. |

---

## Step 4: Field values migration

After successfully migrating your field configurations, you need to transfer the actual data values from your legacy fields to the new next-generation fields. This can happen automatically through the Migration Wizard or manually using SIL scripts when automatic migration fails.

### Method 1: Automatic value migration

The Migration Wizard attempts to transfer existing field values automatically. However, this might fail for complex configurations.

### Method 2: Manual value migration with SIL scripts

When automatic migration doesn't transfer values, use SIL scripts to move data from legacy fields to new fields.

#### **Example SIL script for value migration**

This example SIL script demonstrates the basic structure for migrating field values. You'll need to customize this script for your specific environment and field configuration before running it.

```
for(string k in selectIssues("project = YOUR_PROJECT")) {
    string[][] data;
    string[] oldData = %k%.customfield_OLD_FIELD_ID;
    
    data[0] = sql("YOUR_DATASOURCE", "SELECT col1, col2 FROM your_table WHERE col2 = ?", oldData[0]);
    
    %k%.customfield_NEW_FIELD_ID = data;
}
```

> ℹ️ **Note:** This example works for single select and autocomplete fields. Multiselect fields and special cases (such as data no longer present in the external database) require modified scripts. Contact support for assistance with complex migration scenarios.

To use this example script in your environment, you must modify the following parameters to match your specific configuration:

|  |  |
| --- | --- |
| **JQL query** | Replace `YOUR_PROJECT` with your actual project key, or modify the search criteria to target the issues you want to migrate. |
| **Data source name** | Replace `YOUR_DATASOURCE` with the actual JNDI name from your legacy field configuration (found in the legacy field's data source settings). |
| **SQL query** | Update the `SELECT` statement and table name to match your field's actual database query structure. |
| **Custom field IDs** | Replace `customfield_OLD_FIELD_ID` and `customfield_NEW_FIELD_ID` with the actual custom field IDs from your Jira instance. |

> ℹ️ **Important:** Never run this script without customizing these parameters first, as it will fail or potentially affect unintended data.

#### **Procedure**

1. Navigate to **Administration** > **SIL Manager**.
2. Right-click the **silprograms** folder and select **New **> **File.**
3. Create a file with a `.sil` extension (for example, `migrate_values.sil`)
4. Paste your customized migration script.
5. Click the **Check** button to validate syntax.
6. Click the **Run** button to execute.
7. Verify migration results:
  - Check **Editor Console** for "DONE!" success message or error details.
  - Use the Issue Navigator to compare old and new field values side-by-side.
  - Open individual issues to confirm data transferred correctly.

---

## Step 5: Testing and Validation

After completing field conversion and value migration, thorough testing in your test environment is essential before deploying changes to production. This validation process helps identify any configuration issues, data transfer problems, or integration conflicts that need resolution.

Before applying migration to production, follow this testing protocol:

|  |  |
| --- | --- |
| **Functional testing** | - Test field behavior in the Create Issue screen.
- Test field behavior in the Edit Issue screen.
- Verify transition screen functionality.
- Test search and filter capabilities. |
| **Data validation** | - Compare old and new field values.
- Verify that all expected data was transferred correctly.
- Check for any missing or corrupted values. |
| **Integration testing** | - Test JQL queries with new field IDs.
- Verify SIL script functionality.
- Check workflow and automation rules.
- Test any third-party integrations. |
| **Performance testing** | - Verify query performance meets expectations.
- Test with realistic data volumes.
- Check response times in various scenarios. |

---

## Common Issues and Troubleshooting

During migration, you might encounter various technical challenges depending on your field complexity and configuration. Here are the most frequently reported issues and their solutions to help you resolve problems quickly.

| **If…** | **Do this…** |
| --- | --- |
| **Migration Wizard fails to parse query** | - Review SQL query complexity.
- Simplify the query if possible.
- Use manual migration instead. |
| **Values not migrated** | - Check SIL script syntax and parameters.
- Verify data source connectivity.
- Review custom field IDs in script. |
| **Field dependencies not working** | - Verify external parameter configuration.
- Check primary key column usage in dependent queries.
- Enable auto-bind feature if needed. |
| **Performance issues** | - Review query efficiency
- Check database indexing
- Consider query optimization |

---

## Step 7: Post-migration tasks

Once you've successfully migrated and validated your fields in the test environment, several important tasks remain to complete the transition to production. These steps ensure your organization can fully utilize the new fields while maintaining operational continuity.

|  |  |
| --- | --- |
| **Update documentation** | - Document new field configurations.
- Update user guides and training materials.
- Record custom field ID changes. |
| **Update integrations** | - Modify JQL queries to use new field IDs.
- Update SIL scripts with new field references.
- Adjust workflow and automation rules.
- Update third-party integration configurations. |
| **User communication** | - Notify users of field changes.
- Provide training on any new functionality.
- Document any workflow changes. |
| **Cleanup** | - Remove legacy fields after confirming migration success.
- Archive old configuration documentation.
- Clean up test environments. |

---

## Getting help

If you encounter issues during migration:

- Review field configuration for accuracy.
- Check SIL Manager Editor Console for error details.
- Test in isolation to identify specific problems.
- Contact Appfire support with specific error messages and configuration details.