article

This topic will talk about the two ways that a batch may be released from the Batch activity. This can happen either when the batch is full (see Organizing Batches for information about how batches are collected and sorted), or when a batch is manually released. In both cases at least one token will leave the Batch activity.

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:

This topic will explain how you can use these properties to control what happens when a Batch activity is ready to release a batch. It will cover the following topics:

• Releasing More than One Token and Destroying Tokens
• Assigning Labels to Outgoing Batches
• Releasing a Batch Early

Releasing More than One Token and Destroying Tokens

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.

Release Order

There are a number of references below to the order in which tokens are released from the batch. Though all of the tokens are released at the same model time (in 0 model time), the order in which they are released may impact the flow of your process flow. For instance, the first token released from the batch will enter an Acquire activity first and may acquire a resource before any other tokens from the same batch arrive.

If # Tokens to Release is Equal to the # of Collected Tokens

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 # Tokens to Release is Greater than the # of Collected Tokens

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 # Tokens to Release is Less than the # of Collected Tokens

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:

1. Tokens that have children in the same batch should be preserved over their children. (See Sub Process Flows for more information about tokens with parent-child relationships.)
2. Tokens with more children should be preserved over tokens with fewer children.
3. Tokens with more allocated shared assets should be preserved over tokens with fewer allocated shared assets.

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:

• If the Batch activity destroys a token that has a parent that is in a Run Sub Flow activity, the parent activity will be notified that the child finished.
• Any shared assets that have been allocated by the token will be deallocated.
• If the token has children, the token will not be destroyed until all its children are destroyed (it will remain in the activity but will not be part of any subsequent batch).

Extra tokens will be destroyed before any tokens are released from the Batch activity.

Assigning Labels to Outgoing Batches

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, utilizing 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:

1. Click the Batch activity to select it.
2. In Quick Properties, under the Label Aggregation group, click the Add button to add a new label. A new row will appear in the table.
3. In the From Label column, double-click on the cell with the text that says labelName. Type the name of the label on the tokens in the batch that will be used as the source of the data. For example, if the incoming tokens all have a label named Weight, you would type that label name here.
4. In the To Label column, double-click on the cell with the text that says labelName. Type the new name of the label that will be assigned to outgoing tokens. For example, the new name could be BatchWeight.
5. In the Aggregation column, you'll select how the value of the new label will be calculated or assigned. Click on the cell with the text that says Batch ID to open a menu. Select the appropriate option from the menu. For example, if you wanted to calculate the total sum of all the batched token's Weight labels, you could select SUM from this menu.

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:

• Batch ID - Starting at 1, each batch that is released from the Batch activity will increment the Batch ID by 1. The Batch ID is only guaranteed to be unique among batches produced by a given Batch activity.
• Token Count - The number of tokens collected in the batch. If the Quantifier property is set to Number of Tokens, this value will be equal to the Batch Quantity value.
• Last Collected - This will get the label value of the From Label on the last token to enter the batch.
• First Collected - This will get the label value of the From Label on the first token to enter the batch.
• SUM - Sums the From Label values on all tokens in the batch.
• AVG - Gets the average of the From Label values on all tokens in the batch.
• MIN - Gets the minimum From Label value on all tokens in the batch.
• MAX - Gets the maximum From Label value on all tokens in the batch.
• STD - Gets the standard deviation of the From Label values on all tokens in the batch.
• VAR - Gets the variance of the From Label values on all tokens in the batch.
• COUNT - Gets the number of tokens in the batch that have a label named From Label.

Aggregating the Quantifier Label when using Overflow

If you are batching by a label on the tokens and your Overflow is set to Hold Excess Quantity or Destroy Excess Quantity then the quantifier label may be modified prior to performing the aggregation. For example, if you collect by the label Weight and if the Batch Quantity is set to 300 and the final batched quantity is 350, the SUM of the Weight label will be equal to 300, not 350.

Releasing a Batch Early

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.