Scanning
What's New
Current and New Value Session Variable
In version 24 it is now possible to see the current and new value of a session variable in the call stack. You can recognize it by the → character.
Unlimited Length Session Variable
It is now possible to store text of unlimited length in the session variables. This can be used, for example, to create filter strings (e.g. Orderpick assignment).
If you want to enter text longer than 250 characters use the BASE64TEXT property.
The Basics
In order to understand scanning one should first be able to grasp the concepts of the following topics:
- View
- Session Variables
- Constants
- Tables
- Field No.`s
- Custom List
- Related field
- Actions
- Codeunits
- Functions
- Criteria Function sets
- Key Codes
- CSS Attributes
- CSS Classes
View
The entire experience of our scanning application is comprised out of a set of views; A view is simply defined as the current "screen" one is working on at that particular moment in time.
Session Variables
Session variable are populated during the scanning process. Variables are used to hold values in order to display data or execute certain functions. By default a session variable has no set value, it either has to be filled with data from a table or by a function.
Constants
A constant is a single value which is used to filter through a set of data. These might be comprised out of any sort of data, including wildcards and sub table numbers, as long as it is recognized within the filters of the actual client.
Tables
A table is comparable to a common spreadsheet in which all company data is stored across rows and columns and is the actual foundation upon what the entire system is build. A table can be selected as the foundation of the current view, in doing so one can collect the records of a single row by defining certain filters through either (session) variables or constants providing it a Y-Axis on the table.
Field No.'s
A Field No. refers to the actual number of a column within a table providing the X-axis within a search across the table.
Custom List
A custom list refers to a table which is somehow connected to the table one is working with within the current view.
Related Field
A related field is referring to the field no. of the custom list once again providing the X-axis on the related table .
Actions
An action is a user-generated input by either pressing a button on a keyboard or touchscreen.
Codeunit
A codeunit is a library which contains a set of functions within 3PL Business central.
Functions
Functions are small pieces of code in which one can collect data from different tables, fill and/or manipulate variables, or perform calculations.
Criteria Function Sets
Similar to a function, with the key deference being that a criteria function sets is used to determine if another function has to be executed or not.
Key Codes
Key codes are integers by which the system can recognize which physical key has to be pressed in order to execute an action, e.g. 112 refers to the F1 key 113 to the F3 key etcetera.
CSS Attributes
A CSS Attribute defines the properties of an object, this might be a simple horizontal line across the screen or an entire datatable. By setting the attribute one provides the system what layout has to be used on an object. If one uses the HTML5 platform an attribute is mandatory!
CSS Classes
A CSS class defines how an object is formatted, this might be a smaller fontsize or the font's color might be switched.
How a view works within a process flow
In the picture below the actual flow in which code and functions are executed is depicted:
- First a filter is set on the table (if selected) with the criteria in the "Table Where" field (1);
- Next the functions within the header of the page are executed followed by the codeunit depicted in "Execute Codeunit" (2);
- Then all functions that are placed on a line are executed, followed the collection of the fieldvalue of a field on that line (if selected) (3);
Here the execution of the flow pauses, waiting on either a user-generated input (action) or an automatic postback (defined in the header). Once an action has been triggered by the user, the process flow resumes.
- By defining the action, the functions attached to that action will be triggered (4);
- However in the occurrence that an action is defined by the selection of a row within a datatable the next view is defined in the header of the view, where when a physical button is pressed the view defined in the field "No." will be executed next.
Once all above steps are completed the next view is generated and the entire process is restarted.
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.
The header
When we look a bit closer at a single view, a lot more can be defined. During this chapter we are going to create a more detailed and in depth view at the header part of a view.
Overview
As always, there are some areas that are easy to define, others need a bit more explaining. Therefor we start with a general outline of all fields in the header, followed by a bit more explanation where needed.
- No.:The primary key for the scan view, therefor it has to be unique. Best practice; Use the field in order to identify in which procesflow one is acting/ working, e.g. 10-*for receipt 20-* for shipment etcetera, or "Building Abbreviation"-"Proces"-Flowno. Example: BOL-SHIP-10, Boltrics-Shipment-10.
- Description:A general statement describing the views function.
- Height:The set amount of characters a view is allowed to display vertically. For example: a set height of 50 allows for 50 rows to be displayed vertically.
- This value is retrieved from the scan setup page by default.
- Width:The set amount of characters a view is allowed to display horizontally. For example: a set width of 250 allows for a string of 250 characters to be displayed horizontally.
- This value is retrieved from the scan setup page by default.
- Auto postback: Refreshes the view within a set timeframe. Please note this resets any information entered.
- Execute Codeunit: Executes a codeunit to be used in conjunction with the view. A good example of this is the data repeater, this displays multiple rows of a table which is set in the field table no.
- No. of attached functions: Here a set of functions can be run prior to building the lines of the view.
- Reset Session Variables: Use with caution! Resets all variables when this screen is activated.
- Table No.: The table on which the current view is based, this is used to retrieve fields out of the database to be used in the line types "field" and "data repeater".
- Table Where: Used to set filters on the selected Table No., these filters can be based on constants or variables alike.
- Table Sorting Fields: This is used to define on which way a table or data repeater creates the table to be displayed by setting an order on certain columns.
- Table Sorting Fields (2)End of Life
- Table Sorting: Used to set the direction of the columns set in the table sorting fields, this can be descending and ascending.
- User Order Control Role Filter: Allows you to overrule the current views table filter based on the scan employees Role or Order Control Roll
- Postback Okay View: Defines which view is to be loaded when a data repeater line is selected and all related functions, which need to be executed prior to the next view to be loaded, are successfully executed.
- Return to Previous View On Okay: Returns to the previous view when a data repeater line is selected and all related functions, which need to be executed prior to the next view to be loaded, are successfully executed.
- Beep on Okay Code:End of Life
- Exception View: Defines which view is to be loaded when a data repeater line is selected and a related function, which need to be executed prior to the next view to be loaded, returns an error.
- Beep on Exception Code: Sounds an audible scanner alert when a function returns an error.
- Beep on Not Okay Code: End of Life
Header in-depth
1. No of attached functions:
As stated in the overview, one can run functions prior to the view's lines are loaded in the view, a good example of this is a reset variable(-s) function:
Lets say that you have a flow in which one needs to return to a view multiple times to perform a certain task, chances are that you need to do this on multiple variables, not just one. By using one of these functions you can reset certain variables while retaining others.
Tips
- Use functions in conjunction with criteria function sets.
- The header is the only place to automatically redirect a view directly to another view without user interaction, using this in conjunction with a criteria function set allows you to build certain loops e.g Do... Until = x. (This is solely possible to be used with function 46 in codeunit 11155090).
- Need a function that you already created in another view? Use the function Copy Scan Function from the ribbon.
- Need a function that you already created in the same function list view? Use the function Copy Scan Function Line from the ribbon.
- Need a function to be placed elsewhere in the same function list view? Use the Up an Down arrows from the ribbon.
- Working on a view which has been build a while ago and need new functionality? Before adding a new function, refresh the parameters of the currently available functions by clicking the update parameter button from the ribbon; You might be able to gain functionality without loosing any performance as a new parameter might have become available.
2. Table Where
As stated you can set a filter on a selected table, defined on the field Table No., which can be achieved as follows:
- In the column Field No.:Enter the column number of the table you are referring to. For example no. 81 refers to the status code column in table 11154660 (Doc. Header).
- In the column Type:Set the type of value you desire to use, this defines which columns to be filled next.
- For the Column No.:The value of the type variable must be used, thereby creating a dynamic filter. For example by logging in as the user "Boltrics" we fill the variable USERFILTER with the value "Boltrics", by setting a filter on the Column orderpicker in table 11154660 (Doc. Header) we retrieve all records from table 11154660 where the Column Orderpicker (98) is equal to the value Boltrics. However when you log in with the username 3PL you retrieve entirely different records from the table due to the fact that the variable USERFILTER has now changed to 3PL instead of Boltrics.
- Prefix:Add a set value to a variable. Let's say that you have logged in with the value Boltrics, we filled the variable USERFILTER with the value Boltrics once more. However now we need to see all documents with the Column ' ' (empty) as well, in this case we can add " ' '| " as a prefix to that variable. This would result in the variable USERFILTER to be resolved as "' '|Boltrics" by the system.
- Postfix:Taking the example above this would result in the value of the variable USERFILTER to be "Boltrics|' '".
- Operator:Defines if the variable has to match (=), be unequal to (<>), larger (>) or smaller (<) than the value set in the Constant Value Column.
- Constant Value:A set value which a valuable is being evaluated against.
3. Table Sorting Fields & Table Sorting
Allows you to set a sort on certain columns:
In the example above you can see that the current sorting method is set on the columns "Entry No.", "Document No." and "To Zone Code". This setting in itself serves no purpose, it only starts to make sense once we have set the field "Table sorting" as well. Once set you will notice that the currently loaded table will retrieve a different sort on certain columns in case of a data repeater or will retrieve different values for lines of the type "field", as the data is retrieved in a different manner.
With the above example one should expect that the first table sort is done on by setting the entry no in a de- or ascending manner, after that with entryno being equal a sort is set on the Column Document No. and lastly the same applies to the field To Zone Code.
Lines
As we have just discussed the header, it only makes sense that we move on to the lines at this point.
Once more we will start with a general outline of its properties before we move to a more in-depth point of view.
- Key Code: Corresponds to the key code in the action part of the screen or a physical button on the keyboard of the device at hand. When pressed, those actions will be triggered in as a result.
- Control Type: End of Life
- Type: Defines what kind of data is presented on that particular line.
- Execute Codeunit: End of Life
- Page Size: Defines the number of rows presented within a data repeater
- Text: Defines the text to be presented within the view, please note that information presented through a variable should be set with underscores '________'.
- Caption: TBD
- Input: Checking this box allows an inputbox to be presented next on this line.
- Validate Line: Triggers the actions defined under the enter key (key code 13), can be triggered multiple times and serves as a postback.
- Hide: Hides the line if this option is checked.
- Length: Defines the maximum amount of characters to be shown on that line.
- No.: Sets the variable name to be bonded to that line and Declares the variable responsible for holding the provided information for that line.
- Table No.: Defines which table is selected on the header of that view.
- Field No.: Defines the Column no. which is to be retrieved.
- Relation Table No.: Defines a table which is connected to the table in the field Table No. through the value set in the field Field No.
- Relation Field No.: Defines which Column to retrieve from the table set in the field Relation Table No.
- Clear Variable First Enter: Clears a variable's value as it the first enter, keycode 13, is triggered.
- Clear Variable After Postback: Clear a variable's value when a postback is performed on a view trough a defined action.
- Allowed Characters: Allow Alphanumeric values or numeric values to be defined in a variable.
- Custom List: Allows you to set a dropdown with custom values to appear on screen.
- Value Format: Sets the size of the value set in the CSS attribute field, has to be set in a percentage. E.g. 50%.
- No. Of Attached Functions: Perform a function or a set of functions before a line is build.
- Icon Code: Sets an icon to be presented in the object created by the value set in the CSS Attribute field.
- Icon Format: Sets the height of the action button generated through the CSS Class, value range: 1-5.
- CSS Attribute: A CSS Attribute defines the properties of an object, this might be a simple horizontal line across the screen or an entire datatable. By setting the attribute one provides the system what layout has to be used on an object. If one uses the HTML5 platform an attribute is mandatory!
- CSS Class: A CSS class defines how an object is formatted, this might be a smaller fontsize or the font's color might be switched.
- Format code: End of Life.
- Output: End of Life.
- Regex Code: End of Life.
- Session Type: Defines if a line is set to be used in combination with a TelNet (Scanner) or HTML (APP) client.
Key Code
A key code is set to define which button is connected to which set of defined actions.
As you might observe in the illustration above the value of key 27 (ESC) leads to a different set of triggered actions when compared to key 112 (F1).
Please note that it is advised to set key code 13 (enter key) to en empty line at the bottom of the view, furthermore duplicate key codes are not allowed.
Type
There are 4 types of data:
- Datarepeater
- Has the potential to create an entire table within the current view.
- Caption
- Holds a static value, like text, or a CSS Attribute like "HZLINE", which creates a horizontal line.
- Session Variable
- A session variable has the property that it has no default value, it's an empty shell which one can assign a value to through either a function or field.
- Field
- Retrieves a value from a certain Column of a table (Table Field), based on the filters set (Table Where field) and fields associated with sorting.
Data Repeater
By setting the field "Type" to represent the value "data repeater", please note that the right codeunit and a table have to be defined, one can create a table view within the current view. It might look something like this:
Page Size
As this is a directly related field to the data repeater, we have decided to directly address it instead of naming it separately. Setting this value on the line sets the maximum amount of (vertical) lines to be presented on screen for the data repeater.
Setting up
In the illustration above you see three columns forms the receipt table, when we look at the view itself we can define its values as follows:
Select the line on which the Data Repeater is present and either click on "Data Repeater" in the ribbon, or press CTRL+D.
The following view will open:
Some field should be familiar to you now, however some need some further explanation.
Type
Can be set to 5 different values:
- Numbering 1..: Sets the key codes representing to each line, in an up down approach, to represent 1 until 9.
- Numbering F1...: Sets the key codes representing to each line, in an up down approach, to represent F1 until F9.
- Numbering A..: Sets the key codes representing to each line, in an up down approach, to represent A until I.
- Text: Sets a default text op the line which value can be set in the field "Text Part"
- Session variable: session variable has the property that it has no default value, its an empty shell which one can assign a value to through either a function or field.
Field No
Sets the Column on the table from which all data needs to be collected for that Column of the data repeater.
No
Sets the variable name to be bonded to that line and Declares the variable responsible for holding the provided information for that line.
Declaring a variable data type
When creating a new variable, you can set the type of data which it will contain:
Click on "+ New) in the ribbon and provide a name to the variable in the field "Code", next click on the dropdown in the field "Data Type".
![Set_Data_Type_Variable](../media/Scanning/Set_Data_Type_Variable.png}
There are 5 types of data:
Return Session Variable Code
Sets the value of the variable set in this field to the value retrieved form the Column "Field No.".
Group By
If this box is checked, all records with the same value on that columns will be grouped. Therefor generating unique values for that Column.
Variable No
If a function is triggered before this line is executed then the value of this variable will be set to that value.
Please note that there is a clear difference in which variable fields needs to be filled, based on the source of its value;
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
The following CSS classes are available at this time:
Scan setup
The scan setup, is the part of the system where most generic information is stored. For that reason we'll quickly go over each setting:
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
As with all things in life there is a right way and a wrong way in doing things, and of course we are here to inform you about both but to teach you the first.
The wrong way
For the sake of argument lets just say that we wish to export the following set of views:
Now through the ribbon click on Actions > Functions > Export:
The result of this is that either a singe ".xml" file is downloaded or a ".zip" file comprised out of a set of ".xml" files, each representing a single view.
The right way
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.
What's wrong?
What's the difference between the two, what is wrong about the first offered method and better concerning the second?
Well that's due to the development of newer and better services, due to the fact that there are a lot more checks and balances which are handled through the second method, there is a smaller chance for things to go wrong when exporting and importing the different formats. Besides that the development of the first method has reached its end of life stage and could therefor run into compatibility issues with newer versions of our software. The only reason that it is still around is due to legacy concerns.
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.