Trigger is an Envision plug-in that allows for "triggers" to be run whenever specified changes in the underlying spatial database (IDUs) happen as a result of some other Envision process running - in effect, a trigger is a "listener" that responds when specific database changes occur. In that sense, it is similar to another Envision plug-in, Sync. Defining a trigger is straightforward - like most Envision plug-ins, Triggers are specified using an XML file, described below. Triggers are defined based on what field changes they are listening for. Triggers can be turned on and off for specific scenarios through use of the "use" attribute, which is exposed as a scenario variable (settable scenario by scenario in the study area project file.

The basic XML format for a Trigger input file is provided below.

<?xml version="1.0" encoding="utf-8"?>
<triggers>
    <trigger name='MyTriggerName' use='1' query='myQuery' >
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'/>
            ...
        <outcome target_col="SomeCol" target_value='SomeOtherExpression" probability='SomeOtherProbability'/>
    <trigger>
    ...
</triggers>

In the example above, for each time step, the trigger "MyTriggerName" would invoked for every IDU for which the query "MyQuery" is satisfied. In that case, each outcome associated with this trigger would be applied to the IDU database. Using the example above, the IDU field "SomeCol" would get populated with the result of evaluating the expression "SomeExpression"; the likelihood of that expression being applied is determined by the value "SomeProbability". Specific tags and attributes shown in the figure above are described below.

Tag Definitions for Trigger

<trigger> tag

The <trigger> tag defines the name of the trigger, the spatial domain of the trigger, and whether the trigger is enabled by default. Any number of <trigger>s can be placed in the file; each operate independently of the other. Triggers are executed in the order specified in the input file; changes made by a 'higher' trigger are not seen by "lower" triggers (the results of the trigger outcomes aren't written to the IDU database until all triggers have executed.

Attribute	Description	Default Value	Required?
name	Name of the model		Yes
query	A query used to determine which IDU's are triggered		Yes
use	Flag indicating whether this trigger should be active during a run.  It is expled as a scenario variable.	1 (use is enabled)	No

<outcome> tag

The <outcome> tag specifies the IDU field to be updated when the trigger is invoked, along with an expression that is evaluated to determine what value is written to the IDU field. Optionally, a probability (0-1) can be defined that determines the likelihood of that outcome actually being wrtten to the IDU.

Attribute	Description	Default Value	Required?
target_col	IDU field that will be populated by this outcome		Yes
target_value	a map expression that is evaluated when this trigger is invoked		Yes
probability	decimal fraction (0-1) specifying the probability that this outcome will be applied.	1.0	No

An Example Trigger Input File

Below is an example trigger input file.

<?xml version="1.0" encoding="utf-8"?>

<triggers>
    <!-- this trigger populates the LULC_B field with the value '4' for 
        all IDUs in the specified zones, for 50 percent of the IDU's that match the query. -->
    <trigger name="LULC_B Zoning" query="ZONE_B > 1 and ZONE_B < 9 ">
       <outcome target_col="LULC_B" target_value="4" probability="0.5" />
  </trigger>

  <!-- this trigger calculates a unit change in population (#/m2 to #/acre)
       and stores the results in a new field for all IDUs -->
  <trigger name="PopDens Unit Change" query="POPDENS > 0">
    <outcome target_col="POPDENS_AC" target_value="POPDENS*0.0002471" probability="1.0" />
  </trigger>

</triggers>