Breaking changes: Starting with version 4.0 the ui-sdk will no longer expect the authToken to be present in the LOCAL_STORAGE. Instead, the authToken will be passed as an input to the flx-process-renderer component. This is mandatory for the SSE to work properly.

Prerequisites

  • Node.js min version 18 - Download Node.js
  • Angular CLI version 17. Install Angular CLI globally using the following command:
npm install -g @angular/cli

This will allow you to run ng related commands from the terminal.

Angular project requirements

Your app MUST be created using the NG app from the @angular/cli~17 package. It also MUST use SCSS for styling.

npm install -g @angular/cli@17
ng new my-flowx-app

To install the npm libraries provided by FLOWX you will need to obtain access to the private FLOWX Nexus registry. Please consult with your project DevOps.

The library uses Angular version @angular~18, npm v10.8.0 and node v18.20.4.

If you are using an older version of Angular (for example, v16), please consult the following link for update instructions:

Update Angular from v16.0 to v17.0

Installing the library

Use the following command to install the renderer library and its required dependencies:

npm install \
  @flowx/ui-sdk@5.9.8 \
  @flowx/ui-toolkit@5.9.8 \
  @flowx/ui-theme@5.9.8 \
  vanillajs-datepicker@1.3.4 \
  @angular/flex-layout@15.0.0-beta.42 \
  @angular/cdk@17.3.9 \
  ng2-pdfjs-viewer@17.0.3 \
  date-fns \
  inputmask
  

A few configurations are needed in the projects angular.json:

  • in order to successfully link the pdf viewer, add the following declaration in the assets property:
{
  "glob": "**/*",
  "input": "node_modules/ng2-pdfjs-viewer/pdfjs",
  "output": "/assets/pdfjs"
}

Initial setup

Once installed, FlxProcessModule will be imported in the AppModule as FlxProcessModule.forRoot({}).

You MUST also import the dependencies of FlxProcessModule: HttpClientModule from @angular/common/http.

Theming

Component theming is done through the @flowx/ui-theme library. The theme id is a required input for the renderer SDK component and is used to fetch the theme configuration. The id can be obtained from the admin panel in the themes section.

Authorization

Every request from the FlowX renderer SDK will be made using the HttpClientModule of the client app, which means those requests will go through every interceptor you define here. This is most important to know when building the auth method as it will be the job of the client app to intercept and decorate the requests with the necessary auth info (eg. Authorziation: Bearer ...).

It’s the responsibility of the client app to implement the authorization flow (using the OpenID Connect standard). The renderer SDK will expect the authToken to be passed to the flx-process-renderer as an input.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';
import { FlxProcessModule } from '@flowx/ui-sdk';
import {AppRoutingModule} from './app-routing.module';
import {AppComponent} from './app.component';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    // will be used by the renderer SDK to make requests
    HttpClientModule,
    // needed by the renderer SDK
    FlxProcessModule.forRoot({
      components: {},
      services: {},
    }),
  ],
  // this interceptor with decorate the requests with the Authorization header
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

The forRoot() call is required in the application module where the process will be rendered. The forRoot() method accepts a config argument where you can pass extra config info, register a custom component, service, or custom validators.

Custom components will be referenced by name when creating the template config for a user task.

Custom validators will be referenced by name (currentOrLastYear) in the template config panel in the validators section of each generated form field.

// example with custom component and custom validator
FlxProcessModule.forRoot({
  components: {
    YourCustomComponentIdenfier: CustomComponentInstance,
  },
  services: {
    NomenclatorService,
    LocalDataStoreService,
  },
  validators: {currentOrLastYear },
})

  // example of a custom validator that restricts data selection to 
  // the current or the previous year 
   
  currentOrLastYear: function currentOrLastYear(AC: AbstractControl): { [key: string]: any } {
    if (!AC) {
      return null;
    }

    const yearDate = moment(AC.value, YEAR_FORMAT, true);
    const currentDateYear = moment(new Date()).startOf('year');
    const lastYear = moment(new Date()).subtract(1, 'year').startOf('year');

    if (!yearDate.isSame(currentDateYear) && !yearDate.isSame(lastYear)) {
      return { currentOrLastYear: true };
    }

    return null;
  }

The error that the validator returns MUST match the validator name.

The entry point of the library is the <flx-process-renderer></flx-process-renderer> component. A list of accepted inputs is found below:

<flx-process-renderer
  [apiUrl]="baseApiUrl"
  [processApiPath]="processApiPath"
  [authToken]="authToken"
  [themeId]="themeId"
  [processName]="processName"
  [processStartData]="processStartData"
  [debugLogs]="debugLogs"
  [keepState]="keepState"
  [language]="language"
  [httpVersion]="httpVersion"
></flx-process-renderer>

Parameters:

NameDescriptionTypeMandatoryDefault valueExample
apiUrlYour base urlstringtrue-https://yourDomain.dev
processApiPathProcess subpathstringtrue-onboarding
authTokenAuthorization tokenstringtrue-‘eyJhbGciOiJSUzI1NiIsIn…‘
themeIdTheme id used to style the process. Can be obtained from the themes section in the adminstringtrue-‘123-456-789’
processNameIdentifies a processstringtrue-client_identification
processStartDataData required to start the processjsontrue-{ "firstName": "John", "lastName": "Smith"}
debugLogsWhen set to true this will print WS messages in the consolebooleanfalsefalse-
languageLanguage used to localize the application.stringfalsero-RO-
keepState

By default all process data is reset when the process renderer component gets destroyed. Setting this to true will keep process data even if the viewport gets destroyed

booleanfalsefalse-
isDraftWhen true allows starting a process in draft state. *Note that isDraft = true requires that processName be the id (number) of the process and NOT the name.booleanfalsefalse-
legacyHttpVersionSet this to true only for HTTP versions < 2 in order for SSE to work properly. Can be omitted otherwise.booleanfalsefalse-

Data and actions

Custom components will be hydrated with data through the $data input observable which must be defined in the custom component class.


@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
  styleUrls: ['./custom-component.component.scss'],
})
export class CustomComponentComponent  {
  @Input() data$: Observable<any>;
  }

Component actions are always found under data -> actionsFn key.

Action names are configurable via the process editor.

# data object example
data: {
   actionsFn: {
      action_one: () => void;
      action_two: () => void; }
   }

Interacting with the process

Data from the process is communicated via Server Send Event protocol under the following keys:

NameDescriptionExample
Datadata updates for process model bound to default/custom components
ProcessMetadataupdates about process metadata, ex: progress update, data about how to render components
RunActioninstructs the UI to perform the given action

Task management component

The flx-task-management component is found in the FlxTaskManagementModule. In order to have access to it, import the module where needed:

import {FlxProcessModule} from '@flowx/ui-sdk';
@NgModule({
  declarations: [
    ...,
  ],
  imports: [
    ...,
    FlxTaskManagementModule
  ],
  
})
export class MyModule {}

Then in the template:

<flx-task-management 
  [apiUrl]="baseApiUrl"
  [authToken]="authToken" 
  [title]="'Tasks'">
</flx-task-management>

Parameters:

NameDescriptionTypeDefaultMandatoryExample
apiUrlEndpoint where the tasks are availablestring-truehttps://yourDomain.dev/tasks
authTokenAuthorization tokenstring-true
titleTable header valuestringActivitiesfalseTasks
pollingIntervalInterval for polling task updatesnumber5000 msfalse10000

For basic styling to work the following configuration is needed in the angular.json file:

"stylePreprocessorOptions": {
  "includePaths": [
    "./node_modules/@flowx/ui-sdk/src/assets/scss"
  ...
},

Development

If you want to start the designer app and the flx-process-renderer library in development mode (no need to recompile the lib for every change) run the following command:

npm run start:designer

When modifying the library source code and testing it inside the designer app use the following command which rebuilds the libraries, recreates the link between the library and the designer app and recompiles the designer app:

./start_with_build_lib.sh

Remember to test the final version of the code by building and bundling the renderer library to check that everything works e2e.

Trying to use this lib with npm link from another app will most probably fail. If (when) that happens, there are two alternatives that you can use:

  1. Use the build-and-sync.sh script, that builds the lib, removes the current build from the client app node_modules and copies they newly build lib to the node_modules dir of the client app:
./build-and-sync.sh ${path to the client app root}

# example (the client app is demo-web):
./build-and-sync.sh ../../demo-web

NOTE: This method uses under the hood the build-and-sync.sh script from the first version and the chokidar-cli library to detect file changes.

  1. Use the build-and-sync:watch npm script, that builds the library and copies it to the client app’s node_module directory every time a file changes:
npm run build-and-sync:watch --target-path=${path to the client app root}

# example (the client app is demo-web):
npm run build-and-sync:watch --target-path=../../demo-web

Running the tests

ng test

Coding style tests

Always follow the Angular official coding styles.

Below you will find a Storybook which will demonstrate how components behave under different states, props, and conditions, it allows you to preview and interact with individual UI components in isolation, without the need for a full-fledged application:

Storybook