Skip to main content
Version: 5.3.0.0

Start of external services

Whenever Orchestra is started, some additional services may be required to implement the modeled scenarios. An example is an MQTT broker. With this enhancement, users can specify external processes that are started alongside Orchestra, allowing for the bundling of an MQTT broker with Orchestra.

Configuration​

This feature is configured in a separate XML file named external_process_definition.xml, located in the config folder of the Orchestra installation.

The following configuration options are available:

<!--

    | #################################################################################################################

     | # Configuration of all external services that have to be started together with Orchestra

     | #################################################################################################################

     |

     | For each external program that has to be started together with Orchestra, an element "ExternalService" must

     | be added. Configure the ExternalService according to the following description.

     |

     | name             The name of the external service. It is added to the log output so that

     |                  the output of different executables can be distinguished.

     | executable       The name of the executable that has to be started.

     | workingDir       Absolute path to the working directory of the started process.

     | arg              An arg element identifies one argument that is passed during process start.

     |                  An arbitrary set of arg elements can be specified. They are passed in document

     |                  order to the started process.

     | env              An env element identifies an environment variable that is passed to the started process.

     |                  If no env elements are provided, the environment of the starting process is inherited.

     |                  An env entry contains a string that must follow the pattern:

     |                  NAME=VALUE.

     | sendToConsole    One or more commands that are sent to the running process to indicate that

     |                  the process should be aborted.

     | waitTime         Defines how long Orchestra should wait for the graceful termination of a process.

     | logLevelStdErr   Defines the log level used to write all output from stderr to

     |                  the log file. Allowed values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST.

     | logLevelStdOut   Defines the log level used to write all output from stdout to

     |                  the log file. Allowed values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST.

     |

     | To make the configuration more flexible, parameters can be added that are replaced with real parameters

     | during startup. The following parameters are supported:

     |

     | {property.<name>}            Gets the system property indicated by the specified name.

     | {system.<name>}              Gets the value of the specified environment variable. An environment variable

     |                                is a system-dependent external named value.

     | {basepath}                   The absolute path of the installation directory of this Orchestra instance.

     | {host.name}                  The name of the local machine.

     | {host.ip}                    The IP address of the local machine.

     -->

<ExternalService        name              = "Externalprocess"

                        executable        = "path to executable"

                        workingDir        = "working directory"

                        logLevelStdErr    = "WARNING" 

                        logLevelStdOut    = "FINE" >

    <!-- An arbitrary number of entries specifying environment variables -->

    <env>KEY=VALUE</env>

    <!-- An arbitrary number of entries specifying command line arguments -->

    <arg>Argument</arg>

    <shutdown waitTime="10" >

        <!-- An arbitrary number of commands that are sent as shutdown hints -->

        <sendToConsole>shutdown</sendToConsole>

    </shutdown>

</ExternalService>

Integration of an MQTT Broker​

The ExternalService can be used to start an external MQTT broker whenever Orchestra is started.

The integration with HiveMQ is outlined below.

  1. Download the HiveMQ MQTT broker (e.g., community edition).

  2. Extract the package to a local folder in your Orchestra installation.

  3. Configure the ExternalServices so that HiveMQ is started automatically. The following sample illustrates how this can be achieved. Please replace <path-to-hive-mq> with the installation directory of your HiveMQ installation.

<ExternalService        name             = "hivemq"

                        executable       = "cmd"

                        directory        = "<path-to-hive-mq>\bin\"

                        logLevelStdErr   = "WARNING" 

                        logLevelStdOut   = "FINE" >

    <arg>/C</arg>    

    <arg><path-to-hive-mq>\bin\run.bat</arg>

    <shutdown waitTime="10" >

    </shutdown>

</ExternalService>