The FlowHeater Server

FlowHeater Server is an optional component that can automatically run executable programs and FlowHeater Definitions as scheduled or event-triggered tasks highly efficiently. This makes it simple, for example, to monitor a folder for added files and run a predetermined task for each new file.

FlowHeater Server is installed as a Windows service and so can run programs or FlowHeater Definitions without needing a user logged on.

Please note: a Company License is required to use the FlowHeater Server component.

System requirements

In order to run, FlowHeater Server itself places a relatively minor load on the system. The processes that its services execute decide the performance needs. FlowHeater Server is scalable from the “lowly” workstation to high-performance server systems with multiple processors.

• Operating systems: Windows 8 / 10 / 11 as well as Windows 2012 / 2016 / 2019 / 2022 Server
• Processor: x64, only 64-bit
• Main memory: min. 4 GB
• Disk space: min. 100 MB free space

Please note: FlowHeater Server will only run on systems with a 64-bit processor (x64) and a 64-bit Windows operating system. However, FlowHeater Server is able to run Definitions created with a 32-bit version of FlowHeater in its 32-bit mode.

Installation/update

Initial server installation

As FlowHeater Server is not included in the normal ZIP archive downloaded, you must first download the latest FlowHeater Server here. When you have unzipped the archive you will find a Setup file that is necessary to complete the installation. Unlike FlowHeater Designer and the Batch Module of the interactive product, FlowHeater Server cannot be used without running the Setup file.

Server service log onAdministrator rights are required to complete the installation. The Setup file creates/registers a Windows service called “FlowHeater Server” in the system. The startup type of the service will be installed as “automatic” by default. During the installation you will be prompted to specify a “technical” log on name and password. The service will then robotically run the defined tasks under this “technical” user account.

It is necessary for the service to run under a “technical” user account. An installation as “Local system” or “Network service” is not possible at present. The user must have “Run as a service” authorization and must have read and write permission for all the files the service requires. In the installation folders, write permission is required for folders “Data” and “Log” as well full access to the “Temp” folder.

Note: The “technical” user account must exist before installation; it will not be created by Setup. If this user does not exist, installation of the service will fail.

Updating an existing server installation

The same Setup file can be used to update an existing server installation. During installation the running service will be stopped, but existing settings and configured tasks are retained. As part of an update the server database may also require updating. If this is the case a backup copy will first be created in the “{Installation folder}\Data\Backup” folder.

Please note: With each installation or update a version of the FlowHeater Batch Module will be saved in the “{Installation folder}\Versions” folder as 32-bit and 64-bit variants compatible with FlowHeater Server, previous versions installed are thus retained. These versions will later be used to run FlowHeater Definitions with a matching version. For example, if a FlowHeater Definition is created with FlowHeater version 4.0.6 (32-bit) it will also be run using this version. This ensures that no unexpected side-effects occur due to the differences between versions.

FlowHeater Server Manager

FlowHeater Server ManagerTasks are defined and modified in the FlowHeater Server Manager, where also running tasks can be monitored and FlowHeater Server settings configured.

Status tab

The Status tab contains a compact and dynamic summary of the present server status

Service

Current state: This tells you whether the Windows service is running or not.
   Stopped = The Windows service is not running and cannot execute tasks. In this state it is also not possible to access the other tabs.
   Running = The Windows service is active and will execute tasks.

Start time: When the Windows service is “Running” the date and time last started is displayed here.

Start / Stop / Restart: These buttons enable you to stop and start the Windows service afresh. Warning: It is necessary to have started FlowHeater Server Manager with administrative rights in order to operate these buttons.

Status

Maximum processes: This displays the maximum number of processes defined as possible for FlowHeater Server to simultaneously run. This value can be modified using the “Configuration” tab.

Running tasks: This shows the number of actively running tasks/processes at present. This number is always smaller than the configured number of maximum processes.

Defined tasks: The count of tasks defined under the “Tasks” tab is shown here.

Waiting tasks: This number indicates the number of pending tasks that are currently waiting to be run. There are two possible reasons that tasks cannot be run immediately.

1. There are currently as many tasks running as than the configured maximum processes.
2. A configured task is already running for which a further run of the task is required. In this case the task will await completion of the running task before being started.

Tasks performed: This shows the number of tasks that have been run since the last start of FlowHeater Server (Windows service).

Tasks tab

Server tasks overviewThis tab allows you to enter new tasks and to amend or delete existing tasks. Each task is listed with name, type, when last run, for scheduled tasks when planned, a description of the task and whether the task is active.

Any number of tasks can be defined; there is no limit. By a single click on the “New” or “Edit” buttons, or by double click on a task listed, a popup window opens to configure all the settings about a task.

Settings tab - create and modify tasks

Name: Create or modify a Server taskThe name entered here will appear in the list of tasks to distinguish between them.

Description: Optional text to describe the task.

Active: This switch enables you to deactivate tasks temporarily without deleting them completely. Tasks that are not active will not run.

Trigger
There are two possible ways to cause a task to run.

File- / Directory monitoring: This is certainly the most powerful event-driven function of FlowHeater Server. This function is able to monitor a folder (and its subfolders). Whenever a new file appears in the specified folder it triggers running the task. This also works when many, perhaps thousands, of new files arrive there at about the same time. When there is more than one file to process in the folder only a task to process the first is run and tasks for the other files form a queue of “waiting tasks” that will then be run consecutively. The tasks are processed in strictly the same sequence as the files were created.

Scheduled: This is the most familiar method. This way tasks are run at a particular time (or on repeated occasions).

Run as
If no user is specified, the task will be run under the account FlowHeater Server was installed (Windows service logon).

User name: Windows user account for running the task.

Domain: Windows domain user account. If no “Active Directory” is available, the local computer name is used for user authentication.

Password: User password for the account. Note that the password is stored in encrypted form.

Perform tab

Perform tabHere you can define one or more steps that the task will execute in the sequence given. The file extensions supported include .fhd, .fhrt, .exe, .bat, .cmd and .ps1 (Power Shell). Whenever a FlowHeater Definition file (.fhd | .fhrt) is specified, the same version of FlowHeater that the Definition was created with is automatically executed. For this to work a FlowHeater version must exist in the “{Installation folder}\Versions\” folder with the corresponding version number. Both 32-bit and 64-bit variants of FlowHeater are supported. The sequence of steps listed can be modified using the “Up” and “Down” buttons.

FlowHeater Server - task executionFor each step you can specify the program, script or FlowHeater Definition to run.

Step name: A name to distinguish the step in the list displayed.

Execute: The absolute path of an executable program (.exe), a script file (.cmd | .bat | .ps1) or the FlowHeater Definition file (.fhd | .fhrt) to run.

Arguments (optional): With this you can define the format of the parameters passed to the program to be executed. When the task is defined as triggered by “file monitoring” and the option “hand over the current filename“ is checked, the current filename to be processed (incl. absolute path specification) is passed as the last parameter. When the program under “Execute” specifies a FlowHeater Definition (*.fhd | *.fhrt) the parameter /ReadFileName followed by the current filename is automatically passed for execution by the Batch Module.
Alternatively you can use the server variable “%CURRENT-FILENAME%” to manually specify the format of the parameter list, so that the filename is entered in the correct position and with whatever options are appropriate. Warning: The options selected in the example illustrated would cause the current filename to be passed twice. Once because it is contained in the server variable “%CURRENT-FILENAME%” in the first parameter position and a second time as the last parameter because the option “hand over the current filename” is checked.

Start folder (optional): The path of a folder specified here will be set when this step is executed.

Return/Exit code handling

This enables you to specify how FlowHeater Server should interpret the return/exit codes when program/script tasks end. By default the value “0” is interpreted as successful execution. If a task gives other return/exit codes depending on its run status, you can arrange that these are interpreted individually. A list of possible exit codes can be entered separated by commas. It is also possible to define ranges like “10-20” or in combinations such as “0, 10-20, 100”.

OK exit codes: Specify the return/exit codes that should be interpreted as successful execution.

Warning exit codes: Enter the return/exit codes here that should be interpreted as execution that ended with warnings.

Any return/exit codes not defined in these lists will be interpreted by FlowHeater Server as failure with a fatal error!

Delay

For each task step you have here the possibility to delay execution for a specified time (seconds). This is useful, for example, before a second task step when a short pause is introduced before running. If you also check the “Random delay” option, execution will delay for a random period within the specified range of times (from/to). The maximum delay is limited to one day. The entries here are in seconds, where one day is 86400 seconds.

Trigger tab (File monitor)

File path and filter

Path: Trigger (file monotor)Specify here the device/path of a folder to monitor for new files. Supports local drives, network drives and resources specified by UNC path.

Filter: For setting a filter to select files in the folder. You can enter fixed filenames or a wildcard mask: e.g. *.csv for all CSV files in the given folder or “import_*.csv” for only those that commence with “import_”.

Include subfolders: When this option is checked all folders beneath the folder specified in the path are also monitored, applying the filter specified.

Include hidden files: Checking this option will also monitor files that have the file attribute “Hidden” set. Warning: Some applications (such as Excel) create a hidden temporary file while editing (~filename.xlsx). When making use of this option, it is important that wildcards are used to ensure unwanted files of this type are not unintentionally included.

Triggered by file creation: The task will be triggered when a new file appears in the monitored folder. If in addition the “Process existing files at server start” option is checked, all existing files in the monitored folder will be reprocessed as soon as the server is started.

Triggered by file modification: The task will be triggered when an existing file in the monitored folder is modified.

Triggered by file rename: The task will be triggered when an existing file in the monitored folder is renamed.

Actions performed after execution

Delete file: When checked the file is deleted after successful completion of the task.

Move file (in cases of success): As an alternative to deletion, the file can be moved to another folder upon successful completion of the task. To guard against the possibility of name conflicts, the filename is appended with a unique date stamp to the microsecond processed in the form “_yyyyMMdd-HHmmss.fffff“.

Move file (in cases of error): When errors occur during processing, you have the option to move the file to a separate folder where you for subsequent investigation and processing. The filename will be appended with a unique date stamp in this case as well.

Trigger tab (Scheduled)

Trigger (Scheduled)This gives you the opportunity to define one or more scheduled times to run a task. In order to prevent FlowHeater Server from repeatedly running the same task simultaneously, you must define what should happen when the schedule causes a task to start that is already being performed.

Please note: Different tasks can of course run in parallel and they are not dependent on one another.

When a task is already running

Do not run the task again: When this option is checked the presently triggered task is discarded when the same task is already running.

Queue the task: This option allows you to add the task to a queue of “Waiting tasks” that will run it when the presently running task has completed.

Defining / modifying a schedule

Scheduled trigger settingsIn order to define a schedule, you must first define its starting and ending dates. This makes it possible to define a time plan in advance that only takes effect in the future. The task will not run until the actual date falls within the period defined.

Daily: The task will run every day at the time specified.

Weekly: The task will run on the day(s) of the week specified.

Monthly: The task will be run on specific day(s) of the month. In addition to numbered days an option to specify the “last day of the month” is also available. When this option is selected, the task will always run on the last day of the month, of course taking into account of leap years for the end of February.

Time: The time of day to trigger and run the task.

In this section you can specify the days of the week or days of the month to run the task, as applicable to the type selected.

You can configure here whether the task should be repeatedly run for a particular duration after the scheduled run. A task can be repeatedly run for up to a maximum of one day.

Notifications tab

Server task notificationsUsing this tab you can arrange for a message to be sent when a task completes. Any number of notifications can be defined. There can be different notifications, depending on whether the task completed successfully or failed with an error. For each notification you can define an individual message text and specific recipient(s).

Defining / modifying a notification

Label:
Defining / modifying a notificationText to briefly describe the notification. This is simply used to differentiate between notifications listed.

Sending conditions: Select here when a notification should be sent. The options “when successful”, “when warnings”, “when failed” are available. One or any combination of these options can be selected.

To: An email address the notification should be sent to. Multiple recipients can be listed, separated by commas or semicolons.

Subject: Subject line for the email. You can also embed server variables (placeholders) here, as described below.

Message: Freely definable message text. The placeholder {CREATED-FILENAMES} can be used to insert the file names generated into the text of the notification. This lists all the file names created, each on a new line. Alternatively, you can use placeholders such as {CREATED-FILENAME-1}, {CREATED-FILENAME-2}, {CREATED-FILENAME-3}, and so on. As many numbered placeholders like this are available as there are files created by the server task. In addition, the placeholder {TRIGGER-FILENAME} can be added to the text of the notification and/or in the subject line, which allows the triggering file name with its path to be embedded in the message.

Enclose standard output: When this option is checked an email enclosure is attached with content from the standard output channel.

Enclose standard error: This option allows you to attach to the email whatever is generated on the standard error channel. Please note: many programs fail to use this possibility for error reporting and for this reason an empty file may be enclosed.

Enclose created files: When this option is checked the file(s) possibly generated by the process will be attached as enclosures to the email. This option is only effective when a FlowHeater Definition is run by the task.

Compress attachments: not yet implemented

All attachments in a ZIP archive: not yet implemented

Configuration tab

Server configurationYou define the global settings for the server with this tab.

Performance

Maximum simultaneously running processes: This value determines how many tasks that FlowHeater Server is permitted to run at the same time. When this maximum is reached it prevents new tasks from being started until one of the running tasks completes, adding them to a queue of “waiting tasks” that are listed under the Status tab. Recommendation: As imports and exports of data are generally very processor-intensive exercises, you should not specify here a number that is more than the processor cores (not logical processors) you have.

Environment

Temp path: The path is used to assign processes that are started a temporary folder. Each task that is started receives its own temporary subfolder in this folder. For each started process the system environment variables TEMP and TMP are individually modified to this subfolder. After completion of the task, its specially created subfolder is automatically deleted by FlowHeater Server. This has the advantage that no garbage files remain that could be output by a started process. The user account assigned to the service that FlowHeater Server is installed by or started under requires full access rights to this folder.

Please note: The temporarily created subfolders are not immediately deleted after running a task. As a rule the subfolder is automatically deleted within an hour of successful completion. However, when a task ends in failure, deletion may be delayed for up to 3 days.

Email settings

If notifications are to be sent by email, it is necessary to configure here the settings of the mail server used for sending.

SMTP server / port: The DNS name or IP address and TCP/IP port to connect to the mail server. If an SSL encrypted connection must by established, you must also check the option “using SSL” here. The mail server must also accept the “STARTTLS” command.

SMTP user / password: If the mail server is so configured that authentication is required, you can enter here the user and password to use for SMTP logon that will be used for sending mails. If no user/password is needed then the mail servers must be configured for SMTP relaying.

Mail from: Enter here the email address of the sender to be used for mails sent. Depending on the mail server configuration, this information may be overwritten by the mail server with the standard email address of the SMTP user.

Logging

This section gives you control over what is written to log files and their retention period.

Log level: With this you can select the events that FlowHeater Server should log. The levels available are “Debug” = highly detailed, “Info” = default, “Warning” = only warnings and errors are logged and “Error” where only errors are written to the log file.

Log path: You can enter a folder here to store log files. A separate log file is started each day. The filename has the form “fhserver_YYYYMMDD.log” where YYYY is the current year, MM the current month number and DD the current day number.

Days to retain log files: To prevent the accumulation of endless numbers of log files to store, this option allows you to specify how long to keep log files. FlowHeater Server automatically deletes log files that are older than this number of days. If you enter a value of zero here, no log files will ever be deleted.

History information

Save history for: You can specify here how many months the FlowHeater Server should record an invocation history of individual tasks. With the number of months set to “-1” no history data will be recorded. With this set to “0” the saving of history data is unlimited.

Save console output: If you check this option, runtime console output is saved for possible downstream analysis with the invocation history. Note: The console output saved is limited to a maximum of 1 MB per invocation.

Logging tab

If a task fails to run as expected, you can use this tab to view live what steps FlowHeater Server is currently logging. You can use the “Start” and “Stop” buttons to pause the log output and then allow it to continue. The detail of the steps of tasks logged is according to the log level currently defined. You can use the “Clear” button to wipe all details logged from the window.

Server Database Maintenance

FlowHeater Server - Database maintenanceThe FlowHeater Server uses an internal database to store tasks, execution histories and logs. No special supervision is normally required for this. However, when it proves necessary or if it is required to make a backup the database, maintenance tasks are available in the menu option "Maintenance->Database" of the Server Manager.

Database maintenance options

Compact & repair: If the FlowHeater Server service will not start, you can attempt a repair using this button. An attempt is made to compact the database at the same time. This option can only be used when Windows service for FlowHeater Server is not running.

Database backup file: The associated Backup button allows you to create a manual backup of the FlowHeater Server database during operation.

Create a task to backup the server: This makes it possible to create a server task that automatically performs a backup of the FlowHeater Server database.

Backup folder: Enter the path to save backups. With the option “Retain [number] backup files” you can specify how many backup generations to keep. The FlowHeater Server will automatically delete older backups than this number in the specified folder. Note: The FlowHeater Server task created this way still requires scheduling. In addition, the server task is inactive by default and must be activated manually!

Backup file of the database: The associated Restore button enables you to reinstate the FlowHeater Server database from a selected backup file. While restoring the database the Windows service for FlowHeater Server must not be started. Note: All settings are thereby reset to their state at the time of the backup!