Skip to main content
Version: 2026 R1

Custom control (External)

The form field allows you to embed an external application on the Modern form. By using the JS API in the control you can manage the behavior of the whole form. The JS API script together with its documentation can be downloaded here. To ensure correct operation, the application run by the control must use communication protocol corresponding to the protocol of the form where it is embedded (https by default). The form field is available only for the processes run on the Modern form.

User control configuration depends on the code of the plugin – it is defined entirely by the plugin creator.

The purpose of this form field is to enable storing data from external controls in the BPS database – hosting of the control itself can also be performed within BPS.

Operation under an alternative application address

The control communicates with the form via postMessage, which requires the message to match the address (origin) of the form's window. For the control to work both in Portal and under an alternative application address, it must:

  1. use the webcon.min.1.1.0.js script or newer,
  2. not define the __WEBCON_PORTAL_ADDRESS__ variable in it – the control resolves the Portal address on its own.

Controls configured earlier with the __WEBCON_PORTAL_ADDRESS__ variable will only work under the address specified in that variable. After the application is published under an alternative address, the control's script must be updated.

The basic configuration is presented in the General form field configuration.

Advanced configuration​

To access additional configuration options, click the Advanced configuration button available in the bottom, right corner of the form field configuration window.

UserControl.png

1. Attribute name placement​

Dictates where the form field name is displayed. Available options:

  • Do not show,
  • Beside,
  • Above.

2. Mode​

  • External application - In this mode, provide a URL hosting the custom field. The control will display the content of the specified address inside an iframe. Ensure that the URL is valid and publicly accessible.
  • Local hosting at BPS - This mode allows you to upload a '.zip' file with the field content. A single file named index.html is required as the entry point. ll files will be hosted locally on the BPS portal. Files can be placed in subfolders, and the link to the associated file should be in the following format: "'folder_name/file_name' or './folder_name/file_name'. Prohibited file types are: bat, com, dll, exe, msc, msi, msp, mst, ps1, reg, regs

3. URL address​

The field allows you to enter an URL address.

4. File list​

Upload a '.zip' file with the field content for use in the Local hosting at BPS mode.

5. API​

To enable integration with User Defined API (API Definitions) use the API tab. This allows the control to communicate with endpoints defined in the API Definition. The list of available API definitions is limited to those that are active, have OAuth authentication enabled, and those that have been explicitly selected beforehand.