Application and configuration of Public Forms

Applies to version: 2024 R1 and above; author: Łukasz Chechelski

Introduction

The Public Forms mechanism is an interesting solution that allows you to create external forms whose main advantage is anonymity. The site built in this way communicates with WEBCON BPS via the REST standard, creating new instances in specific processes. It is important to note that the mechanism is available for free on GitHub under the MIT license.

Public Forms can be installed in one of three ways:

• IIS
• Azure App Service
• Docker container

This article focuses on the first option – direct installation in IIS. The described scenario assumes the preparation of an external site that will allow potential clients to request contact for more detailed information. The functionality prepared in this way will be able to be embedded into the site as an IFrame.

Fig. 1. Diagram showing the communication between Public Forms and WEBCON BPS

For security reasons we recommend to install Public Forms on a different machine than the one where the BPS application server is installed.

Installation

First, download Public Forms from the official GitHub account, available at: WEBCON bps GitHub. On the main page you will find the source code, which you can use for your own development of the solution. The compiled package is located in the right panel. You should download the latest version.

Fig. 2. Download the archive from the highlighted link – not the source code!

The archive should be extracted to a previously created folder on the server. Since this is a .NET-based application, it will be necessary to create an appropriate application pool. At this point, it is advisable to add folder permissions for the account in whose context the application will run.  Change, Read, and Write level permissions are required.

Fig. 3. Permissions assigned to the application pool account

The next step is to configure it in IIS Manager, where you need to select Application Pools in the left panel and then create a new application pool. You can give it any name you like.

Fig. 4. Dialog box of the created application pool

In the advanced configuration of the created pool you should update the data of the account under which the pool operates. In the field shown in Fig. 5, specify the account that has been given permissions to access the Public Forms folder.

Fig. 5. Updated details of the application pool account

With the application pool prepared, create a new site. Right-clicking Sites displays the option to add a new site. You can give your site any name you like. It is important to correctly point to the created application pool and the physical path where the Public Forms mechanism was extracted. Proper addressing configuration in the Binding tab is also crucial.

Fig. 6. Example configuration of a created site

Communication with WEBCON BPS

The created site communicates with WEBCON BPS via REST API. This requires proper preparation of the API application on the BPS side. While on the Portal page, go to the Administration tab available by clicking on the user's avatar. After navigating to the Integrations tab, create a new application. The connection will be made in the context of the application. Note that the login of the created application must be in the form of a BPS ID.

Fig. 7. API application data

After saving the configuration, it is possible to generate the client secret. It is necessary for correct authentication and authorization of communication through BPS API.

Note: Once the secret is generated, it is not possible to preview it again. It is recommended to save it in a safe place.

Fig. 8. Secret generation window

In the same window you can specify permissions for the created application. Permissions work on a similar basis to those of registered applications in the Azure portal. When connecting to the BPS in the context of a given application, it will be possible to perform only those operations that are allowed by the scope of permissions. At least the following permissions are required to start new workflow instances:

• App.Metadata.Read – reading the configuration data of applications and processes. Additional permissions are required for each applications being read.
• App.Elements.ReadWrite.All – reading, starting new, and editing workflow instances in all processes (form data, attachments, metadata). Additional permissions of the appropriate type are required at the instance level.
• Admin.BusinessEntities.Read – reading business entity data.

After saving, add permissions for the application at the process level so that it can start new instances. It will be available in the search engine, just like access groups or users. Access to metadata will allow you to list the available form fields when configuring Public Forms.

Fig. 9. Preview of application level permissions

Process-level permissions, on the other hand, allow new instances to be started via the BPS REST API.

Fig. 10. Preview of process level permissions

Since the communication takes place in the context of the user, a license must be assigned to the user to allow the instance to be started. In BPS Designer Studio, go to System settings and then to the Licenses allocation. This is where the license is assigned for each user.

Public Forms – connection configuration

To communicate with WEBCON BPS, the Public Forms mechanism uses data contained in variables embedded in IIS. In the IIS Manager, select Configuration Editor from the main node and indicate the appropriate section. The variables must be entered in the environmentVariables field. The following list contains the variables to add:

• APP_ADMIN_LOGIN – login that allows you to log in to the Public Forms administration panel,
• APP_ADMIN_PASSWORD – password for the above account,
• APP_BASE_DOMAIN – domain address, e.g. publicforms.example.com,
• APP_BPS_PORTAL_URL – Portal URL,
• APP_BPS_PORTAL_CLIENT_ID – ID of the application created in the Admin panel in Portal,
• APP_BPS_PORTAL_CLIENT_SECRET – secret generated in the Admin panel for the application,
• APP_BPS_PORTAL_DB_ ID – ID of the BPS content database. The default value is 1.

Fig. 11. Entering environment variables

After entering and saving the data, it is recommended to recycle the pool on which Public Forms is running.

Start and configuration of the form

The next step is to prepare the form. When you open the Public Forms site, you will see a login window. Authentication takes place after entering the login data set in the variables. The administration panel is displayed, where it is possible to create a new public form. After clicking the Add button, the form creation wizard will appear. Based on the permissions granted to the API application, the system will return a list of processes and form fields.

Fig. 12. Form configuration

In addition, it is possible to visually improve the design of the created form using graphical elements and CSS.

Fig. 13. Configuration of displayed information

At the bottom of the configuration screen there is a list of form fields taken from the selected process.

Fig. 14. List of form fields

The configuration page also offers the possibility to preview the form before final saving. After saving, the system will generate an IFrame code with a link to the created site. We can embed the created form in any page. Note, however, that a connection to the BPS application server is required for proper operation.

Fig. 15. Generated form

Filling in the fields and going through the path will start the instance in the workflow specified in the configuration. The previously configured API application account will appear as the author.

Fig. 16. Workflow instance started based on Public Forms

Note, however, that the Public Forms solution hosted on GITHub has several limitations:

• no ability to upload an attachment,
• no support for dictionary fields based on a source other than a fixed list of values,
• no support for Item lists.

Summary

Public Forms is a quick to configure tool that allows you to easily create dedicated forms integrated with WEBCON BPS. Thanks to anonymity, it is ideal for supporting complaint, survey or contact workflows. The tool is provided free of charge under the MIT license, so you can develop it yourself. This is also possible within the scope of WEBCON's services.