Stambia versions 2.x, 3.x, S17, S18, S19 and S20 are reaching End of Support January, 15th, 2024. Please consider upgrading to the supported Semarchy xDI versions. See Global Policy Support and the Semarchy Documentation.
The Stambia User Community is moving to Semarchy! All the applicable resources have already been moved or are currently being moved to their new location. Read more…
Stambia DI Runtime can be accessed from several software and tools such as Designer, Analytics, Command line scripts or Process Actions, which offer the possibility to perform operations, consult executed sessions, execute or schedule new deliveries, ...
Communication with Runtime can be performed through different protocols such as RMI or HTTP.
This article summarizes how to use and configure them on the clients.
The Runtime is shipped with command line build scripts which allows to generate deliveries from package files.
Those scripts offer the possibility to extract a configuration file from the package to specify all the Metadata parameters which are defined as externalized.
And finally to generate the delivery file, optionally with those customized parameters.
A package is an archive containing all the needed files to generate a delivery.
Most of the time, a package is generated by the development team when they have finished working on a Mapping / Process / Project.
The package can then be used to generate the delivery that will be executed by the Runtimes.
Packages can contain one or several processes, each one being able to be transformed into a Delivery.
Prerequisites for multi-process Packages:
Multi-process packages can be generated from Stambia DI Designer S19.0.0 and higher, and the build scripts support them from Stambia DI Runtime S17.6.0 and higher
The Runtime is shipped with command line build scripts allowing to generate a delivery from a package: builddelivery.bat / builddelivery.sh.
Depending on if you are on a Microsoft Windows or Unix OS, the .bat or .sh should be used.
The scripts must be used as follow:
builddelivery.sh mypackage.pck [options]
The following options are available:
| Option | Mandatory for generation mode | Mandatory for substitution mode | Supported from Runtime version | Description |
| -buildmode <mode> | X | X | S17.6.0 and higher |
Specifies how the delivery should be generated. The following modes are supported:
When this parameter is not specified the generation mode is used. See below for further information about each mode. |
| -listprocessenames | X | X | S17.6.0 and higher | list all the processes contained in a package |
| -extract | X | X | all versions | Extract the configuration file of the package containing the externalized Metadata parameters which are used in the processes and which can be customized. |
| -conf <name> | -conffile <file path> | No | Yes | all versions |
When used with the -extract option, specifies a name for the configuration which will be extracted. When used for building a delivery, specifies the previously extracted configuration to use for replacing the externalized Metadata parameters.
|
| -processname <name> | No | No | S17.6.0 and higher |
Indicate which process contained in the package should be built. It is not necessary if you want to build all the processes contained in the package (could be only one process). |
| -deliveryfolder <folder path> | No | No | S17.6.0 and higher | specify the target folder where the deliveries will be generated. |
About build mode
Two build mode are actually available to generate the deliveries, each one having its advantages.
You can find below the differences:
| Build Mode | Supported from Runtime version | Description | Pros and cons |
| generation | all versions |
Mode which has been used by default since the build scripts exist, which launches a generation mechanism to build the delivery. The principal advantage of this mode is that it allows to customize Metadata parameters which were not defined as externalized when generating the package. This offers the possibility to add extra parameters on the extracted configuration file used to build the delivery, to replace parameters which were not anticipated when generating the package. The con is that because of the generation mechanism, it can be time consuming for large processes. Note: Specifying a configuration while building a delivery in this mode is not mandatory. If not specified, the default value with which the package has been generated is used for parameters which has not been valuated. |
Pros
Cons
|
| substitution | S17.6.0 and higher |
Mode which consists of simply replacing the externalized parameters with the values provided inside the extracted configuration file. The builder simply retrieves the pre-built delivery which is inside the package and replace the parameters in. This is also the method that uses Stambia DI Production Analytics for generating deliveries, and this offers better performances as no generation is performed to build the delivery. This also offers the possibility to generate deliveries for all the processes contained in a multi-process package, which is not possible with generation mode. Note: In this mode it is mandatory to build the delivery using a configuration with all the externalized Metadata parameters valuated. |
Pros
|
Which build mode should I use?
For most common usage, the substitution mode can be used as it offers better performances and allows to build all the processes contained in a package.
The generation mode, which is still the default mode for backward compatibility, can be useful when you need to override values for parameters which were not originally externalized when the package was generated.
About configuration files
When using the -extract option, the configuration file of the package is extracted and re-named as specified with the -conf (or -conffile) options.
This file contains all the Metadata parameters which are defined as externalized in the Metadata.
Some are externalized by default, such as the JDBC URL or JDBC User and password, and others can be externalized manually by the user from the Designer in the Metadata.
Those parameters are commented with a default value in the extracted configuration file, for the user to be able to customize them when generating deliveries.
Example of configuration file
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210
### Type: com.stambia.rdbms.server
#_-1vK4CVLEeWjxY2_6aCFbA/url=jdbc:hsqldb:hsql://localhost:62210
#_-1vK4CVLEeWjxY2_6aCFbA/user=sa
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210/HOTEL_MANAGEMENT
### Type: com.stambia.rdbms.schema
#_aUU9YE26Eeay9ZeykqAlHA/TABLE_SCHEM=HOTEL_MANAGEMENT
#################################################################
To specify a value for a parameter, uncomment the corresponding line (remove the '#' which is at its start) and specify the wanted value.
Example of modified configuration file
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210
### Type: com.stambia.rdbms.server
_-1vK4CVLEeWjxY2_6aCFbA/url=jdbc:hsqldb:hsql://productionhost:62210
_-1vK4CVLEeWjxY2_6aCFbA/user=productionuser
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210/HOTEL_MANAGEMENT
### Type: com.stambia.rdbms.schema
_aUU9YE26Eeay9ZeykqAlHA/TABLE_SCHEM=HOTEL_PRODUCTION_SCHEMA
#################################################################
When the parameters correspond to the expected values, the delivery can be built using the configuration.
Below are examples of script usage
Listing the processes contained inside a package
builddelivery.sh mypackage.pck -listprocessnames
Extracting a configuration
builddelivery.sh mypackage.pck -conf myconf -extract
Building a delivery using a previously extracted configuration
builddelivery.sh mypackage.pck -conf myconf
Building a delivery using a configuration, process name, and delivery folder
builddelivery.sh mymultipackage.pck -conf myconf -processname "Load All Datamart" -deliveryfolder D:/deliveries/
Building all the deliveries of a multi-process package inside a specified folder (using substitution mode is mandatory)
builddelivery.sh mymultipackage.pck -conf myconf -deliveryfolder D:/deliveries/ -buildmode substitution
When a session ends with errors, it can be configured to be restarted automatically a certain amount of times, with a defined delay.
By default, it will restart from the last detected error, but Restart Points can also be defined to manage the Process' flow more precisely.
Here is the minimal list of what should be backed up, in order to be able to restore / reinstall a Runtime.
The following directories should be backed up regularly, recursively (including their files and subdirectories).
| Directory | Comments |
| build/deliveries |
Default location of the published deliveries. The subdirectory "wsdl" contains the deliveries published as a webservice. |
| build/packages |
Default location where the Runtime will search for .pck packages. Useful only when the Runtime is used for building Deliveries from Packages. |
| lib/addons | This is where the jar files for optional connectors are installed (Salesforce connector, SAP connector, Amazon web services, etc.) |
| lib/jdbc | This folder contains the JDBC drivers that the Runtime uses |
| log | The Runtime log files. They can be deleted with no harm, but you may want to keep them for further investigation. |
| properties | The Runtime properties. |
| scheduler | This is where the default H2 Scheduler database is located. If you the Runtime uses an external scheduler database then this folder can be ignored, see below. |
| sessions | This is where the default H2 Log database is located. If the Runtime uses an external log database then this folder can be ignored, see below. |
If the Runtime uses an external log database then a proper backup strategy must be defined and applied on this database.
Note : if for any sad reason the Runtime log database is lost and/or corrupted and cannot be repaired, then the Runtime will be able to start after droping the 15 tables. All session history will be lost.
If the Runtime uses an external scheduler database then a proper backup strategy must be defined and applied on this database.
This article is a Work In Progress. We might also change its structure and category soon.
Please feel free to suggest improvements at the bottom of the page.
This article provides a few ideas for controlling a Runtime's status.
The Runtime comes with a startcommand utility. It is a script (.bat for windows, .sh for Linux/Unix).
The idea is to check the Runtime's services status with this command:
D:\apps\stambia\stambiaRuntime_Service>startcommand "connect to localhost port 42070;get services"
D:\apps\stambia\stambiaRuntime_Service>echo off
Connecting to localhost on port 42070
Connected
Name Status Duration
rmi Running 23:11:34.392
rdbms Running 23:11:35.95
execution Running 23:11:34.548
soap Running 23:11:32.847
listener Running 23:11:34.548
scheduler Running 23:11:33.628
D:\apps\stambia\stambiaRuntime_Service>echo %ERRORLEVEL%
0
In this example, the output indicates that all the Runtime's services are "Running".
The return code (%ERRORLEVEL% in Windows, $? in Linux) of the startcommand script is 0 when the Runtime is up, or -1 when the Runtime is down.
You can also specify which service you want to check, and format the output:
D:\apps\stambia\stambiaRuntime_Service>startcommand "connect to localhost port 42070;get services name rmi format '%status'"
D:\apps\stambia\stambiaRuntime_Service>echo off
Connecting to localhost on port 42070
Connected
Running
It can be useful to develop a specific process which will check what is necessary in your very own use cases.
For example, you can design and execute a process which makes use of FTP actions, SendMail actions, Write files, SQL To Parameters... in order to check that the Runtime is able to work with the underlying servers in your architecture. And at the end of the process, you can imagine sending an email or update a flag somewhere to confirm that everything's up and running.
