Microsoft Dynamics AX 2012
®
How to apply catch-weight to
customizations
Concept Paper
This document describes the best practices to consider when
developing features that utilize the catch-weight functionality.
August 2011
CCAX2012IC0056
Table of Contents
Overview..................................................................................................... 3
Reference methods ..................................................................................... 3
Rules of catch-weight ................................................................................. 4
Know when the quantity in the inventory unit is editable ........................................................... 4
One-Way ............................................................................................................................. 4
One-Way-Once ..................................................................................................................... 4
One-Way-Once “while it’s valid”........................................................................................... 4
Last box logic ....................................................................................................................... 5
No 0-CW transactions ............................................................................................................ 5
Catch-weight in tables ................................................................................ 5
Make new field groups for CW unit fields .................................................................................. 5
Place the validation of CW fields on ValidateField ...................................................................... 5
Place the conversion validation of CW unit to inventory unit on ValidateWrite ............................... 5
Place the conversion of CW to inventory on ModifiedField ........................................................... 5
Have a display method for the CW unit .................................................................................... 6
Catch-weight on methods ........................................................................... 6
Duplicate the inventory logic or replace it with CW units ............................................................ 6
Extend quantity methods to handle also the CW quantity ........................................................... 6
Manually invoke <table>.ValidateField/<table>.ValidateWrite .................................................... 6
Catch-weight in forms ................................................................................. 6
Always display the CW Unit ID ................................................................................................ 6
Display the CW units after the inventory units .......................................................................... 6
Avoid validation or conversion in individual forms ..................................................................... 6
Glossary of terms ........................................................................................ 7
2
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS
Overview
The catch-weight feature enables dual unit of measure functionality in Microsoft Dynamics® AX,
allowing the physical tracking of inventory with two units throughout the product management.
These two units are not necessarily convertible to one another. The two units are independent on
another, but must have a nominal conversion. The nominal conversion represents the estimated
conversion factor between the two units and is used throughout the application to calculate a default
nominal value for the inventory quantity. As the two units are independent it is possible to vary the
inventory quantity from the nominal quantity between a minimum and a maximum value.
This is because any conversion assumes that a fixed ratio of one unit reflects on the other. However,
for the catch-weight functionality, the conversion is not possible: two distinct values of the catchweight unit may represent the same value of the inventory unit. In other words, overlap of conversion
may happen.
Figure 1 Scenario where CW1 = [101...107], CW2 = [105...113], and CW3 starts at 111
Due to the complexity of such a system, a set of best practices (or BPs) is defined in all element
types, to ensure catch-weight has the same behavior throughout the application.
Those BPs are either rules applicable to all element types or general guidelines per element type.
Exceptions to the rules need to be considered carefully and, if possible, avoided.
This document presents these BPs so that the implementation is consistent throughout the application.
Reference methods
The following methods should be used to support the scenarios described later in this document.
Class
Method
Description
Global
pdsIsCWItem
Checks whether an item is CW.
PdsCatchWeight
inventQty
Gets the nominal quantity for a CW
value.
PdsCatchWeight
cwQty
Gets the nominal CW quantity for an
inventory quantity.
PdsCatchWeight
validateQty
Checks whether a combination of
CW and Inventory quantity values is
accepted. If it is not, an error
message states the accepted
values.
PdsCatchWeightItem (table)
pdsCWIsValidQty
Checks whether a combination of
CW and inventory quantity values is
accepted. If it is not, an error
message is not displayed; the
method just returns false.
3
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS
Rules of catch-weight
This section presents the rules of catch-weight that need to be respected, regardless of the element
type or functional area.
Know when the quantity in the inventory unit is editable
This is a fundamental rule that cannot be broken: within a functional area, there must be consistency
about when the units are editable. This is crucial to maintain data integrity and to be consistent with
all the forms that work over the same tables.
The following scenarios are allowed.
Scenario/field
CW field
Inventory field
Purchase/sales
unit
Rules of
adjustment
allowed
1
Editable
Blocked
Blocked
One-Way
2
Editable
Editable
Blocked
One-Way
One-Way-Once
3
Editable
Editable
Editable
One-Way
One-Way-Once
“while it’s valid”
4
Editable
Blocked
Editable
One-Way
One-Way
If the form or code allows input in the CW unit, the inventory unit should always be calculated based
on nominal conversion.
One-Way-Once
If the form or code allows input to both CW and inventory units, it should convert one time (from
either direction) based on nominal conversion, while the other unit is empty (cleared).
After the first conversion, all input to these values is manual, and only validation should be in place,
not conversion.
Example (based on Figure 1):

Set CW quantity to 1  Inventory quantity is set to 106.

Set CW quantity to 2  Inventory quantity is not changed (stays 106).

Set CW quantity to 3  Inventory quantity is not changed (stays 106) and must return an error
on validation, because the value is not within the conversion ratio.
One-Way-Once “while it’s valid”
As a small variation of the previous rule, the value on the inventory unit can be recalculated to the
nominal conversion value if the input in the catch-weight unit was changed to a value outside of
range.
Example (based on Figure 1):

Set CW quantity to 1  Inventory quantity is set to 106.

Set CW quantity to 2  Inventory quantity is not changed (stays 106), because 106 is still valid.

Set CW quantity to 3  Inventory quantity is changed to 114, because 106 was no longer valid.
4
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS
Last box logic
When a transaction moves a portion of inventory with a collection of CW and inventory quantities, and
the original CW volume (for example, on-hand) is consumed entirely by that transaction, all remaining
inventory should be moved too.
Example (based on Figure 1):

The on-hand amount of Item A is 107 inventory quantity, 1 CW.

The transaction is moving 1.

All 107 should move (even if 107 is more than the nominal conversion of CW=1).
Example (based on Figure 1):

The on-hand amount of Item A is 107 inventory quantity, 2 CW.

The transaction is moving 2.

All 107 should move (even if 107 is less than the nominal conversion of CW=2).
No 0-CW transactions
All processes that move inventory should be prepared so that the transactions are always in a correct
state after the process is over.
It is typical that a process leaves incorrect transactions in the middle stages of the process, but
corrective code should be put in place so that the transactions are correct at the end of the process.
A correct transaction should:

Not have CW=0, inventory quantity != 0.

Have both units with the same sign.
Catch-weight in tables
This section presents some suggested BPs for implementing BPs on tables.
Make new field groups for CW unit fields
The code developed in another layer should preferably create field groups that keep the specific
functionality isolated.
Place the validation of CW fields on ValidateField
The code that validates CW values should be placed on the ValidateField/ValidateFieldValue
methods.
Place the conversion validation of CW unit to inventory unit on
ValidateWrite
Add extra validation for the quantities on the ValidateWrite method.
Place the conversion of CW to inventory on ModifiedField
The code that converts CW values to inventory values should be placed on ModifiedField.
5
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS
Have a display method for the CW unit
Implement a method that returns the ID of the CW unit, such as:
//<PMF>
[SysClientCacheDataMethodAttribute(true)]
public display PdsCWUnitId pdsCWUnitId()
{
return PdsCatchWeight::cwUnitId(this.ItemId);
}
//</PMF>
Catch-weight on methods
Duplicate the inventory logic or replace it with CW units
Depending on the functionality requested, the logic that manipulates the inventory quantity should be
extended in such a way that the same operations are executed for CW values, or they are only done
for CW values (and inventory values are calculated later on, for instance).
Extend quantity methods to handle also the CW quantity
If the inventory quantity is passed as a parameter, most likely the CW quantity also needs to be. If
logic is executed in some way for the inventory quantity, most likely the same logic should be applied
to the CW quantity. Typically, tracing the code based on the inventory quantity is a good exercise for
locating all the customization points that have been done.
Manually invoke <table>.ValidateField/<table>.ValidateWrite
Invoke the validation methods on the records being manipulated in the business logic classes. Often,
these elements skip the validation methods and directly manipulate the values in the records.
Catch-weight in forms
Always display the CW Unit ID
Always include a field connected to the display method <table>.PdsCWUnitId() in all grids that
present CW values, and position the field after the CW value control.
Display the CW units after the inventory units
Position the controls on the forms in such a way that catch-weight controls are positioned after the
inventory ones.
Avoid validation or conversion in individual forms
Use a PdsCWFormCtrl-derived class to automatically convert and validate the CW and inventory
controls, and to automatically toggle the enabled/disabled status, avoiding manual implementation of
the logic.
See the PdsCWFormCtrl_SalesTable class for an example of the customization applied to the
SalesTable form.
6
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS
Glossary of terms
Term
Definition
BP
Best practice.
CW
Catch-weight.
Nominal conversion
The reference factor between one quantity of a product in the catchweight unit and one quantity of the same product in the inventory unit.
Qty
Quantity.
7
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS
Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your
people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar
Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a
way that helps you drive business success.
U.S. and Canada Toll Free 1-888-477-7989
Worldwide +1-701-281-6500
www.microsoft.com/dynamics
This document is provided “as-is.” Information and views expressed in this document, including URL and other Internet Web site
references, may change without notice. You bear the risk of using it.
Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or
should be inferred.
This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and
use this document for your internal, reference purposes. You may modify this document for your internal, reference purposes.
© 2012 Microsoft Corporation. All rights reserved.
Microsoft, Microsoft Dynamics, and the Microsoft Dynamics logo are trademarks of the Microsoft group of companies.
All other trademarks are property of their respective owners.
8
HOW TO APPLY CATCH-WEIGHT TO CUSTOMIZATIONS