Bpm'online update guide to 7.14.3
PDF

This guide covers the process of updating bpm'online to version 7.14.3. Our team at bpm’online 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 bpm’online version 7.14.3. in the release notes.

You can update to version 7.14.3 from any version.

Note

The update requires NET Framework of version 4.7.2 and Runtime and Developer Pack installed on the application server. Download .NET Framework 4.7.2. Download Developer pack.

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 executing these actions causes any errors, you will need to correct them before starting the update.

Note

The process differs for MS SQL Server, Oracle Database and PostgreSQL.

How to update

We recommend updating in two stages:

1. First, perform the update on a pre-production site with a copy of your current bpm’online database.

2. If the first stage completes successfully, perform the update of the production site of the application.

Attention

Update of the production site should not be carried out during business hours, as the site will be unavailable.

The update process consists of the following general steps:

1. Create a copy of the database of the production site, which you will deploy on the pre-production site.

2. Create a new pre-production site in IIS. Application deployment is described in a separate article.

3. Install the update on the pre-production site.

4. Verify that the pre-production site is fully operational. If the primary and frequently used functions run without errors, you can begin updating the production site.

5. Create copies of the database and application. You will need them to return to a working version in case of problems.

6. Stop the production site of the application.

7. Install the update on the production site.

8. Run the website and verify that the updated version is operational.

If your application operates in the web farm mode, perform additional steps after you complete the update of the pre-production site and one of the production sites:

1. Set the Data Source and Initial Catalog values in the Terrasoft.Tools.WorkspaceConsole.exe.config file.

2. Disable all sites except for the ones that have been updated.

3. Copy the contents of the myapp\webapp\conf folder from the upgraded site to the disabled sites.

4. Enable all sites.

Note

To enable domain-based authentication in bpm’online, transfer Windows authentication settings to the updated application. More information about Windows authentication settings in bpm’online is available in a separate article.

Creating database backup

You will need a backup copy of your production database to create a test site before applying the update to the production site, as well as to roll back the update in case of problems (e.g., compatibility with customizations).

Note

If you deploy a backup copy of the production database and you want to disable your integrations in it, run the Disable_Synchronization.sql script. Download the script.

Creating database backup for MS SQL Server

1. Run Microsoft SQL Server Management Studio.

2. Select the [Back Up] command under the [Tasks] section of the context menu of the application database catalog.

3. Specify the name of the database copy and the directory in which the backup will be created. Click [OK] to start the backup process (Fig. 1).

Fig. 1 Creating database backup

scr_setup_database_backup.png 

Note

Make sure the directory for the database backup copy already exists, since SQL server does not have access to creating catalogs.

When updating the bpm’online production version, we recommend creating a copy of the application using any file manager.

To open a database backup:

1. Log in to Microsoft SQL Studio.

2. Create a new database if you need to extract only certain data from the backup, or select an existing database if you need to restore all data.

3. Select the [Restore database] command in the right-click menu of the database.

4. Specify path to the backup file in the opened window.

5. Click [OK] and wait for the restoration process to complete. More information is available in a separate article.

Creating Oracle Database backup

1. Connect to the Oracle server using the SqlPlus utility:

sqlplus "SYS/SYS_PASSWORD@ORACLE_HOST:ORACLE_PORT/SERVICE_NAME AS SYSDBA"

SYS_PASSWORD – a password for authorization on the Oracle server.

ORACLE_HOST – Oracle server address.

ORACLE_PORT – Oracle server port.

SERVICE_NAME – Oracle service name.

2. Execute the following SqlPlus commands:

CREATE OR REPLACE DIRECTORY DIRECTORY_ALIAS AS 'PATH_TO_BACKUP_DIRECTORY';

GRANT READ, WRITE ON DIRECTORY DIRECTORY_ALIAS to BACKUP_SCHEMA_NAME;

DIRECTORY_ALIAS – an alias for the directory where the backup copy will be placed.

PATH_TO_BACKUP_DIRECTORY – full path to the directory where the backup copy will be placed.

BACKUP_SCHEMA_NAME – name of the schema for which the backup is made.

3. Back up your schema using the expdp utility:

expdp "BACKUP_SCHEMA_NAME/BACKUP_SCHEMA_PASSWORD@//ORACLE_HOST:ORACLE_PORT/SERVICE_NAME" SCHEMAS=BACKUP_SCHEMA_NAME DIRECTORY=DIRECTORY_ALIAS dumpfile=BACKUP_FILE_NAME NOLOGFILE=YES

ORACLE_HOST – Oracle server address.

ORACLE_PORT – Oracle server port.

SERVICE_NAME – Oracle service name.

DIRECTORY_ALIAS – an alias for the directory where the backup copy will be placed.

BACKUP_SCHEMA_NAME – name of the schema for which the backup is made.

BACKUP_SCHEMA_PASSWORD – password for the schema for which the backup is made.

BACKUP_FILE_NAME – name of the file where the schema will be exported.

As a result, the expdp utility will create a backup copy of the BACKUP_SCHEMANAME schema with the BACKUP_FILE_NAME in the PATH_TO_BACKUP_DIRECTORY directory.

Deployment of the backup copy database is covered in the “Installing bpm’online” article.

Creating the backup copy of PostgreSQL database

To create a backup copy of the database, you need to use the pg_dump utility. It is located in the PostgreSQL software setup folder.

1. Enter the data base connection password in the environment variable:

set PGPASSWORD=pg_password (“env PGPASSWORD=pg_password” – for linux)

2. Run the following command:

“C:\PostgreSQL\pg_dump.exe” --host=#ServerIP# --port #ServerPort# --username #SysUserName# --format=c --blobs --verbose -c -f #BackupFilePath# #DatabaseName#

ServerIP – PostgreSQL server address.

ServerPort – PostgreSQL server port.

SysUserName — name of the PostgreSQL system user (you specify it when installing the PostgreSQL server).

SysUserPassword — password of the PostgreSQL system user (you specify it when installing the PostgreSQL server).

BackupFilePath – full path to the directory where the backup copy will be placed.

DatabaseName – name of the data base, whose backup is being made.

As a result of the utility operation, the backup of the data base will be created in the BackupFilePath directory.

Deployment of the backup copy database is covered in the “Installing bpm’online” article.

Installing updates

To install the update:

1. Delete the current bpm'online files from the website catalog.

The path to the files to be deleted is specified in the “tempDirectory” setting, the “compilation" block. You can find the setting in the web.config loader and web.app.

If the “tempDirectory” setting is not specified, clear the files stored at the following paths (where “%ApplicationName%” is the name of the website in IIS):

  • 64 bit
    • ?%windir%\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files%ApplicationName%
    • %windir%\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files%ApplicationName%_0
  • 32 bit
    • ?%windir%\Microsoft.NET\Framework\v4.0.30319\Temporary ASP.NET Files%ApplicationName%
    • %windir%\Microsoft.NET\Framework\v4.0.30319\Temporary ASP.NET Files%ApplicationName%_0

2. Download the UpdaterService.ps1 for uploading distributions.

3. Open the config.json script file to edit. Populate it with the corresponding values:

webRootDirectory – path to the website root folder.

workDirectory – path to the folder, where all installation packages and the update utility will be stored.

product – name of the product where the website is deployed. Copy the needed name from the enum Product block in the UpdaterService.ps1 file.

dbEngineType – type of the DBMS. Copy the needed name from the enum DbEngineType block in the UpdaterService.ps1 file.

versionBuild – current version of you application.

connectionString – database connection string. Copy this string from your connection to the database.

RedisServer – Redis server.

RedisDB – the number of Redis database.

RedisPort – Redis port.

Example of a config.json script file configuration:

{
     "webRootDirectory": "c:\\inetpub\\wwwroot\\delivery",
     "workDirectory": "c:\\temp\\delivery",
     "product": "Studio",
     "dbEngineType": "MSSQL",
     "versionBuild": "7.14.1.935",
     "connectionString": "Server=db_server;Port=5432;Database=delivery;User ID=postgres;password=pass_word;Timeout=500; CommandTimeout=400;MaxPoolSize=1024;",
     "currentSchemaName": "dbo",
     "redis": {
            "server": "localhost",
            "db": 1,
            "port": 6379
     }
}

4. Run the UpdaterService.ps1 Powershell script.

When you run the script, the following elements are created in the folder that you specified in the workDirectory: an “InstallPackages” folder containing a set of update packages, a folder containing the update utility and a Start.lnk file.

The following folder/file structure will be used in the InstallPackages folder:

?A separate folder appears for each version in the alphabetical order as per the update schedule.

?Each version folder contains:

?An archive with files of the corresponding version (the archive will be automatically unpacked to the App, Pkg, Template folders during the update process).

A “Scenario” folder.

      Example of the file structure:

  • folder_icon.png 7.13.0

folder_icon.png 7.13.0.284_SalesTeam _SoftKey_MSSQL_ENU.zip

folder_icon.png Scenario

  • folder_icon.png 7.13.1

folder_icon.png 7.13.1.769_SalesTeam _SoftKey_MSSQL_ENU.zip

folder_icon.png Scenario

  • folder_icon.png 7.13.2

folder_icon.png 7.13.2.934_SalesTeam _SoftKey_MSSQL_ENU.zip

folder_icon.png Scenario

5. In the folder containing installation packages and the update utility (your “workDirectory” folder), find and run the Start.lnk file.

During the execution, a number of commands will be run sequentially. Please wait for the entire process to complete.

If the update process has failed, stop the procedure and contact the customer support. Provide the folder with update log: [The BpmonlineUpdater catalog]\InstallPackages\%Version%\Log.

Note

To restore the database, use the database copy created earlier.

information_icon.png Updating to 7.8.2

Preparing the development environment (for version 7.8.2)

If you use SVN in the development process, additionally run the FlatPackageConverter utility, which:

1. Rebuilds the structure of the resources. Resources will be associated with a package, not a schema.

2. Corrects invalid SVN properties of resource files.

3. Corrects invalid names of cultures.

4. Removes invalid resource files (empty or without items) and resources that do not have schemas in the same package.

Download and unzip FlatPackageConverter.rar. Open example.bat file that runs the FlatPackageConverter.exe utility in any text editor and edit required parameters:

FlatPackageConverter.exe relocateResources
--repositoryUri=<repositoryUri> --version=<version> --user=<user>
--password=<password> --commentFilePath=<commentFilePath>
--copyPath=<copyPath> --kind=<kind>
--needDeletedWrongResources=<needDeletedWrongResources>

Description of the used parameters is available in the table below.

Parameter

Function

<repositoryUri>

Path to your SVN repository.

<version>

Version of the packages to be updated.

<user>

SVN user login.

<password>

SVN user password.

<commentFilePath>

Path to the local file that contains a comment to commit changes in SVN.

<copyPath>

Path to a folder where the utility will copy its temporary files.

<kind>

Determines the type of resource movement:

  • "package" — transfer resources on the package level (7.8.1 –> 7.8.2) with the addition of the manager name.

  • "schemas" — transfer resources from schemas to packages with the addition of the manager name (7.7.x –> 7.8.2).

  • "oldschemas" — transfer resources from schemas to packages (7.7.x –> 7.8.0).

<needDeletedWrongResources>

True — deletes all invalid resource files; records all information in deletion log. Recommended option.

False — displays information about errors and warnings that you must then manually correct.

Example of updating bpm'online from 7.8.1 to 7.8.2:

FlatPackageConverter.exe relocateResources
--repositoryUri=http://tscore-svn:8050/svn/ts5conf/branches/TestPS_14
--version=7.8.0 --user=login --password=password
--commentFilePath=C:\Temp\111.txt --copyPath=C:\Temp\1 --kind=package --needDeletedWrongResources=True

Note

In this example, the “--version=7.8.0” parameter is not an error, as it specifies the version of the packages that need to be changed during the update. Be sure to specify your repository login and password.

Attention

After the update is complete, the utility displays a list of errors and warnings, as well as records detailed information on each package in the log. Errors are resources in packages without schemas, warnings are empty resource files that do not contain a single element. To remove invalid resource files, use the needDeletedWrongResources=True parameter.

information_icon.png Updating to 7.8.4

Preparing the development environment (for version 7.8.4)

If you use SVN in the development process, additionally run the FlatPackageConverter utility after you perform the update. It will delete the outdated files for schema resources.

Download and unzip FlatPackageConverter.rar. Open example.bat file that runs the FlatPackageConverter.exe utility in any text editor and edit required parameters:

"Full path to FlatPackageConverter.exe" deleteSchemaLegacyResources
--repositoryUri=<repositoryUri> --version=<version> --user=<user>
--password=<password> --commentFilePath=<commentFilePath>
--copyPath=<copyPath>

Description of the used parameters can be view on the table.

Parameter

Function

<repositoryUri>

Path to your SVN repository.

<version>

Version of the packages to be updated.

<user>

SVN user login.

<password>

SVN user password.

<commentFilePath>

Path to the local file that contains a comment to commit changes in SVN.

<copyPath>

Path to a folder where the utility will copy its temporary files.

Example of updating bpm'online from 7.8.3 to 7.8.4:

FlatPackageConverter.exe deleteSchemaLegacyResources
--repositoryUri=http://tscore-svn:8050/svn/ts5conf/branches/TestPS_14
--version=7.8.0 --user="login" --password="password"
--commentFilePath=C:\Temp\111.txt --copyPath=C:\Temp\1

Note

In this example, the “--version=7.8.0” parameter is not an error, as it specifies the version of the packages that need to be changed during the update. Specify your repository login and password.

Attention

After the update is finished, the utility will display a list of errors and warnings. Detailed information on each package will be available in the Out.txt file in the same directory. The error “svn: E195022: is locked in another working copy” in the log indicates that some files in the repository are locked in the version control system. To correct the error, unlock the files and run the utility again.

information_icon.png Updating to 7.9.0

Preparing the development environment (for version 7.9.0)

If you use SVN in the development process, additionally run the FlatPackageConverter utility after you perform the update. It will remove the incorrectly generated metadata for localized strings.

Download and unzip FlatPackageConverter.rar. Open example.bat file that runs the FlatPackageConverter.exe utility in any text editor and edit required parameters:

"Full path to FlatPackageConverter.exe" fixResourcesInMetadata
--repositoryUri=<repositoryUri> --version=<version> --user=<user>
--password=<password> --commentFilePath=<commentFilePath>
--copyPath=<copyPath>

Description of the used parameters can be view on the table.

Parameter

Function

<repositoryUri>

Path to your SVN repository.

<version>

Version of the packages to be updated.

<user>

SVN user login.

<password>

SVN user password.

<commentFilePath>

Path to the local file that contains a comment to commit changes in SVN.

<copyPath>

Path to a folder where the utility will copy its temporary files.

Example of updating bpm'online from 7.8.4 to 7.9.0:

FlatPackageConverter.exe fixResourcesInMetadata
--repositoryUri=http://tscore-svn:8050/svn/ts5conf/branches/TestPS_14
--version=7.8.0 --user="login" --password="password"
--commentFilePath=C:\Temp\111.txt --copyPath=C:\Temp\1

Note

In this example, the “--version=7.8.0” parameter is not an error, as it specifies the version of the packages that need to be changed to update. Specify your repository login and password.

Attention

After the update operation is finished, the utility will display a list of errors and warnings. Detailed information on each package will be available in the Out.txt file in the same directory. The error “svn: E195022: is locked in another working copy” in the log indicates that some files in the repository are locked in the version control system. To correct the error, unlock the files and run the utility again.

Stopping the site

To avoid data loss, we recommend you to stop the production website before updating. You can omit this step when working with the test site.

1. Open the Internet Information Services Manager (IIS).

2. Stop the production web site using the [Stop] command in the [Actions] area (Fig. 2).

Fig. 2 Stopping a website in IIS

scr_user_upgrade_instruction_site_start.png 

Website starting, compilation and verification

After the update process has completed, start the bpm’online website in IIS, compile the application and test the website by opening it in a web browser.

1. Open the Internet Information Services Manager (IIS).

2. Start the web site using the [Start] command in the [Actions] area.

3. Open the web site using the [Browse] command in the [Actions] area (Fig. 3).

Fig. 3 — Opening test website in a web browser

scr_user_upgrade_instruction_test_site_browse.png 

Attention

If the update process has failed, stop the procedure and check the update logs located at: [The BpmonlineUpdater catalog]\InstallPackages\%Version%\Log. If you receive the “Error:Error” type of a bug in base packages, contact the support and provide the folder with log records. If errors occur in custom packages, contact the developers of these packages.

4. Generate client static content by running the [Compile all items] action in the [Configuration] section.

5. Open the application in a web browser, verify that your routine bpm’online operations are performed correctly.

6. If everything works properly, you can delete the backup application and database.

information_icon.png Updating to 7.10.0

Additional settings

After updating to 7.10.1, data enrichment service address and IP has changed. The new address is: api.bpmonline.com (ip: 185.3.141.228). You must open the access to the service on your servers (port 443).

The previously valid address cloud-service.bpmonline.com (ip: 188.99.10.125) is now used only for the bpm'online marketing (for example, for bulk email).

information_icon.png Updating to 7.11.1 (for the bpm'online lending product)

Additional steps for bpm’online lending

If you are using bpm’online lending and have a custom application page (FinApplicationPage), then perform the following steps after the base update scenario completes.

1.Update packages from SVN.

2.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\.

3.Commit changes to SVN.

4.Update the configuration from SVN by running the [Restore from repository] command in the [Configuration] section.

Enjoy the new version of bpm'online!