Externally triggered runs are ad-hoc runs that are initiated through a third party application by modifying a trigger file that has been defined in the manifest object in InfoWorks ICM Ultimate or ICMLive Configuration Manager.
Overview
There are two different types of automatic simulations in InfoWorks ICM :
- Scheduled – Automatic simulations may be scheduled per the existing manifest run schedule set in in InfoWorks ICM Ultimate or ICMLive Configuration Manager.
- Externally triggered – Automatic simulations may be generated through a third party application by modifying the trigger file specified at manifest configuration time in in InfoWorks ICM Ultimate or ICMLive Configuration Manager.
The automatic run type (Scheduled or Externally triggered) is displayed in the ICMLive Operator Client interface, in the Server Simulation Schedule Window.
If an externally triggered simulation completes with an alert trigger being fired, then the appropriate alert category full run schedule is invoked. Meanwhile, externally triggered simulations will continue to be satisfied.
Whether runs can be externally triggered depends on the mode of operation of the manifest:
- Normal - The server will process the run schedule and will service externally triggered runs. If an alert job sets an alert trigger, the alert trigger will also be processed.
- Manual runs only - The server will NOT process the run schedule and will NOT service externally triggered runs. However, runs can be generated manually by the user in ICMLive Operator Client.
- Ignore alert triggers - The server will process the run schedule and will service externally triggered runs. However, if an alert job sets an alert trigger, the alert trigger is ignored.
Trigger File Configuration
Trigger files are specified in InfoWorks ICM Ultimate or ICMLive Configuration Manager as part of the manifest configuration. See the InfoWorks ICM help for further details.
Initiating an Externally Triggered Run
For a third party to externally initiate a run, it is only necessary to modify, create or overwrite the trigger file. If the content of the file is empty or the trigger file extension is not XML, only default parameters will be used (see Default column in the table below).
The parent directory of the external trigger file must exist, but the file does not have to exist until it is time to trigger a run.
Trigger File Structure
The format of the trigger file can be structured XML, CSV, or text. However default parameters (shown in the Default column in the table below) will be used if the content of the file is empty, or it is not a structured XML file with an XML extension.
An example of an XML file is given below.
Example
For trigger files with the XML file extension, one or more simulations may be initiated by inserting multiple run elements to the XML file.
File parameters
| Parameter |
Description |
Default |
|---|---|---|
|
run type |
Either full or observed. Tip: The run type is displayed in the
ICMLive Operator Client interface. See
Server Simulation Schedule Window for more information.
|
full |
| origin |
YYYYMMDDTHHMMSS YYYY - year MM - month DD - day T - date time separator hh - hour mm - minute ss - seconds |
The current local machine time, excluding daylight savings time. |
Innovyze Live Server Configuration Settings
Further configuration may be implemented in the Innovyze Live Server to meet specific user requirements. These include parameters preventing externally triggered runs to be generated:
- if the last file write has occurred within the tolerance specified since the last file write
- if the last file write occurred earlier than the current time minus the number of stale minutes specified.
For example, if the tolerance is set to 120 seconds the next externally triggered simulation will be initiated only on any trigger file modification that occurs 120 seconds after the last initiated externally triggered run. This advanced server setting will allow a user to mitigate any unwanted triggered runs in the event that a third party application might get into an error state that could erroneously modify the trigger file in a tight loop.
Let us now look at the number of stale minutes and imagine it is set to 15 minutes. If the trigger file is modified at 08:40:00, but the Innovyze Live Server is not running, the run cannot be initiated. If the server is then started at 08:50:00, the run will be initiated, albeit late, because the trigger file has been modified within an acceptable time period (current time - number of stale minutes = 8:50:00 - 00:15:00 = 8:35:00. The last timestamp at which the trigger file was modified is 8:40:00 and this time is later than 8:35:00 therefore the run is initiated). However if the server is started at 09:00:00 the run will NOT be initiated.
For further details, please refer to the Innovyze Live Server Administration Guide available for download here.