Load custom Javascript and CSS in Flowable Design

Flowable Design allows for runtime customization through client-defined custom.js and custom.css files. These files enable developers to enhance or adapt the behavior and appearance of the Flowable Design web application without modifying its core source code.

By placing these files in a predefined location, you can inject additional logic or styling, such as:

• Modifying or extending API requests and responses
• Overriding default backend endpoints
• Adding or modifying global configuration
• Registering custom utilities or event listeners
• Dynamically setting headers or tokens
• Applying custom styles and themes to the UI

---

Where to Place the Files

The files needs to be placed in the Flowable Design customization folder src/main/resources/static/custom/.

Both files will be automatically loaded at runtime before the application is initialized, ensuring your custom logic and styles are available early in the lifecycle.

---

warning

While custom.css can be loaded inline, advanced features in custom.js such endpoints configuration and the httpClientCustomConfiguration described in the following sections require it to be loaded as an external script. Inline scripts are executed too late in the application lifecycle to influence the setup of the HTTP client or API endpoints.

To load custom.js externally, make sure the inline-js property is set to false (which is the default value) in your deployment configuration.

You can find more information about this setting in the Design-specific properties section of the documentation.

HTTP Client Custom Configuration

It is possible to customize the HTTP client behavior used by the application through the httpClientCustomConfiguration extension point. Flowable Design uses fetchBaseQuery from RTK Query, which is a lightweight wrapper around the native fetch API.

To add a custom configuration to the HTTP client, you can define a function and assign it to the httpClientCustomConfiguration extension point in the custom.js file. This function receives the original fetchBaseQuery and allows you to return a modified version with additional logic - similar to how interceptors work in Axios.

For example, you can:

• Add custom headers to all outgoing requests
• Handle specific error codes (e.g., redirect on 401)
• Log or modify requests and responses
• Inject tokens or other context dynamically

In the example below, two custom behaviors are added:

• A custom header is injected into every request
• The response is checked for 401 Unauthorized, and the user is redirected to an external IDM

// custom.js

window.flowable = {
  httpClientCustomConfiguration(originalBaseQuery) {
    return async (args, api, extraOptions) => {
      // Add a custom header to each request
      if (!args.headers) {
        args.headers = new Headers(args.headers);
      }
      args.headers.set('X-Custom-Client-Header', 'my-value');

      // Execute the original base query
      const result = await originalBaseQuery(args, api, extraOptions);

      // Redirect to IDM on 401 response
      if (result.error?.status === 401) {
        window.location.href = 'https://idm.example.com/login';
      }

      return result;
    };
  }
}

Overriding Default API Endpoints

Flowable Design exposes a flexible way to override the default backend endpoints used by the application. This can be useful when integrating with custom backend services, API gateways, or proxy paths.

To override the default endpoints, you can define a custom endpoints object inside your custom.js file. This object allows you to selectively replace the default API paths used for key services such as authentication, logout, palette loading, and the design API itself.

Available Endpoint Keys

The following keys can be overridden:

• design: endpoint used for the main design API (e.g., models, workspaces)
• logout: endpoint called when the user logs out
• auth: authentication endpoint used during login
• palette: endpoint used to retrieve the palette configuration

// custom.js

export const endpoints = {
  design: 'design-api/custom',
  logout: 'logout/custom',
  auth: 'auth/custom',
  palette: 'palette/custom',
};