Delivery in WorkspaceConsole

Medium
PDF

Creatio provides various tools for functionality delivery.

The delivery management tools are as follows:

  • Creatio IDE
  • WorkspaceConsole utility

This article covers supply management using the WorkspaceConsole utility.

WorkspaceConsole is a utility for operations with Creatio packages and schemas of configuration elements (client modules, objects, and source code (C#).

The WorkspaceConsole utility provides the following solution transfer options:

  • Transfer packages and configuration element schemas between environments and configurations.
  • Install new packages when updating or when exporting from a development environment.
  • Transfer package-related data, such as the lookup content, new system settings, demo section records, etc.
  • Transfer localizable resources.
  • Create and transfer workspaces between environments.

WorkspaceConsole on .NET Framework 

Set up the WorkspaceConsole utility before using it.

Set up the WorkspaceConsole utility 

  1. Find out the relevant connection string value.

    To do this, open the ..\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe.config file. The connectionStringName attribute of the <db> XML element contains the connection string.

    Terrasoft.Tools.WorkspaceConsole.exe.config file
    <terrasoft>
    ...
    <db>
        <general connectionStringName="db" securityEngineType="Terrasoft.DB.MSSql.MSSqlSecurityEngine, Terrasoft.DB.MSSql" ... />
    </db>
    ...
</terrasoft>

  2. Edit the connection string.

    To do this, open the ConnectionStrings.config file in the Creatio root directory. The name attribute of the <connectionStrings> XML element contains the connection string. The value of the name attribute in the ConnectionStrings.config file must match the value of the connectionStringName attribute in the Terrasoft.Tools.WorkspaceConsole.exe.config file.

    ConnectionStrings.config file
    <connectionStrings>
    <add name="db" connectionString="Data Source=dbserver\MSSQL2016; Initial Catalog=YourDBName; Persist Security Info=True; MultipleActiveResultSets=True; Integrated Security = true; Pooling = true; Max Pool Size = 100" />
    <add name="dbOracle" connectionString="Data Source=(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = dbOracleServer.yourdomain.com)(PORT = 1521))) (CONNECT_DATA = (SERVICE_NAME = TSOra10) (SERVER = DEDICATED)));User Id=CreatioUser;Password=CreatioUserPassword;" />
</connectionStrings>

    The configuration file has the following connection string types set up:

    • "db" string. Required to connect to the Microsoft SQL server database.
    • "dbOracle" string. Required to connect to the Oracle database.

    To perform a one-time operation with WorkspaceConsole, run the utility with the -webApplicationPath parameter. Specify the path to the Creatio directory in this parameter. In this case, the utility independently determines all necessary database connection settings from the ConnectionStrings.config file. However, the connection parameters in the Terrasoft.Tools.WorkspaceConsole.exe.config file are ignored.

  3. Enable downloading from remote sources. To do this, set the enabled attribute of the loadFromRemoteSources element in the Terrasoft.Tools.WorkspaceConsole.exe.config file to true.

    <loadFromRemoteSources enabled="true" />

  4. Install the WorkspaceConsole utility.

    To do this, run a preinstalled batch command file in the ..\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\ directory as an administrator. This is required to install the executable file version and libraries the utility uses.

    Batch files of the WorkspaceConsole utility commands:

    • For 32-bit operating systems, run the PrepareWorkspaceConsole.x86.bat file.
    • For 64-bit operating systems, run the PrepareWorkspaceConsole.x64.bat file.

  5. Configure the utility to perform operations on the SVN repository (optional).

    To do this, copy the SharpPlink-x64.svnExe, SharpSvn.dll, and SharpSvn-DB44-20-x64.svnDll files from the appropriate directory to the ...\Terrasoft.WebApp\DesktopBin\WorkspaceConsole directory.

    • For 32-bit operating systems, copy the files from the ...\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\x86 directory.
    • For 64-bit operating systems, copy the files from the ...\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\x64 directory.

Transfer solutions 

The Terrasoft.Tools.WorkspaceConsole.exe executable file of the utility is located in the ..\Terrasoft.WebApp\DesktopBin\WorkspaceConsole directory. The utility version matches the Creatio version.

Attention. The WorkspaceConsole utility version must match the Creatio version. For example, if the current Creatio version is 7.18.1.1794, and you need to update the packages to version 7.18.2.1658, use WorkspaceConsole version 7.18.2.1658. To obtain the relevant version of the utility, contact support.

WorkspaceConsole works directly with the Creatio database. Thus, specify the database information in the Terrasoft.Tools.WorkspaceConsole.exe.config utility configuration file to ensure the utility works properly. If you deploy Creatio in the cloud, only employees of the cloud service department can work with the utility. In this case, contact support to transfer the changes.

We recommend preparing the WorkspaceConsole commands in a batch file (*.bat or *.cmd) created in a text editor.

To transfer solutions using the WorkspaceConsole utility:

  1. Check data bindings.
  2. Back up the database.
  3. Export packages.
  4. Import packages.
  5. Restart Creatio in IIS.

1. Check data bindings 

Before exporting the package, check that the data is bound to the package correctly. Bound data includes lookup values, new system settings, demo section records, etc.

If you create a section in the Section Wizard, the Wizard automatically binds the data required for the section to work. To ensure Creatio displays the section in the workplace after the import, bind the corresponding value of the SysModuleInWorkplace object.

2. Back up the database 

Before you implement the changes in Creatio using the WorkspaceConsole utility, back up the database. This lets you restore Creatio if the utility commands and parameters are used incorrectly.

3. Export packages 

Use the WorkspaceConsole utility to export a package from the database or SVN repository.

Export packages from the database 

  1. Configure the command to export packages from the database.

    Run the command to export packages from the database at the Windows command interpreter (console). Structure the command as follows:

    [Path to WorkspaceConsole]\Terrasoft.Tools.WorkspaceConsole.exe -operation=SaveDBContent -contentTypes=Repository -workspaceName=[Workspace name] -destinationPath=[Path to a local directory] -webApplicationPath=[Path to the Creatio directory] -configurationPath=[Path to a local directory]
    WorkspaceConsole parameters for exporting packages
    Parameter
    Value
    Description
    -operation
    SaveDBContent

    Saves the database content to the file system. The -contentTypes parameter determines the content type. The -destinationPath parameter determines the content export path in the file system.

    Requires either the -webApplicationPath or -configurationPath parameter.
    -contentTypes
    Repository
    		 The type of content exported from the database to the drive. If set to Repository, the utility exports the workspace specified in the -workspaceName parameter to the directory specified in the -destinationPath parameter.
    -workspaceName
    Workspace name
    		 The name of the workspace (configuration) where the operation is performed. By default, all users work in the Default workspace.
    -destinationPath
    Path to a local directory
    		 Path to a local directory. The utility exports the *.gz package archives to this directory.
    -webApplicationPath
    Path to a local directory
    		 Path to the Creatio installation directory. The utility follows this path to fetch the database connection information from the ConnectionStrings.config file. If you omit this parameter, the utility connects to the database specified in the connection string in the utility’s configuration file.
    -configurationPath
    Path to a local directory
    		 Path to the ..\Terrasoft.WebApp\Terrasoft.Configuration directory. The utility exports the source code and resources of custom package schemas to this directory in the file system development mode.
  2. Run the utility.

Note. The package export operation exports all packages of the workspace. The process may take several dozen minutes.

As a result, the utility will export the workspace package archives to the local directory.

Export packages from the SVN repository 

  1. Configure the command to export packages from SVN.

    Run the command to export packages from the SVN repository at the Windows command interpreter (console). Structure the command as follows:

    [Path to WorkspaceConsole]\Terrasoft.Tools.WorkspaceConsole.exe -operation=SaveVersionSvnContent -workspaceName=[Workspace name] -destinationPath=[Path to a local directory] -workingCopyPath=[Path to a local directory] -sourcePath=[Path to the SVN repository] -packageName=[Package name] -packageVersion=[Package version] -sourceControlLogin=[SVN username] -sourceControlPassword=[SVN user password] -cultureName=[Language culture] -excludeDependentPackages=true -logPath=[Path to a local directory]
    WorkspaceConsole parameters for exporting packages
    Parameter
    Value
    Description
    -operation
    SaveVersionSvnContent
    		 Downloads the package hierarchy as a set of *.zip archives. The -destinationPath parameter determines the content export path in the file system. The -sourcePath parameter determines the SVN repositories.
    -workspaceName
    Workspace name
    		 The name of the workspace (configuration) where the operation is performed. By default, all users work in the Default workspace.
    -destinationPath
    Path to a local directory
    		 Path to a local directory. The utility exports the *.gz package archives to this directory.
    -workingCopyPath
    Path to a local directory
    		 The local directory for the working copies of packages stored in SVN.
    -sourcePath
    Path to the SVN repository
    		 The address of the SVN repository that stores the package structure and metadata. Can accept multiple values separated by commas.
    -packageName
    Package name
    		 The name of the package from the source SVN repository. The utility downloads the packages on which the current package depends as well.
    -packageVersion
    Package version
    		 The version of the package from the source SVN repository.
    -sourceControlLogin
    SVN username
    		 SVN user login.
    -sourceControlPassword
    SVN user password
    		 SVN user password.
    -cultureName
    Language culture
    		 Language culture code. For example, en-US.
    -excludeDependentPackages
    true or false
    		 The flag that specifies whether to export packages on which the package listed in the -packageName parameter depends.
    -logPath
    Path to a local directory
    		 The utility saves the operation log file to this directory. The file name consists of the operation start date and time. Optional.
  2. Run the utility.

As a result, the utility will export the workspace package archives to the local directory.

4 Import packages 

  1. Configure the command to import packages into the database.

    Run the command to import packages into the database at the Windows command interpreter (console). Structure the command as follows:

    [Path to WorkspaceConsole]\Terrasoft.Tools.WorkspaceConsole.exe -operation=InstallFromRepository -packageName=[Package name] -workspaceName=[Workspace name] -packageName=[Package name] -sourcePath=[Path to a local directory] -destinationPath=[Path to a local directory] -skipConstraints=false -skipValidateActions=true -regenerateSchemaSources=true -updateDBStructure=true -updateSystemDBStructure=true -installPackageSqlScript=true -installPackageData=true -continueIfError=true  -webApplicationPath=[Path to a local directory] -confRuntimeParentDirectory=[Path to a local directory] -logPath=[Path to a local directory] -configurationPath=[Path to a local directory]
    WorkspaceConsole parameters for importing packages
    Parameter
    Value
    Description
    -operation
    InstallFromRepository

    Imports the package content and metadata from *.zip archives into the configuration. If needed, the utility runs bound SQL scripts, re-generates source code, installs bound data. Works only with updated or new packages and their elements. Requires either the -webApplicationPath or -configurationPath parameter.

    Also requires the -confRuntimeParentDirectory parameter.
    -packageName
    Package name
    		 The package name in the configuration specified in the -workspaceName parameter. The utility downloads the packages on which the current package depends as well. If you omit the parameter, the utility downloads all packages of the configuration.
    -workspaceName
    Workspace name
    		 The name of the workspace (configuration) where the operation is performed. By default, all users work in the Default workspace.
    -sourcePath
    Path to a local directory
    		 Path to a local directory. The directory must contain the *.gz package archives to install.
    -destinationPath
    Path to a local directory
    		 Path to a local directory. The utility exports the *.gz package archives specified in the -sourcePath parameter to this directory.
    -skipConstraints
    false
    		 Skips the creation of foreign keys in database tables. Can be true or false.
    -skipValidateActions
    true
    		 Skips checking if table indexes can be created when updating the database structure. Can be true or false.
    -regenerateSchemaSources
    true
    		 Specifies whether to re-generate the source code after saving the packages to the database. Can be true or false. The default value is true.
    -updateDBStructure
    true
    		 Specifies whether to update the database structure after saving the packages. Can be true or false. The default value is true.
    -updateSystemDBStructure
    true
    		 Specifies whether to modify the structure of the system schema database before installing the packages. Also creates the missing indexes in the system tables. Can be true or false.
    -installPackageSqlScript
    true
    		 Specifies whether to run the SQL scripts before and after saving the packages. Can be true or false. The default value is true.
    -installPackageData
    true
    		 Specifies whether to install the bound package data after saving the packages. Can be true or false. The default value is true.
    -continueIfError
    true
    		 Specifies whether to abort the installation after encountering the first error. If set to true, the installation process goes through to the end. You will receive the list of the errors encountered. Can be true or false. The default value is false.
    -webApplicationPath
    Path to a local directory
    		 Path to the Creatio installation directory. The utility follows this path to fetch the database connection information from the ConnectionStrings.config file. If you omit this parameter, the utility connects to the database specified in the connection string in the utility’s configuration file.
    -confRuntimeParentDirectory
    Path to a local directory
    		 Path to the parent directory of the ..\Terrasoft.WebApp\conf directory.
    -logPath
    Path to a local directory
    		 The utility saves the operation log file to this directory. The file name consists of the operation execution date and time. Optional.
    -configurationPath
    Path to a local directory
    		 Path to the ..\Terrasoft.WebApp\Terrasoft.Configuration directory. The utility exports the source code and resources of custom package schemas to this directory in the file system development mode.
  2. Run the utility.

  3. Configure the command to generate the static content in the file system.

    Run the command to generate the static content in the file system at the Windows command interpreter (console). Structure the command as follows:

    [Path to WorkspaceConsole]\Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=[Workspace name] -destinationPath=[Path to a local directory] -webApplicationPath=[Path to a local directory] -confRuntimeParentDirectory=[Path to a local directory] -logPath=[Path to a local directory]
    WorkspaceConsole parameters for generating the static content
    Parameter
    Value
    Description
    -operation
    BuildConfiguration

    Generates the static content in the file system.

    Requires either the -webApplicationPath or -configurationPath parameter.
    -workspaceName
    Workspace name
    		 The name of the workspace (configuration) where the exported packages are specified. By default, all users work in the Default workspace.
    -destinationPath
    Path to a local directory
    		 Path to a local directory. The utility exports the *.gz package archives specified in the -sourcePath parameter to this directory.
    -webApplicationPath
    Path to a local directory
    		 Path to the Creatio installation directory. The utility follows this path to fetch the database connection information from the ConnectionStrings.config file. If you omit this parameter, the utility connects to the database specified in the connection string in the utility’s configuration file.
    -confRuntimeParentDirectory
    Path to a local directory
    		 Path to the parent directory of the ..\Terrasoft.WebApp\conf directory.
    -logPath
    Path to a local directory
    		 The utility saves the operation log file to this directory. The file name consists of the operation start date and time. Optional.
    -force
    true or false

    Sets the conditions of the file content generation If set to true, the utility generates the file content for all schemas. If set to false, the utility generates the file content for updated schemas. The default value is false.

    Requires either the -webApplicationPath or -configurationPath parameter.
    -configurationPath
    Path to a local directory
    		 Path to the ..\Terrasoft.WebApp\Terrasoft.Configuration directory. The utility exports the source code and resources of custom package schemas to this directory in the file system development mode.
  4. Run the utility.

Note. Creatio considers packages imported using the WorkspaceConsole as preinstalled. You cannot modify them.

We do not recommend using the WorkspaceConsole utility for importing packages into the database if the file system development mode is enabled. If you use the utility, it modifies the schema source code in the database but not in the file system. As such, if you open the configuration element schema in Creatio IDE, the schema will contain unmodified code from the file system. However, the modification date of the configuration element schema will be updated. This will make the schema falsely appear to have transferred correctly.

To import packages into the database when the file system development mode is enabled:

  1. Use the WorkspaceConsole utility to import packages into the database. To do this, follow this guide: 4. Import packages.
  2. Select Download packages to the file system in the File system development mode action group on the toolbar.

As a result, Creatio will download all packages to the ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg path as a set of directories that match package names.

5. Restart Creatio in IIS 

Restart Creatio in IIS to apply the changes. This is required since the WorkspaceConsole utility makes changes directly in the database.

WorkspaceConsole on .NET Core 

You can use the WorkspaceConsole utility to generate and compile Creatio .NET Core.

To generate and compile Creatio .NET Core:

  1. Edit the connection string.

    To do this, open the Terrasoft.Tools.WorkspaceConsole.dll.config file in the ..\WorkspaceConsole directory. The name attribute of the <connectionStrings> XML element contains the connection string. The "db" string in the Terrasoft.Tools.WorkspaceConsole.dll.config file must match the corresponding string in the ConnectionStrings.config file.

    Terrasoft.Tools.WorkspaceConsole.dll.config file
    <connectionStrings>
   ...
    <add name="db" connectionString="Pooling=true; Database=7.18.4(netcore); Host=; Port=5432; Integrated Security=true; Username=; Timeout=5; CommandTimeout=400" />
    ...
</connectionStrings>

    "db" string is required to connect to the Microsoft SQL Server database.

  2. Open the command line and go to the ..\WorkspaceConsole directory. To do this, run the command below.

    cd [Path to the WorkspaceConsole directory]

  3. Configure commands to generate and compile Creatio .NET Core.

    Run commands to generate and compile Creatio .NET Core at the command interpreter (console) sequentially. Structure the commands as follows:

    dotnet Terrasoft.Tools.WorkspaceConsole.dll -operation=RegenerateSchemaSources -workspaceName=Default -configurationPath=[Path to a local directory] -confRuntimeParentDirectory=[Path to a local directory] -logPath=[Path to a local directory]

dotnet Terrasoft.Tools.WorkspaceConsole.dll -operation=RebuildWorkspace -workspaceName=Default -configurationPath=[Path to a local directory] -webApplicationPath=[Path to a local directory] -confRuntimeParentDirectory=[Path to a local directory] -logPath=[Path to a local directory]

dotnet Terrasoft.Tools.WorkspaceConsole.dll -operation=BuildConfiguration -force=True -workspaceName=Default -configurationPath=[Path to a local directory] -destinationPath=[Path to a local directory] -confRuntimeParentDirectory=[Path to a local directory] -logPath=[Path to a local directory]
    WorkspaceConsole parameters for generating and compiling Creatio .NET Core
    Parameter
    Value
    Description
    -operation
    RegenerateSchemaSources

    Re-generates the source code and compiles it.

    Requires the -confRuntimeParentDirectory parameter.
    ReBuildWorkspace

    Recompiles the workspace (configuration). Use when developing schemas in Visual Studio.

    Requires the -confRuntimeParentDirectory parameter.
    BuildConfiguration

    Generates the static content in the file system.

    Requires either the -webApplicationPath or -configurationPath parameter.
    -workspaceName
    Workspace name
    		 The name of the workspace (configuration). By default, all users work in the Default workspace.
    -configurationPath
    Path to a local directory
    		 Path to the ..\Terrasoft.Configuration directory. The utility exports the source code and resources of custom package schemas to this directory in the file system development mode.
    -confRuntimeParentDirectory
    Path to a local directory
    		 Path to the Creatio parent directory.
    -logPath
    Path to a local directory
    		 The utility saves the operation log file to this directory. Optional.
    -webApplicationPath
    Path to a local directory
    		 Path to the Creatio installation directory. The utility follows this path to fetch the database connection information from the ConnectionStrings.config file. If you omit this parameter, the utility connects to the database specified in the connection string in the utility’s configuration file.
    -force
    True or False

    Sets the conditions of the file content generation If set to True, the utility generates and compiles the source code for all schemas. If set to False, the utility generates and compiles the source code for updated schemas.

    Requires either the -webApplicationPath or -configurationPath parameter.
    -destinationPath
    Path to a local directory
    		 Path to a local directory. The utility exports the *.gz package archives to this directory.
See also
Packages basics
Client module
Object
Source code (C#)
Environments
External IDEs. Visual Studio
Packages file content