gravitonian

Building a Process Management App with ADF 2.0.0

Blog Post created by gravitonian Employee on Jan 25, 2018

Introduction

In this article we will look at how you can use the Alfresco Process Services (APS) related ADF components to build a Process Management application. This could be useful if you are about to start on an ADF trial, you need to build a PoC with ADF, or you just want to play around with it and see what's available.

 

This article builds on two other articles in the ADF Developer Series. The first article talks about how to generate an application with Angular CLI and prepare it for use with ADF 2.0.0 and the second article improves on the first article by adding a navigation system, menu, toolbar, and logout functionality.

 

We want our new process management application interface to look something like this:

 

This application should allow the user to browse the Process Applications available in APS. While browsing the Apps the user will be able to look at the associated Process Definitions, and start processes based on those definitions. It will then be possible to interact with the active Task Instances. Running Process Instances can also be inspected directly. The application will cover most of of the available APS related ADF components.

 

It is likely that you will create different types of Process Management applications depending on the user role. And you will probably not use all the ADF components shown in this article in every application. For example, if the user should only interact with ongoing Task Instances assigned to them, then you would use ADF components shown in the My Tasks section. If the user should be able to start Process Instances, then you would look at ADF components talked about in the Process Apps section. If the user is a sys admin, then they would most likely benefit from the ADF components used in the My Processes section.

 

Before we start building an application with the Process Services related ADF components it might be a good idea to know what they actually are. At first you might think, great, now I can build a custom UI for all the workflows I got deployed in my Alfresco Content Services (ACS) installation. As you know, ACS has the Activiti workflow engine embedded, and most consulting projects revolving around Alfresco has traditionally implemented business processes with this workflow engine. The Process Services ADF components cannot be used for ACS workflows. They can only be used for Alfresco’s stand-alone Business Process Management solution, which is Alfresco Process Services (APS).

 

The Process Services ADF components uses indirectly, via the Alfresco JavaScript API,  the APS ReST API, which is separate from the ACS ReST API.

 

The Process Services ADF components can also not currently be used to design and implement workflows. That still need to be done via the APS App Designer.

 

Article Series

This article is part of series of articles covering ADF 2.0:

 

 

Prerequisites

This articles assumes that you are starting with an ADF application that has a menu, navigation, toolbar, and logout as per the Adding Navigation, Menu, Toolbar, and Logout to your ADF 2.0 App   article. You can either walkthrough this article first, or clone the source code as follows:

 

Martins-Macbook-Pro:ADF mbergljung$ git clone https://github.com/gravitonian/adf-workbench-nav20.git adf-workbench-process20

 

This clones the starter project within a new directory called adf-workbench-process20. Install all the packages for the project like this:

 

Martins-Macbook-Pro:ADF mbergljung$ cd adf-workbench-process20

Martins-Macbook-Pro:adf-workbench-process20 mbergljungnpm install

Martins-Macbook-Pro:adf-workbench-process20 mbergljungnpm dedup

 

The de-duplication (i.e. npm dedup) attempts to removes all duplicate packages by moving dependencies further up the tree, where they can be more effectively shared by multiple dependent packages

If you are just cloning the source code from the article, please remember that you must have Node.js 8 and Angular CLI 1.5.x already installed. If you don't, then resort to the linked article for information about how to install these tools.

Source Code

While walking through this article it is a good idea to have the source codeavailable. You can clone the source as follows:

 

Martins-Macbook-Pro:ADF mbergljung$ git clone https://github.com/gravitonian/adf-workbench-process20.git adf-workbench-process20-src

 

Listing Process Apps and Process Definitions

Now that we have the Angular app ready for ADF, and we can login to APS, it’s time to add some Process Services specific ADF components. Let’s start by building a Process Application view. Why do we do this? It is because when you work with processes in Alfresco Process Services (APS) they are all contained within applications.  You usually start by creating a Process App and then you define one or more process definitions and add them to it.

 

Generating the Process Apps module and page components

We are going to need a Process Apps parent page component. It will contain two child page components, one for the Process Apps List and one for the Process Apps Details page component. Plus a module to keep everything organized.

 

As usual, we can easily create a new module and the needed components with the Angular CLI tool:

 

Martins-MacBook-Pro:adf-workbench-process20 mbergljung$ ng g module process-apps --flat false --routing

  create src/app/process-apps/process-apps-routing.module.ts (254 bytes)

  create src/app/process-apps/process-apps.module.ts (300 bytes)

 

Martins-MacBook-Pro:adf-workbench-process20 mbergljung$ cd src/app/process-apps/

 

Martins-MacBook-Pro:process-apps mbergljung$ ng g component process-apps-page

  create src/app/process-apps/process-apps-page/process-apps-page.component.css (0 bytes)

  create src/app/process-apps/process-apps-page/process-apps-page.component.html (36 bytes)

  create src/app/process-apps/process-apps-page/process-apps-page.component.spec.ts (693 bytes)

  create src/app/process-apps/process-apps-page/process-apps-page.component.ts (311 bytes)

  update src/app/process-apps/process-apps.module.ts (416 bytes)

 

Martins-MacBook-Pro:process-apps mbergljung$ ng g component process-apps-list-page

  create src/app/process-apps/process-apps-list-page/process-apps-list-page.component.css (0 bytes)

  create src/app/process-apps/process-apps-list-page/process-apps-list-page.component.html (41 bytes)

  create src/app/process-apps/process-apps-list-page/process-apps-list-page.component.spec.ts (722 bytes)

  create src/app/process-apps/process-apps-list-page/process-apps-list-page.component.ts (330 bytes)

  update src/app/process-apps/process-apps.module.ts (552 bytes)

 

Martins-MacBook-Pro:process-apps mbergljung$ ng g component process-apps-details-page

  create src/app/process-apps/process-apps-details-page/process-apps-details-page.component.css (0 bytes)

  create src/app/process-apps/process-apps-details-page/process-apps-details-page.component.html (44 bytes)

  create src/app/process-apps/process-apps-details-page/process-apps-details-page.component.spec.ts (743 bytes)

  create src/app/process-apps/process-apps-details-page/process-apps-details-page.component.ts (342 bytes)

  update src/app/process-apps/process-apps.module.ts (700 bytes)

 

This creates a Process Apps module with routing, a Process Apps parent page, and a Process Apps list page component where we will display the available process applications. It also creates a Process Apps details page where we can display more detailed information for a specific process application.

 

We need to set up a new route configuration with a parent route that has two child routes for the list page and details page. Let’s add it in the src/app/process-apps/process-apps-routing.module.ts file as follows:

 

import { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';

import { ProcessAppsPageComponent } from './process-apps-page/process-apps-page.component';
import { ProcessAppsListPageComponent } from './process-apps-list-page/process-apps-list-page.component';
import { ProcessAppsDetailsPageComponent } from './process-apps-details-page/process-apps-details-page.component';

import { AuthGuardBpm } from '@alfresco/adf-core';

const routes: Routes = [ {
  path: 'process-apps',
  component: ProcessAppsPageComponent,
  canActivate: [AuthGuardBpm],
  data: {
    title: 'Process Apps',
    icon: 'apps',
    hidden: false,
    needBpmAuth: true,
    isLogin: false
  },
  children: [
    { path: '', component: ProcessAppsListPageComponent, canActivate: [AuthGuardBpm] },
    { path: ':process-app-id', component: ProcessAppsDetailsPageComponent, canActivate: [AuthGuardBpm] }
  ]
}];

@NgModule({
  imports: [RouterModule.forChild(routes)],
  exports: [RouterModule]
})
export class ProcessAppsRoutingModule { }

 

When we use the http://localhost:4200/process-apps URL we will hit the parent page component ProcessAppsPageComponent and as there is a child component ProcessAppsListPageComponent

 with empty path '' it will automatically be invoked and the process apps list displayed.

 

When one of the items in the process apps list is clicked, and we select a Details content action from the 'Three Dots' menu, then the http://localhost:4200/process-apps/<process-app-id> URL will be invoked taking the user to the ProcessAppsDetailsPageComponent.

 

If the data object properties are not familiar, then read the previous two articles mentioned in the introduction. They explain everything around these properties and the navigation system. 

 

The AuthGuardBpm ADF component makes sure that the route cannot be activated if the user is not authenticated with APS. Which leads us to make sure that the app is set up to authenticate with APS and only that backend service. Open the src/app/app-login/app-login-page/app-login-page.component.html template file and make sure the providers property is configured as follows:

 

<div fxFlex="100">
  <adf-login class="app-logo"
    [providers]="'BPM'"
    [copyrightText]="'© 2017 Alfresco Training.'"

Also, when we only login to the BPM server we need to change the function that gets the current user, it is currently getting the username from the ECM server session. Open up the src/app/app.component.ts file and update the getCurrentUser function as follows:

 

getCurrentUser() {
  return this.authService.getBpmUsername();
}

For these routes to be known to the Angular Router, and then indirectly to the AppMenuService, we need to import this module in the AppModule. Open the src/app/app.module.ts file and add as follows:

 

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

import { AppCommonModule } from './app-common/app-common.module';
import { AppLoginRoutingModule } from './app-login/app-login-routing.module';
import { AppLoginModule } from './app-login/app-login.module';
import { AppMenuService } from './app-menu/app-menu.service';

import { ProcessAppsModule } from './process-apps/process-apps.module';
import { ProcessAppsRoutingModule } from './process-apps/process-apps-routing.module';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,

    AppCommonModule,
    AppLoginModule,
    AppLoginRoutingModule,
    ProcessAppsModule,
    ProcessAppsRoutingModule
  ],
  providers: [AppMenuService],
  bootstrap: [AppComponent]
})
export class AppModule { }

 

Automatically route to the Process Apps List page after Login

First, start up the server as follows:

 

Martins-MacBook-Pro:adf-workbench-process20 mbergljung$ npm start

 

Then access the app at http://localhost:4200 and login to APS:

 

 

You should see the Process Apps menu item in the left Navigation Menu. Let's configure the login component to route to the Process Apps parent page directly after a successful login. Open up the src/app/app-login/app-login-page/app-login-page.component.ts file and uncomment the router code in the onLoginSuccess method and have it navigate to /process-apps:

 

onLoginSuccess($event) {
  console.log('Successful login: ' + $event.value);

  // Tell parent component that successful login has happened and menu should change
  this.menuService.fireMenuChanged();

  // Now, navigate somewhere...
  this.router.navigate(['/process-apps']);
}

 

However, it will not work just yet as there is no router outlet for the child page. This can be fixed by putting a router-outlet in the Process Apps parent page template. Open up the src/app/process-apps/process-apps-page/process-apps-page.component.html file and add it as follows:

 

<router-outlet></router-outlet>

 

If you now again logout and then login, you will see that the Process Apps List page is displayed automatically after a successful login:

 

 

Implementing the Process Apps List page

Now we can move on and implement the Process Apps List component that will provide a list of the applications that the logged in user has access to. Let’s start with the page template for the Process App list. Open up the src/app/process-apps/process-apps-list-page/process-apps-list-page.component.html file and replace whatever is there with the following:

 

<div class="process-apps-list-height">
  <adf-apps
    [layoutType]="'LIST'"
    [filtersAppId]="processAppsFilter"
    (appClick)="onAppClick($event)">

  </adf-apps>
</div>

 

Here we are configuring the page view to display a list of Process Applications with the ADF component <adf-apps. We enclose the Process Apps list in a div with a class that sets the height of the page so the left navigation menu will be visible even if there are no apps available, or just one. Add the CSS class to the src/app/process-apps/process-apps-list-page/process-apps-list-page.component.css file as follows:

 

.process-apps-list-height {
  height:900px;
}

 

The <