Manually Installing, Upgrading and Patching

Introduction

Purpose of this document

The purpose of this document is to describe the install, upgrade and patch procedures, for Comflow. How to manage deploy deployment operations between different environments will also be described.

Recommended Comflow system setup

The figure above shows a typical schematic preferred setup of the Comflow environments installed at a site.

Recommended Approach

The recommended approach is to have 3 Comflow/Tomcat servers (port number):
•One for development environment (7070)
•One for the testing environment (9090)
•One for the production environment (8080)

If more than one developer will be involved, development and unit testing can be done by each developer on their own PC, followed by a deployment to the development server for integrated testing (Please also see chapter "Application Deployments" for information about deployment management between the different environments). Hence, one Comflow Studio should be installed on every development, test and production server.
Once the development has passed initial testing, it will be deployed to the test server, and that version then tagged and user testing started. No further deployments should be made to the test server except where absolutely necessary, and in this case, it should be done in a controlled manner.
Once testing is complete and the tagged version has been approved, it will then be deployed to the production server.
If a particular environment requires multiple Tomcat servers, this environment would still only require one instance of Comflow Studio, but with a different sitedef for each Tomcat server.

Alternative approach with two Tomcat Servers

If only two Tomcat servers can be made available, then there would be one for test and one for production.
Development and unit testing would be done by each developer on their own PC.
Deployments to test would need to be controlled and coordinated between each of the developers and those responsible for testing. After a new version is deployed to test, the version should be tagged, and fully tested. No further deployments should be made to the test server except where absolutely necessary, and in this case, it should be done in a controlled manner.
Once testing is complete and the tagged version has been approved, it will then be deployed to the production server.
Please also see chapter "Application Deployments" for information about deployment management between the different environments!

Installation of Comflow

Installation of a complete Comflow environment requires a number of different steps:
•Installation of Comflow Studio.
•Installation of required Java version.
•Installation and configuration of Apache Tomcat.

These different steps do not have to be performed in any specific order. Also, of course, in a distributed environment, not all of the different components have to be installed (see chapter "Recommended Comflow system setup" for preferred setup).

License

All installations require a Comflow license, which controls among others the number of users in the system. All installations include a Basic license, which allows one user to run the system. Thereby you can always start a Comflow system via the included “comflow”-user or with the in sitedef overridden default user.
If you do a new installation or upgrade an installation to another version, you will require a license file for the system. So order that license in advance from Corzia, so you have it available when you install.

Installation prerequisites

The prerequisites listed in the tables below are valid for version 2.22 of Comflow.

Hardware requirements/recommendations – Server in production

Server Hardware

Server Software

Client Hardware

Client Software

Manual installation procedure

In this example we will install Comflow on Windows Server 2012.
Note that C:/ is used as installation path in all installation examples in this chapter. This path could of course just as well be D:/ or E:/ depending on disk space. The important (recommended) thing is that the Comflow installation is done directly under the root.
The install procedure is the following:

1. Install Comflow Studio
2. Install Java
3. Install Tomcat
4. Configure Comflow Studio
5. Configure Tomcat

Install Comflow Studio

This describes the actions sequence for installing a Production/8080 environment. For other environments, replace 8080 with the correct port number.

1. Add https://.corzia.com, https://.oracle.com and https://*.apache.org to trusted sites in Internet Explorer if that browser is used or similar for the used web browser.    
2. To download the Comflow Studio (here version 4.8) then first go to https://update.corzia.com and login with the supplied credentials. This will take you to the Comflow update site where you can download Comflow related software. 
3. Download the latest version of Comflow Studio (here for Windows) and save the file in C:\Corzia\downloads 
4. Unzip the folder comflow*.zip file and choose to extract to folder C:\Corzia\eclipse\eclipse8080.

Install Java JDK

JDK is used in conjunction with Comflow Studio and for Apache Tomcat. Both Oracle and Open JDK via Adopt is supported. Java 8 is used in this action sequence.

1. Download Oracle Java Development Kit from: http://www.oracle.com/technetwork/java/javase/downloads/index.html . This might require login at Oracle. Select the latest version of the JDK. Or download Open JDK HotSpot from https://adoptopenjdk.net/. This instruction though focus Oracle Java, but the same principles are valid for Open JDK.
2. Accept the license agreement and select the ‘Windows x64’ version. Preferably all Comflow related downloads should be placed in a download folder (C: \Comflow\download) for easy access at any time 
3. Run the downloaded executable.
4. Press [Change..] to change the Install to directory as below:
5. Change the location to the specific Java version, like C:\Corzia\Java\jdk1.8.0_201 and press [OK].
6. Install at least on jre at default location and press [Next]
7. The installation is done.

Install Apache Tomcat

In this action sequence Apache Tomcat 9.0 is used in conjunction with JDK8.

1. From https://tomcat.apache.org/download-90.cgi download the Apache Tomcat 9.x (64-bit Windows zip). Change the mirror site to site to https://www-eu.apache.org/dist/ before start. 
2. Use [Save as] to save the file in the downloads folder
3. Open the zip- file and choose to extract to C:\Corzia\Apache\tdk8080. Note that 8080 indicates which Tomcat main connector port that is used. Should any other port be used, because of parallel Tomcat installations, other port conflicts etc, the directory should have a corresponding suffix.

After having extracted the zip- file the installation path should now look as in the picture below:

Tomcat ports

The default Tomcat port is port 8080. If you have more than one Tomcat server, or if port 8080 is used by another process, you can change the port by modifying the server.xml file located under the conf folder of the Tomcat installation. Here the path would be C:\Comflow\Apache\tdk8080\bin\server.xml.
If you change the main connector port used, you should change all the other connector ports as well – You would typically change from an 80 to a 90 for each connector port for example 8080 to 9090 for the main port
In our example the Tomcat is installed running on port 8080. Hence, the installation path is C:\Comflow\Apache\tdk8080. Suppose that we are running a parallel Tomcat on the same machine. In that case we, if free, choose to use port 9090 with an installation path that looks like: C:\Comflow\Apache\tdk9090. In the same way we would choose to use 7070 for a third installation etc. (see below).

Configure Comflow Studio

Chapter "Recommended Comflow system setup" describes the preferred setup of a complete (development, test and production) Comflow environment.
Suppose that a production server only has the Studio and a Tomcat runtime environment installed. In that case the Tomcat should have 75% of the total RAM allocated (see chapter "Configure Tomcat for Comflow Portal"). The rest of the RAM should be allocated as the maximum allocated memory (Xmx) for the Studio.

So, Xmx indicates the maximum allocated memory usage for the Comflow Studio. This setting shall of course never be bigger than the total RAM of the machine. Xms is the setting for the minimum allocated memory for the Studio. Xmx should, preferably and if possible, be set to at least 1024M. Xms should be set to at least 128M.
•Right click on comflow.ini (located in C:\Corzia\eclipse/eclipse8080) and select Open with -> Notepad. Modify –Xmx1024M and –Xms256M according to your machine.

Setup Tomcat within Comflow Studio

1. Select Windows->Show View->Other-> Server->Servers
2. Right click in the Servers view and select New->Server.
3. Select Apache -> Tomcat v9.0 Server and press Next.
4. Point to the correct Tomcat installation directory.
5. In the Server view double click on the created Apache Tomcat v9.0 Server. In the Overview make sure that ‘Use Tomcat installation’ is selected. Set Timeouts -Start 450 and Stop 150
6. In the Server View right click on the server and select Debug, Start or Stop. If the service starts and stops properly, you have a functional Tomcat service for Comflow.

Configure Tomcat for Comflow Portal

In C:\Corzia\Apache\tdk8080\bin you can find the tomcat98080w.exe executable (the name of the executable must correspond to the windows service name as described in chapter "Install Apache Tomcat" and Error! Reference source not found.). This executable is an Apache Tomcat configuration tool and can be used to configure a number of different Apache Tomcat settings.

1. Double click the executable.Many of the Apache Tomcat property settings are quite self-explanatory but some of them must be mentioned here anyhow.
2. The Java tab of the configuration tool contains a Java Options editor, and two very important tomcat memory pool settings (Initial memory pool and Maximum memory pool as displayed in the picture below) 

The Java Options editor contains startup options for the Java Virtual Machine. Please set the following options for optimal Tomcat performance:
•Dcom.sun.management.jmxremote.port=48080(<- the port to run on e.g. 8080)
•Dcom.sun.management.jmxremote.ssl=false
•Dcom.sun.management.jmxremote.authenticate=false
•XX:+HeapDumpOnOutOfMemoryError
•XX:HeapDumpPath=C:\Corzia\Apache\tdk8080\logs(<- logs directory on your Tomcat install path)

Initial memory pool (minimum allocated memory) and Maximum memory pool should be set to the same value.
Note! If the Apache Tomcat is running alone on the production server (except from the installed Studio), the memory allocation is recommended to be set to total RAM - 1GB of the server. Hence, if total RAM is 4 GB then the memory pool settings should be set to 3 GB (3072 MB). The 1 GB is for the OS and other processes.
Then the Assigned memory is recommended to be shared in the following way:
Maximum Memory PoolInitial Memory PoolXmnMaxPermSizePermSizeReservedCodeCacheSize
100%100%25%256M256M128M

A JVM running in a 32 bit Windows environment can only allocate a maximum of 1.5 GB RAM so, in such case, there is no reason to allocate more memory than that for an Apache Tomcat installation.
Verify the Apache Tomcat memory usage as described in chapter "Verify memory usage of Comflow".

Verify Comflow Portal

1. Left click on the start and select Control Panel -> Systemand Security ->Administrative Tools->Services. Right click on Services and select Send To->Desktop (create shortcut) 
2. Double click on the “Services” shortcut and verify at the newly created services exists.
3. Right click on the service, select properties and make sure that Startup type is set to be Automatic.
4. Use the start and stop button to control the service. 

Verify memory usage of Comflow

Start the portal and verify memory usage. System Administration->System->System status

Upgrading 

When a new release of Comflow is available it is possible to update the environment (update plug-ins) using Comflow Studio.
Moving from one version to another sometimes require doing an upgrade of the Studio (see chapter "Upgrade Studio "). Either contact your local representative or check the update site, https://update.corzia.com/, for information about whether a Comflow Studio upgrade is necessary for your version update or not.
An upgrade/update procedure should be done with great caution. Compatibility issues should be carefully examined before proceeding with an update of the environment.
Note that upgrades of minor version might lead to necessary code changes in your java code. Always do an upgrade and verification of the applications in a test environment before updating the production environment.
Should you have any uncertainties about the requirements when moving from one version of Comflow to another then please contact your local representative!
Upgrades from one minor version to another requires update of the data base tables. See chapter "Database setup and upgrade" for details.

Upgrade Studio

When migrating between major or minor releases (see Figure below) it is often necessary to upgrade to a newer version of Comflow Studio.

Either contact your local representative or check the update sit (https://update.corzia.com) for information about whether a Studio upgrade is necessary for your version update or not.

Before installing the new Studio

Before installing the new Studio, a number of steps should be performed.

1. Start the Comflow Studio that should be upgraded
2. Close all open editors (Ctrl+Shift+F4)
3. Select File->Export… as below:
4. Expand the General folder, highlight Preferences and press [Next >]
5. Select Export all, enter a preference file path and press [Finish]
6. If you have more than one workspace repeat the steps 1-5 for all workspace.
7. Rename the C:\Corzia\eclipse\eclipse8080 folder to eclipse8080_old. 

Download and install the new Studio

Download and install the new Studio as described in chapter "Install Comflow Studio".

Studio configuration

Go through the following steps after installing the new Studio:

1. Configure the Studio as described in chapter "Installation of Comflow".
2. Copy the workspace folder from C:\Corzia\eclipse\eclipse8080_old to C:\Corzia\eclipse\eclipse8080
3. Remove the .metadata folder from C:\Corzia\eclipse/eclipse8080\workspace
4. Start the Studio.
5. Select Project from the toolbar menu and uncheck Build automatically.
6. From the toolbar menu select File->Import
7. Expand the General folder, highlight Preferences and press [Next >].
8. Browse to the preference file exported in chapter "Before installing the new Studio", check Import all and press [Finish].
9. Import the latest version of all Plug-ins as described in chapter "Update plug-ins".
10. Import project(s) from workspace: From the toolbar menu select File->Import. Expand the General folder, highlight Existing Projects into Workspace and press [Next >]. In ‘Select root directory’ browse to C:\Comflow\eclipse\workspace and choose to select all projects. Last press [Finish].
11. Delete all binary eclipse projects from the package explorer.
12. Import all binary Comflow projects as described in chapter "Importing binaries".
13. From the toolbar menu select Project->Clean… Check Clean all projects and press [OK]
14. Select Project from the toolbar menu and check Build automatically. 

The installation is complete! After a test period delete the eclipse8080_old folder from C:\Comflow\eclipse\eclipse8080, as well as the exported preference file.

Updating plug-ins

Major, and sometimes minor, releases sometimes require a new version of Comflow Studio (chapter "Upgrade Studio") as well as possibly Apache Tomcat. All upgrades of Comflow though requires update of plug-ins in Comflow Studio.
Should you have any uncertainties about the requirements when moving from one version of Comflow to another then please contact your local representative!

To update Comflow plug-ins perform the following steps:

1. Stop possibly the Tomcat server
2. Select Help->Install New Software… from the toolbar menu. Select Comflow 2.22 and check all Comflow features. Uncheck “Contact all update sites during install to find required software”.
   Press [Next->]
3. You can now expand the different nodes to see which updates are available (see figure further below).
   Press [Next->] again
4. Press [Next->] again
5. Choose to accept the license agreement and press [Next>] The update manager will start to download and install the selected plug-ins.
6. Choose whether you want to restart the Studio immediately [Restart now] or later [No]. 

Importing binaries

To be able to successfully compile any Java files in your project(s) you need to import a number of binaries. If you have an environment where you don’t plan to do any development, importing binaries is not necessary.

1. Right click in the package explorer and choose Import…
2. Select Plug-ins and Fragments and press [Next>]
3. Select the options as below and press [Next>]
4. Press [Existing Plug-ins]
5. Make sure the below listed binary plug-ins are selected to import, else add them one by one.
   •net.comactivity.AsynchWorkflow
   •net.comactivity.connect
   •net.comactivity.core
   •net.comactivity.core.applications
   •net.comactivity.core.cag
   •net.comactivity.core.foundation
   •net.comactivity.core.jobmonitor
   •net.comactivity.core.jobscheduler
   •net.comactivity.core.mbeans
   •net.comactivity.core.osgi
   •net.comactivity.jetspeed
   •net.comactivity.lib
   •net.comactivity.renderer
   •net.comactivity.Rep_CACORE
6. Press [Finish]  

Deploy portal

When upgrading, as described in chapter "Upgrading", you have the possibility to update Comflow core plug-ins. Comflow core plug-ins are plug-ins for the runtime environment of Comflow Portal.

Because Comflow core plug-ins are runtime environment plug-ins they somehow must be sent to the runtime environment. This is done using the Deploy Portal functionality of Comflow Studio.

The Deploy Portal operation builds the complete Comflow runtime web application within the context of a web server environment (here an Apache Tomcat installation).

Follow the steps below to perform a Deploy Portal operation:

1. Select Window->Preferences… from the toolbar menu:
2. In the tree choose Comflow->Deploy
3. Select the appropriate sitedef from the drop down list and press [Deploy Portal] as below: 
4. Select the replace checkbox (this will clean out the Tomcat folders, removing any old patches or customer applications previously deployed). Hence, after a Deploy Portal operation, all projects have to been deployed to the runtime environment once again.
5. If you want to back up the previous installations (recommended in production), select the backup checkbox, and select a path to store the backup. This will enable the old Tomcat files to be restored in case major problems are encountered. 
6. Press [Finish]
7. Deploy all desired projects in order to apply the wanted applications

Note that the selected sitedef.xml must have an app root path type entry that points to the web server installation (here Apache Tomcat). In this example the Apache Tomcat is installed to C:\Comflow\Apache\tdk8080. The path in the sitedef should then be set to C:\Comflow\Apache\tdk8080\webapps\comflow:

<Application><Container type="servletContainer" version="2.3" name="Tomcat" />

            <Path type="approot" value="C:/Comflow/Tomcat/tdk8080/webapps/comflow" />

</Application>

Patching

Patches are CVS projects that can be added to a revision. They are cumulative and include packed changes of certain components to the actual revision.
There are four different kinds of customer project patches:

All patches for a Comflow release are managed via Comflow Studio and deployed manually after Portal Deploy.

If you previously have applied a patch to the Comflow installation, then please see chapter "Remove old patches" for removal information!

Applying a patch

Previously installed patches should be removed before installing any new ones (see chapter "Remove old patches" ).

1. Right click on the package explorer and select Import
2. Expand the CVS folder, choose Projects from CVS and press [Next >] The repository used for patches is the public repository. If this is the first time you are connecting to the CVS, you will need to create the repository location:
3. Choose Create a new repository creation and press [Next >]
4. Enter the parameters as below (authentication details must have been provided to you):
5. Press [Finish]
6. Select Use an existing module and press [Next >]
7. Scroll down to the required patch, highlight the folder and press [Finish].
8. Right click the patch customer project in Studio and choose Local Deploy. 

Remove old patches

Patches should always be removed by a Deploy Portal operation.
When performing a Deploy Portal operation all patches (as well as customer projects) will be deleted. See chapter "Deploy portal" for detailed information of how to carry out a Deploy Portal operation.
The patch should also be closed as a project or deleted from the workbench in the Studio to signal that it is not active!

Application Deployments

An important aspect of managing deployments is to ensure that the version of the application which is eventually promoted to the production server is exactly the same version that was tested and approved on the test server. In order to achieve this, it is recommended that changes not be made on the test server itself. A couple of approaches are outlined below

Deployment of application for Test

1. Ensure all development has been synchronized into the repository from the development server or development PC’s.
2. Bring down the Tomcat server in Test.
3. Synchronize all required projects from the central repository:
   •Right click on the project and take Team/Synchronize with Repository
   •Update all changes which are required to be included in the deployment
4. Tag the version
   •Right click on the project and take Team/Tag as Version
   •Enter a tag name – If you click details you can see the existing tagged versions – Follow the same naming convention as used for previous versions
5. Deploy portal
   •Go to Window/Preferences/Comflow/Deploy
   •Select the sitedef to use (the root path of the Tomcat server is retrieved from the sitedef selected (in the Application element), so it is important to use the correct one if you have multiple Tomcat servers installed)
   •Select Deploy Portal
   •Select the replace checkbox (this will clean out the Tomcat files, removing any old patches or customer applications previously deployed)
   •Select the backup checkbox and select a path to store the backup (typically C:\Comflow\Backup). This will enable the old Tomcat files to be restored in case major problems are encountered. This step is optional for the Test deployment
   •Select Finish
6. Deploy Application Projects
   •Right click on the Application Project and take Deploy/Local deploy projects
   •The ‘Projects to deploy’ box should list all projects connected to the customer project, in the order they are required to be deployed in (the order should be from most general to most specific – i.e. the Customer project should be the last to be deployed).
   •Select Finish, and all projects should be deployed
7. Deploy the sitedef for the project

Deployment of application for Production

1. Bring down the Tomcat server in Production;
2. Inspect the changes to be brought in:
   •Right click on project and take ‘Compare With’ and select the tagged version which will be brought in
   •Satisfy yourself that everything looks ok
3. Bring tagged version into workspace:
   •Right click on the project and take Team/Switch to Another Branch or Version
   •Select the version to bring in and take finish
4. Deploy portal – Follow same steps as with the Development to Test deployment (remembering to store a backup of the current files in case problems are encountered).
5. Deploy Customer Projects – Follow the same steps as with the Development to Test deployment
6. Deploy the sitedef for the project. 

Rollback Process

If a deployment does not provide the wanted result, you can rollback to the previous back up version:

1. Stop the Tomcat server
2. Move the webapps\Comflow folder (C:\Comflow\Apache\tdk8080\webappps\Comflow) to C:\Comflow\Tmp for later inspection
3. Move the latest backup from C:\Comflow\Backup to the webapps folder
4. Restart the Tomcat server. 

Sitelog

A Sitelog should be kept for each environment (particularly the production environment). It would typically be stored in the site folder for each environment

The Sitelog should contain an entry for each upgrade, deployment or rollback preformed. The entry should be dated and should contain a brief description of the task performed as well as who performed it

Database setup and upgrade

When you do a new installation or upgrading from one minor version to another, the data base needs to be setup or updated with new table definitions. That is achieved mainly via the Database tool in Comflow Studio. You start that tool via the Comflow – menu and select of Database….
If it is a new installation, the data base schema must first be created. That is done via the current data base manager tool.

If your installation needs persistent scheduling, like via the job scheduler or Process framework, you also need to install the QUARTZ database. This one includes trigger settings in the table generation, why it can't be generated via the Database tool, so it needs to be generated via SQL scripts instead.

All steps in this chapter requires a sitedef for the current Comflow environment with configured database connections.

Setup and upgrade CACORE and CACOREAWF data bases

The 2 standard Meta data id’s for Comflow are CACORE and CACOREAWF. They are normally setup in 2 different data base schemas but can share the same schema depending on how you want to structure your database.

For setup, start with creating the schema via the data base management tool. Then the process is the same for both setup and upgrade of data base.

Using the Comflow Database Management Wizard for setup and upgrade of Comflow database

In this step you shall setup or upgrade the following Metadata Ids:
•CACORE - project  net.comactivity.Rep_CACORE
•CACOREAWF - project net.comactivity.AsyncWorkflow

Do the procedure that follows for each Metadata Id:

1. On the Comflow Studio menu select Comflow/Database…
2. Chose Repository----> Database. Click in Use Hierarchy and chose the Top Project. For CACORE choose net.comactivity.Rep_CACORE and for CACOREAWF choose net.comactivity.AsyncWorkflow. Press Next.
3. Select the Metadataid in the actual project. CACORE in net.comactivity.Rep_CACORE and CACOREAWF in net.comactivity.AsyncWorkflow. Press Next.
4. Select the right database schema from the right sitedef. Press Next.
5. In the check control panel check out Table removed, since there might be other tables in the schema that shall not be removed. Press Next.
6. You will now see the net change of table changes between the new definitions in the project and the existing database schema. Review the changes in order to make sure there is no unwanted changes. If so, go back to the previous page and adjust the selection or start all over with this process. When you find the net change satisfactory, press Finish or if you want to see the actual SQL script, press Next and the Finish.
7. You will get a result log of you database changes. Make sure that all changes are OK, otherwise investigate the errors and perform the appropriate action.

Installing or updating QUARTZ

Quartz is an open source component as the scheduler engine for Comflow. It is only mandatory to install if the Job scheduler shall be used or if processes requires time-controlled events.
The QUARTZ data base is created via ready-made SLQ scripts. These scripts are supplied in the Studio in the project net.comactivity.core.jobscheduler/Docs/Quartz_2_3_0_DbTables. There you find a large number of scripts for different data base managers supplied from different sources, which will need some adjustments before they are processed. That adjustment is included in the procedure below. Search for the right one for your database management system. When you have found it, follow the process below:

1. Start Comflow Studio
2. Copy the content of the selected SQL script above
3. Go to the Database Development Perspective
4. Connect to the Database via the current Sitedef
5. Open a scrapbook for the connected database
6. Paste the SQL script in the scrapbook
7. Adjust the Schema and partly table name in the script. In the example above “qrtz” shall be replaced with the current schema name and addition of “COREJS”. The replace is thereby “qrtz_” to “QUARTZ_COREJS_”.
8. If you are updating a current Quartz database, first run the drop-statements in order to remove all old tables, before running the script for new tables.
9. Run the script for the create table statements.
10. For each run you will get a detailed log. If you find errors in that log, take the appropriate action.