/
Power Database Fields migration process

Power Database Fields migration process

Owned by Vanya Kiritzova
Last updated: Jun 17, 2025

Deprecation notice

Power Database Fields version 6.0+ only supports next-generation fields (Advanced Database Row Field and Advanced Database Table Field). Legacy fields were removed in version 6.0. If upgrading from version 5.8 or earlier, migration is required before upgrading.

For additional information, see the Breaking changes for Power Database Fields version 6.0.820.0.

If you're upgrading from version 5.8 or earlier, you must migrate your legacy fields before upgrading to version 6.0+. This page provides comprehensive guidance for the migration process.

Always perform migration in a test environment first. Depending on your field configurations, the migration process can be complex and time-consuming.

Before you start

Migration can be time and effort-intensive depending on the number of fields and their complexity. Before beginning migration, make sure you complete the following:

1

Check Jira version compatibility

Power Database Fields version 5.8+ is not compatible with Jira 9. Plan your Jira and app upgrades accordingly.

2

Backup your database

This is mandatory before making any changes.

3

Set up a test environment

Never perform migration directly in production.

4

Upgrade to version 5.8+

Migration tools are only available in version 5.8 and later (recommended: version 5.8.0.14).

5

Document existing configurations

Note your current field settings, queries, and dependencies

Contents:

Contents:

Migration process overview

The migration process involves several steps:

1

Assessment

Evaluate your current field configurations.

2

Field conversion

Convert legacy fields to next-generation fields using the Migration Wizard or manual configuration.

3

Convert child field relationships

Redesign legacy child fields using next-generation approaches.

4

Field values migration

Migrate existing field data (if needed).

5

Testing and validation

Verify functionality in a test environment.

Migration complexity varies significantly based on your current implementation. Allow adequate time for testing and validation before deploying to production.

6

Production deployment

Apply changes to production after successful testing.

7

Post-migration cleanup

Update references and remove old fields.

Step 1: Assessment

Before migrating, categorize your legacy fields by complexity:

For…

Recommended migration approach…

For…

Recommended migration approach…

Simple configurations

  • Basic SQL queries without complex joins

  • Single table data sources

  • Standard autocomplete or select list formats

  • No custom scripts or complex dependencies

Complex Configurations

  • Advanced SQL queries with joins, subqueries, or complex WHERE clauses

  • Multiple data source dependencies

  • Custom SIL scripts

  • Child field relationships

  • Complex parameter passing

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.

  3. Set up the required scripts:

    • 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

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:

  • 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:

  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:

      SELECT id, capital FROM countries WHERE id IN ({screen:customfield_FIELD1_ID})

  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

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:

1

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.

2

Data validation

  • Compare old and new field values.

  • Verify that all expected data was transferred correctly.

  • Check for any missing or corrupted values.

3

Integration testing

  • Test JQL queries with new field IDs.

  • Verify SIL script functionality.

  • Check workflow and automation rules.

  • Test any third-party integrations.

4

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…

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.

1

Update documentation

  • Document new field configurations.

  • Update user guides and training materials.

  • Record custom field ID changes.

2

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.

3

User communication

  • Notify users of field changes.

  • Provide training on any new functionality.

  • Document any workflow changes.

4

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.

 

Need support? Create a request with our support team.

Copyright © 2005 - 2025 Appfire | All rights reserved.