<< Click to Display Table of Contents >>

Navigation:  Defining Entity Types > Create a New Entity Type >


Previous pageReturn to chapter overviewNext page
Show/Hide Hidden Text

Actions and triggers are used to make instantaneous changes to stocks and attributes, to create or delete entities, or both. Actions describe what will happen; triggers determine when the action occurs. We will discuss actions first, then triggers. There is also a separate exercise provided as a step-by-step example of using actions.


You define an action as part of an entity type definition. If you are defining chameleon entities, one property you will add is a "change color" action that, when triggered, changes the color of the chameleon. The "change color" action will be listed on the actions tab of the chameleon entity type, and the chameleon entity type is said to be the parent of the action.


Action Components




Most action types have some settings on the Properties tab of their inspector.






All actions have an Invoker and a Parent on the References tab of their inspector.





The Parent is the entitytype or collection within which the action is defined. You can't change this type (unless you redefine the action somewhere else).

The Invoker is the context of the Trigger that caused the action to occur. By default, the invoker type is the same as the parent type, but you can change this if your action will be called from a different entitytype. More than one type can invoke an action, though this will produce a warning, or an error if a necessary variable is needed but not available from the actual invoker.

Create actions have a special reference for the new entity to be created, e.g., newPerson.

Process List actions have a special reference for the current entity target in the iteration over a collection, e.g., refPerson.

You can add other references you may need, for example to the top-level Model singleton, to a collection, or to some other entity known to the Invoker or Parent.


Local Variables and Attributes


Actions can contain local variables for performing intermediate computations, like determining the attractiveness of options to be selected in a Process List.


You can use stock-flow notation to calculate accumulations within a Process List action. In this case, the accumulation is not over time, but over iterations of the action on its target collection.




Because action computations are volatile, these have no independent existence outside the action, and are not stored.


Surrogates and References


Variables used from the Parent, Invoker, or other references can be references or surrogates. A reference is a pointer to a variable somewhere else, whereas a surrogate is a local proxy for the variable.


Reference (or Referenced Variable)


Appearance (in default color schemes)


actionSurrogate1 or actionSurrogate2

Notation (in diagram labels and expressions)

. (dot)


• (bullet)




Drag from the inspector. In some cases you may need to use the <control> key as a modifier while dragging.




Enter the desired name in the expression (autocomplete will help you fill in the name if you start with Parent. etc.). The result will be underlined, indicating that the cause is not shown on the diagram. Right-click the underline and use the "Draw Arrows" method from the context menu.

Generally automatic in a Create action.




To initialize it (Create action only): surrogate

To change it: surrogate

To use it: reference

Unless you already have the surrogate, in which case you could use that




To initialize it (Create action only): surrogate

To change it: reference, with a local flow

To use it: reference


Other variable types always use a reference.



Initializing Surrogates from Parent references.



Initializing a Surrogate from a Parent reference, then propagating the value to initialize another Surrogate (rare).



Making a conserved flow from one referenced stock to another in a Process List action.



Invoker (a Bank) lends startup cash to the surrogate of a newCompany in a Create action.


Action Types


There are several types of actions, but all of them have in common the ability to make immediate changes to the values of stocks and attributes. Actions that do nothing other than make such changes are called command actions, and are the most basic type. The other types of actions have the same capabilities as command actions, plus additional capabilities depending on the type.


Note: On any of the action tabs, you can create surrogate links by dragging and dropping a variable on to the page. You can suppress the creation of surrogates and instead create ghosts by holding the Cntrl key while dragging and dropping a variable.


Command ActionsCommand Actions


Self-delete ActionsSelf-delete Actions


Create ActionsCreate Actions


Process List ActionsProcess List Actions


Allocation ActionsAllocate and Market Actions


To summarize the above, we first discussed command actions, the most basic actions that can change attributes and stock values and trigger other actions. We then looked at three variations on the command action: self-delete actions that perform commands then remove an entity from the model, create actions that create new entities and then perform commands, and process list actions, that perform commands on one or more entities from a collection. Finally we looked at allocate and market actions that resolve mismatches in supply and demand. All these actions specify what will happen. We next discuss how to use triggers to specify whether and when an action happens.




Every action must have a trigger that specifies whether and when the action occurs. A trigger may be created in the same entity where the action is defined, or in a different entity. The entity where the action is defined is called the parent of the action, the entity where the trigger is defined is called the invoker of the action. Thus it is possible and even common for a single entity to be both the invoker and the parent of an action.


To create a trigger, either drag a trigger node onto the diagram of the invoking entity and then right click to edit,




or use the New Trigger button on the actions tab of the inspector for the invoking entity,




or drag an action onto a diagram, which will automatically create a new trigger for that action.




Right-click the new trigger to edit. You will be asked to provide the following:




A name for the trigger. You can name the trigger after the action, as shown here, or give it any other descriptive name.




The sequence number sets the order of priority in case more than one trigger is set to occur at the same time.


Period Start triggers occur at the beginning of the time slice; Period End triggers occur at the end of the time slice after other calculations have been done. Set this to "Never" to disable a trigger. Note: Triggers for Allocate and Market actions must be set to "Period Start".


In the "Trigger If:" field, set the conditions that must be met for the triggered action to occur.




Specify the action that will be performed. When the action and trigger are not defined in the same entity, you will need to use a reference to identify the action. See "Who triggers whom?" below.



The description field is a place for any notes or related information.





As shown in the description field in the image above, this trigger is checked every time slice, at the start of the period. If the chameleon's temperature is over 100 and the color is anything other than red, the "Turn Red" action will be invoked, which will set the chameleon's "color" attribute to "red".


Who triggers whom? What to write in "Action to Invoke"


The most crucial aspect of defining a trigger is making sure the correct entity's action is being invoked. The invoker entity (the entity that owns the trigger) must have a defined relationship to the entity that owns the triggered action.


There are three situations to consider:


1.The parent and invoker are the same entity. In other words, the action is defined in the same entity as the trigger, and both show up on the actions tab of the same inspector. In this simplest case, you can specify the Action to Invoke simply by writing the name of the action, as with the "turn red" example above where the trigger and action are owned by the same chameleon entity.


2.The parent and invoker are different entities. In this case, the Action to Invoke field must include a reference to the owner of the action. If your "boy" entity is going to make his girlfriend blush, then the boy entity must have a reference called "girlfriend" to a specific girl. Girl entities must have a "turn red" action defined. The trigger defined in the boy entity will then list "girlfriend.turn red" in the Action to Invoke field.
Note that this applies even if both entities are of the same type. If each platypus entity has a reference to a second platypus called "mate", then a platypus that wants to make its mate blush must list "mate.turn red" in the Action to Invoke field of the trigger. If it just says, "turn red", then each platypus will be making itself blush.


3.The invoker is an action. In other words, you are chaining actions so one trigger invokes an action, which includes a trigger that invokes a second action. For example, if each phoenix entity has both a self-delete action called "death" and a create action called "rebirth", the trigger for "rebirth" should be defined inside the "death" action so a new phoenix can be created just as the old one dies. In this case, the owner of the trigger is the action called "death". The owner of the action to be invoked is the phoenix--that is, the parent of the death action. So, the trigger for rebirth should list "parent.rebirth" as the Action to Invoke.


Fine print: If you are using chains of references to trigger an action, such as writing for an entity to invoke its cousin's tendency to produce cookies, you may not send that chain through an action other than the one you mean to invoke. The first action that is encountered in the sequence of references will be invoked. If your trigger is owned by an action, the first action found outside of that invoking action will be the one that is triggered.


Multiple Triggers for the Same Action


You may create more than one trigger for a single action. The triggers can even be defined in entities of different types -- for example, lions, cheetahs and wild dogs all might have triggers for the action that results in a particular gazelle being eaten. However, any variables that are used in the trigger must be defined in all the different invoking types. If this is not so, an error will result and the model will not run.