In the Process Flow module, the Batch activity collects incoming tokens and sorts them into groups of tokens (batches). When a batch is ready, the Batch activity will release it to the next activity.
The Batch activity basically functions similarly to Combiners and Separators in the 3D model in that it is capable of both combining and separating tokens.
Using the Batch activity for simple grouping and releasing is relatively straightforward. However, the Batch activity has some additional features that allow you to collect, sort, and release batches in fairly complex ways. If you want to learn more about what the Batch activity is really capable of, consider reading the following topics:
The rest of this topic is a reference page for the Batch activity and its properties.
The Batch activity can collect entering tokens and organize them into batches based on the criteria you specify. The following properties on the Batch activity are directly involved in how batches organize tokens:
With that in mind, the Quantifier has two different methods for collecting and organizing tokens:
Each of these methods will be explained in the following sections.
The simplest (and default) method of batching is to collect by the number of tokens. This means that entering tokens each take up one space in their batch with respect to the Batch Quantity. When the number of tokens reaches the value specified in the Batch Quantity property, the batch will be released.
To set the Batch activity to collect by number of tokens:
If you select this option, the Batch Quantity will be based upon the value of a label on
the entering tokens. In this case, a token can increase the batched quantity by any numeric
value listed in the label. For example, if the Quantifier is set to
token.Weight
and the entering token has a label named Weight with a
quantity of 200, the token will increase the current batch's quantity by 200 when it is
added to the batch.
To set the Batch to collect by label values:
token.YourLabelName
. For example, if the label is named Weight,
the box would read: token.Weight
. Alternatively, you could type
token.Weight
into the box. You can also enter a string into this box using
quotation marks: "Weight"
.300
here.Now each time a token enters the batch, the value of the specified label on each token will be added to the current batch quantity. When the batch quantity reaches the specified limit, the batch will be released. For example, imagine a Batch activity is using a label named Weight to collect tokens and it has a specified Batch Quantity of 300, meaning it needs to collect a total weight of 300 in order to get released. If the first token that enters the Batch activity has a Weight label with a value of 200 and the second token's Weight label has a value of 100, the batch would get released after the second token is added to the batch. That's because the total sum of the Weight label for both tokens would be 300, which was the target weight for each batch.
When batching by a label, it is possible that the batched quantity may be greater than the specified Batch Quantity, which will cause the batch to overflow. When that happens, it will trigger the Batch activity's overflow logic.
To illustrate what happens when a batch is going to overflow, let's return to the same example that was used in the previous section. As a reminder, in this example, the Batch activity is set to release the batch when the total sum of the Weight label is 300. If the first token's Weight label has a value of 200 and the second token's Weight label has a value of 150, the total sum of the Weight label for both tokens would be 350. 350 would exceed the target weight for that batch and it would therefore trigger the Batch's overflow logic.
When overflow occurs the Batch activity's behavior is governed by the Overflow property. This property has a menu with the following options:
The overflow logic only affects the label value that is specified by the Quantifier property. Other labels on the tokens will not be affected. Label Aggregation can also be affected if of a token is held over to be released in a new batch. See Assigning Labels to Outgoing Batches for more information.
When a new token arrives at the Batch activity, it will evaluate the Group By property and place the token into the matching batch. If no matching batch is found, a new batch will be created. By default, Group By is set to None and only one batch will be created at a time. But you can use the Group By property if you want to sort your tokens based upon criteria you specify. For example, you could sort tokens into batches based on the token's label values, names, or the object to which the token is linked. Generally this will be a label on the entering token, but it may reference a global table or other value.
The Group By can be numbers, strings, or objects, as explained in the following table:
Type | Description | Example |
---|---|---|
Number | The tokens can be grouped into batches based on a number, such as a numerical value in a label on the token. The number can be an integer or floating point number and it may be negative or positive. | ![]() |
Text | The tokens can be grouped into batches based on a string (which is another word for text). For example, you could have an Assign Labels activity earlier in the process flow that assigns a new label to each token called Batch and it could assign the strings "First Batch" or "Second Batch" to a certain percentage of the tokens. | ![]() |
Object | The tokens can be grouped into batches based on an object. For example, the tokens might have a label called ProcessBy that references a processor in the 3D model that needs to process that particular batch of tokens (Processor1, Processor2, or Processor3). | ![]() |
Batches displayed on the Batch activity will be displayed oldest to newest from top to bottom and from left to right.
The Batch activity has a variety of different options you can use to control how batches are released. The following properties on the Batch activity are used when a batch is released:
The Batch activity allows any number of tokens to be released when a batch is finished. This can be useful to simulate a process that collects materials, combines them together, and then divides the combined materials equally into a certain number of portions. For example, a Batch activity could be set to collect 5 tokens and release 3 tokens, almost as though it had mixed the original tokens together and divided them up into different portions.
You can use the # Tokens to Release property to change how many tokens get released. This number can be the same number of tokens collected in the batch, greater than the number of tokens collected, or less than the number of tokens collected. It's important to understand what is happening inside the batch for each of these three scenarios.
This is the simplest of the three scenarios. If three tokens are collected in the batch and the # Tokens to Release is set to three, then all three of the original tokens added to the batch will be released in the same order in which they arrived. This can be useful as a method of syncing a set of tokens.
If the Quantifier is set to a label value, the number of tokens in each batch may vary. In order to release all of the tokens that were collected in the batch, you can select the option Number of Tokens Batched or return any number <= 0 in the # Tokens to Release box.
If the number specified in the # Tokens to Release box is greater than the number of tokens collected in the batch, the Batch activity will create and release new tokens. These new tokens will have no initial labels. Labels may be created on these new tokens by using the Label Aggregation. See Assigning Labels to Outgoing Batches for more information. These new tokens will be the last to leave the Batch activity.
If the # Tokens to Release is less than the number of tokens collected in the batch, tokens will be destroyed until the correct number of tokens remains. In deciding which tokens to destroy and which to preserve, the Batch activity prioritizes tokens using the following rules, in order:
Once the Batch activity has prioritized the tokens, it will destroy tokens with the lowest resulting priority.
Be aware that when a Batch activity destroys tokens, it functions in a way that is similar to Finish activity:
Extra tokens will be destroyed before any tokens are released from the Batch activity.
By default, tokens that enter and leave the Batch activity will retain their labels and no new labels will be added to them. Newly created tokens will have no labels assigned to them. However, using the Label Aggregation, the Batch activity can assign new labels or aggregate the labels of the tokens that were included in the batch to all of the outgoing tokens. Label aggregation does not occur until the batch has collected all of its tokens as has reached the Batch Quantity value.
One possible use of the label aggregation would be to calculate the total weight of all of the parts that are combined into a single part. If each token represented a single part and they each had a label named Weight, the label aggregation can be used to sum all of the weights of every token added to the batch and create a new label like BatchWeight that will be assigned to all of the outgoing tokens.
To assign labels to outgoing batches:
For your reference:
From Label - The name of a label on the batched tokens that will be used as a source of data. The value of this label from each token will be used to calculate the aggregated value. If the label does not exist on a token, the returned value will be 0. NOTE: This entry is not used for the Batch ID and Token Count aggregation types.
To Label - The name of the label that the new value will be written to. Each token in the outgoing batch will get a label with this name, and with the assigned value.
Aggregation - The value that will be assigned to the To Label on all tokens released for the batch. The possible values are as follows:
The Batch activity has both a Max Wait Time and Max Idle Time property. These properties allow you to define start criteria and the amount of time to wait before firing a trigger. If the batch reaches one of these times and calls either the OnWaitTimerFired or OnIdleTimerFired trigger, you have the option to release the batch early. However, this is not a requirement. If the batch is not released, the batch will continue to collect tokens until it reaches its Batch Quantity, after which the batch will be released as normal.
The Max Wait Time and Max Idle Time properties give you a reference to the batch. The
releasebatch()
command can be called to release a batch prematurely from within
the OnWaitTimerFired or OnIdleTimerFired triggers or from anywhere else in the model. If
failed is 1, the batch will immediately release all tokens in the batch and not perform any
label aggregation or evaluate the # of Tokens to Release property. If failed is 0, the batch
will release normally and evaluate the # of Tokens to Release and perform all of the label
aggregations on the tokens in the batch. The releasebatch()
command also gives
you the ability to send the released tokens out any connector of the Batch activity. The
connector can be referenced by index or name. The releasebatch()
command even
allows you to release tokens to an activity that is not directly connected to the Batch
activity by referencing the activity using getactivity()
.
See Max Wait Time and Max Idle Time for more information about these properties.
The Batch activity allows for any number of connectors out. However, batches that complete will always exit out the first connector. Only manually released batches have the opportunity to exit out a different connector. See Adding and Connecting Activities for more information.
The following image shows properties for the Batch activity:
Each of these properties will be explained in the following sections.
Used to change the name of the activity. See Name for more information about this property.
This button opens a window to edit the
activity's background color and font properties. See
Font for more information
about this property.
This button opens the activity's
statistics window. See
Statistics for more
information about this property.
The Batch Quantity box sets the target value for the batch. The batch will continue collecting tokens until this value is reached, after which the batch will be released. See Organizing Batches for more information.
The Quantifier box sets the criteria that will determine how the batch quantity is calculated. You can either collect by Number of Tokens or by a label on the incoming tokens. See Organizing Batches for more information.
Specifies the quantity of tokens that the batch will release once it has finished collecting.
The Group By box sets the criteria by which incoming tokens will be grouped into batches.
The Overflow setting controls what happens to values that exceed the Batch Quantity while collecting. This option is not available when collecting by the Number of Tokens Batch Overflow Options for more information.
Using this set of properties, you can create and modify labels on tokens when a batch is released. The operation performed, as set in the Aggregation column, will be done on every token that was added to the batch, even if the token is destroyed when the batch is released. Once the operation is performed, the resulting value will be set on every token being released by the batch. See Assigning Labels to Outgoing Batches for more information.
The Max Wait Timer will be evaluated when a batch is first created. If a timer is not created because the Start Criteria evaluates to false, the max wait timer will be evaluated each time a token is added to the batch until the Start Criteria does evaluate to true. See Releasing a Batch Early for more information.
The Max Idle Timer will be evaluated each time a token is added to a batch. See Releasing a Batch Early for more information.