Version: 8.3

Custom request handler implemented using remote module

Level: advanced

The @creatio-devkit/common library includes a wide set of out-of-the-box request handlers that cover most event-handling requirements on Freedom UI pages. Learn more: handlers schema section. For business scenarios with more specific requirements — for example, implementing complex multi-step event logic or integrating with external services on user interaction — Creatio lets you implement custom request handlers and apply them directly to Freedom UI page elements.

Creatio lets you implement custom request handlers in the following ways:

Using the handlers schema section of the Freedom UI page. Examples: Freedom UI.
Using a remote module.

To implement a custom request handler using remote module, complete the following steps.

1. Create an Angular project

To create an Angular project to develop a custom request handler, follow the instructions: Create an Angular project.

2. Install npm packages

To install npm packages, follow the instructions: Install npm packages.

3. Create a custom request

Ensure the project includes the "AGENTS.md" file. Instructions: Create a custom Freedom UI component (step 1).
For Creatio version 8.3.4 and later, run the ng g class features/runtime/requests/some-request-name.request command in the Visual Studio Code terminal to create an Angular class in the project, where some-request-name.request is a custom class name. This adds the SomeRequestNameRequest class files to the "src/app/features/runtime/requests" project directory.

For Creatio version 8.3.3 and earlier
Run the ng g class some-request-name.request command in the Visual Studio Code terminal to create an Angular class in the project, where some-request-name.request is a custom class name. This adds the SomeRequestNameRequest class files to the "src/app" project directory.
Implement the request.
1. Open the "some-request-name.request.ts" file.
2. Inherit the BaseRequest class from the @creatio-devkit/common library.
3. Add the type and parameter of the request.
4. Import the required functionality from the libraries into the file.
5. Save the file.
"some-request-name.request.ts" file
```
/* Import the required functionality from the libraries. */
import { BaseRequest } from "@creatio-devkit/common";

export class SomeRequestNameRequest extends BaseRequest {
  /* The type and parameters of the request. */
  public someParameterName!: someParameterType;
}
```

4. Create a custom service

For Creatio version 8.3.4 and later, run the ng g class features/runtime/services/some-service-name.service command in the Visual Studio Code terminal to create an Angular class in the project, where some-service-name.service is a custom class name. This adds the SomeServiceNameService class files to the "src/app/features/runtime/services" project directory.

For Creatio version 8.3.3 and earlier
Run the ng g class some-service-name.service command in the Visual Studio Code terminal to create an Angular class in the project, where some-service-name.service is a custom class name. This adds the SomeServiceNameService class files to the "src/app" project directory.

Implement the service that receives data from an external web service.

Open the "some-service-name.service.ts" file.
Flag the SomeServiceNameService class using the @Injectable decorator.
Implement the someMethodName() method that receives data from an external web service.
Import the required functionality from the libraries into the file.
Save the file.

"some-service-name.service.ts" file
/* Import the required functionality from the libraries. */
import { Injectable } from "@angular/core";

@Injectable({
  providedIn: 'root',
})
export class SomeServiceNameService {
  /* Receive data from external web service. */
  public someMethodName(someParameterName: someParameterType): Promise<{
    someParameterName: Record<string, number>
  }> {
    /* Implement the business logic. */

    /* Return data from external web service. */
    return Promise.resolve({
      someParameterName: {
        /* Replace with actual data from the external web service. */
        'someParameterName': ''
      }
    });
  }
}

5. Create custom request handlers

Create a custom handler that displays data received from the external web service on the Freedom UI page.

Set up the Freedom UI page.

Repeat steps 1-5 of the instructions: Add the custom Freedom UI component to the Freedom UI page.

Add a SomeAttributeName attribute that stores data received from the external web service to the viewModelConfigDiff schema section.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    {
        "operation": "merge",
        "path": [
            "attributes"
        ],
        "values": {
            /* The attribute that stores data received from the external
            web service. */
            "SomeAttributeName": {}
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Bind the caption property of the corresponding component to the $SomeAttributeName model attribute in the viewConfigDiff schema section.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        "operation": "insert",
        "name": "SomeComponentName",
        "values": {
            /* Bind the SomeAttributeName attribute to the caption
            property. */
            "caption": "$SomeAttributeName",
        },
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Click Save.

For Creatio version 8.3.4 and later, run the ng g class features/runtime/request-handlers/some-handler-name.handler command in the Visual Studio Code terminal to create an Angular class in the project, where some-handler-name.handler is a custom class name. This adds the SomeHandlerNameHandler class files to the "src/app/features/runtime/request-handlers" project directory.

For Creatio version 8.3.3 and earlier
Run the ng g class some-handler-name.handler command in the Visual Studio Code terminal to create an Angular class in the project, where some-handler-name.handler is a custom class name. This adds the SomeHandlerNameHandler class files to the "src/app" project directory.

Implement the handler.

Open the "some-handler-name.handler.ts" file.
Add the configuration object that declares the request handler.
- Set the type property to usr.SomeHandlerNameHandler. The type property identifies the handler.
- Set the requestType property to crt.SomeRequestNameRequest. Creatio runs this handler when the crt.SomeRequestNameRequest request is sent.
Flag the SomeHandlerNameHandler class using the @CrtRequestHandler decorator.
Inherit the BaseRequestHandler class from the @creatio-devkit/common library.
Implement the handling of the request result.
Generate the value to display on the Freedom UI page.
Import the required functionality from the libraries into the file.
Save the file.

"some-handler-name.handler.ts" file
/* Import the required functionality from the libraries. */
import {
  BaseRequestHandler,
  CrtRequestHandler
} from "@creatio-devkit/common";
import {
  SomeServiceNameService
} from "../services/some-service-name.service";
import {
  SomeRequestNameRequest
} from "../requests/some-request-name.request";

/* Register the SomeHandlerNameHandler as a Freedom UI request handler. */
@CrtRequestHandler({
    type: 'usr.SomeHandlerNameHandler',
    requestType: 'crt.SomeRequestNameRequest',
  })

export class SomeHandlerNameHandler extends BaseRequestHandler {
  constructor(private _someServiceNameService: SomeServiceNameService) {
    super();
  }
  public async handle(request: SomeRequestNameRequest): Promise<unknown> {
    const result = await this._someServiceNameService
      .someMethodName(request.someParameterName);
    const someParameter1Name =
      result.someParameterName[request.someParameterName] ?? 0;
    /* Generate the value to display on the Freedom UI page. */
    request.$context['SomeAttributeName'] = someParameter1Name;
    return someParameter1Name;
  }
}

Create a custom handler that is executed when Creatio initializes a Freedom UI page.
1. For Creatio version 8.3.4 and later, run the ng g class features/runtime/request-handlers/some-page-init-handler-name.handler command in the Visual Studio Code terminal to create an Angular class in the project, where some-page-init-handler-name.handler is a custom class name. This adds the SomePageInitHandlerHandler class files to the "src/app/features/runtime/request-handlers" project directory.
  
  For Creatio version 8.3.3 and earlier
  Run the ng g class some-page-init-handler-name.handler command in the Visual Studio Code terminal to create an Angular class in the project, where some-page-init-handler-name.handler is a custom class name. This adds the SomePageInitHandlerHandler class files to the "src/app" project directory.
2. Implement the handler.
  1. Open the "some-page-init-handler-name.handler.ts" file.
  2. Add the configuration object that declares the request handler.
    - Set the type property to usr.SomePageInitHandlerHandler.
    - Set the requestType property to crt.HandleViewModelInitRequest.
    - Set the scopes property to the code of the Freedom UI page. The request handler is executed when Creatio initializes the Freedom UI page that has the specified code. If the property is empty or missing, it is a global handler that Creatio executes on all Freedom UI pages.
  3. Flag the SomePageInitHandlerHandler class using the @CrtRequestHandler decorator.
  4. Inherit the BaseRequestHandler class from the @creatio-devkit/common library.
  5. Implement the update of data received from the external web service when Creatio initializes the Freedom UI page.
  6. Import the required functionality from the libraries into the file.
  7. Save the file.
  "some-page-init-handler-name.handler.ts" file
```
/* Import the required functionality from the libraries. */
import {
  BaseRequest,
  BaseRequestHandler,
  CrtRequestHandler,
  HandlerChainService
} from "@creatio-devkit/common";
import {
  SomeRequestNameRequest
} from "../requests/some-request-name.request";

/* Register the SomePageInitHandlerHandler as a Freedom UI request handler. */
@CrtRequestHandler({
  type: 'usr.SomePageInitHandlerHandler',
  requestType: 'crt.HandleViewModelInitRequest',
  scopes: ['CodeOfSomeFreedomUIPage'],
})

export class SomePageInitHandlerHandler extends BaseRequestHandler {
  public async handle(request: BaseRequest): Promise<unknown> {
    /* Update data received from the external web service when Creatio
    initializes the Freedom UI page. */
    await HandlerChainService.instance.process({
      type: 'crt.SomeRequestNameRequest',
      someParameterName: 'someParameterValue',
      $context: request.$context
    } as SomeRequestNameRequest);

    return this.next?.handle(request);
  }
}
```

Register the handlers.

For Creatio version 8.3.4 and later, the template already contains the runtime feature activation and bootstrapCrtModule() call. Extend the existing runtime feature files to register the request handlers.

Open the "runtime-feature.module.ts" file.

Add the SomeHandlerNameHandler and SomePageInitHandlerHandler handlers to the requestHandlers section in the @CrtModule decorator.

"runtime-feature.module.ts" file
/* Import the required functionality from the libraries. */
import { ApplicationRef, DoBootstrap, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CrtModule } from '@creatio-devkit/common';
import {
  SomeHandlerNameHandler
} from './request-handlers/some-handler-name.handler';
import {
  SomePageInitHandlerHandler
} from './request-handlers/some-page-init-handler-name.handler';

@CrtModule({
  requestHandlers: [
    SomeHandlerNameHandler,
    SomePageInitHandlerHandler
  ],
})
@NgModule({
  declarations: [],
  imports: [BrowserModule],
})
export class RuntimeFeatureModule implements DoBootstrap {
  ngDoBootstrap(_appRef: ApplicationRef): void {}
}

Open the "runtime.feature-definition.ts" file.

Add the public type property of the handlers to the discovery.requestHandlers section.

"runtime.feature-definition.ts" file
/* Import the required functionality from the libraries. */
import type {
  RemoteDesignerDefinitionsLoadContext,
  RemoteFeatureDefinition
} from '@creatio-devkit/common';

export const runtimeFeatureDefinition = {
  id: 'some-package-name-runtime',
  discovery: {
    viewElements: [],
    mobileViewElements: [],
    requestHandlers: [
      {
        type: 'usr.SomeHandlerNameHandler',
        requestType: 'crt.SomeRequestNameRequest',
        scopes: ['CodeOfSomeFreedomUIPage']
      },
      {
        type: 'usr.SomePageInitHandlerHandler',
        requestType: 'crt.HandleViewModelInitRequest',
        scopes: ['CodeOfSomeFreedomUIPage']
      }
    ],
  },
  loadDesignerDefinitions: (context: RemoteDesignerDefinitionsLoadContext) =>
    import('./runtime.designer-definitions').then(
      (m) => m.loadRuntimeDesignerDefinitions(context)),
  activate: () =>
    import('./runtime.feature-activation').then(
      (m) => m.activateRuntimeFeature()),
} satisfies RemoteFeatureDefinition;

Import the required functionality from the libraries into the files.
Save the files.

For Creatio version 8.3.3 and earlier

Register the handlers in the AppModule root module.

Open the "app.module.ts" file.
Add the SomeHandlerNameHandler and SomePageInitHandlerHandler handlers to the requestHandlers section in the @CrtModule decorator.
Import the required functionality from the libraries into the file.
Save the file.

"app.module.ts" file
/* Import the required functionality from the libraries. */
import { DoBootstrap, Injector, NgModule, ProviderToken } from '@angular/core';
import { bootstrapCrtModule, CrtModule } from '@creatio-devkit/common';
import { BrowserModule } from '@angular/platform-browser';
import { SomeHandlerNameHandler } from './some-handler-name.handler';
import { SomePageInitHandlerHandler } from './some-page-init-handler-name.handler';

@CrtModule({
  /* Specify that SomeHandlerNameHandler and SomePageInitHandlerHandler are request handlers. */
  requestHandlers: [
    SomeHandlerNameHandler,
    SomePageInitHandlerHandler
  ],
})
@NgModule({
  declarations: [],
  imports: [BrowserModule],
  providers: [],
})
export class AppModule implements DoBootstrap {
  constructor(private _injector: Injector) {}

  ngDoBootstrap(): void {

    /* Bootstrap CrtModule definitions. */
    bootstrapCrtModule('some-package-name', AppModule, {
        resolveDependency: (token) => this._injector.get(<ProviderToken<unknown>>token)
    });
  }
}

Run the npm run build command in the Visual Studio Code terminal to build the project.

As a result, the build will be added to the "dist" directory of the Angular project.

6. Add the request to the Freedom UI page

Repeat steps 1-5 of the instructions: Add the custom Freedom UI component to the Freedom UI page.

Bind the button click event to the custom request in the viewConfigDiff schema section.

Enter the request name in the request property.
Enter the configuration object of parameters in the params property.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    {
        "operation": "insert",
        "name": "SomeButtonName",
        "values": {
            "clicked": {
                /* Bind the sending of the custom request to the button click event. */
                "request": "crt.SomeRequestNameRequest",
                "params": {
                    "someParameterName": "someParameterValue"
                }
            }
        },
    },
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Click Save.

As a result, the custom request handler will be added to the Freedom UI page. When an event initiates a request, the related handler is executed.

Resources

Remote module template (for Creatio version 8.3.4 and later)

Remote module template (for Creatio version 8.3.3 and earlier)

1. Create an Angular project​

2. Install npm packages​

3. Create a custom request​

4. Create a custom service​

5. Create custom request handlers​

6. Add the request to the Freedom UI page​

See also​

Resources​