What is a substitution?
Substitutions are functions to allow you to manipulate a string or an array of strings that are pulled from your data in Acumatica. Substitutions are a useful and powerful tool to apply to Data Elements as they control the output of values printed onto the label. For example, use cases for substitutions are to format the weight of a product to round up to 2 decimals on the label or format a date time value to only print the date in a particular sequence (i.e., MM/DD/YYYY).
Substitutions can vary in complexity from datetime, string functions to Regex expressions. For the sake of simplicity, this article will discuss the most common substitutions.
What makes a substitution?
Substitutions on their own cannot be used to manipulate data. To use a substitution, a composite substitution needs to be created. Composite substitutions always have at least 3 main components. These components are a Child Substitution and 2 arguments.
Child Substitution: Refers to the foundation on which the composite substitution will be built. It is composed of a substitution type and a function (i.e., AcuFunctions - DateTimeToString or MathFunctions - Format). The child substitution also tells the composite how many arguments are expected and the object type (object, string, int, datetime, etc.) that needs to be mapped for each argument.
Argument 1: Every substitution requires an argument. For the case of the first argument, the composite substitution requires a reference to an object to which the substitution will be applied to. Since the substitution is applied directly to the data element, the typical argument that will be used for substitution is "_this_"
Argument 2: Unlike argument 1, the second argument is almost always different and depends on the substitution that is being built. Its object type will change and so will the function call mapped to the substitution.
Argument 3+: Not always required. Some substitutions will require more than 2 arguments by which the appropriate functions will need to be mapped accordingly.
How to create a substitution?
All substitutions are created from the Substitutions screen (AL206500). There are hundreds if not thousands of different substitutions that can be created. Even within a single substitution type such as a Datetime or Math Format substitution, many variations can be created. For the sake of simplicity, the following substitutions will cover 1 variation of a given substitution with guidance on creating other variations will be provided.
DateTime formatting substitution
To create a substitution to format the date, the child substitution to use is "DateTimeFunctions.ToString"
Arg. 1 will always be "_this_" to refer to the data element object
Arg. 2 will have some variations depending on how you would like the date the be represented on the label. The elements, regardless of their order, must be encased in between single quotation marks (' '). The list below showcases some of the variations.
Variable | Explanation | Example |
%Y | returns the full year | '2024' |
%y | returns the last 2 digits of a year | '24' |
%m | returns the month | '09' |
%d | returns the day | '16' |
(As an example, using the following argument '%Y%m%d' would return 20240916)
Separation characters can also be added to the argument to make the date easier to read. For instance, adding a slash ('/'), or a hyphen ('-') to separate the date elements. So, if we re-used the above example with added separation characters '%Y/%m/%d', the returned value would be 2024/09/16.
Number Formatting substitution
To create a substitution to format a number, the child substitution to use is "MathFunctions.Format"
Arg. 1 will always be "_this_" to refer to the data element object
Arg. 2 will always follow the same convention. The argument will be encased between single quotation marks (' ') and start with a capital 'F' followed by a number. This number dictates the number of decimals that will be returned.
In the above image, 'F2' refers to cutting the number at 2 decimal points. For example, given the number 20.952, using the 'F2' argument would return 20.95
Join array substitution
Join substitution can be useful to join a sequence of words together. For instance, joining an address, state, country, and zip code into a single string to be represented on the label.
To create a substitution to join an array, the child substitution to use is "ArrayFunctions.Join"
Arg. 1 will always be "_this_" to refer to the data element object
Arg. 2 will always follow the same convention. The argument will be encased between single quotation marks (' '). Between the quotation marks, a character may be placed to mark a separation between the words. For example, given two words "Hello"' and "World". If we use ', ' as the second argument, the substitution would yield "Hello, World".
If we use ' ' as the second argument, the substitution would yield "Hello World".
Any character can be placed between the quotation to mark a separation between the strings of an array.