This chapter contains all appendixes related to the Operating Guide

Convertigo Java System Properties

Some Java System Properties can modify the behavior of your Convertigo instance.

All settings of the Administration Console Configuration page can be overridden by launching’s parameters.

To set a Java System Property when the JVM is launched, just a -Dconvertigo.engine.{property key}={property value}.

For servers, this can be done by customize the JAVA_OPTS environment variables of launch scripts.

{property key}={property value} are exactly the same as the {convertigo workspace}/configuration/engine.properties content.

All keys, description and default values can be found in this source file.

Example for change the engine log filename and disable the automatic project zip backup:

export JAVA_OPTS="-Dconvertigo.engine.log4j.appender.CemsAppender.File=/tmp/myConvertigo.log -Dconvertigo.engine.project.zip_backup_old=false"
# then run the convertigo server

Convertigo workspace

Convertigo plugin and war contain static data, that are not subject to be modified by the user. All other files are in a user directory: the Convertigo workspace.

This section presents the Convertigo workspace, as well as information about setting this directory or updating it:

Presentation of Convertigo Workspace

The Convertigo workspace is a directory external to the installation directory into which the user has write permissions. This workspace contains all Convertigo user data: the projects, the configuration files, the logs, etc.

The default location of the Convertigo workspace depends on the Convertigo type (Studio/Server), the Operating System and the Application Server (for Servers). See the appropriate installation documentation for each case.

The Convertigo workspace contains the following folders and data:

  • cache: this folder contains the file cache repository, including the cached responses,
  • certificates: this folder contains the Convertigo installed certificates (client or server),
  • configuration: this folder contains the configuration files for the Convertigo engine,
  • databases: this folder contains HSQLDB databases files,
  • logs: this folder contains the Convertigo engine log files,
  • minime: this folder contains the default legacy emulator configurations as well as Convertigo licensed keys,
  • projects: this folder contains the Convertigo projects,
  • studio: this folder contains some Studio specific configurations,
  • xulrunner-work: this folder contains the work directory of embedded xulrunner for HTML connector.

Setting Convertigo workspace

It is possible, from Convertigo version 5.1.2, to specify the Convertigo workspace directory. This is done through:

  • JVM property
  • Installation wizard

JVM property

The Convertigo workspace path is provided through a JVM property:

-Dconvertigo.cems.user_workspace_path= < absolute_path_to_the_convertigo_workspace_directory>

If this JVM property is not provided, search for a file named .convertigo and located at the root of the user home. It contains a property giving the path to the Convertigo workspace:

cems.user_workspace_path= < absolute_path_to_the_convertigo_workspace_directory>

Installation wizard

If you are installing Convertigo Studio with installation package (on Windows), the Eclipse workspace path is configurable after installation at the Studio’s first start.

If you are installing Convertigo Server with installation packages (on Windows or on Linux/Tomcat), the Convertigo workspace path is configurable through the installation wizard.

If you are installing convertigo with war file, the Convertigo workspace can be specified, but it depends on the Operating System and the Application Server. Refer to the appropriate installation documentation depending on the Operating System and the Application Server.

Updating Convertigo workspace

It is possible to update the Convertigo workspace directory after installation, depending on the Operating System and the Application Server. See the appropriate installation documentation depending on the Operating System and the Application Server, or find below other cases.

Linux + Websphere configuration

If you are using WebSphere application server, and if you want to change the workspace directory after Convertigo installation, the Convertigo workspace can be specified in WebSphere console.

In left menu, expand Java and Process management > Process definition and select Java Virtual Machine. Then, edit Generic JVM arguments to add:

-Dconvertigo.cems.user_workspace_path= < absolute_path_to_the_workspace_directory>

You have to restart WebSphere server for Convertigo to use the new workspace location.

Connector monitoring windows

Two windows are connector monitors: the Legacy connector monitor and the HTML connector monitor.

This section presents both windows as well as the requirements needed for displaying these windows on several server environments:

Presentation of the connector monitoring windows

Convertigo Server includes two connector monitoring windows:

Legacy connector monitor

The Legacy connector monitor is a window that is used for monitoring the screens that are reached by the legacy connectors. It displays a graphical rendering of the legacy connectors currently in use in the active contexts of the Convertigo Server.

It is not instantiated by default after a Convertigo Server installation and has to be activated.

HTML connector monitor

The HTML connector monitor is a window that is used for monitoring the pages that are reached by the HTML connectors. It displays a graphical rendering of the HTML connectors currently in use in the active contexts of the Convertigo Server.

It is a necessary tool for the HTML connector to work in Convertigo Server. It is not always visible but it always exists after a Convertigo Server installation (using the Windows installer of the Linux installation file).

Activate the connector monitors on a Windows-based system

This section presents the common configuration to perform on Windows installed Convertigo Server before activating each of the monitors:

  • Interaction with desktop
  • HTML connector monitor display
  • Legacy connector monitor display

Interaction with desktop

After installing a Convertigo Server on a Windows operating system, the Convertigo Server is installed as a service. To be able to display the connector monitors, the service has to be authorized to interact with the desktop.

Activate service’s interaction with desktop on Windows

1 Open the properties window of the Convertigo Server service:

Figure A - 1: Convertigo Server service properties

2 You can also find a shortcut icon in Windows taskbar, named Convertigo Server. Right-click on this icon and select Configure… option:

Figure A - 2: Convertigo Server Tomcat Configurator

3 Switch to the Log On tab:

Figure A - 3: Log On tab of Convertigo service properties

4 Check the Allow service to interact with desktop option:

Figure A - 4: Activation of the desktop interaction on the Log On tab of Convertigo service properties

5 Click on the OK button to validate the option and close the window.

You may have to restart the service for the property to be completely taken into account.

HTML connector monitor display

Now that the service is authorized to interact with the desktop, any transaction execution using an HTML connector displays the HTML connector monitor.

Depending on Windows version, the monitor can appear directly on the desktop or popup indicates that the program wants to display a message. While accessing this message, the HTML connectors monitor appears:

Figure A - 5: HTML connector monitor

Every context that will use an HTML connector will the be displayed in the same monitor, added in a new a tab:

Figure A - 6: Several contexts in HTML connector monitor

This window must never be closed as it would cause Convertigo Server to be killed.

Legacy connector monitor display

To display this monitor, an option has to be configured in the Administration Console Configuration page, see Real-time activity monitoring.

After restarting the server, the Legacy connector monitor will appear next to the HTML connector monitor:

Figure A - 7: Legacy connector monitor

Every context that will use a legacy connector will the be displayed in the same monitor, next to others:

Figure A - 8: Several contexts in Legacy connector monitor

Activate the connector monitors on a Linux-based system

After installing a Convertigo Server on a Linux operating system, the HTML connector monitor is automatically instantiated in an XVNC.

To display the HTML connector monitor, you can directly launch a VNC player on port 5903.

To display the Legacy connector monitor, an option has to be configured in the Administration Console Configuration page, see “Real-time activity monitoring”.

After restarting the server, the Legacy connector monitor will appear next to the HTML connector monitor:

Differences between Convertigo Server and Convertigo Cloud in Administration Console

In Convertigo Cloud, a number of functionalities (pages or configurations) of the Administration Console are not accessible. This appendix lists these differences.

Pages

The following list shows the pages of the Administration Console that are not available at all in Convertigo Cloud:

  • Keys page

Configuration categories and settings

Configuration page of the Administration Console includes categories, in which is proposed the edition of settings.

This first list shows the categories of Configuration page that are not available at all in Convertigo Cloud’s Administration Console:

  • Legacy Carioca portal management category,
  • Billing system category.

This second list shows the settings that are not available in Convertigo Cloud’s Administration Console, from visible categories of Configuration page:

  • in Main configuration parameters category:
    • Convertigo Server application URL,
    • (Linux only) Launch Xvnc server using DISPLAY environment variable at startup,
    • Linux only) Depth parameter for the Xvnc, default is 16,
    • (Linux only) Geometry parameter for Xvnc, default is 320x240,
    • Enable the compatibility mode for projects data (required for JSP usage); engine restart required,
  • in Log management category:
    • Log4J default appender,
    • Log4J default appender file,
    • Log4J default appender layout,
    • Log4J audit appender file,
    • Log4J audit appender layout,
  • in HTML parser configuration category:
    • XulRunner path,
    • XulRunner work directory,
  • in Cache management category:
    • Cache manager class,
    • File cache directory.

Analytics in Convertigo Server

In Convertigo Server, an analytics feature is available.

This section presents the analytics feature, as well as more detailed information:

Analytics feature

The analytics feature is available in Convertigo Server, as well as for the Convertigo engine embedded in the Studio, but not in Convertigo Cloud. It can be activated in the Configuration page of the Administration Console, in Analytics tab.

The analytics feature consists in writing in a database one entry, also known as ticket, for each executed transaction or sequence. This is useful to monitor the Convertigo Server’s activity. The analytics feature produces the raw data, but the management and treatment of these data has to be manually performed and personalized by each Convertigo administrator.

Ticket content

For each execution of a transaction or sequence, a ticket is inserted in the database. The Ticket table contains the following columns:

Table A - 1: Ticket table columns

Column name Type Description
id bigint(20) PK The primary key of the record, it is an auto-incremented integer.
clientIp varchar(255) The IP address of the client that called the transaction or sequence.
In the case of a transaction or sequence called by a Call Transaction or Call Sequence step, the IP address is 127.0.0.1.
connectorName varchar(255) The name of the connector containing the executed transaction, in case of a transaction. Empty in the case of a sequence.
connectorType varchar(255) The type (the name of the Java class) of the connector containing the executed transaction, in case of a transaction.

For example: HtmlConnector, JavelinConnector, SqlConnector, HttpConnector, etc.

Empty in the case of a sequence.
creationDate bigint(20) The ticket creation date and time (as a timestamp).
customerName varchar(255) Contains a predefined value:
• CONVERTIGO Studio in case of an execution in a Studio, or
• CONVERTIGO Server in case of an execution in a Server.
projectName varchar(255) The name of the project containing the executed transaction or sequence.
requestableName varchar(255) The name of the executed transaction or sequence.
requestableType varchar(255) The type (the name of the Java class) of the executed transaction or sequence. For example: GenericSequence, HtmlTransaction, JavelinTransaction, SqlTransaction, XmlHttpTransaction, HttpTransaction, etc.
responseTime bigint(20) The response return date and time (as a timestamp).
score bigint(20) The score calculated for this execution. Depending on the executed object, the score is different and calculated with the following method:
• the number of detected screen classes for a transaction executed in one of the connectors with screen classes (Legacy, HTML),
• 1 for another transaction execution (SQL, HTTP, …),
• 0 for a sequence execution.
userName varchar(255) The username defined for the execution, which is:
• the value of the username property set in the context of execution of the transaction or sequence:
• set using the expression context.set(“username”, “value”)
• retrieved using the expression context.get(“username”),
• the Carioca portal username, of if no Carioca portal is used, the default Carioca portal username:
• set in the Administration Console Configuration page, in Legacy Carioca portal tab, using property Default user name,
• user if no previous value is set.

The SQL connector allows to connect to several types of databases. You can refer to the SQL connector documentation in the Reference Manual for more information about SQL connector and its configuration properties.

The type of database accessed by the SQL connector can be configured through the Driver property. Depending on the selected driver, Convertigo can or cannot deliver the needed jar file for execution.

When possible, Convertigo directly delivers the jar file needed to run code for connecting to the database. But sometimes, it is impossible to do so, because this jar file is not free.

In this case, Convertigo provides a fake jar instead, already declared in the software. When trying to execute, a log is displayed in the engine logs to warn you about this.

To run your SQL connector correctly, you only need to:

  • get the correct jar file by your own
  • rename it to match the Convertigo jar file name
  • replace the fake jar in Convertigo by the real one:
    • in Convertigo Studio, jar files are located in < Convertigo Studio installation folder>pluginscom.twinsoft.convertigo.studio_x.y.z.v12345lib
    • in Convertigo Server, jar files are located in < Convertigo Server installation folder>tomcatwebappsconvertigoWEB-INFlib
  • and re-start Convertigo (Studio or Server).

The following table shows the matches between SQL Driver, jar file, and their presence or not in Convertigo for running:

Table A - 2: SQL Drivers and jar files in Convertigo

Driver Database jar file name Delivered
sun.jdbc.odbc.JdbcOdbcDriver JDBC-ODBC bridge for accessing ODBC databases rt.jar (delivered in Java) true
com.ibm.as400.access.AS400JDBCDriver IBM AS400 database jt400.jar true
com.mysql.jdbc.Driver MySQL database mysql-connector.jar false (fake jar)
net.sourceforge.jtds.jdbc.Driver Microsoft SQL Server database jtds-1.2.2.jar true
org.hsqldb.jdbcDriver HSQLDB database hsqldb.jar true
com.ibm.db2.jcc.DB2Driver IBM DB2 Server database db2jcc.jar
+ db2jcc-licence.jar
false (fake jars)
oracle.jdbc.driver.OracleDriver ORACLE database ojdbc5.jar true
org.mariadb.jdbc.Driver MariaDB database, community-developed fork of MySQL mariadb-java-client-1.1.3.jar true