Stages Documentation

Install System

Perform basic installation

  • Download and install Java Development Kit 8 (see System Requirements for supported variants)
  • Stages installation on Windows: Execute Stages installer as administrator (will be sent to you by Stages Support)
  • Stages installation on Linux:
    • Install RPM package (will be sent to you by Stages Support)
    • A user with the name “stages” is needed to allow the command “stages start” to automatically start the Stages search engine. The user needs recursive read and execute permissions on the sub-direcory “elasticsearch” and additionally write permissions on “elasticsearch/data” and “elasticsearch/logs”.
  • Database installation with Oracle 11g or 12c:
    • Get Oracle database dump and installation instructions from Stages Support.
    • Download Oracle JDBC connector for your Oracle version.
    • Copy JDBC connector to “<stages installation path>/stages/lib” and rename it to “ojdbc.jar”.
  • Database installation with MySQL5.7:
    • Get MySQL database dump from Stages Support.
    • Download MySQL JDBC connector (Connector/J 5.1 Platform Independent) and installer for MySQL 5.7.
    • Copy JDBC connector to “<stages installation path>/stages/lib” and rename the file mysql-connector-java-*-bin.jar to mysql.jar.
    • Install MySQL 5.7 (if not already installed):
      • Select Setup Type “Server only”
      • Install MySQL with Config Type “Server Machine”, default encoding “UTF-8” and servicename “mysql”.
      • Adapt/check the following properties within “[mysql]” and “[mysqld]” section in my.ini configuration file.
        (Windows: “\ProgramData\MySQL\MySQL Server 5.7\my.ini”)
        [mysql]
default-character-set=utf8

[mysqld]
character-set-server=utf8
max_allowed_packet=500M
transaction-isolation=READ-COMMITTED
lower_case_table_names=1
sql-mode = "STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"
  • Restart the mysql service.
  • MySQL: Create database user “stages” and grant privileges.
    • Start MySQL console within path “<MySQL installation path>/bin”: mysql -uroot -p<mysql-root-password>
    • Execute the following commands:
grant all privileges on *.* to 'stages'@'%' identified by '<stages-password>';
flush privileges;
exit;
  • MySQL: Create database “stages” and import dump file (unzip the file -or- customer specific dumpfile that has been sent to you). All commands need to be executed within path “<MySQL installation path>/bin”:
mysqladmin -uroot -p<mysql-root-password> create stages
mysql -uroot -p<mysql-root-password> stages <[PATH TO DUMP FILE\stages7_mysql_content.sql]
  • MySQL: Establish database connection: Edit “<Stages installation path>/stages/conf/database.properties” appropriately like in the following example:
torque.database.default.driver = org.gjt.mm.mysql.Driver
torque.database.default.url = jdbc:mysql://localhost:3306/stages?zeroDateTimeBehavior=round&jdbcCompliantTruncation=false
torque.database.default.username = stages
torque.database.default.password = <stages-password>
  • Oracle: Establish database connection: Edit “<Stages installation path>/stages/conf/database.properties” appropriately like in the following example:
## settings for oracle
torque.database.default.driver=oracle.jdbc.driver.OracleDriver
torque.database.default.url=jdbc:oracle:thin:@<IP/hostname>:<port>:<SID>
torque.database.default.username=<oracle-username>
torque.database.default.password=<oracle-password>
  • If you are updating from another version, check the release notes for any additional mandatory manual upgrade steps which may be necessary
  • Activate the configuration
    • Windows Start Menu: Execute “Programs > Method Park > Stages > Update Configuration”
    • Linux: Execute “stages update”
  • Start Stages
    • Windows: Start the services “Stages Search” and then “Stages”
    • Linux: Execute “stages start”

(Optional) Secure MySQL connection with SSL

If you want to secure your MySQL connection with SSL you need to provide the server certificate to the MySQL driver. To do this follow these steps:

  • Copy the server certificate pem file into the stages conf folder
  • Create a Java trust store based on the MySQL server certificate:
$JAVA_HOME/bin/keytool -importcert -alias MySQLCACert -file ca.pem -keystore truststore -storepass mypassword
  • Change the database.properties and append the following to your JDBC url:
&clientCertificateKeyStoreUrl=file:/opt/stages/conf/truststore&&useSSL=trueclientCertificateKeyStorePassword=mypassword
  • The complete JDBC url should now look similar like this:
torque.database.default.url = jdbc:mysql://localhost:3306/stages?zeroDateTimeBehavior=round&jdbcCompliantTruncation=false&useSSL=true&clientCertificateKeyStoreUrl=file:/opt/stages/conf/truststore&clientCertificateKeyStorePassword=mypassword

Configure Virus Scanner

If you are using a virus scanner on your Stages server, please exclude all MySQL database files from analysis operations as this might corrupt your database. Also excluding Stages installation directory and Java installation directory might significantly improve Stages performance.

Adjust Java Heap Space

Depending on the desired performance and the purpose of your Stages Server, we strongly suggest to adjust the Java heap space according to the following values:

  • Low-range system: 4096 MB or more
  • Mid-range system: 8192 MB or more
  • High-range system: 16384 MB or more

Please check System Requirements for Stages 7.2, 7.3 and 7.4 for detailed information on the range levels.

To adjust the Java heap space settings please proceed as follows:

  • Windows:
    • Open file “<Stages installation path>\stages\config.bat”
    • Modify the red colored setting: set TOMCAT_OPTS=–JvmMx=<RAM in MB>
    • Open a cmd with administrative permissions and navigate to folder “<Stages installation path>\stages\bin”
    • Reinstall the Stages service: reinstallService.bat
    • Restart Stages service: net start stages
  • Linux:
    • Open file “<Stages installation path>/stages/bin/rc.conf”
    • Modify the red colored value: CONF_TOMCAT_OPTS=“-Xmx<RAM in MB>m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow”
    • Restart the Stages service: stages restart

Search engine memory

Depending on the size of your database it can be necessary to adjust the memory settings of the search engine. To do that open the file “<Stages installation path>elasticsearch/config/jvm.options”.

Adjust the lines 

-Xms1g
-Xmx1g

After that restart the Stages search service.

Install customer specific metamodel (if available)

If a customer specific metamodel has been migrated from Stages V6 to V7 by a Method Park product consultant, this metamodel will be provided as *.mm file. To install the metamodel please proceed as follows:

  • Windows:
    • Copy the *.mm file to directory: “<Stages installation path>\stages\conf\model”
    • Open a CMD with administrative permissions
    • Stop the Stages service: net stop stages
    • Navigate to folder: “<Stages installation path>\stages\bin”
    • Execute command: update.bat
    • Restart the Stages service: net start stages
  • Linux:
    • Copy the *.mm file to directory: “<Stages installation path>/stages/conf/model”
    • Stop the Stages service: stages stop
    • Execute command: stages update
    • Restart the Stages service: stages start

Install Fonts

If you want to work with international UTF-8 charsets (e.g. Chinese), we suggest to install and configure Stages to use dedicated fonts:

  • Windows:
    • Process visualizations: Arial Unicode MS (subject to add. license conditions)
    • PDF Print: Arial Unicode MS (subject to add. license conditions)
  • Linux:
    • Process visualizations: DejaVu Sans Condensed (license free)
    • PDF Print: Arial Unicode MS (subject to add. license conditions)

Configuring font for Stages process visualizations (metamodel: Unified Configuration) [STAGES 7.4.4.4 and earlier]:

  • Windows:
    • Unzip: “<Stages installation path>\stages\conf\model\unified_configuration.mm” to “<Stages installation path>\stages\conf\model\unified_configuration”
    • Open file: “ <Stages installation path>\stages\conf\model\unified_configuration\diagram\trunk\configs\scriptconfig.js”
    • Adjust the following setting: var FONTNAME = “Arial Unicode MS”;
    • Repeat this step for file: “ <Stages installation path>\stages\conf\model\unified_configuration\diagram\trunk\configs\scriptconfig-bpmn_classic.js”
    • Add the diagram.font.list property to your config.xml file in the following way: <property name=“diagram.font.list” value=“Arial Unicode MS:/destinationOfYourFontFile/arialuni.ttf”/>
    • Execute: “<Stages installation path>\stages\bin\update.bat”
  • Linux:
    • Unzip: “<Stages installation path>/stages/conf/model/unified_configuration.mm” to “<Stages installation path>/stages/conf/model/unified_configuration”
    • Open file: “<Stages installation path>/stages/conf/model/unified_configuration/diagram/trunk/configs/scriptconfig.js”
    • Adjust the following setting according to the font to be used:
      var FONTNAME = “Arial Unicode MS”;
      var FONTNAME = “DejaVu Sans Condensed”;
    • Repeat this step for file: “<Stages installation path>/stages/conf/model/unified_configuration/diagram/trunk/configs/scriptconfig-bpmn_classic.js”
    • Add the diagram.font.list property to your config.xml file in the following way: <property name=“diagram.font.list” value=“DejaVu Sans Condensed:/destinationOfYourFontFile/arialuni.ttf”/>
    • Execute: “<Stages installation path>/stages/bin/update”

Caution: If Stages doesn't recognize your font via the config.xml, please additionally set the JVM parameter to the path of your fonts folder: -Dsun.java2d.fontpath=“c:/yourownfolder”.

Configuring font for Stages process visualizations (metamodel: Unified Configuration) [STAGES 7.4.4.5 and newer]:

  • Make sure the scriptconfig.js in your metamodel is up to date and contains var FONTNAME = availableFontFamilies.getConfiguredFont();
  • Place the custom font in your conf/fonts folder
  • Add the diagram.font property to your config.xml file in the following way: <property name=“diagram.font” value=“DejaVu Sans Condensed:DejaVuSansCondensed.ttf”/>
  • Execute: “<Stages installation path>/stages/bin/update”

Configuring font for Stages PDF printing:

  • Windows:
    • Open file: “<Stages installation path>\stages\conf\config.xml”
    • Adjust the following property: <property name=“pdf.font.list” value=“C:\WINDOWS\Fonts\ARIALUNI.TTF” />
  • Linux:
    • Open file: “<Stages installation path>/stages/conf/config.xml”
    • Adjust the following property: <property name=“pdf.font.list” value=“/usr/share/fonts/TTF/arialuni.ttf”/>

Install Stages license

  • Windows:
    • Execute the Stages license installer with administrative permissions on the Stages server.
    • The Stages service will be restarted automatically.
  • Linux:
    • Extract the .tar.gz archive to folder “<Stages installation path>/stages/conf”.
    • Restart the Stages service: stages restart

Configure SSL

To encrypt all connections between the users and Stages, we strongly recommend to configure SSL for the Stages server.

  • Ask for a DNS alias for the server, e.g. “stages.company.com”
  • Ask for a SSL certificate for the server which refers to the above alias. Depending on your local procedures, this might require creating a certificate request (see https://www.digicert.com/csr-ssl-installation/tomcat-keytool.htm for more info).
  • Import the SSL certificate into a keystore (see link above for more info)
  • Configure Tomcat to use this SSL certificate (see link above for more info). The relevant Tomcat config file is located in conf/server.xml and the SSL info needs to be configured for each <Connector> section. After updating the config file, run bin/update.sh or bin\update.bat to install it at the correct location.
  • To enforce redirection from http to https add the following to conf/web-customer.xml. This needs a Stages Version > 7.4.2.0.
    <security-constraint>
    <display-name>Enforce HTTPS</display-name>
    <web-resource-collection>
        <web-resource-name>stages-public</web-resource-name>
    </web-resource-collection>
    <user-data-constraint>
        <description>Force SSL for all connections.</description>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>
  • Enable global secure mode for Stages to set the neccessary headers for cross site scripting prevention in config.xml
[...]
<properties>
    [...]
   <property name="global.secureMode.enabled" value="true"/>
</properties>
[...]

Accessing Stages

After successful installation process - Stages is accessible via web browser by URL https://localhost:8443 or http://localhost:8080 (depending on the SSL port)

Prepare Stages for productive usage

Users

Delete all users except Superuser and Default, especially the demo users.

Workspaces

Delete the workspaces “Samples” and “Proof of Concept” or move them under “Archive”.

Further setup

Please contact your Method Park Product Consultant to further adapt the Stages process content for productive usage.