Update guide
This guide covers the process of updating Creatio application to the latest available version. Our team at Creatio is constantly working to deliver advanced capabilities to automate your sales, service and marketing processes. You can learn more about the new features included in the Creatio latest version in the release notes.
If you are using version 7.11.0 and lower, contact Creatio technical support for further instructions.
How to update
We recommend updating in two stages:
- First, perform the update on a pre-production website using a copy of your current Creatio database.
- If the first stage completes successfully, perform the update of the production Creatio website of the application.
Carry out the update of the production version outside of business hours, as the site will be unavailable.
The update process consists of the following steps:
- Copy the database and the binary files of the production website that will be required to deploy the pre-production website. To back up the binary files, archive them in any other directory. Learn more: Back up database.
- Create a new pre-production website in IIS. Learn more: General Creatio deployment procedure.
- Install the update into the pre-production website. Learn more: Installing updates.
- Verify that the pre-production website is fully operational. If the primary and frequently used functionality runs without errors, you can begin updating the production website. Learn more: Maintain Creatio website in IIS.
- Create copies of the database and application. You will need them to return to a working version in case of problems. Learn more: Back up database.
- Install the update into the production website. Learn more: Installing updates.
- Verify that the updated version is operational. Learn more: Maintain Creatio website in IIS.
Install updates
To install the update:
- Prepare system to update. Read more >>>
- Get artifacts for update. Read more >>>
- Run Updater. Read more >>>
- Complete the update. Read more >>>
1. Prepare system to update
Before proceeding with the update, verify the following software for availability and compliance with the specified versions:
- .NET SDK – 8.0.404 or later, x64 (for all applications; required on the server where you run the update utility). Download .NET 8 SDK
- .NET Core – minimum 3.1 (only for .NET Core applications). Download .NET Core SDK 3.1 x64
- .NET Framework – minimum 4.7.2 (only for .NET Framework applications). Download .NET Framework 4.7.2. Download Developer pack
- Microsoft Visual C++ 2015-2022 Redistributable (x64) – version 14.51.36247 or later (only for .NET Framework applications). The update utility compares the installed version with the version Creatio currently requires; newer builds are accepted. Download the latest supported Visual C++ Redistributable
- Internet Information Services – minimum 10.0 (only if IIS hosting is used)
- Redis Server – minimum 6.4
- For corresponding Database Management System:
- Microsoft SQL Server – minimum 2016
- PostgreSQL – minimum 16.0
Learn more: Server-side system requirements and Requirements calculator.
If your Creatio instance has installed cultures that are not used by company employees, we recommend removing these cultures before starting the update. This reduces the amount of data that needs to be downloaded as part of the update. Learn more: Clean up the drive space.
Also, before starting the update, go to the Configuration section and run the Generate source code for all items action, then run the Compile all items action. If taking these steps causes any errors, fix them before starting the update.
The update utility checks the result of the last compilation before it starts the update. If the compilation history contains errors, the update stops and the utility saves the errors to the "#Updater#/artifacts/CompilationErrors-yyyyMMddTHHmmss.txt" file. Fix the errors, compile the application again, and restart the update.
2. Get artifacts for update
The distribution downloading service (Downloader) and the update utility (Updater) are now combined into a single utility.
- Get the update utility: download Updater.zip.
- Unpack the archive to a folder on the application server outside of the website folder, for example, "C:\Creatio\Updater". This folder is referred to as "#Updater#" below.
You need a Nexus account to download the update packages. If you do not have an account, contact Creatio support.
When your application server is not connected to the Internet
You need a machine that is connected to the Internet and has .NET 8 installed to download the update packages. Unpack the "Updater.zip" archive on that machine and follow the instructions below up to and including step 4 on that machine. After you complete step 4, switch to the application server.
- Open the creatio.json file from the "#Updater#" folder to edit. Fill out its parameters with the corresponding values. Keep the parameters you do not need at their default values.
Parameter | Value |
|---|---|
| Path to the website root folder. |
| Path to the directory where the update packages will be downloaded. The utility creates the "InstallPackages" subfolder in it. |
| Path to the folder with the update packages. Must point to the "InstallPackages" subfolder of |
| Name of your website in IIS. If not specified, the name of the website root folder is used. |
| Name of the product where the website is deployed. Studio |
| Current version of your application, for example, "8.2.1". You can leave the value empty if |
| Optional. The version up to which to update, for example, "8.2.3". Leave the value empty to update to the latest available version. |
| Optional. Keep the empty list unless Creatio support instructs you otherwise. |
| Type of the application. NetFramework The legacy value "NetCore" is still accepted and treated as "Net". |
| Type of the hosting, one of the values: IIS |
| Ports of the Kestrel process, comma-separated, for example, "5000,5002" (only for Kestrel hosting). |
| Type of the DBMS. MSSQL |
| Database connection string. Copy this string from the "ConnectionStrings.config" file of your website. |
| Current database schema. for MS SQL – "dbo" |
| Redis server. |
| The number of Redis database. |
| Redis port. |
| Redis password. Leave empty if Redis has no password. |
| Database connection timeout of the WorkspaceConsole utility, in seconds. Keep the default value of "1024". |
| Nexus username (login). |
| Nexus password. |
| Parameters of the built-in backup. They are used only if Creatio support instructs you to enable the automatic backup. Keep the default values. |
Example of a "creatio.json" file for a .NET Framework website hosted in IIS on a server connected to the Internet:
{
"WebRootDirectory": "C:\\inetpub\\wwwroot\\creatio",
"WorkDirectory": "C:\\temp\\delivery",
"InstallPackagesPath": "C:\\temp\\delivery\\InstallPackages",
"Product": "Studio",
"Site": "creatio",
"ConnectionString": "Data Source=dbserver; Initial Catalog=creatio; Integrated Security=SSPI; MultipleActiveResultSets=True; Pooling=true; Max Pool Size=100",
"DbEngineType": "MSSQL",
"CurrentSchemaName": "dbo",
"Version": "8.2.1",
"TargetVersion": "",
"SkipVersions": [],
"RedisServer": "localhost",
"RedisDB": "1",
"RedisPort": "6379",
"RedisPassword": "",
"WCConnectionTimeout": "1024",
"ApplicationType": "NetFramework",
"HostingType": "IIS",
"KestrelPorts": "5000,5002",
"HubUser": "j.smith",
"HubPassword": "12345678",
"Backup": {
"AppDirectory": "C:\\temp\\backup\\app",
"DbDirectory": "C:\\temp\\backup\\db",
"Frequency": "25"
}
}
When your application server is not connected to the Internet
On the machine connected to the Internet, fill out the parameters shown in the following example. The website is not available on this machine, so specify the current version and the DBMS type explicitly:
{
"WorkDirectory": "C:\\temp\\delivery",
"Product": "Studio",
"Version": "8.2.1",
"TargetVersion": "",
"ApplicationType": "NetFramework",
"DbEngineType": "MSSQL",
"HubUser": "j.smith",
"HubPassword": "12345678"
}
-
Download the update packages. Open a terminal window as administrator, navigate to the #Updater# folder and run the following command:
dotnet Updater.dll --downloadWhen the download completes, the "#WorkDirectory#/InstallPackages" folder contains the following structure:
- A separate directory appears for each version in the update order.
- Each version directory contains an archive that has files of the corresponding version (the archive is unpacked automatically to the "App" and "Pkg" folders during the update process) and a "Scenario" folder.
Every download recreates the "InstallPackages" folder: the packages downloaded earlier are deleted and downloaded again.
When your application server is not connected to the Internet
Before you take the next step, switch to the application server. To do this:
- Copy the #Updater# folder and the "#WorkDirectory#/InstallPackages" folder to the server where your application is placed.
- Open the creatio.json file from the "#Updater#" folder on the application server for editing. Fill out the remaining parameters:
WebRootDirectory,InstallPackagesPath(the folder to which you copied the packages),Site,HostingType,ConnectionString,CurrentSchemaName, and the Redis parameters. - Save the changes.
3. Run Updater
Open a terminal window as administrator. Navigate to the #Updater# folder (the folder that contains the "Updater.dll" and "creatio.json" files). Run the following command:
dotnet Updater.dll --update
The utility checks the software prerequisites, verifies that the update packages and scenarios for all versions are available, stops the website, installs the packages version by version, flushes the Redis cache, starts the website, and collects the logs. Multiple commands will be executed sequentially during the update process. Wait for the entire process to finish.
Running dotnet Updater.dll without a command starts the update as well.
If you encounter the error Installed components/software have an outdated/incorrect version. In order to start the Creatio update, please upgrade it, review the list of software components above the error message for any missing software. Install any missing components before proceeding with the Creatio update.
If you encounter the error Updater version is outdated, a newer version of the update utility is required. Download the latest "Updater.zip" archive, unpack it to a new folder, copy your "creatio.json" file to that folder, and run the update again.
Update utility commands
Run the commands from the "#Updater#" folder as dotnet Updater.dll <command>.
Command | Short form | Description |
|---|---|---|
|
| Starts the update. This is the default command. |
|
| Downloads the update packages and scenarios to the "#WorkDirectory#/InstallPackages" folder without starting the update. |
|
| Displays the changelog of the update utility. |
|
| Removes the rollback marker after a failed update. Learn more: Roll back the Creatio application before re-updating. |
| Displays the list of commands. | |
| Displays the version of the update utility. |
Options:
-s– silent mode. The utility does not wait for a key press after the command completes. Use it when you run the utility from a script, for example,dotnet Updater.dll --update -s.--<parameter>=<value>– overrides a setting from the "appsettings.json" file for the current run, for example,--features:ExtendProduct=true. Can be combined with a command.
Update together with product upgrade
To perform a product upgrade, e.g., from Creatio Sales Enterprise edition to the CRM product lineup, the update utility uses the update package of the new product of the same version as your current product.
-
In the "creatio.json" file, set
Productto the name of the new product and setTargetVersionto your current version. -
Run the update with the
ExtendProductfeature enabled:dotnet Updater.dll --update --features:ExtendProduct=trueThe utility downloads the update package of the new product for your current version and installs it.
-
To update to a newer version after the product upgrade, clear
TargetVersionand run the regular update.
Update the web farm
If your application operates in the web farm mode, perform additional steps after you complete the update of the pre-production website and one of the production websites:
- Set the
ConnectionStringparameter in the "Terrasoft.Tools.WorkspaceConsole.exe.config" file. - Disable all websites except for websites that were updated.
- Copy the contents of the "#Application#myapp\webapp\conf" folder from the updated website to the disabled websites.
- Enable all websites.
To enable domain-based authentication in Creatio, transfer Windows authentication settings to the updated application. Learn more in the "How to setup Windows authentication" article.
Learn more about the web farm mode: Application server web farm.
4. Complete the update
The update utility flushes the Redis cache automatically after a successful update. If the utility reported that the Redis cache was not cleared, flush the cache manually.
After the update is complete, ensure you are using the latest versions of all microservice components. If any components are outdated, update them.
If you have made any customizations to your "web.config" files, e.g., integrations or external services, manually transfer those changes to the updated configuration after a successful update.
Licenses need to be re-ordered after each update. We recommend that you generate a license request and upload the licenses either before or after upgrading. If you request the license before the update but upload it afterward, you might encounter license format errors. In that case, you will have to send the license request to Creatio support again. Learn more: Creatio licensing.
After the update process is complete, open the Creatio website in browser, compile the application and test whether the website functions as intended.
- Open the website.
- To re-generate client static content, run the Compile all items action in the Configuration section.
- Open the application in a web browser and verify that your routine operations function correctly.
If IIS session state settings were upset by the changes you implemented this makes it impossible to log in to the mobile application. After an update, make sure the "Use Cookies" mode is enabled in the IIS cookies settings.
Roll back the Creatio application before re-updating
If the update process has failed, follow these steps:
-
Restore the application files:
- Delete all current application files.
- Copy the binary files to the application directory from the backup that you made before the update.
-
Restore the database using the database backup that you made before the update.
-
If you plan to contact support, gather all relevant logs. The utility collects the logs of every run to a single archive: "#Updater#/artifacts/logs-yyyyMMddTHHmmss.zip", where
yyyyMMddTHHmmssis the date and time of the run. The path to the archive is displayed at the end of a failed run. The archive contains:- the update utility log "#Updater#/UpdateExtendedLog-yyyyMMddTHHmmss.txt"
- the log directories of each version "#InstallPackagesPath#/%Version%/Log"
If the update stopped at the compilation check, also attach the "#Updater#/artifacts/CompilationErrors-yyyyMMddTHHmmss.txt" file.
-
In child directories of "#InstallPackagesPath#" that have the version numbers, delete the App, Log, Pkg, Temp directories if they exist. Alternatively, run
dotnet Updater.dll --downloadto download the update packages again. -
Make the necessary corrections recommended by the Creatio technical support.
-
Restart the system update process.
When the update scenario starts, the utility stores a rollback marker in the Creatio database and removes it when the update completes successfully. Restoring the database from the backup removes the marker as well. If Creatio support instructs you to restart the update without restoring the database, remove the marker first, otherwise the update stops with the error Application was not rolled back. Update process is terminated. Please roll back all changes and try again. To remove the marker, run the following command in the "#Updater#" folder (or run the "cmd\remove-rollback-marker.bat" script on Windows, "cmd/remove-rollback-marker.sh" on Linux):
dotnet Updater.dll --remove-rollback-marker
Special features of version updates
Update to 7.11.1 (for Creatio Financial Services, lending edition)
Take these steps before you update from Creatio version 7.11.0 to version 7.12.0 as well.
If you are using Bank.AI, lending edition and have a custom application page (FinApplicationPage), take the following steps after the base update scenario is complete.
-
Update packages from SVN.
-
Run the UpdateFinAppLendingPage utility.
Running the UpdateFinAppLendingPage from Windows command prompt:
UpdateFinAppLendingPage.exe "Path to the downloaded operational copy of svn".Example:
UpdateFinAppLendingPage.exe C:\MyPackagesFromSvn\. -
Commit changes to SVN.
-
Update the configuration from SVN by running the Restore from repository command in the Configuration section.
Update to 7.15.2 - 7.18.3 (if you use Redis Sentinel)
If your Redis configuration is fail-proof, contact Creatio support for more information about Redis Sentinel (that ensures Redis remains reliable) before updating to version 7.15.2 and later.
The Redis Sentinel mechanism was retired in Creatio version 7.18.3. We recommend switching to Redis Cluster after updating Creatio to version 7.18.0 and later.
Update to version 7.15.3
Take these steps before you update from Creatio version 7.15.0 to version 7.16.0 as well.
Before you update to version 7.15.3, make sure no ReportService customization has been performed in your configuration.
To do this, download and execute one of the following scripts depending on which DBMS you use: download the script for Microsoft SQL, download the script for PostgreSQL.
If the script returns no results, proceed with the following update steps.
If the script returns a list of replaced schemas, compare them with the out-of-the-box schema.
Check which packages contain the schemas from the selection below:
- If the selection contains any of the schemas from the base packages: verify whether the base package is blocked. The "Maintainer" value of the base package should be "Terrasoft".
- If the selection only contains schemas from custom packages, analyze the selection schemas.
- If the custom schema contains "using Terrasoft.Reports:", delete "using" (the action is recommended but does not affect the update).
- If the replaced schema references other report designers, but the logic of using it does not change as compared to the out-of-the-box logic, use the instruction.
- If the replaced schema references other report designers and the logic of issuing the reports is changed, analyze the replaced schemas and adapt them to work with the package (the package is part of your configuration starting from version 7.15.0).
Update to 7.16.0
After you update to version 7.16.0, deploy the Exchange Listener synchronization service to make sure the IMAP/SMTP and Exchange services work correctly.
Update to 7.16.1 and 7.16.2
Take these steps before you update from Creatio version 7.16.0 to version 7.17.0 as well.
Before you update to versions 7.16.1 and 7.16.2 make sure you do not have any customization using the obsolete library and the Terrasoft.Mail.SmtpClient class in your configuration.
To do this, run the following MSSQL script:
SELECT SysSchema.Name AS SchemaName FROM SysSchema (NOLOCK)
WHERE SysSchema.Id IN (
SELECT SysSchemaId FROM SysSchemaSource
WHERE SysSchemaId IN (
SELECT
ss.Id
FROM SysSchema ss WITH (NOLOCK)
INNER JOIN SysPackage sp WITH (NOLOCK) ON ss.SysPackageId = sp.Id
WHERE sp.Name NOT IN ('Base', 'ProcessDesigner', 'NUI', 'SSP')
AND sp.Maintainer != 'Terrasoft'
AND ss.ManagerName NOT IN ('ClientUnitSchemaManager', 'DcmSchemaManager', 'PageSchemaManager')
)
AND (Source LIKE '%MailBe%' OR (Source like '%SmtpClient%' AND Source like '%Terrasoft.Mail%'))
)
If the script does not return anything, proceed with the following update steps.
If the script returns a list of schemas:
Check the packages for the schemas from the selection:
- If the selection contains base package schemas, check whether the base package is blocked and if the "Maintainer" value of the base package is set to "Terrasoft".
- If the selection only contains the custom package schemas, analyze the selection schemas.
- If the custom schema contains the "using" directive but does not involve its types, delete "using".
- If the custom schema contains obsolete directives, change the mechanism as per the following instructions:
Enjoy the new version of Creatio!