I. EPICOR Configuration
This module outlines setup requirements for on premises hosted EPICOR Applications.
1. Finding REST URL
The Epicor Kinetic Warehouse (EKW) application uses a REST API to communicate to the EPICOR Application Server, which in turn communicates with your EPICOR DB.
a. The Rest API path uses the following format:
https://[MyAppServerHost]/[MyAppServerInstance]
1) This URL will be entered at login.
2) This can also be found in your IIS services.
b. Browse to check it is all working by opening a browser to the API help page.
c. Append /api/help onto your URL.
Example: https://[MyAppServerHost]/[MyAppServerInstance]/api/help
cd Use EPICOR credentials to access EPICOR API Help.
2. Server-side Configuration
This module outlines the specific steps to configure your Epicor Application Server to be compatible with Epicor Kinetic Warehouse (EKW).
Note: The Epicor Kinetic Warehouse (EKW) application can authenticate to Epicor Application Server to use Epicor API with EPICOR Basic authentication, Azure Active Directory authentication or EPICOR IdP authentication (Cloud installations only).
Endpoint Binding configuration for EPICOR Basic authentication EPICOR and Kinetic versions prior to Kinetic 2022.1.0
Note: To use EPICOR Basic authentication i.e., EPICOR Username and Password, the binding supporting this type of authentication needs to be configured on the server.
a. In the Application Server Configuration window, in the Net.Tcp Endpoint Binding field, enter in “UsernameWindowsChannel”.
Note: Domain based, Windows authentication is not supported.
Where Windows Net.Tcp bindings are configured on the server to allow desktop clients SSO authentication it is the requirement that the application server is duplicated with the UsernameWindowsChannel Endpoint Binding for use with EKW application.
b. In Application Server Configuration window, enter in “HttpsBinaryUsernameChannel” In the Https Endpoint Binding field.
Authentication Mode configuration for EPICOR Basic authentication Kinetic version 2022.1.0 and above.
a. In Kinetic version 2022.1.0 and above, the Endpoint Bindings used for authentication were replaced with the Authentication Modes.
b. In the Classic Client Authentication field, select Basic.
Other supported Authentication Modes that could be used with EKW are:
AzureAD: Azure Active Directory
IdentityProvider: EPICOR Identity Provider
Configuring Azure Active Directory authentication
Please refer to the relevant EPICOR/KINETIC server version installation guides for instructions on how to set up Azure AD authentication.
a. Additional configuration in Azure AD is required to enable Azure AD authentication for EKW.
1) The following Redirect URI https://emwkineticapp/ needs to be added to Azure AD Registered Client Application to allow EKW to be authenticated with Azure AD.
The redirect address for EKW needs to be entered against the AD Application (client) ID
2) This also appears in EPICOR Azure Active Directory Configuration Maintenance and was set up in Azure AD for Epicor client access (i.e. http://localhost)
Configuring EPICOR IdP authentication
Note: EPICOR IdP authentication is available only to Cloud customers
Additional configuration in Identity Provider server is required to enable EPICOR IdP authentication for EKW
a. The following Replay URI https://emww-biscit.com needs to be added for the specific tenant's ERP JavaScript type client (WebApp) in IdP for successful connection.
3. Token Authentication
Note: By Default, Enable Token Authentication is always enabled. However, you can double check through the provided steps.
Ensure that token authentication service is enabled in the Epicor Administration Console. This allows applications to obtain a token and verify the application as a trusted source to the backend.
a. Open the Epicor Administration Console.
b. Open Server Management, click on the Server Name and select the EPICOR Instance.
c. Under Actions, click on Configure Token Authentication.
d. Ensure that Enable Token Authentication checkbox is ticked.
1) To avoid frequent requests to re-authenticate while using EKW app, default Lifetime (sec) could be extended e.g., to value of 36000, which equivalent to 10 hours.
Note: There are no lines of code deleted in the following steps, only new lines inserted. Administrator credentials are required to modify web.config and/or host.config files.
4. Cross-origin resource sharing (CORS)
Permission for EKW application requests from outside of the domain of the Epicor application server needs to be added. Without this modification, the handheld application will be denied access to communicate with the Epicor application server.
a. Epicor versions prior to 10.2.300
1) In web.config file, located in the Server sub directory of the Epicor Web Applications physical installation path search for “</appSettings>”.
2) Insert the following code above this line:
<add key="CorsOrigins" value="*" />
b. Epicor/Kinetic versions 10.2.300 and above
1) The standard product ships with the CorsOrigins modification added. Just verify the web.config has the CorsOrigins key added to the app settings.
5. Detailed Error Messaging
Modifications to configuration files on the Web server are required to see detailed server error messages in the EKW application instead of generic ‘Sorry! Something went wrong. Please contact your system administrator…’ message.
a. Epicor and Kinetic versions prior to Kinetic 2022.1.0
1) In the web.config file, located in the Server sub directory of the Epicor Web Applications physical installation path search for “<system.webServer>”.
2) Insert the following 3 lines of code directly above this line:
<system.web>
<customErrors mode="Off" />
</system.web>
3) Add the following line inside the <system.webServer> tag.
<httpErrors errorMode="Detailed" />
b. Kinetic versions 2022.1.0 and above
1) To enable detailed error messages, instead of editing the web.config file, add a line of code in host.config file found in the Server sub directory of the Epicor Web Applications physical installation path.
2) Add the lines inside the <appSettings> tag.
<add key="SecureErrors" value="False" />
2) If the line already exists, SecureErrors value needs to be set to False in that line.
Note: For the changes in host.config file to take effect the IIS Application Pool needs to be Recycled
6. BPM Messages
Epicor passes BPM messages through the ‘Context Header’ on a web. EKW application needs access to the Context Header to display any BPM messages returned from the server.
This step can be ignored if display of BPM messages in EKW application is not required.
a. For Epicor versions prior to 10.2.600
1) In web.config file, located in the Server sub directory of the Epicor Web Applications physical installation path search for “<system.webServer>”.
2) Insert the following code below the line
<httpProtocol>
<customHeaders>
<add name="Access-Control-Allow-Headers" value="ContextHeader" />
<add name="Access-Control-Expose-Headers" value="ContextHeader" />
<add name="Access-Control-Allow-Methods" value="GET, POST, PUT, DELETE, OPTIONS" />
</customHeaders>
</httpProtocol>
b. For Epicor/Kinetic versions 10.2.600 and above (i.e., 10.2.600, 10.2.700, 2021.1, 2021.2 2022.1)
1) From version 10.2.600 onwards the access to Context Header is given by default in the REST service API.
2) No changes to web.config file are required for those versions.
7. Recycle Application Pool
a. Once modifications are complete, save the web.config file and/or host.config.
b. Open Epicor Administration Console and Recycle IIS Application Pool of the application that was modified.
Note: For cloud server installations, any changes to host.cofig file are done by the Epicor Cloud Team and they would need to also recycle IIS Application Pool.
8. Epicor Setup
To connect to the Epicor Application Server using EKW, one must have a valid Epicor user account and defined Employee ID.
Please refer to Epicor User guides for User Accounts and Employee ID set up instructions.
Note: Created Employees need to have relevant Employee Roles assigned to be able to perform required inventory and/or production activities.
9. EKW and EPICOR Licenses
a. For Epicor versions prior to 10.2.600
1) In the first instance EKW attempts to use Data Collection license when making calls to REST API, if the Data Collection license cannot be found, then Default User license is used.
2) If there are no free Default User licenses available, an error message stating Out of Licenses will show up and the user will not be able to log in.
Note: Even though Data Collection license may be available, at least one free Default User license is required during the logging in process to obtain the authentication token.
b. Epicor/Kinetic versions 10.2.600 and above (i.e., 10.2.600, 10.2.700, 2021.1, 2021.2 2022.1)
1) In the first instance, EKW attempts to use Epicor Mobile Warehouse license when making calls to REST API.
Note: If the license is not installed, the updated license file should be requested through Wayfinder within EpicCare.
An alert message notifying users that the expected Epicor Mobile Warehouse license cannot be found is displayed in EKW versions 4.0.0 and above.
1) If Epicor Mobile Warehouse license cannot be found, Data Collection license is used.
2) If Data Collection license cannot be found, the Default User license is used.
3) If there are no free Default User license available, an error message stating Out of Licenses will show up and the user will not be able to log in.
Note:
When connecting to Epicor versions 10.2.600 up to and including version 2021.1.3, even though Epicor Mobile Warehouse or Data Collection license may be available, at least one free Default User license is required during the logging in process to obtain the authentication token.
EKW versions 4.0.0 and above connecting to Epicor versions 2021.1.4 and above will never use Default User or Data Collection licenses, as long as, Epicor Mobile Warehouse is installed.
II. EPICOR Kinetic Warehouse Installation
1. Device Management
a. Managing your devices and the applications installed on them is your responsibility. We recommend implementing an EMM (Enterprise Mobility Management) solution, particularly as your number of devices increase.
1) Benefits of an EMM:
a) Allows a central administrator to manage all company devices and push out software to all devices
b) Lock down devices
c) Manage software versions
d) Replace the need to physically handle each device and do updates or changes
b. The following configuration variables which are also referred to as app restrictions are exposed in EKW application.
1) epicor_server_url
2) epicor_username
3) license_key
Note: These variables can be pre-set and pushed to the device together with EKW application to configure it on new, not yet registered, devices without involving the device user.
All values are optional and especially username can be omitted.
If the devices are managed individually, EKW application can be installed from Google Play Store or the installation APK file can downloaded from Biscit download site: https://downloads.biscit.com/ and installed.
2. Installing EKW from Google Play Store
For this method, user must have a google user profile. How this is managed is entirely up to the user.
a. Search Epicor Kinetic Warehouse in the Google Play Store.
b. Select the Epicor Kinetic Warehouse application in the result list.
c. Tap on the INSTALL button.
d. Once the application is finished downloading and the OPEN button is available, the application installation has completed.
e. Tap on the OPEN button to start EKW application.
3. Enabling Automatic Updates
Enable auto-update option is set by default on Android devices when applications are installed from The Google Play Store.
However, this is not recommended for EKW and must be turned off. This is to prevent updates from production that has not been tested from going live in the current version of EKW installed on the device.
It is imperative that customers choosing to leave the auto-update ON join the Beta testing program on at least one device (see point 5 in this section on how to join Beta testing) and make sure those devices are in use so that any issue with an update version is detected it can be reported before all devices are updated.
a. To check if this is enabled, go to the Google Play Store and search for the Epicor Kinetic Warehouse application.
4. Disabling Automatic Updates
Disabling automatic updates is recommended for EKW. This is to prevent any updates in production that has not been tested from going live in the current version of EKW installed on the device.
a. To check if the Enable auto-update is disabled, go to the Google Play Store and search for the Epicor Kinetic Warehouse application.
b. Tap on the three dots and ensure that the Enable auto-updates checkbox is un-ticked.
5. Joining Beta testing
Upcoming versions of EKW on Google Play Store are available for testing/review prior to them being released to production by users that join Beta testing.
a. Search Epicor Kinetic Warehouse in the Google Play Store.
b. Select the Epicor Kinetic Warehouse application in the result list.
c. Tap on the Join link in Join the beta section.
c. Tap on the Leave link in You’re a beta tester section to leave Beta testing.
6. Downloads Platform
Application installations can also be done outside of the Google Play Store. The EPICOR Kinetic Warehouse APK installation file can be obtained from the Biscit download site for manual installation.
Follow the steps outlined below to get an APK file for the required EKW version.
a. Downloading EKW from Downloads Platform
1) Open Google Chrome and navigate to https://downloads.biscit.com.
2) Enter EKW License Key and tap on Login.
3) Tap the EMW directory.
All versions of the application that have been released will be displayed as selectable folders.
4) Tap on the folder for the specific release to be downloaded.
Kindly note, the latest stable release for download will always be the highest number in the list. Our release name structure is Major.Minor.Build.
5) Within the release folder, you will see an installation file: xxxxxx.apk.
6) To install the application, tap on the xxxxxx.apk file.
7) Choose the download location and select and tap on the Download button.
8) Disregard the warning message and tap on Download anyway.
9) Tap on Open after the file has been downloaded.
10) Once prompted to install the application, tap on INSTALL (whether installing for the first time or updating the version).
11) A message will confirm if the installation has been successful.
12) Tap on OPEN to open the application or tap on DONE to open the application later.
Note: Actual screens and dialogs presented during download and installation may look different as they depend on the version of Android currently installed.
EKW Users can also choose to view the list of versions and its specifications in the Release Notes.
b. Choosing a version of EKW via Release Notes
1) Open Google Chrome and navigate to https://downloads.biscit.com.
2) Tap on the Menu icon and select Release Notes.
2) Tap on the Licence key field and enter EKW License Key.
3) Tap on Login.
4) Read through and choose a version of EKW from the list.
5) Go back to the previous section to download accordingly.
7. EPICOR Login
Note: Kindly refer to the Epicor Setup documentation for configuration guides to enable you to log into the application from your device.
a. Review and accept the Terms of Service.
b. Tap on CONTINUE.
c. The application will send a request to the Epicor Application Server URL and attempt to obtain a token.
d. Enter the URL path to your REST API’s in the following format:
“yourservername\yourenvironmentname”
For example: ERPAppServer\ERP10Live
e. Tap on CONTINUE.
f. Enter EPICOR username and password
g. Tap on LOG IN.
8. Applying License Key
a. Enter a license key or run the application in Demo Mode.
Note: This feature allows you to use the application without a license, however, it is limited to the use of Epicor demo companies EPIC03, EPIC06 and/or EPICORE6.
1) Entering the License Key on the device will register it as an active device against the license. Once all of devices allowed by the license have been registered, it will no longer be possible to register any additional device.
a) It is advised to keep an internal log of which devices have been registered.
2) When DEVICE button is tapped, the ID of the device used to register it is displayed. Depending on the Android and EKW versions it could be a SERIAL, IEMI or UUID.
Note: A device can be deregistered later to free up the license count. For more information, refer to the Deregistering Device License section in the guide.
b. Depending on the Android and EPICOR Kinetic Warehouse application versions, access permission pop-ups may be presented.
c. Tap on the ALLOW button. Selecting DENY will not allow the application to function.
d. The collected information is non-personal, non-identifiable, and complies with EPICOR Privacy Policy, as well as international laws and regulations.
e. In the Employee Config window, select the Company, Plant, and Employee ID.
f. Tap on LOGIN.
Note: In DEMO MODE, the company list is restricted to the Epicor Demo Database companies EPIC03, EPIC06 and/or EPICORE6
g. An info message prompt will indicate that Roaming settings are not configured.
Note: This message is displayed only when the user with EPICOR’s Security Manager privileges logs in.
Refer to the Roaming Settings in Settings section of Epicor Kinetic Warehouse User Guide for more information.
h. Tap on OK.
Note: The licensing process is complete only after successfully logging in to the EPICOR environment with Home screen displayed in EKW.
9. Deregistering Device License
How to: Deregister a device and free up a device license for the user’s license key.
a. Log into the application.
b. On the Home screen, tap on the employee image and select Licensing.
c. Tap on Remove Licence.
Note: Device can also be deregistered from the login screen.
d. On the Log in screen, tap on the employee image and tap on Remove Licence.
How to deregister single or multiple devices in the Product Portal
a. Access the Product Portal
b. Select device/devices to be deregistered
c. Press DEREGISTER SELECTED DEVICES button
d. Enter reason for deregistering the device/devices (optional) and press SUBMIT button
10. Downgrading installed version
How to: Downgrade installed version on a device without consuming additional licenses.
a. Deregister Device License as described in point 8 of this guide (above).
b. Uninstall the current version (drag the app icon to the top of the screen and drop on Uninstall icon or long press the app icon and press app info icon and press UNINSTALL icon)
c. Download the required EKW version from https://downloads.biscit.com (access with valid license key)
d. Install the application following instructions in points 5, 6 and 7 of this guide.
Note: Use of Mobile Device Management (MDM) can greatly help to complete steps a. and c. above
III. Recommended Devices
EKW features Advanced Scanning functionality, such as default scan, item selection in the list by scan, scan validation, count increment by scan, multielement barcode scan, template scan and scan sequencing.
To be able to support these in-app event processing triggered of a barcode scan, the application needs to be able to interact with an in-build hardware.
Zebra and Honeywell provide this interaction on their devices via the DataWedge and the programming SDK respectively.
For that reason, it is recommended that devices with Android 5.1 and above OS with inbuild scanners by those manufacturers are used to run EKW.
1. Honeywell Device Configuration
Honeywell devices use predefined configuration that supports majority of scanning needs.
However, internal scanner’s Default profile can be modified to suit specific scanning requirements and then selected for use in EKW.
Furthermore, when SCANNER SETTINGS button is pressed the Default profile settings can be accessed and modified for the duration of the current session.
2. Zebra Device Configuration
Zebra devices require an EMW profile created in DataWedge to allow for in-app events triggering with barcode scans.
a. To create the EMW profile, verify that EMW profile does not exist in the DataWedge.
1) Tap on the DataWedge app icon to view configured profiles.
b. In EKW, navigate to Settings and tap on Scanner.
c. Tap IMPORT PROFILE button.
Note: A warning message will be prompted if there is no existing EMW profile. Tap on YES to proceed.
d. Re-check DataWedge to check if the profile is now visible in the list.
Note: The Zebra device is now set up for in-app events processing triggered by barcode scans and able to take advantage of the EKW Advanced Scanning functionality.