Installation

Installing the Designer

In the following section:

To install the Designer:

  1. Download the Semarchy Convergence for DI distribution ( semarchy-di-designer.zip) corresponding to your platform.
  2. Uncompress the semarchy-di-designer.zip file in your machine. This will create a semarchy_di sub-folder. This sub-folder will be referred to as <semarchy_di> (the Semarchy Convergence for DI installation directory).
  3. Start Convergence for DI Designer
  4. When the DI Designer starts, it prompts you for the license key.
  5. In the Please validate your product dialog, enter in the Key the key string that was provided to you by Semarchy.
  6. Click the Apply button.
  7. After registering the license key, you must create the folder into which the DI Designer will store its data. This folder in your local machine is the Workspace. Semarchy DI Designer prompts creates by default a workspace folder in its installation directory. To install it in a different location:
    1. In the Workspace Launcher window, click the Browse button.
    2. In the Select Workspace Directory dialog, select the folder into which the workspace will be created.
  8. Click OK to create the workspace and open it. The Semarchy Convergence for DI Designer window opens on the Introduction page. This page provides access Overview, Tutorials and Web Resource pages.
  9. Click the Workbench link to open the newly created workbench.

Directories Contents

The <semarchy_di> directory contains the following sub-folders:

Installing the Runtime Engine

Important: The Runtime Engine is not shipped as a standalone installer or package. It is deployed the first time you start a Designer in the /runtime sub-folder. You must first install and start a designer in order to deploy runtime engines on your servers.

Before you begin the installation:

Installing the Runtime Engine on Linux/UNIX

To install the runtime engine:

  1. Transfer the runtime directory from a Semarchy Convergence for DI Designer installation to the target folder.
  2. Grant execution permissions for the SH files in the target runtime folder.
  3. Grant write permission in the temp, build and sessions sub-directories.
  4. Create and set a STAMBIA_HOME environment variable pointing to the runtime folder.
  5. If required, edit the engine configuration, as explained in the following sections.
  6. Start the engine using the ./startengine.sh command from the runtime folder.

Installing the Runtime on Windows

To install the runtime engine on Windows:

  1. Transfer the runtime directory from a Semarchy Convergence for DI Designer installation to the target folder.
  2. If required, edit the engine configuration, as explained in the following sections.
  3. Start the engine using the startengine.bat command from the runtime folder.

To configure the runtime engine as a windows service, use the following scripts available in the runtime directory:

Semarchy support services may request that you modify the service configuration using the external\stambiaService\conf\stambiaEngine.conf file. You do not need to edit this file for a standard configuration.

Warning: Any parameter change in the properties sub-folder requires that you remove and reinstall the Windows service to take these changes into account.

Tip: The user used to start the Runtime Engine as a Windows service should be changed to a user with network abilities, usually a domain user.

Installing and Configuring Additional Drivers

To connect or use database technologies with their own drivers, you must add these drivers to your Architecture and Setup Guide installation for each machine running a Runtime Engine or Designer.

To install and configure an additional driver:

  1. Copy the driver file (.jar) into the runtime/lib/jdbc/ folder.
  2. Stop and restart the Runtime Engine or/and the Designer. The runtime automatically takes into account the new driver from that folder.
  3. If Designer is installed, you must declare the driver into the workspace.
    1. Open Designer and connect to your workspace.
    2. Select Window > Preferences
    3. In the preferences, select SQL Explorer > JDBC Drivers.
    4. Click the Add button.
    5. In the Name field, enter the name of your driver.
    6. In the Example URL field, enter an example URL for this driver.
    7. Select the Extra Class Path tab and then click the Add JARs... button.
    8. Browse and select the JAR File(s) required for your driver. They should be located in the runtime/lib/jdbc/ sub-folder of your Architecture and Setup Guide installation.
    9. Click List Drivers and then select your driver class name in the Driver Class Name field.
    10. Click OK to create the new driver.
    11. Click OK to close the preferences.

Configuring the Engine

Environment Variables

Two environment variables are used by the runtime engine and may have to be set specifically for your configuration:

Note: In order to facilitate future upgrades of the runtime engine, it is recommended to copy the properties sub-directory to another location and to set the STAMBIA_PROPERTIES_LOCATION environment variable to points to this new location. With such a configuration, an entire replacement of the runtime folder for an upgrade will not erase the configuration.

Log Storage Database

If you want to store logs in a specific database schema, you must configure a connection to this database.

To configure this connection, add in the properties/logs sub-folder a file configuring the connection the database, and name it log[name].xml where [name] describes the database to connect.

Tip: Sample connection files are available from the properties/logs/samples sub-folder.

The example below is a connection to an Oracle database.

<?xml version="1.0" encoding="UTF-8"?>
<repository>
<logs>
<log userLogName="oraclePROD" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog" enable="false">
	<parameter name="userLogRdbmsDriver" value="oracle.jdbc.driver.OracleDriver"/>
	<parameter name="userLogRdbmsUrl" value="jdbc:oracle:thin:@[host]:[port]:[sid]"/>
	<parameter name="userLogRdbmsUser" value="user"/>
	<parameter name="userLogRdbmsPassword" value="password"/>
	<!-- parameter name="userLogRdbmsEncryptedPassword" value="password"/ -->
	<parameter name="userLogRdbmsVarcharType" value="varchar2"/>
	<parameter name="userLogRdbmsVarcharMaxSize" value="4000"/>
	<parameter name="userLogRdbmsClobType" value="clob"/>
	<parameter name="userLogRdbmsBlobType" value="blob"/>
	<parameter name="userLogRdbmsNumericType" value="number"/>
	<parameter name="userLogRdbmsDeleteSyntaxe" value="Delete from"/>
	<parameter name="userLogRdbmsdeliverableFormat" value="text"/>
	<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
	<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
	<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
</log>
</logs>
</repository>

In the example, you can modify the following parameters to connect to your own Oracle database and schema:

After creating the connection file, reference it from the runtime/properties/engines/commonParameters.xml by adding the following line:

<include file="../logs/log[name].xml"/>

Finally, in the commonParameters.xml file, specify the default logging storage. Note that the value specified must match the userLogName value from the connection configuration file.

<engineParameters>
	<parameter name="userLogDefaultName" value="OraclePROD"/>
	<!-- The value specified must match the userLogName value from the connection configuration file-->
	…
</engineParameters>

Listening Ports

In the engineParameters4200.xml file, or in a copy of this file, change as needed the RMI, SOAP, etc. listening ports.

<engineParameters>
…
<parameter name="rmiPort" value="42000"/>
	<!--<parameter name="rmiCallbackPort" value="42000"/>-->
	<parameter name="internalDbTcpPort" value="42100"/>
	<parameter name="internalDbWebPort" value="42101"/>
	<parameter name="soapServerPort" value="42200"/>…
</engineParameters>

Note: It is recommended when changing the ports to copy the file and name the copy with the number of the RMI port. For example: engineParameters5500.xml

Schedules Storage

By default, the scheduler stores the schedules in an embedded database. It is possible to change this storage to another location.

When the org.quartz.jobStore.dataSource property is set to internal (which is the default value), the scheduler stores its schedules in the runtime embedded database.

To store schedules in a different database, you must first create a database schema, and run in this schema the script to seed the storage structure. Scripts for the supported database technologies are available from the /scripts/scheduler/ sub-folder.

Then you must configure the /properties/engineScheduler.properties file to connect to this new storage, as shown in the example below for an Oracle Server.

org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
org.quartz.jobStore.useProperties=false
# org.quartz.jobStore.dataSource=internal
org.quartz.jobStore.dataSource=database01
org.quartz.jobStore.tablePrefix=QRTZ_
org.quartz.jobStore.isClustered=false
#============================================================================
# Configure Datasources
#============================================================================
org.quartz.dataSource.database01.driver = oracle.jdbc.driver.OracleDriver
org.quartz.dataSource. database01.URL = jdbc:oracle:thin:@[host]:[port]:[sid]
org.quartz.dataSource.database01.user = oracle_user 
org.quartz.dataSource.database01.password = oracle_password
org.quartz.dataSource.database01.maxConnections = 5
org.quartz.dataSource.database01.validationQuery=

Other Parameters

Services Startup

It is possible to select those of the services (Scheduler, SOAP, Embedded H2 Database) should be started with the runtime engine.

The parameters for the services are located in the engineParameters42000.xml and commonParameters.xml files

<parameter name="startInternalDb" value="true"/> Start embedded H2 database
<parameter name="startSoapServer" value="true"/> Start SOAP service
<parameter name="launchSchedulerEngine" value="true"/> Start scheduler
<parameter name="launchExecutionEngine" value="true"/> Start execution engine
<parametername="launchReportEngine" value="true"/> Start reporting

Note: A standard runtime engine should at least start the Execution Engine and Reporting.

Folders Configuration

In the commonParameters.xml file, two folder parameters should be reviewed and modified as needed.

<parameter name="deliverableFolder" value="build/deliveries"/> Location of the deliveries
<parameter name="temporaryFolder" value="temp"/> Runtime temporary folder

Start an Engine with a Specific Configuration File

A runtime can start with a specific configuration file.
To specify this file, use the STAMBIA_CONF_FILE_LOCATION environment variable.

By default, the value configured in the file initvariable.sh|bat in the following line:

STAMBIA_CONF_FILE_LOCATION=$STAMBIA_PROPERTIES_LOCATION/engineParameters.xml

Automating Log Purge

You can configure an automatic purge of the runtime session logs.

To automate the log purge:

  1. Run the startcommand.sh (Linux/UNIX) or startcommand.bat (Windows) script.
  2. Use the following command to schedule a log purge.
schedule  purge keep <number> <minute|hour|day|session>  
			cron <cronExpression> 
			[sessionname <name,name2,...>] 
			[status <done,error,killed>] 
			[on host <hostname>] 
			[port <hostport>]

The command defines:

For example, to keep 90 days of log history for all jobs and schedules and purge every evening at 23:00:

schedule purge keep 90 day cron "0 0 23 * * ?"