In this article
You can find below the major changes and improvements of the Stambia DI Runtime 2020 (S20.2.x) version.
This article only highlights the most important changes.
Migration from S17
Stambia DI Runtime 2020 (S20) major version changes some important part of the software which require your attention.
Migrating from Stambia DI Designer S17, S18 or S19 require to follow the migration guide, which can be found in the following article.
If you are simply updating from another Stambia DI Runtime 2020 (S20) version, simply follow the minor version upgrade guide, as usual.
There is no change on this Runtime version, only the related Designer contains fixes.
This version fixes a minor issue about HTTP REST Component which was including too much dependencies libraries in previous version.
This was leading to having a larger archive file for the HTTP REST Component.
This has been fixed, HTTP REST Component file size is now back to normal.
Note that except the larger file size, this had no other consequences.
Complete changelog can be found here.
Runtime Log Database connection and reconnection
The Runtime will now wait and retries a certain amount of time to connect to its Log Database when it is unavailable.
This applies when starting the Runtime, which will now wait and retry several times to connect if it is not available.
This applies also when the connection is lost during the execution of a session, the Runtime will wait and retry several times to reconnect before given up and ending the session execution.
Two parameters have been added in Runtime configuration file (engine.parameters.xml) to configure the number of retries and the delay between each.
They respectively default to 20 retries with a delay of 1000milliseconds (1s.)
<parameter name="userLogRdbmsConnectionRetryNumber" value="20"/>
<parameter name="userLogRdbmsConnectionRetryDelay" value="1000"/>
Note that those parameters define the number and delay of connection retries which will be performed by the Runtime itself.
When performing a connection, the client libraries (usually JDBC Drivers) have each their own connection mechanism, so they may perform some additional connection retries on their own.
Real times observed may therefore be longer than defined because each connection retry performed by the Runtime is delegated to the client libraries, which themselves may perform their own additional retries with their own timeouts (which are managed by the libraries themselves and not the Runtime.)
Ability to define a custom Module for Log Database and Scheduler database
Runtime Log Database and Scheduler Databases are using an internal H2 database in a default installation, which can be changed to another database through Runtime configuration file (engineParameters.xml) and Scheduler configuration file (engineScheduler.properties).
Until this version, the client libraries (usually JDBC Drivers) were searched inside the "default" Module of the Runtime, meaning you needed to add you client libraries inside this default Module.
Two parameters have been added in the configuration files to define a custom Module for those databases.
- "UserLogRdbmsModule" in Runtime configuration file (engineParameters.xml).
- "Org.quartz.dataSource.database01.module" for the Scheduler configuration file (engineScheduler.properties)
Example of a custom Module in engineParameters.xml:
<parameter name="userLogRdbmsModule" value="MySQL"/>
Example of a custom Module in engineScheduler.properties:
#============================================================================ Configure Datasources #============================================================================ org.quartz.dataSource.database01.driver =com.mysql.jdbc.Driver
org.quartz.dataSource.database01.URL = jdbc:mysql://mysql.stambia.fr/LOGS
org.quartz.dataSource.database01.user = user
org.quartz.dataSource.database01.password = password
org.quartz.dataSource.database01.maxConnections = 5
org.quartz.dataSource.database01.mmodule = MySQL
Securing Runtime endpoints
When a secure Runtime is used, the information to use the keystore must be defined: the location of the keystore, the keystore password and the key password.
It was not possible to define the key to be used, the Runtime was trying all the keys and using the first one matching with the password.
A new parameter has been added in Runtime configuration file (engineParameters.xml) to be able to define it: "webServiceKeyAlias"
Services Transport Security
<parameter name="webServiceKeyAlias" value="keyalias"/>
Raise Error Process Action
Sometimes, you may need to end a session in error with a custom message such as "Email has been sent to the administrators", for example.
As for now, the workaround was to use a Scripting Process Action to throw an error.
So to simplify, a new Process Action named "Raise Error" has been added in the palette, in the Miscellaneous category. Whatever happens in the Process, this action always throws an error. You just have to write the message you want.
When the Raise Error Process Action is executed, it produces an error, and the message is displayed in the returned error and in the Message variable.
Email Metadata and Read Email Process Action
- Stambia DI Designer S20.2.0 or higher
Additional connection properties can now be defined in Email Metadata on Incoming Account attributes.
It allows to define the various properties which may be required for some servers.
As an example, this unlock the ability to access Office Shared Mailboxes which requires some properties to be defined.
As an example, accessing Office shared mailboxes requires the two following properties which are shown in the previous image.
Process Action synchronization
A new advanced property named "Semaphore Name" is available on Process Actions.
It allows to define a name which will be used to synchronize actions between them.
When a Process Action is executed, it checks if the Semaphore Name defined is not currently in use by another Action, and if it is the case, it will wait for the other Action to finish before executing.
When multiple Actions are defined with the same Semaphore Name, they will therefore be automatically executed sequentially even if they are started in parallel in the Process, but the order of execution is not predictable.
Note that you should prefer, when possible, ordering and linking actions properly in Processes, by linking them sequentially when they cannot be parallelized.
As an example, defining the same Semaphore Name on two following Process Actions will make sure they will not be executed at the same time even if they are not linked between each other in the Process.
If a different Semaphore Name was defined on each of them, they would be executed in parallel, as usual.
If no Semaphore name is defined, Process Actions are executed in parallel, as usual.
You can see in this example that the execution time is 10seconds, because the two actions are using the same Semaphore Name, so they are executed one after the other
Note about the particular case of SQL connections and transactions
There is one particular case, where a Semaphore is automatically created to synchronize Process Actions even if no Semaphore Name is defined by a user.
This is the case of Process Actions using SQL Connections such as SQL Operation Process Actions.
When two SQL Operation Process Actions are executed parallelly on the same connection and transaction, they will automatically use the same Semaphore - if none is defined, so that they are not executed at the same time.
This has been done to automatically fix parallelism issues when having in the same Process multiple SQL operations executed at the same time on the same transaction and connection, which can cause issues and erratic behaviours.
This is one of the causes which encouraged the addition of the Semaphore mechanism, to automatically fix those situations in which erratic behaviours can happen.
Note that you should prefer, when possible, design your Processes in such a way that those operations on the same connection and transaction are sequentially executed, with defining links between them.
startDelivery.bat / startdelivery.sh scripts
Addition of a new option to specify the path to a session variable containing the code to be used for the Operating System Exit code which is returned: - returnCodePath
This can be the path to any session variable available in the Process.
The variable must return a numeric value.
Example with the Raise Error Action:
- On Linux, the values are between 0 and 255.
This version fixes a list of issues which can be found on the full changelog.
Do not hesitate to take a look at it to have an idea of what have changed.