i
This is not the latest version of this document; to access the latest version, click here.

GeneXus Server Storage Migrator Utility

Official Content
This documentation is valid for:

The Genexus Server Storage Migrator utility is a command-line tool used to migrate a Knowledge Base between GeneXus Server instances. The migration includes all the activity related to the Knowledge Base, these means, all the information about all the Commits, Updates, Bring changes...made on it.

The file name is gxssm.exe, and it's located under the following directory:

C:\<GeneXus Server installation path>\VDir\Bin

Note: this tool it's only available when GeneXus Server is configured with a local SQL Server Instance, in another case the following error will appear:

Import cannot proceed. GeneXus Server is configured to use a remote instance of SQL Server (<Remote SQL Instance Name>).

Recommendation: execute the command prompt with administrator's rights (Run As Administrator).

Note: this tool can be downloaded from Genexus Server Storage Migrator Utility Setup.

Availability

Export and Import features are available as of  GeneXus Server X Evolution 1 Upgrade #8.

Features

Help

Execute it with /h parameter to get the utility help:

C:\GeneXusServerXev2\VDir\Bin>gxssm.exe /h
gxssm v10.2.0.54462
Input:/h
gxssm.exe v10.1.0.0
Copyright c 2006-2012 Artech. All Rights Reserved
Usage: gxssm.exe @argfile error v1
       kb:<value> c e i:<value>
       /IgnoreGAM:<value> out:<value> ?|h v
@argfile             Read arguments from a file.
/ExitOnError         Exits the program on the first error found
/Version1            Forces v1 Reorg
/KBAlias:<value>     Knowledgebase to migrate
/Clean               Deletes any existant data on the tables
/Export              Export the Knowledge Base and evry associated GXserver
                     data
/Import:<value>      Path to the export file of a Knowledge Base
/IgnoreGAM:<value>   Tells the Export or Import to ignore Genexus Access
                     Manager data (Default is "False")
/OutputPath:<value>  Full path to the directory where the generated output file
                     will be placed.
/help                Show usage.
/version             Show version.

 

Export

This option will generate a zip file containing all the information about the Knowledge Base.

To export a Knowledge Base use the /e/kb and /out parameters, the entire command it will as follows:

C:\<GeneXus Server installation path>\VDir\Bin>gxssm.exe /e /kb:"<Knowledge Base Name>" /out:"C:\<Destination path>"

Where

  • /e indicates that it's an export operation.
  • /kb:"<Knowledge Base Name>" indicates the Knowledge Base's name of the one to be exported.
  • /out:"C:\<Destination path>" indicates the path where the zip file will be saved.

Usage Example

C:\GeneXusServerXev2\VDir\Bin>gxssm.exe /e /kb:"TravelAgency" /out:"C:\Export"
gxssm v10.2.0.54462
Input:/e /kb:TravelAgency /out:C:\Export
=== Section Exporting GAM data started ===
Parameters OK.
============ start to export gam data ============
Application exportation OK.
  * 1 record(s) exported from Table Application
ApplicationRole exportation OK.
  * 1 record(s) exported from Table ApplicationRole
User exportation OK.
  * 1 record(s) exported from Table User
UserRepository exportation OK.
  * 1 record(s) exported from Table UserRepository
UserMemRole exportation OK.
  * 1 record(s) exported from Table UserMemRole
UserMemAppRole exportation OK.
  * 1 record(s) exported from Table UserMemAppRole
RoleAppTypePrm exportation OK.
  * 16 record(s) exported from Table RoleAppTypePrm
AppTypeAction exportation OK.
  * 8 record(s) exported from Table AppTypeAction
AppTypePermission exportation OK.
  * 8 record(s) exported from Table AppTypePermission
Role exportation OK.
  * 8 record(s) exported from Table Role
RoleMemRole exportation OK.
  * 8 record(s) exported from Table RoleMemRole
=== Section Exporting GAM data ended successfully ===

Import

This option will uncompress the zip file generated by the Export operation, and it will attach all the information to the new GeneXus Server instance.

To import a Knowledge Base, use the /i and /kb parameters, the entire command it will as follows:

C:\<GeneXus Server installation path>\VDir\Bin>gxssm.exe /i:"<Zip file location>" /kb:"<New Knowledge Base name>"

Where

  • /i indicates that it's an import operation.
  • "<Zip file location>" indicates the entire path where the zip file is located.
  • /kb:"<New Knowledge Base name>" indicates the name that the Knowledge Base will have in the new GeneXus Server instance.

Note: the chosen name can not exist in the GeneXus Server destination Instance.

Usage example

C:\GeneXusServerXev2_2\VDir\Bin>gxssm.exe /i:C:\Export\TravelAgency.zip /kb:TravelAgencyNewServer
=== Section Import KB started ===
Extracting file to tmp folder 'C:\Users\<User name>\AppData\Local\Temp\ATT201203051134'
Loading GXserver defaults...
Renaming database files...
Attaching database...
Starting BL...
Processing Knowledgebase 'TravelAgency' @ 'C:\GeneXusServerXev2_2\Catalog\TravelAgencyNewServer-7ffa5161-9a2a-494a-992a-32f578d0bf60'
Adding 'TravelAgencyNewServer' to the catalog table
Processing commits for version 'TravelAgency...'
5 commits were migrated.
Processing updates for version 'TravelAgency'
3 updates were migrated.
Processing checkouts for version 'TravelAgency'
1 checkouts were migrated.
========Deploy data process started ========
Verifying package correctness.
Checking directory C:\GeneXusServerXev2\Catalog\TravelAgencyNewServer-7ffa5161-9a2a-494a-992a-32f578d0bf60\GAM\...
Package is correct.
======== Import Application. ========
Import completed successfully.
X records(s) inserted.
======== Import Role. ========
Role Unknown already in the database
Role Admin already in the database
Role KBAdmin already in the database
Role KBUser already in the database
Role ServerGuest already in the database
Import completed successfully.
No data was inserted.
======== Import User. ========
User admin already in this database.
Import completed successfully.
No data was inserted.
======== Import UserRepository. ========
Import completed successfully.
No data was inserted.
======== Import RoleMemRole. ========
Import completed successfully.
No data was inserted.
======== Import UserMemRole. ========
Import completed successfully.
No data was inserted.
======== Import AppTypeAction. ========
Import completed successfully.
No data was inserted.
======== Import AppTypePermission. ========
Import completed successfully.
No data was inserted.
======== Import ApplicationRole. ========
Import completed successfully.
No data was inserted.
======== Import UserMemAppRole. ========
Import completed successfully.
No data was inserted.
======== Import RoleAppTypePrm. ========
Import completed successfully.
No data was inserted.
Kb 'TravelAgencyNewServer' saved at 'C:\GeneXusServerXev2_2\Catalog\TravelAgencyNewServer-7ffa5161-9a2a-494a-992a-32f578d0bf60'
=== Section Import KB ended successfully ===

Troubleshooting

Run As Administrator 

When the tool runs in a command prompt without administrator rights, it may cause the Export or Import process to end abruptly (with errors). Also, the following error will be displayed:

=== Section Exporting GAM data ended successfully ===
Taking DB 'GXS dl portal d0128365-f2f1-448b-8c00-85097c5da3a5' offline...
Zipping files...
Bringing DB 'GXS dl portal d0128365-f2f1-448b-8c00-85097c5da3a5' online...
Error: Error exporting data
Error: Could not zip files
Error: en GenexusServer.StorageMigrator.Reorgs.Export.ExportKB(GXS KBCatalog kb)
en GenexusServer.StorageMigrator.Reorgs.Export.ExecuteOperation()

Could not find file

C:\GeneXusServerXEv2 U3\VDir\Bin>gxssm.exe /e /kb:TestSendKBToEv2U3 /out:c:\export\
gxssm v10.2.3.5185
Input:/e /kb:TestSendKBToEv2U3 /out:c:\export\
=== Section Exporting GAM data started ===
System.IO.FileNotFoundException: Could not find file 'C:\GeneXusServerXEv2'.File name: 'C:\GeneXusServerXEv2'
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access,FileShare share, Int32 bufferSize, FileOptions options, String msgPath, BooleanbFromProxy)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access,FileShare share, Int32 bufferSize)
   at System.Xml.XmlDownloadManager.GetStream(Uri uri, ICredentials credentials)

   at System.Xml.XmlUrlResolver.GetEntity(Uri absoluteUri, String role, Type ofObjectToReturn)
   at System.Xml.XmlTextReaderImpl.OpenUrlDelegate(Object xmlResolver)
   at System.Threading.CompressedStack.runTryCode(Object userData)
   at System.Runtime.CompilerServices.RuntimeHelpers.ExecuteCodeWithGuaranteedCleanup(TryCode code, CleanupCode backoutCode, Object userData)
   at System.Threading.CompressedStack.Run(CompressedStack compressedStack, ContextCallback callback, Object state)
   at System.Xml.XmlTextReaderImpl.OpenUrl()
   at System.Xml.XmlTextReaderImpl.Read()
   at GeneXus.Configuration.Config.loadConfig(String filename)
   at GeneXus.Configuration.Config.get_config()
   at GeneXus.Application.GxContext.LocalInitialize()
   at GeneXus.Application.GxContext..ctor()
   at GAM.API.adp_exportgamdata..ctor()
   at GAM.API.adp_exportgamdata.Main(String[] args)
=== Section Exporting GAM data ended with errors ===
Taking DB 'GXS_TestSendKBToEv2U3_ab27b42b-87b9-45c4-b51e-968b3686faee' offline
...
Zipping files...
Bringing DB 'GXS_TestSendKBToEv2U3_ab27b42b-87b9-45c4-b51e-968b3686faee' onlin
e...
KB 'TestSendKBToEv2U3' exported to 'c:\export\TestSendKBToEv2U3.zip'

Export and Import process do not work if the GeneXus Server installation directory has space characters. This issue is fixed as of GeneXus Server X Evolution 2 Upgrade 5. See SAC 35543 for more details.


Access is denied

Unable to open the physical file "C:\<GeneXus Server installation path>\Catalog\<MDF File Name>.mdf" operating system 5: "5 (Access is denied.)". 

OR

Error: the database 'GXS_XXX' couldn`t be updated because it is read only

This error could happen in the import process when the SQL Server or Windows user used by GeneXus Server has no permissions over the Catalog directory (where the Knowledge Bases must be stored).
To fix this issue give full control permissions over the Catalog directory (located by default under GeneXus Server's Install directory) to user NETWORK SERVICE1, if SQL Server authentication is used or to the Windows user otherwise. If the directory does not exist, create it and then give "NETWORK SERVICE" or Windows user full control permissions.

See SAC 34486 for more details.

Note1: the service account that is running SQL Server can be found by opening "Services" (and looking for "SQL Server") under the "Log On As" column:

MSSQLServiceAccount


Authentication Failed

Error:Error importing data
Error:AuthenticationFailed
Error:   at Artech.Architecture.Common.Objects.KnowledgeBase.CheckConnection(String location, KBConnectionInfo info)
   at Artech.Architecture.Common.Objects.KnowledgeBase.Open(OpenOptions options)
   at GenexusServer.StorageMigrator.Reorgs.v1.ProcessKnowledgeBase(String kbAlias, String kbLocation)
   at GenexusServer.StorageMigrator.Reorgs.Import.ExecuteOperation()
=== Section Import KB ended with errors ===

This error could happen in the import process when using Genexus Server Storage Migrator Utility to import a Knowledge Base to a GeneXus Server instance configured with SQL authentication. This error is fixed as of GeneXus Server XEv2 U4.

See SAC 34652 for more details.


Login failed for user ' '

=== Section Exporting GAM data started ===
Parameters OK.
============ start to export gam data ============
.....
=== Section Exporting GAM data ended successfully ===
Taking DB '{MDFName}' offline
...
Warning:Login failed for user ''.

This error will happen in the export process when using Genexus Server Storage Migrator Utility to export a Knowledge Base from a GeneXus Server instance configured with SQL authentication.

See SAC 35465 for more details.