Event Listening

What is Event Listening?

Event listening is primarily used for two purposes:

Adding Logic to an Event - The Process Flow tool has event-listening activities that can listen for certain events in the 3D model and add custom logic that will be executed when this event occurs. You can also use FlexScript to add custom logic to 3D model events. Event listening is one of the most common ways to link a process flow to a 3D model.
Collecting Statistics - The Statistics Collector can listen to events in both the 3D model and the Process Flow tool and gather data from those events. This tool makes it possible to create custom statistics to meet your unique business system's analysis needs.

Requirements for Event Listening

Whenever you are using one of the event listening tools, there are two fundamental questions that need to be answered:

Which object will the activity listen to?
Which event on that object will trigger the creation and/or release of a token?

In other words, you need both an object and event to set up an event-listening activity. These two requirements usually correlate with the properties on event listening tools.

Object

You have a couple of different options when deciding which object to link to:

Static Object - You can link to a specific static object in your simulation model such as a 3D object or another activity in a process flow.
Dynamic Object - You can set the object to be context-sensitive, meaning it will change based on certain conditions.
Groups of Objects - You can link to a group of objects and the activity will listen for any time the event fires on any member of that group.
Flow items or tokens - You can link dynamically to flow items or tokens. For example, you could listen to flow items exiting a fixed resource or tokens leaving an activity.
Modeling Tools - Many of the tools found in the toolbox have events associated with them that you can listen to. This is especially useful for objects like the Time Table that will allow you to listen for down and up times.

Event

In general, there are two different types of events:

Standard Events - The normal simulation events that occur during a simulation run, such as an item entering a fixed resource or a token entering an activity in a process flow. Each event has a trigger associated with it that will fire when that event occurs. See Key Concepts About Events for a more thorough explanation of simulation events and triggers.
Statistical Events - Statistical events occur when a statistical value on a object changes or when the object enters into a specific state. For example, you could listen for when the number of items inside a queue changes, or when a processor changes to an idle state, etc.

The event-listening activity will create and/or release a token whenever the activity you select occurs in the simulation model.

Event Parameters and Label Assignment

Standard, object-based events have specific parameters associated with them. These parameters contain basic information about the event, such as which flow item or token triggered the event. You'll usually want to preserve some of this information by putting it into a label that can be referenced by other process flow activities or by putting the value in a statistics collector's data table.

The best way to preserve this information is to use the Label Assignment or Label Matching table that is available in event listening tools. This table will be explained in more depth in the Label Matching topic.

Overriding Return Values

Be aware that event-listening process flow activities have the ability to override the return value of events they listen to when they're used in a sub flow. For example, you may want to perform some complex logic using the Process Flow tool to define the process time of a processor, as illustrated in Process Flow Tutorial 3 - Sub Flows.

Setting Up an Event Listening

The method you will use to set up an event listening will depend on 1) which tool you are using and 2) the type of object you want to listen to.

Process Flow Event Listening

To listen to events in the Process Flow tool, you'll need to use an event-listening activity. The two process flow activities that can listen for events are:

Event-Triggered Source - This activity will listen for a specific event to occur in the simulation model. When that event occurs, it will create one or more new tokens and send the tokens to the next activity in the process flow. You should use an event-triggered source if you want the triggering event to initiate the process flow.
Wait for Event - After this activity receives a token, it will hold the token while it listens for a specific event to occur in the simulation model (or in the process flow). When that event occurs, it will release the token to the next activity in the process flow. If needed, you can also make the Wait for Event act like a Decide activity. In other words, the Wait for Event activity could possibly send the token to different activities next based on certain conditions in the simulation model.

These two activities have properties where you can specify which which Object and Event that should be listened to:

Statistics Collector Event Listening

The Statistics Collector creates a data table by listening to events, and then recording information about those events. For more information, see the Statistics Collector topic.

Listening to a Static Object

Before you can set up event-listening for a static object, make sure the object you want to listen has been added to your 3D model or process flow.

To set up event-listening for a static object:

With the process flow tab active, add a Wait for Event or Event-Triggered Source to the process flow.
Click the activity's icon to open its properties, as shown in the following image:

Next to the Object box, click the Sampler button to enter sampling mode. Click the object you want to listen to. This will open a menu that will list all of the possible events available for that object. Select the appropriate event from the menu.

The object and event you selected will now be listed in both the Object and Event boxes in the activity's properties. Based on the type of event you selected, some additional properties might now be available in the activity's properties.

Listening to a Dynamic Object

You can set the object to be context-sensitive, meaning it will change based on certain conditions. One way to do this is to use the current keyword on any type of process flow except general process flows. The event-listening activity will listen to the object that is attached to each instance of that process flow. (See Process Flow Instances for more information.)

Be aware that you cannot listen to a dynamic object on a general process flow. But the other three types of process flows have this ability.

Before setting up event-listening for a dynamic object, you might want to add at least one of the type of objects to which you will listen to the 3D model or process flow. Even though you won't link to this object directly, you'll need this object so that you can sample its events.

To set up event-listening for a dynamic object:

With the process flow tab active, add a Wait for Event or Event-Triggered Source to the process flow.
Click the activity's icon to open its properties, as shown in the following image:

Check to ensure that the Object box says current, which is the default value for this property. If it says something else, click the arrow next to the Object box to open a menu. Select current (Instance Object) from the menu.
Next to the Event box, click the Sampler button to enter sampling mode. Click the object you want to listen to. This will open a menu that will list all of the possible events available for that object. Select the appropriate event from the menu.
The event you selected will now be listed in the Event box in the activity's properties. Based on the type of event you selected, some additional properties might now be available in the activity's properties.

Listening to a Group

Before setting up event listening for a group, you need to first create the group. Make sure the group has at least one member. Even though you won't link to this object directly, you'll need this object so that you can sample its events.

To set up event listening for a group:

With the process flow tab active, add a Wait for Event or Event-Triggered Source to the process flow.
Click the activity's icon to open its properties, as shown in the following image:

Click the arrow next to the Object box to open a menu. Point to Groups, then select the name of the group you want to listen to.
Next to the Event box, click the Sampler button to enter sampling mode. Click the object you want to listen to. This will open a menu that will list all of the possible events available for that object. Select the appropriate event from the menu.
The event you selected will now be listed in the Event box in the activity's properties. Based on the type of event you selected, some additional properties might now be available in the activity's properties.

Listening to Flow Items or Tokens

To listen to flow items or tokens, you'll need to create a dynamic reference to them on the event-listener. Before setting up event listening for a flow item, you need to add a source to your 3D model. Before setting up event listening for a token, you need to make sure the activity to which you want to listen has been added to the process flow.

Flow items have the following events:

Event	Description
On Entering	Fired when the flow item enters a fixed resource or is loaded by a task executer object
On Exiting	Fired when the flow item exits a fixed resource or is unloaded by a task executer object.

Tokens have the following events:

Event	Description
On Entering	Fired when the token enters an activity
On Exiting	Fired when the token exits an activity.
On Manual Release	Fired when the token is manually released from an activity using the releasetoken() command
On Asset Allocated	Fired when the token allocates a shared asset. This may be acquiring a resource, entering a zone being pushed onto a list or creating a backorder when pulling from a list.
On Asset Deallocated	Fired when the token deallocates a shared asset. This may be releasing a resource, exiting a zone being pulled from a list, or completing a backorder.
On Label Value Change	Fired when a label value changes. This is only available if a label is stored as a tracked variable.

To set up event listening for a flow item or token:

Run the simulation model so that at least one flow item and/or token is in the model.
With the process flow tab active, add a Wait for Event to the process flow.
Click the activity's icon to open its properties, as shown in the following image:

Next to the Event box, click the Sampler button to enter sampling mode. Click the flow item in the 3D model. This will open a menu that will list all of the possible events available for that object.
In the Object box, use a label that will reference the flow items or tokens dynamically.

Listening to a Tool

You can use the sampler to hover over objects in the Toolbox and select the desired event, or you can hover over the picklists in their properties windows to select one of these events.

Listening to a Statistical Event or Change

You can listen to a statistical event on a 3D object or process flow activity. The process is the same as setting up a static event, except that you will choose a statistical event from the menu when you sample the object you are going to list to.

The following table gives examples of some of the most common statistical events:

Event	Description
On Content Change	Fires when the number of flow items inside a fixed resources changes or when the number of tokens in an activity or zone changes
On Input/Output Change	Fires when a flow item enters or exits a fixed resource or when a token enters or exits an activity
On Staytime Change	Fires when a flow item exits a fixed resource or when a token exits an activity; this event will track different statistical information about how long the item or token remained at the activity
On State Change	Fires when an object changes states, such as from Idle to Processing
On Resource Available	Fires when a task executer has finished a task or task sequence

After you've set up event listening to one of these events, you can further specify the statistical conditions that will trigger the event, as shown in the following table:

Change Rule	Explanation
Change	The event will be fired whenever the value changes at all.
Increase	The event will be fired whenever the value increases.
Decrease	The event will be fired whenever the value decreases.
Arrive At Value	The event will be fired whenever the value changes to a specific user-defined value.
Increase To Exact Value	The event will be fired whenever the value increases to a specific user-defined value.
Decrease To Exact Value	The event will be fired whenever the value decreases to a specific user-defined value.
Increase To Or Through Value	The event will be fired whenever the value changes from being less than a user-defined value, to being greater than or equal to that value.
Decrease To Or Through Value	The event will be fired whenever the value changes from being greater than a user-defined value, to being less than or equal to that value.
First Increase	The event will be fired whenever the value changes from decreasing to increasing.
First Decrease	The event will be fired whenever the value changes from increasing to decreasing.
Update	The event will be fired whenever the value is set, whether or not the value changes. This event is only available on the Statistics Collector.

Some additional considerations:

If you use the Arrive At Value, you'll need to specify which value needs to be arrived at in the Value box.
You will need to check the Fire If Initial Value Meets Rule if you wan the first token to be able to meet the initial value.
In some cases, depending on the event you subscribe to, there may be additional fields required in order to properly bind to the event. For example, if you bind to a List's OnContentChange event, you will need to provide the Partition ID that you want to listen to. Just enter the Partition ID in its corresponding field.