This article describes how to enable the Warehouse Mobile Devices Portal for Microsoft Dynamics 365 for Finance and Operations. It also explains how to service and upgrade your environment.
Warehouse Mobile Devices Portal (WMDP) is a web application hosted in IIS. It uses ASP.NET MVC runtime. For the current version of Microsoft Dynamics 365 for Finance and Operations, WMDP is provided as a standalone component, meant for self-deployment on-premises. In order to enable the WMDP on your environment, you need to download the installer, deploy the WMDP application, and configure it to connect with a Finance and Operations server. This article explains how to enable WMDP on your environment. It also explains the process of introducing a hotfix into your environment.
Download the installer for Warehouse Mobile Devices Portal
The WMDP is installed through a standalone Microsoft installation package. The installer file, WarehouseMobileDevicesPortal.msi, can be downloaded directly from Finance and Operations. In order to obtain the installer, you need to have Warehouse Management module enabled. Follow these steps to download the WMDP installer:
- Log-in to Dynamics 365 for Finance and Operations as a user with an Information technology manager role.
- Go to Warehouse management > Setup > Mobile device > Download Warehouse Mobile Devices Portal.
- Familiarize yourself with the Security Best Practices checklist. Select the Complete check box for each item that you’ve reviewed.
- In the Legal Information section, read the software license terms.
- Click OK. The WarehouseMobileDevicesPortal.msi then downloads, as show in the following screenshot.
Install the Warehouse Mobile Devices Portal
The Warehouse Mobile Devices Portal installer supports the installation of up to 100 instances on the same Windows server machine. Follow these steps to install an instance of WMDP instance:
To install a default instance, run the WarehouseMobileDevicesPortal.msi. -or- To install a non-default instance, execute following command:
msiexec /I WarehouseMobileDevicesPortal.msi TRANSFORMS=:<InstanceID> MSINEWINSTANCE=1
- Choose an installation location, or leave the default installation location (recommended).
- Click Next.
- On the IIS configuration page, in the Website port field, enter the TCP port on which the website is meant to be available. For example, type 8999.
- Click Next.
The setup wizard is now ready to complete installation.
- When the installation is complete, click Finish.
Retrieve and install a certificate on your Warehouse Mobile Device Portal host machine
The Warehouse Mobile Devices Portal is deployed to run using https. The installer creates https binding on a chosen port, but does not associate any SSL/TLS certificate with it. In order to complete the initial configuration process, you need to associate the certificate with your binding.
- Deploy a commercial certificate distributed by a well-known certificate authority. By using trusted providers, the certificate will by default be trusted by the client browsers in your warehouse. This is a recommended choice for a commercial deployment.
- Alternatively, you may consider creating a self-signed certificate. This is a handy practice for development and staging environments. Follow this tutorial to create a Self-Signed Server Certificate: https://technet.microsoft.com/en-us/library/cc753127(v=ws.10).aspx
To retrieve and install a certificate on your Warehouse Mobile Device Portal host machine:
- In IIS, open the bindings for your Warehouse Mobile Device Portal site, as shown in the following screenshot.
- Select your binding.
- Click Edit and associate any host names that you will use for the Warehouse Mobile Devices Portal. For more information, refer to https://technet.microsoft.com/en-us/library/cc771629.aspx.
- The following screenshot shows an example of a self-signed certificate named localhostWMDP_DEFAULT, associated with https binding on port 8999.
Configure the Warehouse Mobile Devices Portal web application
To enable the Warehouse Mobile Devices Portal application to interact with a particular Finance and Operations server, you need to complete the following configuration steps after installation:
Register a native application in Azure Active Directory for the Operations tenant. This application should have access to Microsoft Dynamics ERP.
- Read the following guide to learn about Finance and Operations custom service authentication: the Custom services section in the Dynamics 365 for Finance and Operations Services Technical Concepts Guide.
- Follow the steps for “Register a Native Application with AAD”.
- You have now obtained Client ID of the application.
Create a new user account in Azure Active Directory for the Operations tenant. The purpose of this user account is to access the WMDP specific custom service, which the Operations server exposes. After completing this step, you will have WMDP user credentials, which consist of a WMDP email address and a WMDP password. To learn about the basic steps for adding users to Azure AD and Finance and Operations, refer to this tutorial: [Sign up for a Finance and Operations subscription]((/dynamics365/unified-operations/dev-itpro/sign-up-preview-subscription).
Create an Operations user that corresponds to the WMDP user credentials.
Update the Warehouse Mobile Devices Portal web.config file.
- In Internet Information Services (IIS) Manager, find your website.
- On the Actions pane, select Explore in order to browse the WMDP website sources.
- Edit the Web.config file and find ServiceConnection element.
Assign a value to the URI attribute of the ServiceReference element:
<your root Operations URL>/api/services.
Assign values to following attributes of the Authentication element:
ServiceSecurityResource = <your lower-cased root Operations URL> ServiceClientID = <Client ID> (obtained in step 1 of this section) ServiceUserName = <WMDP email address> (obtained in step 2 of this section) ServiceUserPassword = <WMDP password> (obtained in step 2 of this section) ServiceAuthenticationURL = <authentication URL to your tenant>
ServiceSecurityResource = https://usncax1aos.cloud.onebox.dynamics.com ServiceClientID = "aaaaaaaa-1234-bbbb-5678-ccccccccccc" ServiceUserName = WMDPapp@contoso.net ServiceUserPassword = "wmdpP@ss" ServiceAuthenticationURL = "https://login.windows.net/contoso.net"
Even though the Web.config file has an exclusive strong ACL applied to it, for security reasons you should make sure that you remove any credentials from the Web.config file before going live. In this step, you will protect the credentials created in the previous step, by saving them in Windows Credentials Manager.
- Open the main page of the Warehouse Mobile Devices Portal.
- Click Load web application configuration.
- After successfully recording your credentials, the following message displays.
- In the Web.config file, set ServiceUserName and ServiceUserPassword to empty strings:
ServiceUserName = "" ServiceUserPassword = ""
- You can now log on to Warehouse Mobile Devices Portal pages. If your configuration succeeded, you will see the company selection page.
If you see the Select company screen, you will connect to Finance and Operations. Otherwise, visit the “Troubleshooting” section. To start using the WMDP menus, you need to complete the remaining setup steps, which are documented for Dynamics AX 2012 here: https://technet.microsoft.com/en-us/library/dn553159.aspx.
Servicing the Warehouse Mobile Devices Portal
Since Warehouse Mobile Devices Portal is released as a standalone component, you need to manually apply hotfixes when they are available. When a hotfix is available, a new instance of the WMDP is deployed side-by-side with the old one. After it has been properly configured and tested, the administrator can retire the old version and make the new, updated version the live version. This hot-swapping servicing model allows minimization of downtime caused by the configuration and testing of the updated environment. To apply a hotfix:
- After a new update to the Warehouse Mobile Devices Portal is available on your LCS portal, it can be downloaded to your local environment. Follow this tutorial to retrieve the hotfix: Download hotfixes from Lifecycle Services
- The hotfix package will be available as a zip file. If you unpack it, you should be able to find patched version of WarehouseMobileDevicesPortal.msi within SCMSelfService\Packages.
- Follow the “Install the Warehouse Mobile Devices Portal” section in this document to install another instance of WMDP on your server machine, under a different TCP port than the original instance. Let’s call this instance patched WMDP and the original instance old WMDP instance. As a good security practice, you should consider using a TCP port that is not exposed through your firewall to the production network, as it is still under configuration.
- Follow the “Configure the Warehouse Mobile Devices Portal web application” section for configuring the patched WMDP.
- Apply any customizations and execute any tests that ensure that your patched WMDP is ready to go live.
Update the site bindings on patched WMDP and retire the old WMDP instance.
- In IIS, stop the old WMDP instance. Note that this will terminate the work user sessions, but will not damage their work in progress, as the work session state is stored in Finance and Operations.
- In Internet Information Services (IIS) Manger, open the Bindings for your old WMDP instance, as shown in the following screenshot.
- Remove the default binding and close the Site Bindings window.
- Select the patched WMDP instance site in Internet Information Services (IIS) Manger, open Bindings and create a new https binding for exactly the same port as the binding removed from the old WMDP instance.
Your patched WMDP instance should now be live.
- You can now uninstall the old WMDP instance.
- On your computer, open the Uninstall or change a program window (Control Panel > Programs > Programs and Features), or open appwiz.cpl as administrator.
- Find the old WMDP instance in the list of installed programs. The following screenshot the shows DEFAULT instance in the list.
- Uninstall the old WMDP instance, either using the UI or the command line.
Problem: You see this generic error: “Sorry, an error occurred while processing your request. Please retry your request or contact your system administrator.” Solution: If you open the Event Viewer and navigate to Application logs, you will find a log sourced by ASP.NET, with exception details, as shown in the following example. Some additional information about the errors in the Event Viewer is available in this blog post: Warehouse Mobile Devices Portal for Microsoft Dynamics AX.