ImpactECS In-Depth: System Events Overview

Actions, commonly called “events”, occur when activities like clicking the save button or pressing a key, and system-generated activities like logging error messages during model recalculations are performed. This functionality – known as event handling – gives developers the ability to “handle” or react to events in ImpactECS. ImpactECS System Events enables developers to execute custom logic when specific events occur in a model by adding functions to the “SystemEvents” Script Module. The following System Events are available for modification:

  • OnAfterDeleteFolder
  • OnAfterDeleteItem
  • OnBeforeDeleteFolder
  • OnBeforeDeleteItem
  • OnLogMessage
  • OnOpenItem
  • OnOpenItems
  • OnOpenModel
  • OnSaveItem
  • OnSaveItemAs
  • OnSaveItems
  • OnTaskFinished
  • OnTaskStarting
  • System Events support several useful modeling capabilities in ImpactECS. In fact, the System Library relies on System Events to perform much of its core logic. The following examples demonstrate a few common usage scenarios: launching forms when a model opens, loading or exporting data from external sources, and saving task and message logs.

    Launching Forms when Opening a Model

    With the OnOpenModel event handler, developers can create custom views using Forms and display them for different ImpactECS users based on their assigned view. By creating a table to assign the forms to users and adding code telling ImpactECS to determine the correct form to load, when Jennifer launches ImpactECS in the example below, the System Admin Screens form will load automatically.

    ImpactECS Open Mode - Script


    ImpactECS Open Model - Table


    Loading and Exporting Data from External Sources

    System Events can streamline the process of moving data between ImpactECS and external sources. In one example, system events are used to automatically reload cost object data from external sources when a user opens an individual item. Another use case automatically exports cost object data to an external system when the cost object is saved. Implementing these two actions use the OnOpenItem and OnSaveItem event handlers respectively, along with a separate configuration table that defines the Scripts used to execute each unique event.

    ImpactECS System Screens - Script


    ImpactECS System Screens - Table


    Saving Task and Message Logs

    By default, ImpactECS task and message logs are only temporarily visible on the desktop application of the user that executed the task. With System Events, developers can program ImpactECS to save task and message logs in database table, giving users and model administrators the ability to analyze model performance data or identify recurring errors. Saving log records requires either using event handlers OnTaskStarting, OnLogMessage, and OnTaskFinished or leveraging the existing System Library’s pre-built System Logs functionality.

    ImpactECS System Events - Logs


    Implementing System Events

    By creating custom automated events in ImpactECS, developers can significantly expand model capabilities and improve the user experience. If you’re not sure how to get started with System Events, the 3C Software consulting team is happy to help walk you through best practices. Don’t have ImpactECS 7.4 yet? You can learn more about the release or email us and we’ll help you get started.