Converting a KB From GeneXus 9.0 (or prior)

Official Content

Converting to a new version not only enables us to add new features to the KB, but it is also a great opportunity to make the necessary adjustments to the KB (especially those that have been left behind several times).

The list below shows the steps recommended to convert a KB comming from GeneXus 9.0 or prior versions to GeneXus X, X Evolution 1 or X Evolution 2 (hereafter referred to GX X). Maybe you can avoid some of these steps or you have to perform a deeper analysis on some of them. Feel free to adopt this methodology as you wish. If you have any recommendations from your own experience, let us know!

Step 1 - Preparing the Knowledge Base


  • Back up the KB
  • Clean up the KB

Back Up or Copy the KB

The conversion process to GX X requires that the Knowledge Base be in 9.0 format.  If you have a Knowledge Base in a previous version of GeneXus, you need to convert the Knowledge Base to GeneXus 9.0 previously.

Since the process is not backwards compatible, it is advisable to back up or copy the Knowledge Base to be converted before starting the process.

Copy at least the following folders:

  • KB’s root directory.
  • Images directory. 
    Images files will be incorporated into GeneXus X KB as an Image object. Keep in mind these considerations for a proper images conversion
  • KBData directory.
    This folder contains complementary information about Web Services that you have inspected through WSDL Inspector. In GeneXus X that information is fully integrated in the KB as an External Object. The old information will be automatically converted during conversion process. Look at compatibility section for more information.
  • DataNNN.
    In case you have call to external programs (.java or .cs files), it will be necessary to keep the application folder (DataNNN) at least with those files. Nevertheless consider the use of External Object: Native Object

Clean up the KB

  • Delete unnecessary models and backup model.

To achieve a faster conversion we recommend deleting all the non-used models and the corresponding backup models, if any.

Besides, if you are converting to X version, consider that Win Environments Models are not supported, you could save time by deleting those models. Remember that this GeneXus version only supports Web Environments.

GX X Evolution 1 supports Win Models, but does not support Visual Basic generator.

  • Delete objects that you know are not being used any more
  • Delete *.ari and *.00? from the KB directory and subfolders

Also, deleting all the non-used objects will let you save work in the conversion. These non-used objects may have programming errors that may prevent their conversion.

Step 2 – Converting the KB to GX X


  • Convert the KB to GX X
  • Resolve problems in GX 9.0 KB to avoid a conversion fail
  • If it's necessarry, convert it again.

The expected process to convert a Knowledge Base is opening it with the new version instead of exporting and importing on a new one. The main differences between them are as follows:

  • Conversion doesn't work on objects that have errors, so the process stops when an error appears, whereas the Import may leave part of the object and continue with the rest.
  • Conversion tries to keep all the “model” preferences set by the user in the previous version. Besides, when a preference changes its default value in the new version, the previous value is kept in the converted KB. That does not occur when you are importing objects into a new KB.

In some cases, Export/Import is a better option than conversion. For instance, if you’re migrating a full web application, Conversion seems to be the best option; on the other hand, if you want to extract some part of the previous KB (because it was a Win model and you want to convert only a Transaction), Export and Import fits best.

When you perform a KB conversion, that is to say, open the KB with GX X, a progress bar will be displayed for each task that needs to be performed.

If you have Workflow objects in the Knowledge Base, GeneXus detects that and gives you the chance to convert the Workflow Diagram during the KB conversion process. Please refer to GXflow XEv1 Conversion or GXflow XEv2 Conversion for more details.

During the conversion to GX X some errors or warnings could appears. The information will be displayed in the output windows and once it finishes, the complete output information will be saved to a file named "conversion.log" located in the Knowledge Base directory. Besides, a file named "conversion.log.err" is created only containing the errors and warnings. This file is useful in case you need to know all the possible errors that could happen during the conversion process.

The conversion is considered successfully only when no errors have been found. If some appears during the conversion process you need to resolve them in GX 9.0 KB and convert again.

After a successful conversion the Knowledge Base is ready to be used with GeneXus X. The original Knowledge Base in a previous version format is saved to a subdirectory named Backup.

Genexus Rocha/ConversionProgress 

Important: Some considerations are assumed during conversion process. Please, take a look at GeneXus X Conversion General Considerations or GeneXus X Evolution 1 and X Evolution 2 General Considerations depending on your target version.

Step 3 – Adjust the KB (in GX X)


Step 4 – Detailed Analysis


Once the Knowledge Base is ready to use in GeneXus X or higher, the following step is to perform a "Build All", or directly run a main object. Once the process is complete, compare the objects' navigation with the previous version. In this way you can obtain more information about some changes performed on the current version (new features, bug fixes, etc) and how these differences could affect your application.

Finally, check the Generator compatibility section for specific compatibility information about changes performed in your generator.

Community References

Take a look at Enrique's suggestions (spanish)