Using Command Line Utilities
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.
When running ewimpex commands, make sure to run them with root privileges. For Windows, open the Command prompt as an administrator.
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]
. Usek
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
. Usea
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
. Useo
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
. Useb
to back up damaged KBs as well. KBs are flagged as damaged when the projecttype is greater than 1.s
. Uses
to do a strict backup and receive the 0 exit code only if all existing KBs were saved successfully.y
. Usey
to strip history and communication data.z
. Usez
to strip attached files.Z
. UseZ
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
. Usea
to restore all KB files found in the specified folder. If you use-a
with-f
,-f
is ignored.s
. Uses
to skip the admin KB if it exists in the restore list. This is typically used in conjunction with-a
.r
. User
to overwrite system tables during the import, using the tables in the backup file.x
. Usex
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 seth
andP
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.
When running ewimpex commands, make sure to run them with root privileges. For Windows, open the Command prompt as an administrator.
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>