React SDK

​

React project requirements

Your app MUST use SCSS for styling.

​

Installing the library

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

npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32

​

Initial setup

Once installed, FlxProcessRenderer will be imported in the from the @flowx/react-sdk package.

​

Theming

Component theming is done through the @flowx/react-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

import { FlxProcessRenderer } from '@flowx/react-sdk';


export function MyFlxContainer() {
    return <FlxProcessRenderer
        apiUrl={'your API url'}
        language={...}
        authToken={...}
        processName={...}
        processStartData={...}
        processApiPath={...}
        themeId="12345678-1234-1234-1234-123456789012"
        staticAssetsPath={...}
        locale="en-US"
        language="en"
        appInfo={
          appId: ...
        }
        buildId={...}
      />
}

The FlxProcessRenderer component is required in the application module where the process will be rendered. The component accepts a props where you can pass extra config info, register a custom component 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 (customValidator) in the template config panel in the validators section of each generated form field.

import { FlxProcessRenderer } from '@flowx/react-sdk';


export function MyFlxContainer() {
    return <FlxProcessRenderer
        apiUrl={'your API url'}
        language={...}
        authToken={...}
        processName={...}
        processStartData={...}
        processApiPath={...}
        themeId="12345678-1234-1234-1234-123456789012"
        components={{ MyCustomComponentIdentifier: MyCustomComponent }}
        validators={{ customValidator: (...params: string[]) => (v: string) => v === '4.5'}}
        staticAssetsPath={...}
        locale="en-US"
        language="en"
        appInfo={{
          appId: ...
        }}
        buildId={...}
      />
}

The entry point of the library is the <FlxProcessRenderer /> component. A list of accepted inputs is found below:

<FlxProcessRenderer
    apiUrl={apiUrl}
    language={language}
    authToken={authToken}
    processName={processName}
    processStartData={processStartData}
    processApiPath={apiPath}
    themeId={themeId}
    components={customComponents}
    validators={validators}
    staticAssetsPath={assetsPath}
    locale={locale}
    language={language}
    appInfo={appInfo}
    buildId={buildId}
    />

Parameters:

​

Starting a process

​

Prerequisites

• Process Name: You need to know the name of the process you want to start. This name is used to identify the process in the system.

• FlowX Application UUID: You need the UUID of the FlowX Application that contains the process you want to start. This UUID is used to identify the application in the system.

• Locale: You can specify the locale of the process to apply date, currency, and number formatting to data model values.

• Language: You can specify the language used to localize the enumerations inside the application.

​

Getting the application UUID

The application UUID can be obtained from the FlowX Dashboard. Navigate to the Applications section and select the application you want to start a process in. The UUID can be copied from the application actions popover.

​

Getting the process name

The process name can be obtained from the FlowX Designer. Navigate to the process you want to start and copy the process name from the breadcrumbs.

​

Initializing the process renderer

To start a process, you need to initialize the FlxProcessRenderer component in your application. The component accepts various props that define the process to start, the theme to use, and other configuration options.

import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        {...props}
        locale="en-US"
        language="en"
        processName={processName}
        appInfo={{ appId }}
        buildId={buildId}
      />
}

​

Custom components

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

Custom components will be provided through the components parameter to the <FlxProcessRenderer /> component.

export const MyCustomComponent = ( {data }) => {...}

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

To add a custom component in the template config tree, we need to know its unique identifier and the data it should receive from the process model.

The properties that can be configured are as follows:

• Identifier - This enables the custom component to be displayed within the component hierarchy and determines the actions available for the component.
• Input keys - These are used to specify the pathway to the process data that components will utilize to receive their information.
• UI Actions - actions defined here will be made available to the custom component

​

Prerequisites (before creation)

• React Knowledge: You should have a good understanding of React, as custom components are created and imported using React.

• Development Environment: Set up a development environment for React development, including Node.js and npm (Node Package Manager).

• Component Identifier: You need a unique identifier for your custom component. This identifier is used for referencing the component within the application.

​

Creating a custom component

To create a Custom Component in React, follow these steps:

1. Create a new React component.
2. Implement the necessary HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior of your custom component.

​

Importing the component

After creating the Custom Component, you need to import it into your application.

In your <FlxProcessRenderer /> component, add the following property:

<FlxProcessRenderer
  {...otherProps}
  components={{ MyCustomComponentIdentifier: MyCustomComponent }}
/>

​

Using the custom component

Once your Custom Component is declared, you can use it for configuration within your application.

​

Data input and actions

The Custom Component accepts input data from processes and can also include actions extracted from a process. These inputs and actions allow you to configure and interact with the component dynamically.

​

Extracting data from processes

There are multiple ways to extract data from processes to use within your Custom Component. You can utilize the data provided by the process or map actions from the BPMN process to Angular actions within your component.

​

Styling with CSS

To apply CSS classes to UI elements within your Custom Component, you first need to identify the UI element identifiers within your component’s HTML structure. Once identified, you can apply defined CSS classes to style these elements as desired.

Example:

​

Additional considerations

• Naming Conventions: Be consistent with naming conventions for components, identifiers, and actions. Ensure that Angular actions match the names of process actions as mentioned in the documentation.

• Component Hierarchy: Understand how the component fits into the overall component hierarchy of your application. This will help determine where the component is displayed and what actions are available for it.

• Documentation and Testing: Document your custom component thoroughly for future reference. Additionally, testing is crucial to ensure that the component behaves as expected in various scenarios.

• Security: If your custom component interacts with sensitive data or performs critical actions, consider security measures to protect the application from potential vulnerabilities.

• Integration with FLOWX Designer: Ensure that your custom component integrates seamlessly with FLOWX Designer, as it is part of the application’s process modeling capabilities.

​

Custom validators

You may also define custom validators in your FlowX processes and pass their implementation through the validators prop of the <FlxProcessRenderer /> component.

The validators are then processed and piped through the popular React Hook Form library, taking into account how the error messages are defined in your process.

A validator must have the following type:

const customValidator = (...params: string[]) => (v: any) => boolean | Promise<boolean> 

​

Custom CSS

The renderer SDK allows you to pass custom CSS classes on any component inside the process. These classes are then applied to the component’s root element.

To add a CSS custom class to a component, you need to define the class in the process designer by navigating to the styles tab of the component, expanding the Advanced accordion and writing down the CSS class.