Saturday, 4 July 2015

Setup and Configuration of Mobile Device

The devices we see deployed with the advanced warehousing solution are often rugged industrial equipment, designed to work within the hostile environment of the warehouse. These often support integrated barcode scanning and can survive the occasional accidental drop. With an often significant investment in these devices we wanted to ensure the Microsoft Dynamics warehouse solution works across the widest possible distribution of devices. We also wanted to ensure the workflows and capabilities exposed by the mobile device interface were flexible enough to match the business processes of your warehouse. Thus the entire interface that is built and rendered on the mobile device is extremely flexible – with the entire menu system and workflow exposed and extensible both from within core AX and through partner code.
This blog post is the first in a two part series that will cover customizing the mobile device portal. This post will cover the options exposed in Microsoft Dynamics AX 2012 R3 to build custom mobile workflows for your workforce and how to build different mobile experiences depending on user and device criteria. The next blog post will cover the deeper code underpinnings of the mobile device portal and how it can be extended to expose additional workflow options.

Menu


At the heart of the mobile device portal interface lies the concept of Menus and MenuItems. These are configured in AX by navigating to Warehouse Management -> Setup -> Mobile device. The high level concept of a Menu is simply a flexible container that can contain both MenuItems as well as other Menus (i.e. it is a nestable structure). Thus it is possible to construct an interface for your users that provides exactly the capabilities required for the role they are assigned. For example, it is possible to build a Menu that only exposes the outbound picking operations for a certain segment of warehouse workers, and have a separate menu structure used by the forklift operators for replenishment operations.
The menu item interface can be seen below. Menus can be defined in the top section, and MenuItems can be added to the selected Menu in the lower section from the list of all available MenuItems in the bottom right list.


Menu Item


Defining a MenuItem is done in the Mobile device menu item screen – and there are a lot of options available for configuring the workflow exposed to the end user. A complete description of all fields available on this screen can be found at the following TechNet article: https://technet.microsoft.com/en-us/library/dn553216.aspx. This blog post will try to simply touch on the high-level functionality of MenuItems – please see the TechNet article for more details regarding the options available.


Menu Item - Mode


When creating a new MenuItem, you first must decide the Mode that this activity will be operating under. This can be "Indirect" or "Work." This defines if the MenuItem will interact and operate on Work in the warehouse (i.e. Work mode), or if it will support some sort of ancillary process in the warehouse not directly related to a Work line (i.e. Indirect mode). Selecting the Indirect mode will cause the UI to display the list of "Activity codes." This allows the user to select the non-work related workflow that will execute when this MenuItem is selected on the mobile device.


Again – the complete list of activities can be found in the TechNet article, but the following are a sampling of the possible workflows:

Change warehouseChange the warehouse that a worker is logged on to.
Location enquiryView information about all items and quantities for a location.
License plate enquiryView the quantity of items on a license plate, and the location of the license plate.
Start production orderStart a production order.

Changing the Mode to "Work" will change the UI significantly. It will now be possible to select the checkbox "Use existing work." This will configure the MenuItem workflow to either consume an existing Workline (checked) or to generate a new set of Work (unchecked). By leaving the checkbox unchecked (i.e. not to use existing work) the user will be able to define the exact work creation process required to generate new work through this MenuItem. This is often used when receiving items and/or starting putaway work.


There are various options available when defining the work creation process that will get initiated by this MenuItem. 
These will differ depending on the exact work creation process workflow selected – all of the various options are described in detail in the TechNet article referenced above. All of them are available to allow you to customize the exact business process that is enabled by the mobile device user.

Changing the selection to "Use existing work" will indicate that this MenuItem will process existing Work lines – and thus must be configured define exactly how that work should be processed. Again there are a multitude of options available to configure exactly how the workflow should proceed. In addition, two very important settings must be configured: how this work is directed, and the work classes available to process.  The Work classes section defines the valid work that this MenuItem can process; this can be used to restrict access to certain user roles or to separate processing logic for different types of operations.   



The "Directed by" setting defines exactly how the work will be selected for the mobile device user. This is a very important setting – as this is how the system will know what work to assign to a particular user. All of the options are defined in the TechNet article – these are copied here for convenience:


OptionDescription
NoneThis default value does not process work.
System directedMicrosoft Dynamics AX controls the type of work that is assigned to a worker and the sequence in which to perform it.
When you select this option, you can click System-directed work to open the System-directed sorting order form, where you can set up sorting criteria for the work. The sorting criteria control the order in which the worker will perform the work. You can add as many criteria as needed.
User directedThe worker selects the work to perform and the sequence in which to perform it.
User groupingThe worker manually groups work. For example, this is useful when a worker can pick multiple items at the same time in a location. After the worker has finished picking all of the required items, he or she can put the items away.
System groupingMicrosoft Dynamics AX groups work for the worker based on a specified field. For example, picking work is grouped when a worker scans a shipment ID, load ID, or any value that can link each work unit.
If you select this option, the following fields are required:
  • System grouping field – Select the field that the worker will scan to group the work.
  • System grouping label - Enter text to inform the worker about what to scan to group the work.
Validated user directedThe worker selects the work to perform when work is associated with a larger entity, such as a load or shipment. The worker determines the order in which to pick the items.
If you select this option, you must select the following:
  • Validated User Directed Field – Select the field that the worker will scan to group the work.
  • Validated User Directed Label - Enter the text that will inform the worker about what to scan when picking work is grouped by the system.
For example, this is useful when multiple pallets are staged for a load. If you select the LoadId field, the worker can pick any pallet that is associated with the load. An error message is displayed if a worker scans an item that is not associated with the load.
Cluster pickingThe worker groups work into clusters. Clusters enable workers to pick items from a single location for multiple work orders at the same time. For more information, see Set up cluster picking.
Cycle count groupingThe worker selects a zone, work pool, or location, and Microsoft Dynamics AX will assign work based on the selection. For more information, see Set up cycle counting thresholds and plans to perform cycle counting.
If you select this option, you can also click Cycle counting to specify additional information to display, and specify the number of times that the worker must repeat the count if a difference is found.


Work Users


In order to access the WMDP one needs to create at least one warehouse work user, which has a user name, password, default warehouse, and available mobile menu. In order to create a warehouse work user, a worker will first need to be defined within the HRM module. The HRM worker is typically associated with an AX user mapped to an active directory identity (through user associations defined in the administration module).

After creating the HRM worker, one can assign a number of warehouse work users to it through the "Worker" form accessed under Warehouse management -> Setup -> Work users -> Worker. You can think of the warehouse work users as a number of logins for the selected HRM worker – each one which can provide a default warehouse and targeted workflow exposed by the menu. Obviously it is also possible to simple define all your warehouse work users under a single HRM worker, but this is not the recommended pattern.

warehouse work user is defined very simply with a user ID, user name, default warehouse, and a menu. This menu is loaded when the user logins into the portal, and is how different experiences can be tailored to different logins. For example, in the screenshot below we have created separate menus for the UPS drivers, the Forklift operators, and the primary warehouse workers. Each have a different set of MenuItems available, specifically only the ones required for them to perform their jobs effectively.


Mobile Site CustomizationCSS Customization


The site that is created by the configured Menu and MenuItems can be further customized through a variety of options exposed through Microsoft Dynamics AX. These options are available through the work user mobile device display settings form – seen below. This screen allows a CSS file, display settings view, and keyboard shortcut settings to be defined for a set of criteria. This allows different displays to be rendered for different types of devices or browsers.



The most obvious way to customize the mobile site is through CSS customization. The default css file shipped with the mobile device portal (defaultrf.css) can be found at <AX Installation directory> \6.3\Warehouse Mobile Devices Portal\<WMDP Instance folder>\Content\CSS\RFCSS. This file defines the basic look and feel of the UI and includes things like the background color, text font and size, and the width and behavior of the rendered buttons. The default login screen is rendered in the following manner:


The overall look of the interface is defined by the default css file, which includes the following settings:
 

Note the background color and button colors have been customized, as well as the layout (100%) of the button and the hover behavior of the buttons. By removing all of the default css and replacing it with the following simple css, we can dramatically change the look of the UI:


This is achieved with the following css file:
body{    background#777777;    text-aligncenter;}
.whsLabel{    font-size15pt;    color#FFFFFF!important;}
.whsTextLabel{    color#FFFFFF;}
.whsPasswordLabel{    color#FFFFFF;}

Note the requirement for the important keyword in the .whsLabel class definition. This is because all whsLabels are generated with an embedded color component defined in the "mobile device text colors" form (or defaulting to black). This form can be found at Warehouse management -> Setup -> Mobile device -> Mobile device text colors. Unfortunately this form does not allow criteria based filtering or customizing on the generated colors, so utilizing the css styling is the recommended way for updating the text colors.
The ability to change the look and feel of the generated HTML is more important than simply wanting a different background color or text color may initially appear. Different devices used in the warehouse may impose strict limits on what can or should be displayed for optimal visibility and usability. The need to specify a specific width or a specific format for buttons may be a requirement for the specific device utilized in the warehouse, in which case the css styling is a must for enabling the workflow.

Keyboard shortcuts


Another facility exposed in the "Work user mobile device display settings" form are keyboard shortcut definitions. These allow you to customize what hardware keys trigger different MenuItems. It is possible to map specific buttons to MenuItems such that when the MenuItem is visible users can press the hardware button to trigger the functionality on the device. This is often useful for warehouses when devices are used that have obvious keyboard mappings to specific functionality in the portal.


The format for setting up keyboard shortcuts is very specific, and the entered string must match the required format exactly so as to be registered into the client-side JavaScript correctly. The required format string for each shortcut is (note they can be appended together with a semi-colon):
<control name>(<key name>)=<javascript key code>;
The control name is the value of the "id" attribute in the generated HTML. This can be easily found by examining the generated HTML in a browser or developer tool. The key name is a string value displayed to the user in the button text – this is designed to help the user understand the available hardware button options. The JavaScript keycode is the value exposed from the JavaScript onKeyDown/onKeyUp methods.
An example keyboard shortcut string is:
Login(L)=76; Full(F2)=113
This would cause the "L" hardware button to execute the Login button automatically, and the "F2" hardware button execute the Full button. The generated HTML would inject the key name values into the button text, so the above string would result in the following pages:
 

Display Settings View


The last option available on this form is the "Mobile device display settings view." This describes the name of the ASP.NET view file used to render the mobile site in the server-side ASP.NET application. This file controls how the overall structure of the HTML is laid out and customizing this functionality is only recommended if you have serious structural issues with the HTML and JavaScript that need to be changed for your specific devices. Note that, like the CSS files, there is a specific directory where these files need to be located so the IIS application can load them - <AX Installation directory>\6.3\Warehouse Mobile Devices Portal\<WMDP instance folder>\Views\Execute.

Criteria


All of the above settings (CSS file, Keyboard shortcuts, and Mobile device display settings view) can be customized in order to render a different mobile experience to different devices and/or users. The system uses the criteria column to determine exactly which settings to load. The criteria column allows the following attributes of the incoming request to be used to qualify the different settings rows:
  • Requestor IP address
  • Requestor Host name
  • Request User Agent string
Each of these values can be examined using a regular expression – any successful match will cause the specific display settings row to be loaded for that particular user session. The criteria string must match a specific format, and must include all three of the criteria options, even if you are only examining one of these values (wildcards must be specified for the others). The format of the criteria string must be:
Request.UserHostAddress=<user host address>|HostName=<user host name>|Request.UserAgent=<user agent>
Here is an example of the criteria used to differentiate between two browsers (Opera and Internet Explorer) based on the UserAgent field. Note the wildcard settings for the other two criteria options.


The above settings will enable us to display a different css file to different browsers – perhaps we are operating with two different classes of machines in the warehouse each with a different browser and different capabilities. We want to be able to target a different UI experience to each to ensure our users can be productive with their specific devices.

Mobile Device Portal Tools


There are two tools included with the mobile device portal that aim to make the processes describe above easier to configure. These tools can be found in the initial screen for the portal (i.e. go to the root URL of the portal).


The "View codes for keyboard shortcuts" will take you to a simple page that will display the JavaScript key-code for the hardware key pressed. This would allow you to test the specific hardware buttons for your devices in order to configure the keyboard shortcuts described above.
The "View server configuration for display settings" will show you the current display settings view selected, as well as the IP address, Host name of the requester, and the full User agent string. As described above, these three fields are what is available to be queried against in the criteria string – so this page can be used to see exactly what the different values might be for the different devices in use in your warehouse.