Epicor Angular 13+ Template

This is a very basic angular App that takes advantage of the Epicor Rest API and can be used as a guide on how to develop your own Epicor Aware Angular applications using Epicor Rest.

This is not meant to be an all encompassing secure solution that will fit every scenario but it is mean to be used as a guide and a learning tool on how you can safely use Angular and Epicor to create a front end application that relies exclusively on the Epicor back end

I used bootstrap for the visual components I will not be explaining Bootstrap there are no less than a thousand bootstrap tutorials out there.

Authentication Mechanism

This app uses basic authentication to make a POST request to the TokenResource.svc endpoint in your Epicor Application and in return it gets a Bearer Token which is stored locally and used for all subsequent Epicor calls. At no point does this application store the plain text username and password.

Important Files

environment.ts: This file contains the settings that are used for the connection information into Epicor. This is the first file you should modify.

Epicor-Angular-Web-App-Template/src/environments/environment.ts

Lines 5 to 11 in a4ff8b4

	export const environment = {
	production: false,
	EpicorHost:'yourserver.tld.com',
	EpicorInstance:'YourEpicorInstance',
	EpicorAPIKey:'YourAPIKey',
	EpicorDefaultCompany:'MfgSys',
	};

EpicorHost- This is typically your servername along with our domain

EpicorInstance- This is typically the name of your EpicorInstance such as EpicorLive

EpicorAPIKey- This is generated inside Epicor using API Key Maintenance One thing to note is that the API key should be related to an Epicor Scope which limits which parts of Epicor a particular API Key can access. Another thing to keep in mind is that the Epicor Scope is wide access scope unless restricted meaning if you don't add any services to the scope then you will have access to all the services. I typically make sure to add at least 1 BAQ, 1 Service (TipSvc) to ensure your scope is property protecting.

EpicorDefaultCompany- This is your default company Identifier

Building App

It is required that you hava functioning angular environment in the very least you should have NPM installed. NPM is a package manager that comes with node

1. Install node https://nodejs.org/en/download/
2. Install angular https://angular.io/guide/setup-local Once you have both of the above installed you should be able to run the following command to build the application. Remember to change the environment file to match your environment.

npm i
ng serve

The first command will install all needed reference files and libraries, the second one will build your app and start it up in Port: 4200 in your computer. If everything went well you should be able to navigate to http://localhost:4200 and see a login screen like the one below.

Here you should be able to Login by typing in your Epicor Username and Password and Clicking the Login Button. Assuming everything is working as intended you should see the Home screen below with a list of your Epicor companies.

Technical Details

The app consists of: 2 view components login and home

1 partial component navigation

2 services EpicorAuthGuardService and epicorSvc

1 model EpicorTokenResponse

Project Bootstrapping (how the sausage is made)

The project is bootstrapped as follows

1. When the app spins up angular runs main.ts as defined in the angular.json file

   Epicor-Angular-Web-App-Template/angular.json

   Line 22 in 6da5704

   "main": "src/main.ts",

2. main.ts calls the bootstrap function in the app.module.ts file

   Epicor-Angular-Web-App-Template/src/main.ts

   Lines 11 to 12 in 6da5704

   	platformBrowserDynamic().bootstrapModule(AppModule)
   	.catch(err => console.error(err));

3. In turn the boostrap function executes AppComponent.ts which is the root component of the app
4. AppComponent.ts is rendered in the index.html file under the injection point <app-root></app-root>

   Epicor-Angular-Web-App-Template/src/index.html

   Lines 10 to 12 in a4ff8b4

   	<body>
   	<app-root></app-root>
   	</body>

5. AppComponent itself has two render points defined in app.component.html <app-navigation> and <router-outlet>

   Epicor-Angular-Web-App-Template/src/app/app.component.html

   Lines 1 to 2 in a4ff8b4

   	<app-navigation></app-navigation>
   	<router-outlet></router-outlet>

6. navigation.component is rendered across the top of all the "pages" and it is just a navigation bar. It contains a shortcut to Home as well as a link to login / logout based on the current authentication state.
7. app-navigation is where the engular router renders any component or "route" you have navigated to. Angular is what is known as a SPA (or single page aplication) so each view is rendered in the same physical HTML page by manipulating the dom. The routing rules are defined in the app-routing.module.ts file.
8. app-routing.module.ts defines two routes for this app /Login which renders the login.component and / which renders the home.component

   Epicor-Angular-Web-App-Template/src/app/app-routing.module.ts

   Lines 7 to 17 in f5ca78e

   	const routes: Routes = [
   	{
   	path: 'Login',
   	component: LoginComponent
   	},
   	{
   	path: '',
   	component:HomeComponent,
   	canActivate:[EpicorAuthGuardService] //Checks to see whether the user has a valid Epicor token in its current local storage.
   	}
   	];

9. In the routing rule for the home.component we define an AuthGuard via the canActivate property. This is a guard that checks to see if the user is authenticated. If the user is not authenticated the user is redirected to the login.component

   Epicor-Angular-Web-App-Template/src/app/app-routing.module.ts

   Lines 12 to 16 in a4ff8b4

   	{
   	path: '',
   	component:HomeComponent,
   	canActivate:[EpicorAuthGuardService] //Checks to see whether the user has a valid Epicor token in its current local storage.
   	}

10. epicor-auth-guard.service.ts implements the CanActivate interface and returns a boolean value based on whether the user is logged in or not. This is checked by using the epicorsvc.service.ts method IsUserLoggedIn() which reads the Epicor bearer token from the browser HTML 5 storage and determines if the user is logged in and wheter or not the token is expired if it doesn't exist or has expired, the user is redirected to the login.component to allow them to login.

    Epicor-Angular-Web-App-Template/src/app/services/epicor-auth-guard.service.ts

    Lines 12 to 20 in cd65682

    	canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean | UrlTree | Observable<boolean | UrlTree> | Promise<boolean | UrlTree> {
    	if(this.epicorSvc.IsUserLoggedIn())
    	return true;
    	else
    	{
    	this.router.navigate(['/Login']);
    	return false;
    	}
    	}

11. login.component.ts is the login component. It contains a form that allows the user to login and a button to submit the form. It does some basic validation and when the user clicks Login it uses the epicorsvc.service.ts method GetEpicorToken() to make a POST request to the TokenResource.svc endpoint in your Epicor Application passing in the username and password in return it gets a Bearer Token which is stored locally and used for all subsequent Epicor calls. A successful login redirects to the / (home) route.

    Epicor-Angular-Web-App-Template/src/app/views/login/login.component.ts

    Lines 33 to 55 in cd65682

    	async Login()
    	{
    	this.loginErrorMsg='';
    	this.loginForm.markAllAsTouched()
    	if(this.loginForm.valid)
    	{
    	this.epicorSvc.GetEpicorToken(this.loginForm.get('userName')?.value, this.loginForm.get('password')?.value).then(response=>{
    	if((response as EpicorTokenResponse).AccessToken)
    	{
    	this.epicorSvc.StoreToken(response as EpicorTokenResponse);
    	this.router.navigate(['/']);
    	}
    	}).catch(error=>{
    	if(error.status && error.status==401)
    	{
    	this.loginErrorMsg='Could not login. Please check your username and password.';
    	}
    	else
    	this.loginErrorMsg=error.message;
    	});
    	}
    	}

12. home.component.ts is the main navigational component of the app. If the user is logged in it gets a list of all the companies the current has access to and renders them in a table.

    Epicor-Angular-Web-App-Template/src/app/views/home/home.component.ts

    Lines 20 to 44 in cd65682

    	if (this.epicorSvc.IsUserLoggedIn()) {
    	/// See https://rxjs-dev.firebaseapp.com/guide/observer for more info on the Observer pattern
    	const responseObserver = {
    	next: (response: any) => {
    	this.companyResponse = response;
    	},
    	error: (error: HttpErrorResponse) => {
    	console.log(error);
    	if (error.status && error.status == 401) {
    	this.errorMsg = '401 UnAuthorized Error. Check your API Key, Scope and Token';
    	}
    	else {
    	this.errorMsg = error.message;
    	}
    	}
    	}
    	//Returns a company list for the user
    	this.epicorSvc.GetCompanyList()?.subscribe(responseObserver);
    	}
    	else {
    	this.router.navigate(['/Login']);
    	}
    	}

App Walk Through

I have commented as much of the code as I can to make it easier to understand. Let me know if you run into any issues.