Versions Compared

Version Old Version 11 New Version Current
Changes made by

Rama Goberu

Sudhir Kv

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Problem

Users may encounter errors when migrating Jira projects using the Configuration Manager for Jira (CMJ). These errors often result in incomplete deployments or “undefined” errors.

...

Symptoms

  • Deployment fails with an “undefined” error.

  • Deployment process reverts changes due to SQL or system configuration issues.

  • Errors in audit and debug logs such as:

    • SQL parameter limits:

      Code Block
      SQLServerException: The incoming request has too many parameters. The server supports a maximum of 2100 parameters.

    • Java Heap Memory issues:

      Code Block
      java.lang.OutOfMemoryError: Java heap space

    • Dashboard gadget configuration errors:

      Code Block
      Error while exporting app dashboard gadget configuration data for gadget.

    • Custom field or LDAP errors in the logs:

      Code Block
      CUSTOM FIELD ID 0 OUT OF BOUNDS  
LdapCtxFactory not found by com.botronsoft.jira.rollout.configuration-manager-core

...

Root Cause Analysis

  1. SQL Parameter Limitation:
    DB management systems limit the number of parameters in an SQL query. This issue can be triggered by large organizations (e.g., over 2100 members).

  2. Insufficient Heap Memory:
    Jira instances running with insufficient Java Heap memory (e.g., 2GB) fail during resource-intensive operations like large-scale project migrations.

  3. Dashboard Configuration Issues:
    Gadgets from external apps or corrupt configurations cause integrity issues.

  4. System Setting Inconsistencies:
    Differences in language, time zone, or system settings between source and target Jira environments can lead to deployment failures.

  5. Debug Information Insufficient:
    Lack of debug logs or incomplete support files delays root cause identification.

...

Resolution Steps

Pre-Migration Checks

  1. Run the Integrity Check tool: Integrity Check Documentation.

  2. Ensure consistent Jira versions and plugins between source and target instances.

Increase Memory Allocation

  1. Increase the Java Heap size to at least 4GB:
    How to Increase Jira Application Memory.

  2. Restart the Jira instance after making these changes.

Address SQL Limitations

  1. Divide large organizations (>2100 members) into smaller groups before migration.

  2. Reference database queries to identify affected organizations:

    Code Block
    SELECT "USER_KEY" FROM "AO_54307E_ORGANIZATION_MEMBER"  
WHERE "ORGANIZATION_ID" = <org_id>

  3. Database Query Example

    Code Block
    SELECT "ORGANIZATION_ID", COUNT("USER_KEY") AS "USER_COUNT"  
FROM "AO_54307E_ORGANIZATION_MEMBER"  
GROUP BY "ORGANIZATION_ID"  
HAVING COUNT("USER_KEY") > 2100;

Resolve Dashboard Issues

  1. Run native Jira Integrity Checks and re-index the Jira instance:

    • Navigate to Jira Administration > System > Integrity Check.

    • Perform a Full Re-index.

  2. Remove or reconfigure problematic gadgets identified in the logs.

Adjust System Settings

  1. Ensure consistent time zone, language, and locale settings between source and target Jira environments.

Logs for Further Analysis

Enable Debug Logs for Further Analysis

  1. Enable Debug Logging: Debug Logging Documentation.

  2. Attempt the deployment again and collect the updated logs.

  3. Include Audit Logs from CMJ: Audit Logging Documentation.

  4. Share the complete support.zip file: Creating a Support Zip.

...

Conclusion

Migrating Jira projects using Configuration Manager for Jira(CMJ) can encounter various errors due to system resource limits, database constraints, or inconsistencies. Following the outlined steps, including increasing memory, addressing SQL limitations, and ensuring consistent system settings, can resolve most deployment issues. For unresolved errors, enabling debug logs and providing detailed support files is essential for further investigation.

...