Saving packages to the database using WorkspaceConsole
Glossary Item Box
Introduction
Saving packages from the file system to the application database is performed when transferring custom packages between non-shared environments (e.g. development and test environments). Usually, packages are saved from the development environment, and loaded into the test and production environments. Learn more about saving packages in the “Exporting packages from database using WorkspaceConsole ” and “Saving SVN packages using WorkspaceConsole” articles.
To load packages to the database, run the WorkspaceConsole utility with the following parameters:
Table 1. WorkspaceConsole utility parameters for loading packages to the database
| Parameter | Value | Description |
|---|---|---|
| operation | InstallFromRepository | It saves the contents of packages from archives in the database. Bound SQL-scripts, source code regeneration, and bound data installation are performed if necessary. The InstallFromSvn and InstallFromRepository operations work with new or modified packages and their elements. |
| packageName | [Package Name] | The name of the package specified in the workspaceName configuration parameter. All dependent packages are used as well. This parameter is optional. This parameter is optional. The -clearWorkspace parameter |
| workspaceName | [Workspace name] | The name of the workspace (configuration) with the saved packages. By default, all users work in the Default workspace. |
| sourcePath | [Path to local directory] |
Path to a local directory in the file system. This directory should include the required packages in the *.gz format. |
| destinationPath | [Path to local directory] |
Path to a local directory in the file system. The packages from the directory specified in the sourcePath parameter will be saved here. |
| skipConstraints | false | The option to skip foreign key creation in database tables. Available values – true, false. |
| skipValidateActions | true | The option to skip the process of table index creation verification when updating the database structure. Available values – true or false. |
| regenerateSchemaSources | true | Indicates the need to regenerate source codes after saving the packages. Available values – true, false. |
| updateDBStructure | true | Indicates the need to update the database structure before and after saving the packages. Available values – true, false. |
| updateSystemDBStructure | true | Indicates the need to update the database structure before and after saving the packages. Creates all missing system table indexes. Available values – true, false. |
| installPackageSqlScript | true | Indicates the need to execute SQL scripts before and after saving the packages. Available values – true, false. |
| installPackageData | true | Indicates the need to install bound data before and after saving the packages. Available values – true, false. |
| continueIfError | true | Indicates the need to abort the installation process upon encountering the first error. If the parameter value is true, the user will receive the error list once the installation is complete. Available values – true, false. |
| logPath | [Path to local directory] | Path to to the operation log. The log name contains the start date and time of the operation. |
| webApplicationPath | [Path to local directory] | The bpm’online application path. This path is used by the ConnectionStrings.config file to read database connection data. If this parameter has not been indicated, the connection to the database specified in the connection string of the utility configuration file will be established. If this parameter has been indicated, the connection will be established with the database specified in the ConnectionStrings.config file of the bpm'online application. |
| configurationPath | [Path to local directory] |
Path to the Terrasoft.Configuration subfolder in the application folder. For example, C:\bpmonline7.11.1\Terrasoft.WebApp\Terrasoft.Configuration. In this folder, source codes and resources of custom package schemas are exported in the file system development mode. |
| confRuntimeParentDirectory | [Path to local directory] | Path to the parent catalog of the conf directory (see "Client static content in the file system" and "Server content in the file system"). This directory is usually located in the Terrasoft.WebApp catalog of the deployed application. |
Command signature for Windows command prompt that will export packages from the database:
[The WorkspaceConsole utility path]\Terrasoft.Tools.WorkspaceConsole.exe -packageName=[Package name] -workspaceName=Default -operation=InstallFromRepository -sourcePath=[Path to package archives] -destinationPath=[Archive extraction path] -skipConstraints=false -skipValidateActions=true -regenerateSchemaSources=true -updateDBStructure=true -updateSystemDBStructure=true -installPackageSqlScript=true -installPackageData=true -continueIfError=true -webApplicationPath=[Path to application folder] -confRuntimeParentDirectory=[Path to application folder\Terrasoft.WebApp] -logPath=[Log path]
ATTENTION
It is necessary to execute the operation BuildConfiguration after the operation InstallFromRepository (for versions above 7.11).
Operation BuildConfiguration generates static content in the file system. Uses the following parameters: -workspaceName, -destinationPath, -webApplicationPath, -logPath, -force. If the -force parameter is set to “true”, static content is generated for all schemas. If the -force parameter is set to “false”, static content is generated for modified schemas only. One of the following parameters must be specified: -webApplicationPath or -configurationPath (see: "WorkspaceConsole parameters").
ATTENTION
The WorkspaceConsole utility makes direct changes to the database, and therefore they become available only after restarting the application in IIS.
ATTENTION
Packages loaded into the application using WorkspaceConsole are considered pre-installed and can not be modified (see: "Package structure and contents").
Best practices of loading packages with enabled development mode in the file system
If the WorkspaceConsole is used for loading packages to the application with the development mode in the file system enabled (fileDesignMode=true), the installation of the packages works in a special way. Source code of the modified schemas will be modified in the database but will remain unchanged in th file system. In this regard, if you open the schema in the designer, the unchanged source code from the file system will be displayed. At the same time, the schema modification date is changed, which brings more confusion, as the schema transfer looks completed.
Due to this, it is not recommended to use the InstallFromRepository operation for transferring changes from the application with enabled development mode in the file system (fileDesignMode=true). If this operation is required, then you will need to perform the [Download packages to file system] action to upload source codes to the file system after operation is complete.
Saving packages to the database
Case description
The bpm’online application is installed in the C:\bpmonline7.12.4 directory. Save the userPackage package to the Default workspace. The package archive is located in the C:\SavedPackages directory. Extract package contents to the C:\TempPackages directory. Save the operation log file to the C:\Log directory.
Case implementation:
Use any text editor to create a batch command file (*.bat or *.cmd) with a command that will launch the WorkspaceConsole utility. Enter the following command in the file:
C:\bpmonline7.13.0\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe -packageName=sdkBookExample -workspaceName=Default -operation=InstallFromRepository -sourcePath=C:\SavedPackages -destinationPath=C:\TempPackages -skipConstraints=false -skipValidateActions=true -regenerateSchemaSources=true -updateDBStructure=true -updateSystemDBStructure=true -installPackageSqlScript=true -installPackageData=true -continueIfError=true -webApplicationPath=C:\bpmonline7.13.0 -confRuntimeParentDirectory=C:\bpmonline7.13.0\Terrasoft.WebApp -logPath=C:\Log pause
Upon saving the batch file and running it, a console window will appear, and the WorkspaceConsole execution process with specified parameter values will be displayed (Fig. 1).
Fig. 1. Saving a package to the application database
Run the command to load the sdkBookExample package to the Default configuration.
Fig. 2. The package in the [Configuration] section
