Laying the foundations

First, let’s create a new Angular app. We will use the Angular CLI for this, so open up a command prompt and run the ‘ng new’ command.

ng new AdalSample

Now that we have our app, let’s open the folder with VS Code (or your editor of choice) and get going.

The basic structure

Let’s start by creating a new component called ‘main’. This will be the root component for the functional part of our application. It will contain the shared layout for the application (navigation, header, footer…).

ng g component Main

Open up the main.component.html and copy/past the snippet below. The most important part here is the ‘router-outlet’ tag. Our content will get injected after this tag.

<nav>  <a [routerLink]="['/']">Home</a></nav><router-outlet></router-outlet>

Next is the home component. This will be the landing page for our application.

ng g component main/Home

Before moving on to the next part we also have to replace the content of app.component.html with a router-outlet tag.

<router-outlet></router-outlet>

Keeping order

When we open the app.module, we’ll see that the Angular CLI automatically adds new components to the declarations array. It also creates a separate import line for each component. We currently only have two components in larger applications, this can become quite a list. We can remedy this by using a barrel to group our components together.

Barrels are files with a fixed name (index.ts), that contain exports of other files. They are a great way to keep import statements to a minimum or to group imports (for example rxjs operator imports). So let’s create one in the app folder.

export * from './app.component';export * from './main/main.component';export * from './main/home/home.component';

Now we can import the barrel and have all our component imports on one line. While we’re in the app.module, let’s make sure the router module is imported. Otherwise our router-outlet won’t work.

import { Route, RouterModule } from '@angular/router';import * as c from './';@NgModule({  imports: [BrowserModule,RouterModule  ],  declarations: [c.AppComponent,c.MainComponent,c.HomeComponent  ],  providers: [],  bootstrap: [c.AppComponent]})export class AppModule { }

Routing

We still need to tell our application how to use our newly created components. Routing can be configured straight in the app.module, but we will be using a separate file to house our route configuration.

Create a new typescript file called ‘app.routing.ts’ in the app folder and paste the code below into it.

import { ModuleWithProviders } from '@angular/core';import { Route, RouterModule } from '@angular/router';import { MainComponent, HomeComponent } from './';const routes: Route[] = [{ path: '', component: MainComponent, children: [  { path: '', component: HomeComponent },]}];export const AppRoutes: ModuleWithProviders = RouterModule.forRoot(routes);

Now all that’s left is adding the AppRoutes constant to the app.module imports. If we start the development server and navigate to localhost:4200, we’ll see the ‘home works!’ message.

Error pages

A good app needs to have error pages. So let’s start by creating a 404 page. I’m using a separate module for the error pages to make use of lazy loading.

ng g module ErrorPages

ng g component error-pages/NotFound

Just like in the app.module, we also have to define the routing for our new module. Create a new file called ‘error-pages.routing.ts’ and add the code below. Don’t forget to add the ErrorPagesRoutes to the error-pages.module imports.

import { ModuleWithProviders } from '@angular/core';import { Route, RouterModule } from '@angular/router';import * as c from './';const routes: Route[] = [{ path: '404', component: c.NotFoundComponent }];export const ErrorPagesRoutes: ModuleWithProviders = RouterModule.forChild(routes);

For our 404 to work, we also need to add some routes to the app.routing file. The ** path in the last route is a wildcard that matches any route that isn’t defined.

const routes: Route[] = [{ path: 'error', loadChildren: 'app/error-pages/error-pages.module#ErrorPagesModule'},{ path: '', component: MainComponent, children: [  { path: '', component: HomeComponent },]},{ path: '**', pathMatch: 'full', redirectTo: 'error/404' }];

If we go back to our website enter a non-existing URL in the address bar, our 404 page is shown. So far, so good.

Authentication

Authentication is done via the Azure Active Directory Authentication Library (ADAL) created by Microsoft. However, we won’t be using Microsoft’s ADAL.js directly, instead we’ll use an Angular wrapper library for ADAL. That way, we can skip over a lot of the boiler plate code. The one we’ll be using in this example is adal-angular4, so let’s go ahead and add the package to our solution.

npm i adal-angular4 --save

Once installation is complete, open up the app.module and add the imports below.

import { Http, HttpModule } from '@angular/http';import { Adal4Service, Adal4HTTPService } from 'adal-angular4';

To allow the Adal4Service to be injected into our components, we need to add it to the providers array.

  providers: [Adal4Service,{provide: Adal4HTTPService,useFactory: Adal4HTTPService.factory,deps: [Http, Adal4Service]}  ],

The Azure part

Now we need to make Azure aware of our app. Go to the Azure portal and select the Azure Active Directory blade. Under App Registrations, create a new App Registration.

The name you enter here will be displayed on the login screen, so choose something friendly. For the remaining fields, select ‘Web app / API’ and enter the Angular development server URL.

Do not close the Azure portal just yet, we’ll come back to it in a minute.

Setting up ADAL

Back in our Angular project, it is now time to add our ADAL configuration to the environments file(s). The CLI creates two environment files by default. One for production (when building with the –prod switch) and one for everything else.

Open the environments.ts file and add an adalConfig entry as shown. The tenant value can be found in the Azure Active Directory blade under ‘Domain names’. For the clientId we need to go back to the App Registrations list. Open the registration we just created and copy the Application ID guid.

export const environment = {  production: false,  adalConfig: {tenant: 'my-tenant.onmicrosoft.com',clientId: '00000000-0000-0000-0000-000000000000'postLogoutRedirectUri: 'http://localhost:4200/logout'  },};

Now we’re ready to enable authentication for our app. Open the app.component and change it to the the following.

import { Component, OnInit } from '@angular/core';import { Adal4Service } from 'adal-angular4';import { environment } from '../environments/environment';@Component({  selector: 'app-root',  templateUrl: './app.component.html',  styleUrls: ['./app.component.css']})export class AppComponent implements OnInit {  constructor(private adalSvc: Adal4Service) {this.adalSvc.init(environment.adalConfig);  }  ngOnInit(): void {this.adalSvc.handleWindowCallback();  }}

The init call speaks for itself. It initializes the ADAL service using the settings in our environment file. The handleWindowCallback call will extract the bearer token from the URL when Azure returns to our application after sign-in.

At this point, we’ve fully configured the ADAL service, but when we run the application we won’t see any change just yet.

Login / Logout

It is now time to enable login for our application. For this purpose we will create two additional pages.

ng g component Login

ng g component Logout

The actual logging in is handled by Azure, I hear you think. So why do we need a login page in our application? Well, the name says it all. This is going to be the page where we will call the ADAL login function. Additionally it serves as a splash screen of sorts. So the user won’t see a flash of the actual application before being redirected to the Azure login page.

You’ll see I’ve also included the option to provide a return URL in the querystring. This will be used by our authentication guard. If we didn’t have this in place, the user would always end up on the home screen after logging in.

import { Component, OnInit } from '@angular/core';import { ActivatedRoute, Router } from '@angular/router';import { Adal4Service } from 'adal-angular4';@Component({  selector: 'app-login',  templateUrl: './login.component.html',  styleUrls: ['./login.component.css']})export class LoginComponent implements OnInit {  constructor(private route: ActivatedRoute,private router: Router,private adalSvc: Adal4Service  ) { }  ngOnInit() {const returnUrl = this.route.snapshot.queryParams['returnUrl'] || '/';if (this.adalSvc.userInfo.authenticated) {  this.router.navigate([returnUrl]);} else {  this.adalSvc.login();}  }}

Next is the logout page. When the user clicks the logout link, this will be the place they’re sent. This will also be the page Azure redirects to after logging out. We set the redirect using the ‘postLogoutRedirectUri’ property in the Adal configuration.

As you can see in the code, the only thing that happens here is the logout call. Like with the login page, a reason for keeping this in a separate component is to have a splash screen to show between the time the user clicks logout, and the redirect to Azure.

import { Component, OnInit } from '@angular/core';import { Adal4Service } from 'adal-angular4';@Component({  selector: 'app-logout',  templateUrl: './logout.component.html',  styleUrls: ['./logout.component.css']})export class LogoutComponent implements OnInit {  isAuthenticated = false;  constructor(private adalSvc: Adal4Service  ) {this.isAuthenticated = this.adalSvc.userInfo.authenticated;  }  ngOnInit() {if (this.isAuthenticated) {  this.adalSvc.logOut();}  }}

In the markup we set different messages to show based on the status of the user (authenticated or not).

Signing out...  Signed out successfully. Click <a [routerLink]="['/login']">here</a> to log back in.

To test the logout page, we also have to add a logout link to our main.component.

<nav>  <a [routerLink]="['/']">Home</a>  <a [routerLink]="['/logout']">Logout</a></nav><router-outlet></router-outlet>

And before moving on, we still need to clean up some things. As usual, the CLI has already added our new components to the app.module. But we’re using a barrel, remember?

So first add the new components to our barrel in the app folder and correct the declarations in the module. The now unused imports can be removed.

export * from './app.component';export * from './login/login.component';export * from './logout/logout.component';export * from './main/main.component';export * from './main/home/home.component';

  declarations: [c.AppComponent,c.MainComponent,c.HomeComponent,c.LoginComponent,c.LogoutComponent  ],

Securing content

We’ve done a lot of setup work up to this point. But, this is where we will actually see everything come together.

To secure our main component and everything below it, we’re going to use a guard. This is nothing more than a class that implements some interfaces. Angular provides four interfaces for protecting routes.

• CanActivate
• CanActivateChild
• CanDeactivate
• CanLoad

For our app, we will only use CanActivate and CanActivateChild. If you want a more in depth explanation, Pascal Precht has a very nice post on guards.

First, let’s create a new folder called ‘common’ with a subfolder ‘guards’. In the guards folder, we create a new file called ‘authentication-guard.ts’ with the following content.

import { Injectable } from '@angular/core';import { Router, CanActivate, CanActivateChild, ActivatedRouteSnapshot, RouterStateSnapshot } from '@angular/router';import { Adal4Service } from 'adal-angular4';@Injectable()export class AuthenticationGuard implements CanActivate, CanActivateChild {  constructor(private router: Router,private adalSvc: Adal4Service  ) { }  canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {if (this.adalSvc.userInfo.authenticated) {  return true;} else {  this.router.navigate(['/login'], { queryParams: { returnUrl: state.url } });  return false;}  }  canActivateChild(childRoute: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {return this.canActivate(childRoute, state);  }}

When any of the CanActivate methods get called, our guard checks whether the user is logged in. If the user needs to login, it will redirect to our login page with the current route’s URL in the querystring.

For all this to work, we still need to do two things. Add our guard to the providers array in our app.module and register it on some routes.

  providers: [Adal4Service,{provide: Adal4HTTPService,useFactory: Adal4HTTPService.factory,deps: [Http, Adal4Service]},AuthenticationGuard  ],

const routes: Route[] = [{ path: 'error', loadChildren: 'app/error-pages/error-pages.module#ErrorPagesModule'},{ path: 'login', component: LoginComponent },{ path: 'logout', component: LogoutComponent },{ path: '', component: MainComponent, canActivate: [AuthenticationGuard], canActivateChild: [AuthenticationGuard], children: [  { path: '', component: HomeComponent },]},{ path: '**', pathMatch: 'full', redirectTo: 'error/404' }];

Our guard will get called when the user navigates to the main component or one of it’s child routes.

When running the application, you will see that the functional part of our application now requires authentication, while things like the error pages, login and logout are reachable without logging in.

Getting data

Now that we’ve secured our application, it is time to get some data. For that purpose, I have a secure WebAPI hosted in Azure that returns some hard-coded employee data. I won’t go into detail on how to set up a WebAPI since it not in the scope of this post. Koen has written an excellent post on how to do this.

The setup

To make use of Angular’s lazy loading, we will create a new module to group everything employee related. Organising your application into functional blocks like this has the added benefit of having components, services and models in close proximity.

First we’re going to create the module, the list component and the service class.

ng g module main/Employee

ng g component main/employee/List

ng g service main/employee/Employee

Next is our employee model. Add a folder ‘models’ in the employee folder and create a new file called ’employee.ts’. Copy the snippet below and save.

export interface IEmployee {  id: number;  name: string;  function: string;}export class Employee implements IEmployee {  id: number;  name: string;  function: string;  constructor(obj?: IEmployee) {if (obj) {  Object.assign(this, obj);}  }}

Normally I would also create barrels in the ’employee’ and ‘models’ folders. But since this example won’t get any extra functionality, we will skip the barrels.

Create a file called ’employee.routing.ts’ And add the route to the list component.

import { ModuleWithProviders } from '@angular/core';import { Route, RouterModule } from '@angular/router';import { ListComponent } from './list/list.component';const routes: Route[] = [{ path: '', component: ListComponent }];export const EmployeeRoutes: ModuleWithProviders = RouterModule.forChild(routes);

We still need to link everything up, so open up  the employee module and add the EmployeeRoutes and EmployeeService.

import { NgModule } from '@angular/core';import { CommonModule } from '@angular/common';import { EmployeeRoutes } from './employee.routing';import { EmployeeService } from './employee.service';import { ListComponent } from './list/list.component';@NgModule({  imports: [CommonModule,EmployeeRoutes  ],  declarations: [ListComponent  ],  providers: [EmployeeService  ]})export class EmployeeModule { }

And lastly, add a link to our employee list and that’s it for the setup.

<nav>  <a [routerLink]="['/']">Home</a>  <a [routerLink]="['/employee']">Employees</a>  <a [routerLink]="['/logout']">Logout</a></nav><router-outlet></router-outlet>

The implementation

For the service implementation, we have it pretty easy. Adal-angular4 will do almost everything for us. But first we need to make Adal aware of our api and that requires we make some changes in our environments file.

export const environment = {  production: false,  adalConfig: {tenant: 'my-tenant.onmicrosoft.com',clientId: '00000000-0000-0000-0000-000000000000'postLogoutRedirectUri: 'http://localhost:4200/logout',endpoints: {  'https://adaltestapi.azurewebsites.net': 'https://adaltestapi.azurewebsites.net'},  },  apiUrl: 'https://adaltestapi.azurewebsites.net/api/'};

The ‘apiUrl’ is for use in our service and it contains the base URL of our WebAPI. For service authentication to work correctly, we also need to add our API to the endpoints in our Adal configuration. The endpoints value is an object with key/value pairs for each resource the application uses. The key is the resource URL and the value is the App ID URI. You can find this value in the Azure portal under the app registration settings of your API.

Now on to the service itself. We do essentially the same as we normally do, but instead of Angular’s Http, we use the Adal4HTTPService. This wrapper works virtually the same as Http, but it will automatically add the bearer token to the request. But only if the request URL is defined as an endpoint.

import { Adal4HTTPService } from 'adal-angular4';import { environment } from '../../../environments/environment';import { Employee, IEmployee } from './models';@Injectable()export class EmployeeService {constructor(private http: Adal4HTTPService  ) { }  public getEmployees(): Observable<Array<IEmployee>> {return this.http.get(`${environment.apiUrl}Employee`)  .map(response => {const tmp = <IEmployee[]>response.json();return tmp.map(e => new Employee(e));  });  }}

All that is left, is to call our service and show the data on screen. This is exactly the same as you’re used to.

export class ListComponent implements OnInit {  employeeList: Array<IEmployee> = [];  constructor(private empSvc: EmployeeService  ) { }  ngOnInit() {this.empSvc.getEmployees().subscribe(  rslt => this.employeeList = rslt,  error => console.log(error));  }}

<h3>Employees</h3><table><thead><tr><th>Id</th><th>Name</th><th>Function</th></tr></thead><tbody><tr *ngFor="let emp of employeeList"><td>{{emp.id}}</td><td>{{emp.name}}</td><td>{{emp.function}}</td></tr></tbody></table>

Conclusion

And that is it. Using Adal with Angular is pretty easy when using a wrapper like adal-angular4. But as I said in the intro, this post is mostly about providing a decent starting structure for the types of business apps a lot of us typically work on. The biggest advantage I find, is that authentication code is centralised. None of the components under main have to know anything about Adal, Azure or security. All this is handled far away from the business and UI logic, which makes for an easier to maintain application.

The source code of the sample projects can be found on our GitHub.

security_featuredimagejorenpapsaals-home-worksaals-not-found-worksaals-app-registrationaals-appiduriaals-employee-listJoren Paps/2015/10/25/angular-spa-in-dynamics-crm-ngxrmservicetoolkit//2015/10/25/angular-spa-in-dynamics-crm-ngxrmservicetoolkit/#commentsSun, 25 Oct 2015 12:22:21 +0000/?p=511Having spent most of this year learning and using AngularJS and Typescript  on the one hand and working on Dynamics CRM projects on the other, I thought it a nice exercise to combine the two.

Every developer that has worked with Dynamics CRM knows, or at least (s)he should, that client side javascript customizations are a valuable addition to get that little bit of extra out of the standard Dynamics CRM package.

I myself have learned to appreciate javascript more by doing just that. Extending the standard functionalities of Dynamics CRM.

If you want to do more than some little cosmetic changes on a form, you can create your own webpages and use them in Dynamics CRM by inserting them as a WebResource. Keep in mind that you can only use HTML webpages to host in Dynamics CRM and they cannot execute server side code. You can reference other WebResources by creating a folder structure in the naming of your WebResources.
More information on that can be found on the MSDN  website.

So yeah, hosting an Angular SPA in Dynamics CRM, it’s possible.

If you don’t want to use any Dynamics CRM data in your Angular SPA, why host one in Dynamics CRM. So I started a simple CRUD application by using the fantastic XrmServiceToolkit library . There even is a Typescript definition file in the wild for that library. So I was good to go, or so I thought.

While the XrmServiceToolkit works great and is useable inside Angular, it relies on callback functions for asynchronous functionalities and has no support for promises. Which is a valid approach, don’t get me wrong, but I wanted those promises.

And so my focus changed from a simple Angular SPA inside Dynamics CRM with some CRUD executions to developing a reusable toolkit based on the XrmServiceToolkit and an Angular SPA that executes each of the SOAP and REST functions that I converted.

I called it the ngXrmServiceToolkit and it exposes the same SOAP and REST methods as the original, minus the SOAP grantAccess, modifyAccess, revokeAccess and retrievePrincipalAccess. Let’s call those work in progress.

So what is available:

• When accessing the Dynamics CRM SOAP endpoint:
  • createEntity
  • retrieveEntity
  • updateEntity
  • deleteEntity
  • execute
  • fetch
  • retrieveMultiple
  • queryByAttribute
  • queryAllByAttribute
  • setState
  • associate
  • disassociate
  • assign
  • getCurrentUserId
  • getCUrrentUserBusinessUnitId
  • getCurrentUserRoles
  • isCurrentUserInRole
  • retrieveAllEntitiesMetadata
  • retrieveEntityMetadata
  • retrieveAttributeMetadata

• When accessing the Dynamics CRM REST endpoint:
  • createRecord
  • retrieveRecord
  • updateRecord
  • deleteRecord
  • retrieveMultipleRecords
  • associateRecord
  • disassociateRecord

The result of my work is hosted on GitHub .

It includes the source code for the reusable Angular factories I created, a demo project created in visual studio and a managed Dynamics CRM solution that is the WebResource representation of the demo project.

This is the demo web page inside Dynamics CRM:

I made the Index-page the configuration page of the Solution. So all functionalities can be tested without touching anything else but the solution.

No custom entities or fields are being used. Both the SOAP and REST test actions can create (and update/retrieve/delete/…) an account and a contact. If you leave the configuration section of the solution without deleting the created test records, they will persist in your environment.

All actions are hardcoded, so there is little to no user input in the demo. It was just easier to create the demo that way.

How does the demo application work?

As there are 2 factories available, one for SOAP actions and one for REST actions, the demo application is divided into 2 sections to demo the available actions.

Each section has a set of dropdown buttons with actions connected to it.

There are test entities available in the angular controller and their JSON representation is shown on the page.

The result of each action is shown with a popup, or in the Fetch Result section or a combination of both.

A separate section is provided for the metadata actions.

Some actions cannot be executed in certain situation. E.g.: update account cannot be executed before the account has been created. The application will notify you with a popup message when that is the case.

Feel free to leave your thoughts, questions, issues about this demo or the toolkit in the comment section of this blog post, or directly in the GitHub repo.

 

Ruben Biesemans

Analyst Developer @ Spikes

]]>/2015/10/25/angular-spa-in-dynamics-crm-ngxrmservicetoolkit/feed/2ngXrmServiceToolkit_TitlerubenbiesemansspikesngXrmServiceToolkit_01Action ButtonsJSON outputFetch ResultMetadata ResultRuben Biesemans/2015/09/25/multilanguage-dependent-option-sets-for-dynamics-crm//2015/09/25/multilanguage-dependent-option-sets-for-dynamics-crm/#commentsFri, 25 Sep 2015 09:54:10 +0000/?p=414When I needed to create some dependent option sets for a client in Dynamics CRM, I knew where to start: GOOGLE. One of the top results for solving this issue, was this MSDN sample: https://msdn.microsoft.com/en-us/library/gg594433.aspx

The provided sample solutions worked like a charm. Time to implement it in my real world scenario. The documentation on the MSDN sample page clearly states that the label values in the xml are solely there for readability purposes. They are NOT used in the script.

Well, I don’t like typing too much, so when creating my own xml, I left out each and any label attributes.

Imagine my surprise when I used this on my form and the result of the dependent option sets looked like this:

At first I thought I made a mistake and started going through my xml. Except for having no label attributes whatsoever, the file was ok. That’s when the developer in me started going through the actual code. And surely, while the sample documentation states that the label values are not used. They are …

Luckily, there’s just a little bit of extra code needed to make this work as promised.

These steps are necessary to make this work:

1. During the initialize stage, get a hold of the original option set values of the dependent option sets. They will be in the correct language, provided that translations are in place in your environment.
2. When creating the options array for each parent item, get the label from the original option set value that we retrieved in step 1.
3. In the interest of readability, write a separate function to do the search necessary in step 2.

The code before the change:

The code after the change:

I left the option to set a label value provided in the xml, just in case the translated text is not found. Which for me would result in null labels again, but hey, I will configure this correctly so it won’t be needed, right?

The result after changing the script:

A downloadable version of the full improved javascript file can be found here .

This concludes this blog post, hope it helps!

 

Ruben Biesemans

Analyst Developer @ Spikes

]]>/2015/09/25/multilanguage-dependent-option-sets-for-dynamics-crm/feed/1Image6rubenbiesemansspikesImage1Image2Image3Image4Image5Ruben Biesemans/2015/06/30/communication-error-while-configuring-microsoft-dynamics-crm-for-outlook//2015/06/30/communication-error-while-configuring-microsoft-dynamics-crm-for-outlook/#respondTue, 30 Jun 2015 13:14:19 +0000/?p=268Recently our company’s CRM online environment was updated to CRM 2015. This meant that those of us who used CRM for Outlook had to upgrade their CRM for Outlook to the latest version in order to support CRM 2015.

The outlook client itself has undergone some changes, but those are not in the scope of this blogpost. You can read about it here.

After installing the new outlook client, and starting the configuration wizard, the following error message popped-up:

Searching the internet for this error message, a lot of possible causes for getting this error showed up. What eventually pointed me in the right direction was this article on the Microsoft support site.

The instructions are easy enough and the explanation is clear. But after following them, I did not find an issue in my sitemap. I actually went through the xml of the sitemap several times before I saw the problem.

I recreated the issue in a demo environment where I created a sitemap that looks like this:

As you can see, there are multiple areas which in turn contain some groups which contain the subareas. In the sitemap documentation, it is stated that the subareaid should be UNIQUE. Looking at this xml, you can clearly see that the same id is used for multiple subareas.

CRM itself does NOT complain about this, proven by the following image:

So at first I thought this couldn’t be the issue. As you can see that every path to a subarea with id nav_accts is unique. Simplified in a tree it looks like this:

• Area Id=SFA
  • Group Id=Customers
    • SubArea Id=nav_accts
  • Group Id=SFA
    • SubArea Id=nav_accts
• Area Id=CS
  • Group Id=Customers
    • SubArea Id=nav_accts

But for the outlook client, every subareaid should be unique within the AREA that it resides in, REGARDLESS of the groups. I did not find this little quirk documented anywhere.

And sure enough, after modifying the id of one of the subareas in the SFA area, I could go through the configuration wizard without issues.

The result in outlook:

This concludes this blog post, hope it helps!

 

Ruben Biesemans

Analyst Developer @ Spikes

]]>/2015/06/30/communication-error-while-configuring-microsoft-dynamics-crm-for-outlook/feed/0Communication ErrorrubenbiesemansspikesError Message PopupSitemap XmlDynamics CRM NavigationCRM in OutlookRuben Biesemans