Scanning Application Documentation
What's New
Current and New Value Session Variable Display
In version 24, the call stack now displays both current and new values of session variables, indicated by the → character.
Unlimited Length Session Variables
The system now supports storing text of unlimited length in session variables. This enhancement is particularly useful for creating filter strings (e.g., Orderpick assignment).
Note: For text entries longer than 250 characters, use the BASE64TEXT property.
Core Concepts
To effectively understand the scanning application, it's essential to grasp the following fundamental concepts:
View
A view represents the current "screen" or interface that users interact with at any given moment in the scanning application.
Session Variables
Session variables store data during the scanning process. These variables:
- Have no default value
- Must be populated with data from tables or functions
- Are used to display data or execute specific functions
Constants
Constants are single values used to filter data sets. They can include:
- Any recognized data type
- Wildcards
- Sub-table numbers
- Values recognized within client filters
Tables
Tables serve as the foundation of the system, similar to spreadsheets:
- Store company data across rows and columns
- Can be selected as the foundation for the current view
- Allow collection of records through filters using:
- Session variables
- Constants
- Y-Axis table definitions
Field Numbers
Field numbers refer to column numbers within tables, providing the X-axis for table searches.
Custom Lists
Custom lists are tables connected to the current view's working table, enabling related data management.
Related Fields
Related fields reference the field number of custom lists, providing the X-axis on related tables.
Actions
Actions are user-generated inputs triggered by:
- Keyboard button presses
- Touchscreen interactions
Codeunits
Codeunits are libraries containing function sets within 3PL Business Central.
Functions
Functions are code segments that can:
- Collect data from different tables
- Fill and manipulate variables
- Perform calculations
Criteria Function Sets
Criteria function sets determine whether another function should be executed, similar to conditional logic.
Key Codes
Key codes are integers that identify physical key presses:
- 112 = F1 key
- 113 = F3 key
- etc.
CSS Attributes
CSS attributes define object properties:
- Control layout and appearance
- Mandatory for HTML5 platform
- Range from simple horizontal lines to complex datatables
CSS Classes
CSS classes define object formatting:
- Control font size
- Set font colors
- Apply other styling properties
View Process Flow
The following diagram illustrates the code and function execution flow:
Execution Sequence
Table Filtering
- System applies filters to the selected table using criteria in the "Table Where" field
Header Execution
- Executes functions within the page header
- Runs the codeunit specified in "Execute Codeunit"
Line Processing
- Executes functions placed on each line
- Collects field values (if specified)
User Interaction
- System pauses for either:
- User-generated input (action)
- Automatic postback (defined in header)
- System pauses for either:
Action Processing
- Triggers functions attached to the action
- For datatable row selection:
- Next view is defined in the header
- For physical button presses:
- Next view is defined in the "No." field
View Generation
- System generates the next view
- Process restarts
Into detail
As we've now covered the basics, lets take a more in-depth look into a single view in order to really drill down on all its functionality's, I'll start by explaining the header, followed by the lines, actions and app properties. Some areas will have some overlap, I'll briefly state its existence when an occurrence is found but will only explain it in detail upon its first appearance.
Detailed View Components
Now that we've covered the basics, let's examine the components of a single view in detail. We'll explore the header, lines, actions, and app properties. Some areas may overlap, and we'll note these occurrences but explain them in detail upon their first appearance.
The Header
The header section of a view contains several important configuration options. Let's examine each component in detail.
Overview
The header configuration includes both simple and complex settings. Here's a general outline of all header fields:
Header Components
1. Number of Attached Functions
Functions can be executed before the view's lines are loaded. This is particularly useful for resetting variables:
Example: When returning to a view multiple times to perform tasks, you may need to reset multiple variables while retaining others.
Best Practices
- Use functions in conjunction with criteria function sets
- The header is the only place to automatically redirect a view without user interaction
- Combine with criteria function sets to build loops (e.g., Do... Until = x)
- Use function 46 in codeunit 11155090 for automatic redirection
- Utilize the ribbon functions for efficient function management:
- Copy Scan Function: Copy functions from other views
- Copy Scan Function Line: Copy functions within the same function list view
- Up/Down arrows: Reposition functions within the same view
- Update parameter button: Refresh function parameters for existing functions
2. Table Where
The Table Where section allows you to set filters on the selected table (defined in the Table No. field):
Configuration Options
- Field No.: Enter the column number of the referenced table
- Example: No. 81 refers to the status code column in table 11154660 (Doc. Header)
- Type: Set the value type to determine which columns to fill next
- Column No.: Use the type variable value to create dynamic filters
- Example: When logged in as "Boltrics", USERFILTER is set to "Boltrics"
- Setting a filter on Column orderpicker (98) in table 11154660 retrieves records where Orderpicker equals "Boltrics"
- Prefix: Add a set value to a variable
- Example: Adding "' '|" as prefix to USERFILTER results in "' '|Boltrics"
- Postfix: Add a set value after the variable
- Example: Adding "|' '" as postfix to USERFILTER results in "Boltrics|' '"
- Operator: Define comparison logic
- = (equals)
- <> (not equal)
-
(greater than)
- < (less than)
- Constant Value: Set value to evaluate against
3. Table Sorting Fields & Table Sorting
Configure sorting for specific columns:
Sorting Configuration
- Set sorting method on columns (e.g., "Entry No.", "Document No.", "To Zone Code")
- Configure "Table sorting" field to activate sorting
- Affects:
- Data repeater display order
- Field value retrieval order
- Multiple sort levels:
- Primary sort on Entry No.
- Secondary sort on Document No.
- Tertiary sort on To Zone Code
Lines
Let's examine the line properties in detail, starting with a general overview followed by specific components.
Overview
The line configuration includes various properties that control display and behavior. See the fieldcaptions for detailed information.
Key Code Configuration
Key codes define button-action relationships:
Note:
- Set key code 13 (enter key) to an empty line at the bottom of the view
- Duplicate key codes are not allowed
Data Types
The system supports four main data types:
Data Repeater
- Creates tables within the current view
- Requires codeunit and table definition
Caption
- Displays static values or text
- Supports CSS Attributes (e.g., "HZLINE" for horizontal lines)
Session Variable
- Empty container for value assignment
- Values set through functions or fields
Field
- Retrieves values from table columns
- Based on filters and sorting settings
Data Repeater Configuration
Data repeaters create table views within the current view:
Setup Process
- Select the Data Repeater line
- Click "Data Repeater" in the ribbon or press CTRL+D
- Configure the repeater view:
Type Options
- Numbering 1..
- Sets key codes 1-9 for lines
- Numbering F1...
- Sets key codes F1-F9 for lines
- Numbering A..
- Sets key codes A-I for lines
- Text
- Sets default text in "Text Part" field
- Session variable
- Uses variable for value assignment
Text
Sets the text of the line at hand, you can combine this with a variable's value when setting part of the string with an underscore ("__________") and separated with a space.
Multi Language Support
While this is not directly apparent by clicking the 3 dots on the field "Text" you can set a translation for each line based on the language codes available, these can be set individually in the scan setup.
Input
Declares that a line should be expanded with an input field, please note that this should be used in conjunction with an underscore on the field "Text".
Relation Table No. & Relation Field No
Please check the illustration below as an example:
As you might notice, the table set in the header is table 11154988, as we have declared the line to have a field as a data type, we can now take that value to lookup another value in a different table.
E.g. Column 45 equals to the WMS Customer Item record on table 11154988, as field 45 is directly tied to the WMS Customer Item table (11154644) we can use the retrieved record on our View's line to lookup a relevant value on that table, in this case the column 11 which is the item description. This value can also be set in a variable if desired, this can be done by filling the field "No." on the line.
Custom List
A custom list can be generated in order to create dropdowns, radio buttons and set up a resolution on the camera.
In order to do so create a new custom list as such:
In the following view proceed entering the code that describes your list best. In this scenario we will have the following conditions, we desire the list to reflect a satisfaction rating of this guide. Therefor we will name it "ApprovalList":
Now we can start entering its values by setting them through the ribbon:
A new view will open, we can now set the code, the description and the display order for our custom list:
And now if we run it in the scanner, we get the following result:
CSS Attribute
The following CSS attributes are available at this time:
CSS Class
Lookup the values for a detailed explanation. Below you can find a detailed description about certain Classes:
Scan setup
The scan setup, is the part of the system where most generic information is stored. See the tooltips for detailed information.
Scan employees
WIP
Debugging an error within a view
Unfortunately it may occur that an error is generated by your scanner, in order to determine what causes the error it is vital to understand if the error is generated by the client (e.g. 3PL Dynamics itself) or by some functionality within the current (or proceeding) view.
In order to do so you can use the following steps, however please note that you need to have a decent amount of knowledge of 3PL Dynamics itself as well as your own processes in order to succeed.
Before actually starting the debugging of a session please react the entire process in the client without the scanner's, or the emulator's, involvement, using the same steps as the user did when then error was generated. E.g. Use the same carrier(-s), locations and other variables as they did. Does the error occur as well, then you should look for the solution outside of the scan environment and within the client itself.
Does it still happen in the scanner and not in the client once replicated? Then please proceed with the following steps;
- Navigate to "Scan Sessions" within the client.
- Select the line which represents the user which received the error within the scanner.
- In the ribbon, in the top part of the screen, select "Report", followed by "View Call Stack".
- Once the callstack has been opened you can diagnose which function triggered the error which is defined by the "CodeUnit Name" and "No" as well as the current view under the header Active Function".
Navigate to "Scan View List" and find the screen in which the error was triggered. One key thing to note is that this function should be found between the last user generated input (Action) and the next pause. For example:
If a barcode was last scanned before the error was created one should look for the function responsible function between the functions under the "enter" key on the first view (1) as well as all al the other proceeding functions on the proceeding view until the code pauses again (2&3):
Therefor the functions depicted by 2 and 3, in the example above, should be found in view APP-20-140 and not in view APP-20-130.
Before proceeding, please switch to an environment which does not use live data, Any following step may harm your data and/ or process!
In order to test if this actually is the function that fails, we need to generate another error directly before that function is triggered. An easy way to do so is by adding function 11 from codeunit 11155090 (you do not need to define its parameters) above the suspected function in the process flow and retest your scenario, does the error change? If not then there should be another similar function in the same flow. If the error does change please move the newly created function down, below the suspected function, and retest. Does the error return? Then you have successfully found the misbehaving function.
However although you have found the function which created the error, it still doesn't mean that you have found the root cause of the error, as most functions are fed by (session) variables. These variables are used by the concerned function in order to generate an outcome (an error in this case) and are defined under it's parameters.
In order to check whether it is the actual function generating this error by or one of it's input (session) variables it is recommended to change the parameters of the function into constants instead of variables, these constant should resemble the actual data which you would expect to be used in this function;
Please note that the an input, bidirectional or an output variable can be distinct by checking the column "direction", in which the arrow (-->/<-->/<--) defines the type.
By changing these values into actual data which should be used by the function (and with which it should work) we can test the function itself.
If you execute the test and you don't receive a error, the function itself is fine. However the parameters and therefor (most likely) the variables which feed it are not.
Unfortunately the call stack doesn't always reflect all the variables actual state when generating the error, as these can be emptied or reverted due to a rollback in the code itself. However a quick way to check the value of each individual variable is to enter its name into function 11 which we created just before. Please note that it has to be placed above the malfunctioning function once again regarding to the flow.
Now simply rerun your scenario and check if the error which pops up reflects the data which you would expect there to be. If not than you have found the (session) variable responsible. All you need to do now is to trace back this variable, against the normal flow of the code, to each point where it either was manipulated by a function and retest it's value using function 11 until it either has the correct value or it's point of origin.
As you might understand, this might lead into another misbehaving function (or variable) where the previous (session) variable is the output variable. In that case the entire process starts again until you have found the root cause.
Importing & Exporting views
Introduction
Let's say that there was a new customer was just landed by your salesdepartment. However this customer has such specific needs that it doesn't fit your regular processflows and amending them would make them incredibly complicated, or vulnerable for future errors. How can you fix that without having to manually build each view from the ground up? Or what if you want to copy one processflow to another? Or create and test views in a save environment, which doesn't harm or endanger your live data, without loosing them at the end of the day?
Wel the answer to that is to export and import your scan views, a small tool which saves you a lot of potential work and allows you to backup views, amend their ID's (numbers) and (re-)create them in seconds.
Exporting views
Through the ribbon click on Home > Export Package:
An additional bonus of using this method is that you can rename the views to whatever you want, just enter the (part of) the string that you want to replace in "Find What" and enter your replacement string in the replace with:
E.g. in this case we could rename 10-0 with Receipt-STD- if we would like to have a more representative name instead of the current naming scheme. Currently the resulting output of this input would then be: Receipt-STD-12|Receipt-STD-15|Receipt-STD-20|Receipt-STD-30|Receipt-STD-31|Receipt-STD-32.
This result comprises of the download of one ".zip" file and always contain's a ".json" file for all scan-views.
Scan Session
The Scan Sessions (Search for 'Scan Sessions') provide an overview of all the active scan sessions. The field Exceptions provide information of the last error. If you go to Start -> Show callstack you get detailed information how and where in the code the error occurs. Please provide this information if you contact the Helpdesk.