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:
- Batch Quantity - This property 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.
- Quantifier - This property sets the criteria that will determine how the batch quantity is calculated.
- Group By - This property sets the criteria by which entering tokens will be organized and grouped into batches.
- Overflow - This property determines what will happen if an entering token will cause the batch to exceed its Batch Quantity.
With that in mind, the Quantifier has two different methods for collecting and organizing tokens:
- Batch by number of tokens - If you select this option (which is the default), the Batch Quantity will be based upon the number of tokens that arrive at the Batch activity. Each entering token will increase the current quantity of the batch by one. When the number of tokens reaches the value specified in the Batch Quantity property, the batch will be released.
- Batch by a label on the 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 stroed on the label.
Each of these methods will be explained in the following sections. This topic will also cover:
- Batch Overflow Options - Explains how to control what happens if an entering token's label exceeds the specified Batch Quantity.
- Grouping - Describes how to use the Group By property to group entering tokens into different batches allowing you to collect multiple batches simultaneously.
Batch by the Number of Tokens
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:
- Click the Batch activity to select it.
- In Quick Properties, check that the Quantifier box says Number of Tokens.
- Click in the Batch Quantity box and type the number of tokens that should be collected in each batch.
See Releasing Batches for more information about what happens when a batch is ready for release.
Batch by a Label on the 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 Label: 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:
- Make sure an Assign Labels activity or some other activity earlier in the process flow will create the label that will be used for batching.
- Click on the Batch activity in your process flow to select it.
- In Quick Properties, click the arrow next to the Quantifier box to open a menu. Point to Token Label, which will open up a submenu listing all the labels that currently exist in the process flow. Select the desired label from the menu by double-clicking it or using the arrow and Enter keys.
- The Quantifier box will now show the command
Label: YourLabelName. For example, if the label is named Weight, the box would read:Label: Weight. Alternatively, you could typeLabel: Weightinto the box or use the commandgetlabel(token, "Weight"). You can also enter a string into this box using quotes. ie "Weight" - Click in the Batch Quantity box and type the target batch quantity. For example, if you wanted the Batch activity to collect tokens until it reaches a collective weight of 300 grams, you would type
300here.
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.
See Releasing Batches for more information about what happens when a batch is ready for release.
What if the Label Value Exceeds the Batch Quantity?
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. See Batch Overflow Options in the next section for more information about how to control overflows.
Batch Overflow Options
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.
Batching by Number of Tokens Won't Cause OverflowsIf you are batch by number of tokens, your batch will never exceed the specified Batch Quantity and therefore won't trigger the 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:
- Do Not Divide, Release Excess - The batch is released without modification. If this option is selected, the batch would be released including its excess quantity. For example, if the Batch Quantity is set to 300 and an entering token would cause the batch to overflow by 50, the batch would be released with a quantity of 350.
- Do Not Divide, Release Partial - Rather than release an overflowed batch, the Batch activity will release a batch that is only partially full. The entering token that would have caused the batch to overflow is put in the next batch. This logic can be illustrated using the same example in which the Batch Quantity is set to 300 and the current batch has a quantity of 200. An entering token has a value of 150, which would cause the batch to overflow by 50. When this happens, the current batch would be released with a quantity of 200 and the entering token would be placed in a new batch with a quantity of 150.
- Hold Excess Quantity - The current batch will be released with the exact required quantity. A new token is then created and placed in a new batch with a label containing the excess quantity. All labels and label values are copied from the last token (the one that caused the overflow) to the new token. For example, if the Batch Quantity is set to 300 and an entering token would cause the batch to overflow by 50, the batch would be released with a quantity of 300. Then, a new batch would be started with a new, nearly identical token containing a label with a quantity of 50.
- Destroy Excess Quantity - The label value of the last token is reduced until the batch contains the exact amount specified by the Batch Quantity property. This essentially destroys the overflowed quantity.
New Batches Created from Excess Quantities
If you choose the Do Not Divide, Release Partial or Hold Excess Quantity options, you have the possibility of creating new batches with the entering token. Be aware that if the next batch created from the entering token meets the batch quantity, it will be immediately released. If the new batch exceeds the batch quantity, it will trigger the overflow logic again. This will continue until the quantity is less than the Batch Quantity.
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.
Grouping
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.
