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 is available whether the GeneXus Server's SQL configuration is local or remote.

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

Features

Help

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

C:\<GeneXus Server installation path>\VDir\Bin>gxssm.exe /h
gxssm v15.0.3.109723
Input:/h
gxssm.exe v11.0.0.0
Copyright © 1988-2016 GeneXus. All Rights Reserved

Usage: gxssm.exe [@argfile] [/DataFilesLocation|d:<value>]
     [/SQLDataAbsolutePath|sa:<value>] [/ExitOnError|error] [/Version1|v1]
     [/KBAlias|kb:<value>] [/Clean|c] [/Export|e] [/JustJSon|j] [/Import|i:<value>]
     [/IgnoreGAM:<value>] [/BCPExport:<value>] [/OutputPath|out:<value>]
     [/<DataFilesLocation>:<value>]
     [/<SQLDataAbsolutePath>:<value>] [/help|?|h] [/version|v]

 

Parameters

@argfile Read arguments from a file.
/DataFilesLocation:<value> Full path to directory (local or network share) where the data files are taken from/to
/SQLDataAbsolutePath:<value> Full path as seen by the SQL Server to attach a database
/ExitOnError Exits the program on the first error found
/Version1 Forces v1 Reorg
/KBAlias:<value> Knowledgebase to migrate
/Clean Deletes any existent data on the tables
/Export Export the Knowledge Base and every associated GXserver data
/JustJSon Just Export the JSON files from the GAM database
/Import:<value> Path to the exported zip file of a Knowledge Base (if it is a Directory: all zip files of Knowledge Bases exported)
/IgnoreGAM:<value>  Tells the Export or Import to ignore Genexus Access Manager data (Default is "False")
/BCPExport:<value> Tells the Export, to export through BCP instead of copying MDF file. It is useful when you have a remote SQL Server. (Default is "True" since GeneXus 15 Upgrade 9)
/OutputPath:<value> Full path to the directory where the generated output file will be placed.
/help Show usage.
/version Show version.
/BatchImport Specified the Import folder contains many .zip's inside
/verbose Show full output with json when executing import command
/ReplicateKBActivity Replicate the activity of the knowledge base
/RunKbConversions Run the conversion of the knowledge bases hosted in GeneXus Server

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 should be 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 is an export operation.
  • /kb:"<Knowledge Base Name>" indicates the Knowledge Base name to be exported.
  • /out:"C:\<Destination path>" indicates the path where the zip file will be saved.

Note: During the export process the server knowledge base database will be taken offline, once the process has finished It will be brought online again.

Usage Example

C:\GeneXusServer15\VDir\Bin>gxssm.exe /e /kb:"TravelAgency" /out:"C:\Export"
gxssm v15.0.3.109723
Input:/e /kb:TravelAgency /out:C:\Export
=== Section Exporting GAM data started ===
Parameters OK.
============ Export of data started ============
SysPar export OK.
  * 2 record(s) exported from Table SysPar
Browser export OK.
  * 0 record(s) exported from Table Browser
AuditoryAction export OK.
  * 0 record(s) exported from Table AuditoryAction
OperatingSystem export OK.
  * 0 record(s) exported from Table OperatingSystem
Repository export OK.
  * 1 record(s) exported from Table Repository
RepositoryConnection export OK.
  * 1 record(s) exported from Table RepositoryConnection
RepositoryCountry export OK.
  * 0 record(s) exported from Table RepositoryCountry
AuthenticationType export OK.
  * 2 record(s) exported from Table AuthenticationType
SecurityPolicy export OK.
  * 1 record(s) exported from Table SecurityPolicy
Application export OK.
  * 1 record(s) exported from Table Application
AppEnvironment export OK.
  * 0 record(s) exported from Table AppEnvironment
AppPrmTokenType export OK.
  * 0 record(s) exported from Table AppPrmTokenType
AppRole export OK.
  * 0 record(s) exported from Table AppRole
AppMenu export OK.
  * 0 record(s) exported from Table AppMenu
AppPermission export OK.
  * 0 record(s) exported from Table AppPermission
AppPrmMemPrm export OK.
  * 0 record(s) exported from Table AppPrmMemPrm
RoleAppPrm export OK.
  * 0 record(s) exported from Table RoleAppPrm
UserMemRoles export OK.
  * 0 record(s) exported from Table UserMemRole
UserMemAppRole export OK.
  * 0 record(s) exported from Table UserMemAppRole
UserAppPrm export OK.
  * 0 record(s) exported from Table UserAppPrm
UserMemRoles export OK.
  * 1 record(s) exported from Table UserMemRole
UserMemAppRole export OK.
  * 1 record(s) exported from Table UserMemAppRole
UserAppPrm export OK.
  * 1 record(s) exported from Table UserAppPrm
User export OK.
  * 2 record(s) exported from Table User
UserRepository export OK.
  * 2 record(s) exported from Table UserRepository
RepositoryQuestionUser export OK.
  * 2 record(s) exported from Table RepositoryQuestionUser
Role export OK.
  * 4 record(s) exported from Table Role
RoleMemRole export OK.
  * 0 record(s) exported from Table RoleMemRole
Country export OK.
  * 5 record(s) exported from Table Country
City export OK.
  * 8 record(s) exported from Table City
Attraction export OK.
  * 15 record(s) exported from Table Attraction

============ Export of data ended ============
>>> Success
=== Section Exporting GAM data ended successfully ===
Taking DB 'GXS_TravelAgency_1600b0cd-d835-49ca-9b70-7317bff98681' offline...
Zipping files...
Bringing DB 'GXS_TravelAgency_1600b0cd-d835-49ca-9b70-7317bff98681' online...
KB 'TravelAgency' exported to 'C:\Export\TravelAgency.zip'

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 should be as follows:

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

Where

  • /i indicates that it is an import operation.
  • "<Zip file location\file.zip>" indicates the full path or relative path of the zip file or a folder and zip file name, it could be too a folder containing the unzipped files or the MDF and LDF or either only the MDF.

Note: If the path corresponds to a folder path, is required the parameter /batchImport to import all the .zip files in the folder to the GeneXus Server instance.

In the example above, if we use the path "C:\Export" instead of "C:\Export\TravelAgency.zip", all the .zip files (generated by the Export option) in the "C:\Export" folder will be imported.

  • /kb:"<New Knowledge Base name>" indicates the name that the Knowledge Base will have in the new GeneXus Server instance.

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

Note: for avoiding replicate activity add an extra parameter /AvoidActivityReplication 

Usage example

In this example the /ignoregam: true parameter is used to avoid processing all the security-related information (users, groups, permissions..). However, the command can be executed without it.

C:\GeneXusServer15_2\VDir\Bin>gxssm.exe /i:"C:\Export\TravelAgency.zip" /kb:"TravelAgencyNewServer" /ignoregam:true
gxssm v15.0.3.109723
Input:/i:C:\Export\TravelAgency.zip /kb:TravelAgencyNewServer /ignoregam:true
=== Section Import KB started ===
Extracting file to tmp folder 'C:\Users\<User name>\AppData\Local\Temp\ATT201701021144'
Loading GeneXus Server defaults...
Renaming database files...
Attaching database...
Starting BL...
Processing Knowledgebase 'TravelAgencyNewServer' @ 'C:\GeneXusServer15\Catalog\TravelAgencyNewServer-7bc9c176-ac4d-4c71-bec4-465449b74c06'
Adding 'TravelAgencyNewServer' to the catalog table
Processing commits for version 'TravelAgency...'
3 commits were migrated.
Processing updates for version 'TravelAgency'
2 updates were migrated.
Processing checkouts for version 'TravelAgency'
4 checkouts were migrated.
Ignoring GAM data
Knowledge base 'TravelAgencyNewServer' saved at 'C:\GeneXusServer\Catalog\TravelAgencyNewServer-7bc9c176-ac4d-4c71-bec4-465449b74c06'
=== Section Import KB ended successfully ===

 

ReplicateKBActivity

This option will generate all the activity of the knowledge base.

To Replicate Activity, use the /ReplicateKBActivity and /KBAlias parameters, the entire command should be as follows:

C:\<GeneXus Server installation path>\VDir\Bin>gxssm.exe /ReplicateKBActivity /KBAlias:"<Knowledge Base name>"

Where

  • /ReplicateKBActivity is the operation to be executed.
  • "<Knowledge Base name> "  is the name of the Knowledge Base to replicate acitivty

Note: to replicate activity for only one version of the Knowledge Base an extra parameter must be specified /VersionName:"<VersionName>".

Usage example

C:\GeneXusServer15\VDir\Bin>gxssm.exe /replicatekbactivity /kbalias:TravelAgencyNewServer
gxssm v15.0.10.122440
Input:/replicatekbactivity /kbalias:TravelAgencyNewServer
=== Section Replicating Activity for KB 'TravelAgencyNewServer' started ===
Starting BL...
Generating publish activity...
Publish activity succesfully registered.
Processing commits for version 'TravelAgencyNewServer...'
3 commits were migrated successfully.
Processing updates for version 'TravelAgencyNewServer'
2 updates were migrated successfully.
Processing checkouts for version 'TravelAgencyNewServer'
0 checkouts were migrated successfully.
=== Section Replicating Activity for KB 'TravelAgencyNewServer' 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()

See SAC#36272 for further 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



Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.