Ewimpex is a command line utility that allows you to list, backup and restore any or all knowledgebases (KBs) from the database. It is not necessary for the  Agiloft application server, such as JBoss, to be running when you execute this command, so you can turn off access to the system during exports and imports. Ewimpex is included in the installation files on the server.

Usage

The ewimpex utility has three commands: kblist, backup, and restore. Each command is described below.

kblist

The kblist command outputs a list of all available KBs in the database, one KB per line. Each line contains a tab-separated (\t) knowledgebase ID and name. For example: 

1 Demo
    2 Test KB
    3 Production KB

backup

The backup command exports selected KBs to a specified folder or a new backup.

To use this command, you must also enter at least one of these parameters:

• k [KB List]. Use k when you want to back up several KBs at once. Enter -k and then enter a comma-delimited list of KBs you want to back up, using the KB name. For example, enter -k Demo,Tickets,Support to back up three KBs named Demo, Tickets, and Support, respectively.
• a. Use a to back up all available KBs, including the admin KB. If you enter -a along with a -k list, the list is ignored and all KBs are backed up.
• o. Use o to specify a folder where you want to save the KB backups. If you don't use this parameter, the utility creates a folder named backup inside the current working directory, and saves the backup files there.
• b. Use b to back up damaged KBs as well. KBs are flagged as damaged when the projecttype is greater than 1.
• s. Use s to do a strict backup and receive the 0 exit code only if all existing KBs were saved successfully.
• y. Use y to strip history and communication data.
• z. Use z to strip attached files.
• Z. Use Z to strip attached files, history, and communication data.

You must enter "-" before the parameter letter when you use it with the backup command. KBs are saved using the original file names and the .xml.zip extension. All non-standard characters in file names are automatically replaced by "_".

restore

The restore command restores selected knowledgebases from existing backups, created either by this utility or the Agiloft interface.

To use this command, you must also enter at least one of these parameters:

• f. Specify the file name you want to restore. For example, enter -f MyKB.xml.zip to restore a KB from the file MyKB.xml.zip.
• a. Use a to restore all KB files found in the specified folder. If you use -a with -f, -f is ignored.
• s. Use s to skip the admin KB if it exists in the restore list. This is typically used in conjunction with -a.
• r. Use r to overwrite system tables during the import, using the tables in the backup file.
• x. Use x to disable patching. This is useful when importing a KB without the application server running, such as JBoss. If this is used, the imported KBs are patched the next time the application server starts.

If you are restoring a KB that already exists, ewimpex adds a prefix to the restored knowledgebase in order to avoid naming conflicts. For example, if you have a Demo knowledgebase installed and are restoring another Demo knowledgebase from the file, the restored knowledgebase is named 0_Demo. After restoration, you can log in to  Agiloft as an administrator and rename or delete unneeded copies of the databases.

Common Options

In addition to the command-specific options listed above, there are several options that specify the database parameters and are common to all commands. If none of these options are set, ewimpex finds and uses the  Agiloft installation data, so you need to use these options only when they differ from the installation data.

These options are common to all the commands:

• w. Specifies the path to the installation folder, if auto-detection fails.
• d. Specifies the type of database. Enter mysql, db2, or mssql.
• h. Specifies the IP address of the database server you need to connect with. 127.0.0.1 is used by default.
• P. Specifies the port number for the database. The database-specific default port value is used if no value is set.
• H. Specifies both the database server IP and the port number, so you can set h and P at once. For example, -H localhost:3306 sets the database server IP to localhost and the port to 3306.
• u. Specifies the username to use to log in to the database.
• p. Specifies the password to use to log in to the database.
• n. Specifies the database name to connect to. The default name is sw2_std.
• v. Turns on debugging output, which sends additional information to the console. This is used only to investigate problems or generate a bug report for developers to investigate.

Error Codes

On success, ewimpex returns a zero value. On error, the system provides an error message and returns a negative error code. These include:

• -1. Database connection problems.
• -2. Invalid parameters set.
• -3. Invalid database structure.
• -4. Internal error during import or export.
• -5. Specified KB file is invalid or damaged.
• -6. Specified KB is not an admin KB.

Errors -7 to -999 are unspecified, unexpected errors.

Use Cases and Examples

Here are some example uses of the utility. In these examples and in practice, you can replace the letter with the name of the parameter preceded by a hyphen. For example, -a and --all are interpreted the same way by the utility. The examples below include the full parameter name so you don't need to refer back to the lists above.

Get a list of all installed knowledgebases

• On Windows from INSTALL_DIR\bin\ run: 
  

  • ewimpex kblist 

• On Linix/Unix from INSTALL_DIR/bin/ run:

  • ./ewimpex kblist

Export all knowledgebases into a folder

• On Windows from INSTALL_DIR\bin\ run:

  • ewimpex backup --all --output C:\backups

• On Linux/Unix from INSTALL_DIR/bin/ do:

  • ./ewimpex backup --all --output ~/backups

Export one knowledgebase

• On Windows from INSTALL_DIR\bin\ run:

  • ewimpex backup --kbases Demo --output C:\demos 

• On Linux/Unix from INSTALL_DIR/bin/ run:

  • ./ewimpex backup --kbases Demo --output ~/demos

Export a list of knowledgebases

• On Windows from INSTALL_DIR\bin\ run:

  • ewimpex backup --kbases Demo,MyCRM --output C:\MyKB 

• On Linux/Unix from INSTALL_DIR/bin/ run:

  • ./ewimpex backup --kbases Demo,MyCRM --output ~/MyKB

Import all knowledgebases from a folder to  Agiloft system

Existing knowledgebases will not be overwritten.

• On Windows from INSTALL_DIR\bin\ run:

  • ewimpex restore --all C:\backups 

• On Linux/Unix from INSTALL_DIR/bin/ run:

  • ./ewimpex restore --all ~/backups

Import one knowledgebase

• On Windows from INSTALL_DIR\bin\ run:

  • ewimpex restore --file c:\MyCRM.xml.zip 

• On Linux/Unix from INSTALL_DIR/bin/ run:

  • ./ewimpex restore --file ~/MyKB/MyCRM.xml.zip

Reset the admin console password

• On Windows from INSTALL_DIR\bin\ run:

  • ewimpex reset-admin-console -p <new_password>

• On Linux/Unix from INSTALL_DIR/bin/ run:

  • ./ewimpex reset-admin-console -p <new_password>