11/12/2019 Knowledge Page - EpicCare

Epicor Data Discovery (EDD) Troubleshooting Guide KB0039204

 Authored by Frank DiCarlo •  2y ago •     

Issue

Epicor Data Discovery (EDD) Troubleshooting Guide

Error

N/A

Resolution

Trouble Shooter’s Guide

Epicor Data Discovery (EDD) is standalone BI web application service that uses Epicor ERP as token
authentication server and as principal BAQ data source provider. This Document provides the trouble
shooter’s guide for some potential configuration issues, the exceptions that might arise, and suggested
resolutions.

Overview
Because EDD is not stitched directly into the Epicor ERP application, there is some configuration that
needs to be setup and it all needs to be wired up correctly or else there can be varying exceptions or error
conditions.

The Epicor ERP application has a server-side web.config that describes how Epicor ERP will be
made available to outside consumers. This web.config is typically updated using the Epicor Admin
Console, but can be manually updated using your favorite text editor.
Epicor Data Discovery has both a server-side web.config for the EDD REST services, and it has
a UI-side sysconfig.json file. Both these files are configured during installation of EDD.
the EDD REST web.config describes the connection string for the EDD database, and it
has an <AuthServer> node describing where Epicor ERP REST site exists.
the EDD UI sysconfig.json the <restUri> , <odataUri> , <distribution> nodes
describe where EDD REST and, distribution version/license files exist. At the bottom of the

https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 1/8
11/12/2019 Knowledge Page - EpicCare

sysconfig.json, there is <ep.token> > <restUri> node that describing where Epicor ERP
TokenResources site exists.
The Epicor Active Home Page is distributed with Epicor ERP. It has a UI-side
\home\sysconfig.json file that contains an <eddUrl> node that describes the url for the EDD UI
site.

Prerequisite

Verify Epicor ERP REST and TokenResource services are functioning.

Epicor ERP needs to be fully operational with REST services and Token Authentication enabled. With
10.2.200 this is how ERP is delivered by default. Because it is possible to install EDD on separate
machine from Epicor ERP and the Active Home page, all the web sites needs to be configured to operate
under the https protocol with valid SSL certificate. As a rule of thumb when troubleshooting, it is best
practice to verify both Epicor ERP REST service and Epicor ERP TokenResource service are behaving
properly.

browse to https://machineName.domainName/EpicorERP/api/help/
This should be successful to login to the Epicor REST API Help pages/swagger pages.
with simple token, it should prompt (with “Authentication Required”) for ERP user creds
with SSO, it should auto connect and present the “Epicor REST API Help pages”
with Azure AD, it should redirect to Azure login page and/or auto connect and present the
“Epicor REST API Help pages”
browse to: https://machineName.domainName/EpicorERP/api/.configuration.
with simple token, the <Enabled> node should be true, the others false
with SSO, the <UsesWindowsBinding> node should be true.
with Azure AD, the <AzureBindingEnabled> should be true.
This should respond with something like:

<ServerConfiguration xmlns:i="http://www.w3.org/2001/XMLSchema-instance"

<TokenAuthentication>

<AzureBindingEnabled>false</AzureBindingEnabled>

<Enabled>true</Enabled>

<UsesWindowsBinding>false</UsesWindowsBinding>

</TokenAuthentication>

</ServerConfiguration>

NOTE - when using Azure AD

browse to:
https://machineName.domainName/EpicorERP/api/.configuration?tenantId=
to retrieve generic/default Azure AD configuration settings.
https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 2/8
11/12/2019 Knowledge Page - EpicCare

browse to:
https://machineName.domainName/EpicorERP/api/.configuration?tenantId=xxxxx
(where xxxxx is legitimate tenant id) to retrieve Azure AD configuration settings for that
tenant.

When Azure AD is setup properly, this should respond with something like:

<ServerConfiguration xmlns:i="http://www.w3.org/2001/XMLSchema-instance"

<TokenAuthentication>

<AzureBindingEnabled>true</AzureBindingEnabled>

<Enabled>true</Enabled>

<UsesWindowsBinding>false</UsesWindowsBinding>

</TokenAuthentication>

<AzureADSettings>

<Description>Azure AD description</Description>

<DirectoryID>4f4f4c56-....</DirectoryID>

<NativeClientAppID>5de97b51-....</NativeClientAppID>

<WebAppID>f03910c7-.....</WebAppID>

</AzureADSettings>

</ServerConfiguration>

Browse to: https://machineName.domainName/EpicorERP/TokenResource.svc/

with simple token, it should prompt for creds. This should respond with something like:

<Token xmlns="http://schemas.datacontract.org/2004/07/Epicor.Web" xm

<AccessToken>

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOiIxNTIyNDQzMzM
V....

</AccessToken>

<ExpiresIn>3600</ExpiresIn>

<RefreshToken/>

https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 3/8
11/12/2019 Knowledge Page - EpicCare

<TokenType>Bearer</TokenType>

</Token>

All of the Epicor ERP https endpoints should be secure and operational with valid SSL certificate. On the
chrome browser, on the Address bar the site should be locked down and secure.

If the lock is not locked then there is certificate error that needs to be solved.

NOTE: on development or sales image, the self-signed cert needs to include Subject Alternative Name
(SAN). Instructions for creating a Self-Signed cert in addendum at the end of this document.

Installation exceptions.
Below is a list of some potential Install time exception conditions; what the exception text might indicate,
and some possible resolutions.

You can find the full logs for the EDD installation under the Epicor installation directory.

E.g., C:\Epicor\ERP10\ERP10.2.300.0\SupplementalInstalls\Data Discovery

The log file EDD.log and Errors.log may help to locate the problem.

Error -2147467259: failed to create SQL database

This indicates that the SQL server configuration manager has not been configured to allow for named
pipes and tcp/ip protocols used on the wix installer.

From Sql Server Configuration Manager

expand SQL Server Network Configuration
expand Protocols for SqlInstanceName
Enable Named Pipes and TCP/IP

Page Load exceptions.

Below is a list of some potential page load exception conditions; what the exception text might indicate,
and some possible resolutions.

This site can’t be reached. machineName.domainName refused to

connect.
This indicates the EDD website was not properly configured. Or more specifically, at install time when
selecting an Existing Web Site, this site probably does not allow for https binding.

From IIS on the EDD server:

Activate the website in the tree on the left and Edit Site Bindings on the Actions panel on
the right.
verify https is supported binding protocol and if it doesnt exist, add it
on Site Bindings select https and click Edit
on Edit Site Bindings, verify the Host name matches the fully qualified domain name.

https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 4/8
11/12/2019 Knowledge Page - EpicCare

on Edit Site Bindings, select your Self Signed cert in the SSL certificate list and click OK

This site can’t be reached. The webpage

at https://machineName.domainName/xxx might be temporarily
down or it may have moved permanently to a new web address.
If this is followed with ERR_SSL_UNRECOGNIZED_NAME_ALERT , this indicates there might be a conflict
with QUIC protocol.

Solution: From chrome browser enter chrome://flags/

use -f to search for QUIC
Change Experimental QUIC protocol from Default (or Enabled) to Disabled.

Login or access exceptions.

Below is a list of some potential login exception conditions; what the exception text might indicate, and
some possible resolutions.

An error occurred when trying to create a controller of type

‘AccountsController’. Make sure that the controller has a
parameterless public constructor.
This indicates the EDD database cannot be reached by the EDD REST Services.
Open Network tab on the browser debugger tools In the list of requests search for the GetToken request
to get the full exception text. Usually, the useful information when this error occurs are the lines above
when the stack trace began.

When inner exception contains “Login failed for user”:

"message":"Login failed for user 'AMERICAS\\xxxMachinenName$'.",

"ClassName":"System.Data.SqlClient.SqlException",

This indicates the ConnectionString to the DataDiscovery database in the REST web.config is set to
Integrated Security and the IIS AppPool identity does not have access to SQL server.

Solution 1: Change the AppPool Identity to be user that has sufficient access to the SQL
database. – Verify that user has db_owner role. – Verify that user has access to EDD database.
Solution 2: Add the Application Pool Identity to a SQL server login.

When the inner exception contains “The model backing the

‘DataDiscoveryContext’ context has changed”:

"Message":"The model backing the 'DataDiscoveryContext' context has changed sinc

This indicates the software was successful to upgrade, but the Database was not properly updated.

Solution 1: re run the installer and verify the installation user has sufficient access to the
database.
Solution 2: TODO: how to publish / re-run the udpate-database.sql script.
https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 5/8
11/12/2019 Knowledge Page - EpicCare

The model backing the ‘DataDiscoveryContext’ context has changed:

For the developer:
As we discuss above, this indicates that there is schema mismatch. Typically we would use
EntityFramework to provide the sql updates for us.
When running update-database from the Package Manager Console and it responds with:

This operation requires a connection to the 'master' database. Unable to create

a connection to the 'master' database because the original database connection
has been opened and credentials have been removed from the connection string.
Supply an unopened connection.

edit \Epicor.BI.DataDiscovery.Model\App.config.
verify the connection string points to the correct sql instance and database.
add Persist Security Info = True; to the connection string

Application Offline. The connection with the server has been lost.
Attempting to Reconnect…
This indicates the EDD REST site is not properly configured.

verify in IIS for the EDD REST Application, from Advanced Settings, make sure Enabled
Protocols included http,https
verify the AppPool is started.
browse to the EDD REST
site https://machineName.domainName/EpicorDataDiscovery/Epicor.BI.DataDiscovery.REST and
confirm you are presented with Epicor Data Discovery API site.

On Login, Connection failed. please review the username and

password and try again.
This indicates a Fully Qualified Domain Name (FQDN) is not being used on both the EDD UI
sysconfig.json and EDD REST web.config

verify restUri, odataUri and distribution nodes on the top of sysconfig.json are using FQDN.
verify AuthServer node at the top of web.config is using FQDN.

On Login, when successful creds are entered, but the Login page is
not dismissed for the List page
When inner exception contains the following:

"statusCode":404,"severity":1,

"message":"Current User not found"

This indicates there is mismatch between AuthServer nodes on EDD REST web.config and ep.token
nodes on EDD UI sysconfig.json

verify “EnableAuthorization” =”true” in EDD REST web.config

verify “debug”: false in the EDD UI sysconfig.json

https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 6/8
11/12/2019 Knowledge Page - EpicCare

On Login, when greeted with “Token authentication may not be

enabled on the Epicor server”.

Token authentication may not be enabled on the Epicor server, Refer to Epicor A
dministration Console.

If the Epicor ERP endpoints all behave properly and are have green-light certs, then this indicates there is
mismatch between AuthServer nodes on EDD REST web.config and ep.token nodes on EDD UI
sysconfig.json.

verify “AuthServer” =”https://machineName.domainName/EpicorERP/“ value in EDD REST

web.config
matches the value for ep.token > “restUri”:
“https://machineName.domainName/EpicorERP/TokenResource.svc/“ in EDD UI sysconfig.json
TODO: need to create SSO special config
TODO: need to create azure AD special config

Active Homepage / Integration Exceptions.

Below is a list of some potential integration exception conditions that may be visible when EDD is
embedded or integrated into another application, (ie Active Home Page); what the exception text might
indicate, and some possible resolutions.

On Active Homepage: 404 - File or directory not found. The resource

you are looking for might have been removed, had its name
changed, or is temporarily unavailable.
This indicates a potential ERP install issue and suggests the Active Home page is not pointing to EDD.

verify the erp \server\Home\sysconfig.json file

confirm the eddUrl node points to the proper url for the EDD UI.

Addendum
Create a self-signed cert (with SAN)
With Epicor ERP 10.2.300, the Epicor Admin Console will be available to generate a proper SSL
certificate with the Subject Alternative Name. Until then, it is required to have valid SSL certificate.
Below is the manual steps to generate and use a Self-Signed certificate.

From powershell as admin

invoke New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My
-DnsName "xxx.americas.epicor.net" -FriendlyName "xxx.americas.epicor.net"
-KeyUsage DataEncipherment,KeyEncipherment -TextExtension @("2.5.29.37=
{text}1.3.6.1.5.5.7.3.1")
make sure the -DnsName is the proper machine/domain name. Case matters!
make sure the -FriendlyName matches the -DnsName.
From Manage Computer Certificates.
You should find the new Self Signed certificate

https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 7/8
11/12/2019 Knowledge Page - EpicCare

Export the cert.

Import into Trusted Root Certificate Authority.
From IIS.
Activate the website in the tree on the left and Edit Site Bindings on the Actions panel on
the right.
on Site Bindings select https and click Edit
on Edit Site Bindings, select your Self Signed cert in the SSL certificate list and click OK
From the command line as administrator
IISRESET
Verify you can connect to Epicor Admin Console without may not have a private key that
is capable of key exchange exception on Event Viewer.
Using Chrome, verify the Epicor ERP REST, Epicor ERP TokenResource, and Epicor Data
Discovery sites are Secure.

Resources
How to create a self-signed SAN certificate, wildcard certificate vs SAN

Notes

N/A

https://epicorcs.service-now.com/epiccare?id=epiccare_kb_article&sys_id=ea32b993db9d1bccbea3fba9bf961900 8/8