How to migrate from GAM version 4.0.4 to 4.0.5

Official Content
This documentation is valid for:

When opening a knowledge base from GeneXus v17u5 or later, if you are using an older version of GeneXus, it will automatically import the new version of GAM (4.0.5). A Build performed from the IDE will automatically execute a reorganization of the database and a metadata migration right afterwards. Therefore, in the Development environment, the update is performed automatically and transparently.
On the other hand, in the Production environment, the database update must be executed by the developer.

Below are the steps needed to perform the update in the Production environment:

  1. First, reorganize the database. To this end, the content of the SQL script is distributed in the GeneXus installation in the following path: <GX_installation_path>\Library\GAM\Platforms\<environment>\ReorganizationScript404To405.txt
     
  2. To complete the upgrade, migrate the metadata using the GAM Deploy Tool (GDT) by the command line.
    To run this migration, write permissions are required in the directory where it is executed. This only applies to the migration of the connection.gam file.
    It varies according to the environment in which the invocation of the GDT is found. The connection.gam file is generated in the directory that runs the GDT:
    NET: In the directory <KB>\<Net_env>\web\bin the exe is distributed.
    agamdeploytool.exe -upgradegam -admin_name gamadmin -admin_pass gamadmin123

    JAVA: In the directory <TOMCAT_DIR>\webapp\<App_Name>\WEB-INF\classes\<path_to_package> the class is distributed.
    Before running the GDT, copy the connection file from <TOMCAT_DIR>\webapps\<APP>\WEB-INF\connection.gam to <TOMCAT_DIR>\webapps\<APP>\WEB-INF\classes\<Path_to_package> (for example, C:\Program Files\Apache Software Foundation\Tomcat 8.5\webapps\AppJavaSQL\WEB-INF\classes\com\test).
    Next, run the GDT:
    java -cp "<TOMCAT_DIR>\webapp\<App_Name>\WEB-INF\classes\lib\*" genexus.security.api.agamdeploytool -upgradegam -admin_name gamadmin -admin_pass gamadmin123

    NETCORE: In the directory <KB>\<NetCore_env>\web\bin the library is distributed.
    dotnet agamdeploytool.dll -upgradegam -admin_name gamadmin -admin_pass gamadmin123
  3. If the GDT runs successfully, it should end with these lines: 
    Connecting to GAM database ...
    Data migration from 4.0.4 to 4.0.5
    >>> Success
  4. To move the new file to production:
    • If the application is deployed in a container, you can set an environment variable. Open the connection.gam file generated by the tool, obtain the value of the "<key>" tag, and configure it as indicated in the document: support setting key for GAM connection data through environment variable.
    • Otherwise, copy the newly generated connection.gam file to the corresponding location depending on the environment:
      NET:
      The file is generated in the directory <KB>\<Net_env>\web\bin. Copy it to the directory <KB>\<Net_env>\web.
      Note that there is a backup of the old connection.gam file with the name connection-bkp.gam.

      JAVA:
      Copy the connection file generated in <TOMCAT_DIR>\webapps\<APP>\WEB-INF\classes\<Path_to_package>\connection.gam to <TOMCAT_DIR>\webapps\<APP>\WEB-INF.

      NETCORE:
      Similar to Net but in the NetCore environment, <NetCore_env>.

 

Compatibility

The GAM database is totally backward compatible. This means that you can continue using KBs with a GeneXus version prior to v17u5 pointing to a new database.