Welcome Guest! Log in
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…

Communicating with Runtime

    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.

    Read more: Communicating with Runtime

    Building deliveries from build scripts

      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.

       

      Generalities

      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

       

      Build scripts

      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:

      • substitution
      • generation

      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.

      • For the generation mode if the configuration is not specified the values for those parameters will be the default values with which the package has been generated.
      • For the substitution mode, specifying a configuration is mandatory.
      -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

      • Allows to override extra parameters which were not originally externalized when the package was generated

      Cons

      • The generation takes more time as the delivery is entierly rebuilt
      • Does not support to build all the deliveries of a multi-process package at once
      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

      • Allows to generate deliveries for all the processes contained in a package at once
      • Better performances than generation mode

       

      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.

       

      Examples

      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

       

      Backing up Runtime files and data

        Here is the minimal list of what should be backed up, in order to be able to restore / reinstall a Runtime.

        Runtime files

        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.

         

        Runtime log external database

        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.

        Runtime scheduler external database

        If the Runtime uses an external scheduler database then a proper backup strategy must be defined and applied on this database.

        Checking that the Runtime is up and running

          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.

          Using the startcommand utility

          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

          Executing a specific process

          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.

           

           

          Articles

          Suggest a new Article!