Transferring changes using WorkspaceConsole
Glossary Item Box
Introduction
The WorkspaceConsole utility is designed to work with bpm'online packages. Use the utility to:
- Export packages from development environments and migrate them to test environments or production environments (the packages are saved as archives).
- Install new packages when upgrading or migrating from development environments.
- Export and import localization resources of schemas.
- Create and migrate between workspace applications.
- Work with configuration schemas.
ATTENTION
Bpm'online production environments that actively run business processes should not be updated during business hours. Updating production environments during business hours may cause loss of data.
First, you must set up the WorkspaceConsole before start working with it. The setup procedure is described in the “WorkspaceConsole settings” article.
NOTE
WorkspaceConsole needs access to the bpm’online database. If the application is deployed in the cloud, then only employees of the cloud services department are able to work with the WorkspaceConsole utility. Please contact the support if you need to transfer changes to a cloud application.
Benefits of transferring changes via the WorkspaceConsole
- Ability to transfer both the schemas and packages between working environments and configurations.
- Ability to transfer package data, such as lookup or section records.
- Ability to work separately with localization resources, bound data and SQL scripts.
The recommended steps for transferring changes via WorkspaceConsole
1. Check the data binding.
Be sure to check data binding before exporting packages. These data include: system settings, lookups, section filling, etc.
ATTENTION
If the section was created via the section wizard, then the data necessary for its work are bound to the corresponding package automatically. However, for the section to be displayed in the workplace after import, you must bind the corresponding value of the SysModuleInWorkplace object.
2. Backup the application database where you want to transfer the changes
You need to back up the database before updating the application with the WorkspaceConsole. If you use WorkspaceConsole commands incorrectly, the data could be damaged or lost.
3. Export the packages from the application database that contains the changes to transfer
To export the packages from the database, you need to run the WorkspaceConsole with the following parameters (table 1):
Table 1. WorkspaceConsole parameters for exporting database packages
| Parameter | Value | Description |
|---|---|---|
| operation | SaveDBContent |
Saves the contents of database to the file system. The content type is determined by the contentTypes parameter value. The destinationPath parameter determines where to export the contents in the file system. |
| contentTypes | Repository | The database content type to be exported. The Repository value specifies that a workspace (with the name specified in the workspaceName parameter) must be exported to a specific directory (specified by the destinationPath parameter). |
| workspaceName | [Workspace name] | Workspace (configuraion) name where uploaded packages are defined. All users work in the Default workspace by default. |
| destinationPath | [Path to local directory] |
A path to local directory in the file system. The packages archived in *.gz format will be will be exported to this directory. |
An example of a database export command for the Windows command prompt:
[Path to WorkspaceConsole]\Terrasoft.Tools.WorkspaceConsole.exe -operation=SaveDBContent -contentTypes=Repository -workspaceName=[Workspace name] -destinationPath=[Path to local directory]
After you run this command, the archives of all packages from the specified workspace will be exported into the local directory.
NOTE
Use text editor (such as Windows notepad) to create a batch file (* .bat) with the necessary command in it.
4. Import the packages to the application where the changes must be transferred
To import the database packages, run the WorkspaceConsole with the following parameters (table 2):
Table 2. WorkspaceConsole parameters for database packages load
| Parameter | Value | Description |
|---|---|---|
| operation | InstallFromRepository | Imports the contents of packages from archives to the database. The bound SQL-scripts, source code generation and installation of bound data are performed if needed. Operation works only with new or modified packages and their elements. |
| packageName | [Package name] | Name of a package from the configuration specified in workspaceName parameter. Note that all the packages that the specified package depends on will be installed as well. Optional parameter. If it is not specified, then all packages from the configuration will be imported. |
| workspaceName | [Workspace name] | Workspace (configuraion) name where installed packages are defined. All users work in the Default workspace by default. |
| sourcePath | [Path to local directory] |
A path to a local directory in the file system. The directory must contain the package archives for importing (*.gz files). |
| destinationPath | [Path to local directory] |
A path to local directory in the file system. Packages from the directory determined in sourcePath parameter will be unpacked here. |
| skipConstraints | false | The option to skip creating foreign keys in the database tables. Can be true or false. |
| skipValidateActions | true | The option to skip checking for possibility of the creating table indexes during the database structure update. Can be true or false. |
| regenerateSchemaSources | true | Indicates the need to regenerate the source code after saving the packages in the database. Can be true or false. |
| updateDBStructure | true | Indicates the need of modify the database structure after the package installation. Can be true or false. |
| updateSystemDBStructure | true | Indicates the need to modify the structure of the system schema database before the package installation. Also creates all missing indexes in the system tables. Can be True or false. |
| installPackageSqlScript | true | Indicates the need to run SQL scripts before and after package installation. Can be True or false. |
| installPackageData | true | Indicates the need to install the data bound to the packages after the package installation. Can be True or false. |
| continueIfError | true | Indicates the need of interrupt or resume the installation on the first error. If this parameter is set to true, the installation process will continue, even if errors are detected. The user will receive the list of errors after the installation. Can be True or false. |
| logPath | [Path to local directory] | A path to the directory where the log of the completed operation will be created. The file name consists of the date and time of the operation launch. |
An example of a package installation command for the Windows command prompt:
[Path to WorkspaceConsole] -packageName=UsrCustomAuto -workspaceName=Default -operation=InstallFromRepository -sourcePath=[Path to package archives] -destinationPath=[Package extraction path] -skipConstraints=false -skipValidateActions=true -regenerateSchemaSources=true -updateDBStructure=true -updateSystemDBStructure=true -installPackageSqlScript=true -installPackageData=true -continueIfError=true -logPath=[Path to the logs]
5. Restart the application in IIS
The modifications are made by the WorkspaceConsole utility directly into the database and therefore are not available for any application that is already running. Restart the application in IIS for the changes to take effect.
