Runtime Installation and Configuration Guide

Pre-requisites for Installation

In order to execute Stambia Runtime, your system must meet the following requirements:

Operating System:
- The Runtime can be installed on any system having a Java Virtual Machine (JVM)

Memory / CPU
- The memory and CPU capacity required will depend on the flows that are executed

Disk Space
- The system must have at least 80 MO of free disk space

Java Virtual Machine
- JVM version 1.6 or higher

Note: On a 64-bits system you should use a 64-bits JVM for better performance and compatibility.
Runtime versions prior to S17.1.17 used to require a JDK (Java Development Kit) for publishing Web Services.
For higher versions, a JVM is suffisant.

Warning: Careful, because of identified bugs, version 1.6.0.27 of the Java environment is forbidden.

Stambia Runtime Installation

Installing the Runtime on a Linux/Unix environment

Preliminary steps

1. Install a Java Virtual Machine (JVM) 1.6 or higher
2. Set the environment variable STAMBIA_JAVA_HOME to the folder situated located just before the “bin” folder in your JDK

Runtime Installation

1. Unzip the archive which has been downloaded into the target folder
2. Set the execution permissions on the SH files at the root (if needed)
3. Set the write permissions, especially on the directories: ‘temp, ‘build’ and ‘sessions’
4. Modify the engineParameters.xml file, as explained below.
5. If needed create the file engineScheduler.properties, as explained below
6. If necessary, put the ‘sh’ in the starting processes of the Linux server (this procedure depends on the system)

Some environment variables may be modified:

• STAMBIA_JAVA_HOME : path of the JVM that is used
• STAMBIA_PROPERTIES_LOCATION: path of the ‘properties’ folder
• STAMBIA_INIT_MEMORY: Runtime’s JVM initialization memory
• STAMBIA_MAX_MEMORY: Runtime’s JVM maximum memory
• STAMBIA_STACK_SIZE: Runtime’s JVM stack size

Note: In order to ease updates, it is recommended to copy the Stambia ‘properties’ folder into another place and to set the parameters of the STAMBIA_PROPERTIES_LOCATION variable so that it points to it. In this way, Runtime updates can be made by replacing the whole arborescence. The configuration data of the ‘properties’ folder will not be lost, since it will be elsewhere.

Installing the Runtime on a Windows environment

Please refer to Linux/Unix installation, except for points 2 and 6 that are not useful in Windows.

Service installation

The runtime can be easily installed as a Windows service if needed.
For this, navigate to the root directory of the Runtime and use the following commands:

1. use the installEngineAsService.bat -i [<serviceName>] command to install the service
2. use the installEngineAsService.bat -r [<serviceName>] command to remove the service

The <serviceName> parameter can be useful to install multiple Runtimes on the same machine.
If not set the service will be named ‹Stambia Runtime›.

The file «stambiaEngine.conf» which is in the folder external\stambiaService\conf can be used to configure some of the service’s properties. By default, it is not useful to modify this file.

Warning: Any modification of Stambia Runtime files or parameters (in “properties” or in the ‘.bat’ files) requires the removal and reinstallation of the Windows service, so that these modifications may be taken into account.

Tip: The specified user used to launch the Runtime (Windows service) should be changed to a user with network abilities, usually a domain user.

Upgrading in a few steps

After downloading the desired Runtime ZIP archive, proceed through the steps listed below.

We assume your current Runtime is installed into a directory named «stambiaRuntime».

1. Install the new Runtime in a new directory, something like "stambiaRuntime_new"
2. On UNIX/Linux systems make sure that all the stambiaRuntime_new/*.sh files are executable
3. Stop the old Runtime and make a backup
4. Copy the content of the following directories from the old Runtime to the new Runtime:
   1. stambiaRuntime\build\deliveries
   2. stambiaRuntime\build\packages
   3. stambiaRuntime\lib\addons (if you have additional libraries added to the Runtime)
   4. stambiaRuntime\properties (if you have set some properties)
   5. stambiaRuntime\scheduler (if you are using the Runtime’s scheduler)
   6. stambiaRuntime\sessions (if you use the Runtime’s internal log database)
   7. Optionally: stambiaRuntime\temp (if your Processes store specific files intentionnally in this directory)
5. Install the required Jdbc jar files into stambiaRuntime_new/lib/jdbc (do not overwrite the new Runtime’s Jdbc jar files!)
6. Rename the old Runtime’s directory to something like "stambiaRuntime_old"
7. Rename the new Runtime’s directory to "stambiaRuntime"
8. Apply the read / right permissions to the new folder as it was set on the old one
9. If the Runtime is installed as a Windows service, remove and re-install the service
10. Start the Runtime

Runtime Configuration

Most of the Runtime’s configuration is done in the properties/engineParameters.xml file

This file allows to manage:

• The engine parameters (such as started services, listening ports, ...)
• The security of the Runtime (hostname and user / password restriction, roles)
• The repositories where the deliveries are stored
• The Java additional options to add at Runtime’s startup
• The log database configuration

Defining the started services

The services exposed by the Runtime, such as the scheduler, the SOAP component, or the internal Java database can be turned off if needed.
By default, they are all launched at the Runtime’s startup.
To specify which services should be started:

1. Open the engineParameters.xml file
2. Update the parameters accordingly to your needs.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="launchSchedulerEngine" value="true"/>
		<parameter name="launchExecutionEngine" value="true"/>
		<parameter name="launchReportEngine" value="true"/>
		<parameter name="startInternalDb" value="true"/>
		<parameter name="startSoapServer" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

The following parameters are available:

Defining the services ports

The services exposed by the Runtime are running on defined port, that can indeed be modified easily.

1. Open the engineParameters.xml file
2. Update the following parameters accordingly to your needs.

<parameters>
	<...>
	<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>
	<...>
</parameters>

Defining the log database

The Runtime stores the information about sessions' execution in a log database.
This database is by default an internal H2 database, that is shipped with the Runtime and started with it.

This offers a ready-to-go environment that can be used immediately.
We however recommend changing it to a more robust database such as Oracle, Microsoft SQL Server (MSSQL), etc for production use.
You will need to provide to Stambia Runtime a user having read and write permissions on the chosen database/schema.

Here is how to change the log database of the Runtime:

1) Open the engineParameters.xml file
The configuration is performed in this file, which contains samples for the most known databases.

2) Modify the log database parameters as explained below.
This consists of defining the JDBC URL, user, password, schema, ... where the log database will be located.

3) Restart the runtime
All necessary tables will be created automatically the first time the log database is initialized

Log database parameters

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<parameter name="defaultSessionLogLevel" value="400"/>
		<...>
	</engineParameters>
	<...>
	<logs>
		<...>
		<log userLogName="logDatabase" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog">
			<parameter name="userLogRdbmsDriver" value="org.h2.Driver"/>
			<parameter name="userLogRdbmsUrl" value="jdbc:h2:tcp://localhost:42100/sessions/internalDb/sessionLogs"/>
			<parameter name="userLogRdbmsUser" value="sa"/>
			<parameter name="userLogRdbmsPassword" value=""/>
			<!--<parameter name="userLogRdbmsEncryptedPassword" value=""/>-->
			<parameter name="userLogRdbmsVarcharType" value="varchar"/>
			<parameter name="userLogRdbmsVarcharMaxSize" value="1000"/>
			<parameter name="userLogRdbmsNumericType" value="numeric"/>
			<parameter name="userLogRdbmsClobType" value="clob"/>
			<parameter name="userLogRdbmsBlobType" value="blob"/>
			<parameter name="userLogRdbmsSchemaName" value="logs"/>
			<parameter name="userLogRdbmsUseSchemaNameForIndexCreation" value="true"/>
			<parameter name="userLogRdbmsDeleteSyntaxe" value="Delete from"/>
			<!--<parameter name="userLogRdbmsTablePrefix" value="STB_LOG_"/>-->
			<!-- bestCompression / bestSpeed / default-->
			<parameter name="userLogRdbmsCompressedLevel" value="bestCompression"/>
			<!-- text / binary / compressed-->
			<parameter name="userLogRdbmsDeliveryFormat" value="compressed"/>
			<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
			<!-- -1 : infinite -->
			<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
			<!-- binary / compressed-->
			<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
			<parameter name="userLogRdbmsTimestampQuery" value="select now()"/>
			<parameter name="userLogRdbmsInactivityDetectionPeriod" value="90000"/>
			<parameter name="userLogRdbmsActivityRefreshInterval" value="60000"/>
			<parameter name="userLogRdbmsDeletionWithNotExists" value="true"/>
			<!--<parameter name="userLogRdbmsIndexCreationOption" value=""/>-->
			<!--<parameter name="userLogRdbmsTableCreationOption" value=""/>-->
		</log>
		<...>
	</logs>
	<...>
</parameters>

User Log Default Name

The «userLogDefaultName» is used to define which configured log database should be used.
This corresponds to the «userLogName» attribute which can be found in the log database configuration nodes(<log></log> nodes)

Default Session Log Level

The «defaultSessionLogLevel» defines what level of information is logged inside log database for each session executed by the Runtime.
The higher the value is the higher information are logged.
Possible values are the following: -1, 0, 100, 200, 300, 400

Note that is applies only for sessions on which the log level is not defined manually at execution.
Refer to the runtime parameters reference part of this documentation for details information about each value.

Log part

This is the part where you will configure the JDBC URL, user, password, schema, ... to connect to the log database.
All necessary tables will be created automatically the first time the log database is initialized.
The initialization is performed the first time the Runtime is started on this log database.

Under <logs></logs> node, you can find commented examples of configuration for several databases systems.
You can use these examples to configure your log database accordingly to the target database system which will be used.

The Runtime will use as log database the <log></log> node which «userLogName» attribute value corresponds to the «userLogDefaultName» parameter value.

If you uncomment the examples nodes to, you’ll therefore have to be careful to keep only one <log></log> node which «userLogName» attribute value corresponds to the «userLogDefaultName» parameter value.

Example

The example below is for an Oracle database:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<parameter name="defaultSessionLogLevel" value="400"/>
		<...>
	</engineParameters>
	<...>
	<logs>
		<...>
		<log userLogName="logDatabase" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog">
			<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="userLogRdbmsSchemaName" value="[SCHEMA_NAME]"/>
			<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="userLogRdbmsDeliveryFormat" value="text"/>
			<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
			<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
			<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
		</log>
		<...>
	</logs>
	<...>
</parameters>

The minimum to modify are the following parameters:

• userLogRdbmsUrl
• userLogRdbmsUser
• userLogRdbmsPassword
• userLogSchemaName

Note: Refer to the ‹Runtime parameter reference› part of this documentation for the list of all available parameters with explanations.

Defining Repositories

Repositories are the locations where the Runtime will look for the delivery files at execution.

There are two types of repositories:

• File Repositories: a location where .deliv files are stored on the filesystem.
• Http Repositories: permit to retrieve deliveries through HTTP protocol. The Runtime will connect to Stambia Analytics Deployment Managers in order to retrieve deliveries that are marked as Remotely Available.

To add, configure, and specify repositories:

1. Open the engineParameters.xml file
2. Configure the repositories

Example of repositories configuration:

<parameters>
	<...>
	<repositories>
		<fileRepository name="default" default="true" folder="build/deliveries/"/> 
		<fileRepository name="webService" default="true" folder="build/deliveries/wsdl/" webService="true" synchPollingInterval="10000" scanMode="polling"/>
		<httpRepository name="PROD" default="false" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" unreachableTolerancePeriod="30000"/>
	</repositories>
	<...>
</parameters>

Important: It is possible to specify multiple repositories on a same Runtime, but note that you can only set one as default for standard deliveries, and one as default for web service deliveries.

Tip: You can specify the repository name at execution time:
startdelivery.bat -name myDeliv -repository demo

File Repositories

scan Modes

1. polling: The Runtime will check periodically if new deliveries are available in the repository. This is useful only for deliveries exposed as web service. To define the polling interval, please see the synchPollingInterval parameter.
2. disable: The Runtime will not check for new deliveries in the repository. This means that the runtime must be restarted to take into account the web service deliveries that are manually added or modified in the repository. This do not apply for deliveries published from a Designer, that are automatically exposed.

Examples:

<parameters>
	<...>
	<repositories>
		<fileRepository name="defaultRepository" default="true" folder="build/deliveries"/> 
		<fileRepository name="wsdlRepository" default="true" folder="build/deliveries/wsdl/" webService="true" synchPollingInterval="10000" scanmode="polling">
		<...>
	</repositories>
	<...>
</parameters>

HTTP Repositories

Introduction

HTTP Repositories allow to retrieved automatically deliveries from a remote repository through HTTP protocol.
Those remote repositories are created and managed in Stambia Production Analytics.
Depending on Stambia Production Analytics versions, different parameters must be defined, as explained below.

Stambia Analytics 3.x.x

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Example:

<parameters>
	<...>
	<repositories>
		<...>
		<httpRepository name="analytics_3_label_for_this_repository" environment="analytics_3_environment_name_to_retrieve_deliveries_from" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" webService="false" default="false" unreachableTolerancePeriod="30000" />
		<...>
		<httpRepository name="analytics_3_label_for_this_webservice_repository" environment="analytics_3_environment_name_to_retrieve_deliveries_from" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" webService="true" default="true" unreachableTolerancePeriod="30000" synchPollingInterval="10000" scanMode="polling"/>
		<...>
	</repositories>
	<...>
</parameters>

Stambia Analytics 2.x.x

scan Modes

1. polling: The Runtime will check periodically if new deliveries are available in the repository. This is useful only for deliveries exposed as web service. To define the polling interval, please see the synchPollingInterval parameter.
2. disable: The Runtime will not check for new deliveries in the repository. This means that the runtime must be restarted to take into account the web service deliveries that are manually added or modified in the repository. This do not apply for deliveries published from a Designer, that are automatically exposed.

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Example:

<parameters>
	<...>
	<repositories>
		<...>
		<httpRepository name="PROD" default="false" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" unreachableTolerancePeriod="30000"/>
		<...>
	</repositories>
	<...>
</parameters>

Defining External Value Resolvers

What is an External Value Resolver?

There are lot of dedicated technologies which allow to store values such as usernames, passwords, paths, and more... in dedicated stores.

The goal of those technologies, such as HashiCorp Vault, is to store and secure those values and then provide them when they are needed.

You can easily work with those technologies in Stambia through the «External Value Resolver» component which allows to retrieve values from external technologies. You can, as an example, specify in your Metadata that the username and password should be retrieved automatically from an external system, which avoids keeping that sensitive information in your Metadata.

Configuring External Value Resolvers

When you want to retrieve values from external systems, you first have to configure External Value Resolvers.

An External Value Resolver is simply a configuration which allows to specify all required information to access the external system. You can define multiple resolvers and use all of them during your developments.

External Value Resolvers are configured in the Runtime and can then be used in your developments when you want to retrieve values from them automatically.

A resolver is defined as follow.

<externalValueResolver>
	<...>
	<resolver [prefix="unique_prefix_to_access_this_resolver"] class="resolver_plugin_class">
		 <parameter name="parameter_name" value="parameter_value"/>
		 <...>
	</resolver>
	<...>
</externalValueResolver>

Note that you can define multiple resolvers, simply define multiple «resolver» nodes under the «externalValueResolver» container, which must be unique in a Runtime configuration.

<externalValueResolver>
	<...>
	<resolver prefix="resolver_a" class="resolver_plugin_class">
		 <parameter name="parameter_name" value="parameter_value"/>
		 <...>
	</resolver>
	<resolver prefix="resolver_b" class="resolver_plugin_class">
		 <parameter name="parameter_name" value="parameter_value"/>
		 <...>
	</resolver>
	<...>
</externalValueResolver>

Main attributes

• prefix is a unique prefix which allows to identify the resolver, it will be used in your developments to retrieve values from it. It must be unique on each resolver you define. Note that defining the prefix attribute is optional. If you do not specify a prefix, the resolver will be used as default resolver when retrieving external values. Note that only one resolver can be defined without prefix.
• class is the java class of the resolver plugin to be used, which will depend on the external system which needs to be accessed. Stambia provides plugins for different systems, do not hesitate to contact us if you want to access a system we do not support yet.

Parameters

The parameters to define depend on the resolver plugin.

Each external system is different and therefore needs dedicated parameters.

Refer to the documentation of the resolver plugin you want to use for the list of available parameters.

Plugin – Simple External Value Resolver

Stambia is shipped with a simple external value resolver plugin which is available on a default installation.

It’s a sample resolver which allows to define key / value information directly inside this dedicated plain text file.

The class of this plugin is com.stambia.externalvalueresolver.impl.SimpleExternalValueResolverPlugin, and it is defined as follow:

Set Stambia Runtime configuration

<externalValueResolver>
	<resolver prefix="my_prefix_simple/" class="com.stambia.externalvalueresolver.impl.SimpleExternalValueResolverPlugin">
		<parameter name="filePath" value="path_to_a_plain_text_file"/>
		<parameter name="refreshMode" value="dynamic|onStartup"/>
	</resolver>
</externalValueResolver>

Mandatory parameters:

Optional parameters:

Specifying external values in the file

The external values are stored in a text file as key/value pairs (‹=› as separator) :

this_is_a_key=that_is_a_value
another_key=another_value
...

Use simple resolver

Once this resolver is defined, you can access its values in your developments through the following syntax:

%ext{[<resolver prefix>]<key path>}ext%

For the Simple External Value Resolver Plugin, the key path is simply the key name, as follow:

%ext{my_prefix_simple/key_a}ext%

Then, at execution this will be replaced automatically by the value retrieved from the resolver for the «key_a» key.

Plugin – Vault External Value Resolver

Stambia proposes a Vault external value resolver plugin which is available as an addon.

It’s a resolver which allows to retrieve values from HashiCorp Vault servers.

The class of this plugin is com.stambia.externalvalueresolver.vault.VaultExternalValueResolverPlugin, and it is defined as follow:

Set Stambia Runtime configuration

<externalValueResolver>
	<resolver prefix="my_prefix_vault/" class="com.stambia.externalvalueresolver.vault.VaultExternalValueResolverPlugin">
	 	<parameter name="host" value="vault-host-example.stambia.fr"/>
	 	<parameter name="port" value="80"/>
	 	<parameter name="scheme" value="http"/>
	 	<parameter name="token" value="encrypted_token"/>
	 	<parameter name="backendVersion" value="KV_2"/>
	 	<parameter name="startPath" value="secret/test/"/>
	</resolver>
</externalValueResolver>

You must have installed the Vault External Value Resolver Plugin to be able to work with it.
You can download it from Components download page on stambia.org, and install it as usual for additional plugins.

Mandatory parameters:

Token mandatory parameters:

The vaut token is mandatory, but there is 2 ways to set it.
Chosse regarding your context between:

Optional parameters:

Use Vault resolver

Once this resolver is defined, you can access its values in your developments through the following syntax:

%ext{[<resolver prefix>]<key path>}ext%

For the Vault External Value Resolver Plugin, the key path is the Vault’s path to access the key.

%ext{my_prefix_vault/kv/secrets/database/username}ext%

Then, at execution this will be replaced automatically by the value retrieved from Vault for the given path.

Note that if you configured a «startPath» on your Vault Resolver, the start path is added automatically at the beginning of the key path when resolving the value, so you must define only the last part of the key path.

As an example, if the startPath configured on the resolver is kv/secrets and you want to retrieve a Vault key which has the following path kv/secrets/database/username, you will need to retrieve it as follow.

%ext{my_prefix_vault/database/username}ext%

Using an External Value Resolver

Once your resolvers are configured in your Runtime, you can resolve values through, using the following generic syntax:

%ext{[<resolver prefix>]<key path>}ext%

• resolver prefix: The resolver prefix must correspond to the prefix of the External Value Resolver you want to access. If the resolver you try to access does not have a prefix defined, you can omit this part.
• key path: This part represents the key you want to retrieve. Depending on the resolver and plugin used, the key path to define will be different. Refer to the documentation of the resolver you are using to find the syntax of the path. When using HashiCorp Vault, for instance, the key path is the Vault’s key path, such as kv/secrets/database/username.

Troubleshooting

When working resolvers, you can face different errors that will give you some information why it fails to resolve a value.

Below are the main errors you might encounter and some advice to fix them.

The key does not exist.

When working with resolvers in your developments, you might encounter the following error when trying to resolve a key:

The key <key> does not exist.

or

The key does not exist.

This means that the Runtime was unable to find the specified key.

Make sure you enter a correct key path and that the key exists.

Make sure also that the resolver parameters are configured properly, for instance for Vault plugin that the «startPath», if it is defined, is correct.

There is no External Value Resolver configured which can handle the key

When working with resolvers in your developments, you might encounter the following error when trying to resolve a key:

There is no External Value Resolver configured which can handle the key <key>

This means that the Runtime did not find any resolver matching for the path you tried to resolve.

This is generally when the path you tried to resolve has a typo in the prefix for instance, so it does not find any matching resolver.

Make sure that you enter a path as follow:

%ext{[<resolver prefix>]<key path>}ext%

Then, make sure that, if you specified a prefix, that the prefix is correct and corresponds to an existing resolver.

Moreover, if you did not specify a prefix, make sure that there is a resolver without prefix available on the Runtime.

Finally, if all the above points are correct, make sure the resolver is configured properly in the Runtime you are executing, that the nodes are properly named and that it corresponds to what is presented in reference documentation for the plugin you are using.

An Exception occurred in a secured location. Please replace the parameters values

When working with resolvers in your developments, you might encounter the following error:

An Exception occurred in a secured location. Please replace the parameters values using %ext{}ext% syntax to obtain more information about the error.

This means that an unexpected error occurred in a secured location, where external values are implied, such as when performing a connection, and more...

When an error occurs in a secured location, which means a location where sensitive data are involved and retrieved through external resolvers, the real error is caught, and this generic message is returned instead.

This is by purpose, because we cannot control the exceptions returned by the various third-party libraries such as JDBC Drivers, etc, which may print some sensitive data in the error message, such as the value retrieve from the external resolver, which could be a security breach.

How to investigate?

When facing this error, as external values are resolved only in secured locations such as when performing connections, this may be because the values provided are wrong. (a wrong username is provided by the external value, a wrong password, ...).

Double check that the values on your external system are correct.

Moreover, if you want to see the real error, you can replace also temporarily the ext{}ext syntax by the real value and try executing again, to see if it still fails when providing the value directly instead of through a resolver.

Defining Java Additional Options

Java options are generally added to the Java command launching the Runtime with the -DmyOption01=value01 argument.
This part allows to set them directly in the Runtime’s Configuration file through the javaConfiguration node.
The options specified inside will be loaded just after the Runtime’s start.

1. Open the engineParameters.xml file
2. Set the additional options you want to add at Runtime’s startup.

The syntax is the following:

<parameters>
	<...>
	<javaConfiguration>
		<property name="myOption01" value="value01"/>
		<property name="myOption02" value="value02"/>
		<...>
	</javaConfiguration>
	<...>
</parameters>

Securing the Runtime

A Runtime installed with the default configuration can be accessed by anyone.

Any user can connect and make operations on it, such as listing or executing sessions.

This behavior can be configured easily in the Runtime Properties (engineParmeters.xml) , that offer the possibility to secure the connection through

• TLS secured RMI
• User / Password system with roles (permissions)
• Hostname / IP restriction
• HTTPS for Web Service Endpoints

A basic security configuration looks like this:

For TLS secured RMI:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiEnableTls" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

For user / hostname restriction:

<parameters>
	<...> 
	<security>
		<user anonymous="true" roles="Connect View"/>
		<user name="admin"  uncryptedPassword="admin" roles="Admin"/>
		<user name="developer"  uncryptedPassword="developer" roles="Connect View Execute"/>
		<user name="consult"  uncryptedPassword="consult" roles="Connect View"/>
		<allow address="192.168.0.42"/>
	</security>
	<...>
</parameters>

Warning: The security node must contain at least one user, which can be a normal or anonymous user.

For HTTPS Web Services:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
		<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
		<parameter name="webServiceKeyStoreType" value="JKS"/> 
		<parameter name="webServiceKeyStorePassword" value="password"/> 
		<parameter name="webServiceKeyPassword" value="password"/>
		<...>
	</engineParameters>
	<...>
</parameters>

TLS enabled RMI

Set the following parameter to true if you the RMI connection to be secured through TLS.
The RMI connection is used for instance to connect to the Runtime from the Designer or Analytics.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiEnableTls" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

User / Password Restriction and Roles

You can define the users that can connect to the Runtime and their permissions.

The syntax is the following:

<parameters>
	<...> 
	<security>
		<...>
		<user anonymous="true" roles="Connect View"/>
		<user name="user01"  password="encrypted password" uncryptedPassword="plain text password" roles="Connect View Execute"/>
		<user name="user02"  password="encrypted password" uncryptedPassword="plain text password" roles="Connect View Execute"/>
		<...>
	</security>
	<...>
</parameters>

The following parameters are available:

The following roles are available:

About the Anonymous User:

An anonymous user can be set, to specify the permissions of the users that connect to the Runtime without specifying credentials.

<user anonymous="true" roles="Connect View"/>

When the anonymous user is set, it is therefore not mandatory to specify credentials when connecting.
The connected user will have the permissions of the anonymous user.

When the anonymous user is not set, specifying credentials when connecting is mandatory.
Anonymous connections will then be rejected.

Note that only one anonymous user can be set at a time.

Notes:
* Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).
* Only one of the password or uncryptedPassword should be set
* Multiple roles can be assigned to one user, separated with space characters

Warning: The security node must contain at least one user, which can be a normal or anonymous user.

Hostname / IP restriction

You can define the hostnames / IP addresses that are allowed to connect to the runtime.

The syntax is the following:

<parameters>
	<...> 
	<security>
		<...>
		<allow address="Hostname or IP Address"/>
		<allow address="Another Hostname or another IP Address"/>
		<...>
	</security>
	<...>
</parameters>

Warning: The security node must also contain at least one user, which can be a normal or anonymous user.

Enabling HTTPS on Web Services Endpoints

Deliveries published as Web Service can be accessed through the different Web Services Endpoints exposed by the Runtime.
These endpoints can be accessed by default through HTTP using the URLs indicated on the console at Runtime’s startup.
This default behavior can be modified easily in the Runtime configuration file to enable the use of HTTPS, as explained below.

The following parameters are available to enable HTTPS:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
		<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
		<parameter name="webServiceKeyStoreType" value="JKS"/> 
		<parameter name="webServiceKeyStorePassword" value="password"/> 
		<parameter name="webServiceKeyPassword" value="password"/>
		<...>
	</engineParameters>
	<...>
</parameters>

And here is their description:

Configuring the scheduler

The scheduler shipped with the Runtime stores all the schedules into a database.
This database is by default an internal H2 database, that is shipped with the Runtime and started with it.

If you want to change this and store the schedules into another database:

• Create the necessary tables in the target database using the scripts that are in stambiaRuntime/scripts/scheduler
• Copy the stambiaRuntime/properties/samples/schedules/engineScheduler.properties into stambiaRuntime/properties
• Open it and configure it as explained below

When the property org.quartz.jobStore.dataSource is set to internal (which is the default), the scheduler stores its schedules in the internal database.
Therefore, change it to another name when you want to use another database.

Finally, define the datasource parameters to match the location where the tables are created.

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=STB_
org.quartz.jobStore.isClustered=false
#============================================================================
# Configure Datasources  
#============================================================================
org.quartz.dataSource.database01.driver =org.h2.Driver
org.quartz.dataSource.database01.URL = jdbc:h2:tcp://localhost:42100/scheduler/internalDb;SCHEMA=SCHEDULER
org.quartz.dataSource.database01.user = sa
org.quartz.dataSource.database01.password = 
org.quartz.dataSource.database01.maxConnections = 5
org.quartz.dataSource.database01.validationQuery=

Starting a Runtime with a configuration file

A Runtime may be started with a specific configuration file.
To specify this file, use the environment variable STAMBIA_CONF_FILE_LOCATION

By default, the value configured in the file «initvariable.sh (.bat)» is this:

STAMBIA_CONF_FILE_LOCATION=$STAMBIA_PROPERTIES_LOCATION/engineParameters.xml

Automatic log purge

You can plan an automatic purge of the Runtime session logs.
This can be done in Stambia and Stambia Analytics in the Purge tab of the Runtime Editor or alternatively on command line as explained below.

To proceed:

1. Launch startCommand (.bat or .sh).
2. Then use the purge scheduling command, the description of which follows:

schedule purge keep <number> <minute|hour|day|session>  cron <cronExpression> [sessionname <name,name2,...>] [status <done,error,killed>] [on host <hostname>] [port <hostport>]

It is possible to purge while keeping:

• A number of days, hours or minutes
• A number of sessions

For example, to keep 90 days and schedule the purge every evening at 23h:

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

Runtime parameters reference

The configuration of the Runtime is done in the engineParameters.xml file that can be found in the properties folder of the Runtime’s installation.
This file allows to manage:

• The engine parameters (such as started services, listening ports, ...)
• The security of the Runtime (hostname and user / password restriction, roles)
• The repositories where the deliveries are stored
• The Java additional options to add at Runtime’s startup
• The log database configuration

Take care, it is highly recommended to check first with Stambia the modifications you wish to bring to the XML files containing the Runtime parameters.
You can moreover find configuration samples in the properties/samples folder.

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Tip: All the parameters are centralized in this file but can be easily externalized if required.

Engine Parameters

Common Parameters

Services Parameters

Services Ports Parameters

Services Security

Services Miscellaneous Parameters

Standard Output Parameters

Web Services Parameters

Logs parameters

In this part, the default values will be those used for the logs in H2 (the internal base). For other logs examples, please refer to the example files that are provided.

Log header

Internal parameters

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Session Log Level

The session log level defines the level of information which is logged inside log database for each session executed by the Runtime.

The higher the value is the higher information are logged.
You can find below the different log level values and what level of details can be consulted, depending on the session status.