Configuring hyperlinks in process grids or data grids
In v10, hyperlinks in process and data grids have to be manually set up on the back-end side of the application. When the configuration is done, hyperlinks appear in a column of the grid with the following font: hyperlink. In data grids, there are two types of hyperlinks: redirection hyperlinks (links that take the user to a different place) or document download hyperlink (links that download an attached document when clicked). This article describes the configuration of both types of hyperlinks.
Prerequisite
The column of the process grid or the data grid in which the hyperlink is displayed must be of type NVARCHAR. If the column is configured to any other data type, then errors will be visible in the UI of the v10 application, particularly when attempting to filter on values in this column.
Configuring a redirection hyperlink
The configuration of hyperlinks in process and data grids is done on field level via the k_referential_grids_fields table in the database.
The following table describes the fields in this table used for hyperlink definition:
| Parameter | Value |
|---|---|
| hyperlink_enabled | BIT (default value is false) |
| hyperlink_id_display_field (optional) | FK k_referential_tables_views_fields |
| hyperlink_default_display_text | NVARCHAR (MAX) NULL |
| hyperlink_type | TINYINT:
|
Enabling hyperlinks
To enable hyperlinks in a given data or process grid field in the Web App, the hyperlink_enabled parameter in the k_referential_grids_fields table must be set to TRUE.
This is an note/information message.
Hyperlinks are always in read-only mode.
Defining the hyperlink type
To define the type of hyperlink in order to use a redirection hyperlink, proceed as follows:
In k_referential_grids_fields, set the hyperlink_type parameter to 1 for the column in which you want the download link to be displayed in the data grid.
Defining the default label for the hyperlinks
The hyperlink_default_display_text parameter enables you to customize the label of the hyperlink displayed in the application rather than having the entire URL displayed.
This is an note/information message.
You can only set one label per grid (e.g. "Click here").
To define the default label for the hyperlinks in the grid, enter the text that you want to use as the display name in the hyperlink_default_display_text column.
Defining the reference column for the hyperlinks
In addition to the custom label, a reference column for the hyperlink can be set up. With this feature you will be able to fetch a link displayed in another grid. That reference column must exists in the table view of the related grid. The relation between the hyperlink and the reference column is done through the hyperlink_id_display_field parameter that must inform the ID of the table view field.
In the case that the hyperlink_id_display_field value is empty or NULL, the hyperlink value will take by default the one chosen for the hyperlink_default_display_text parameter.
Configuration examples
To illustrate the configuration outlined in the above sections, we will take as example the three following types of hyperlink configuration.
Hyperlink configuration examples
There are three possible configuration case scenarios:
The hyperlink parameter is enabled in a grid field, but the hyperlink_default_display_text parameter is NULL. In this case, the hyperlink is displayed as an URL.
The hyperlink parameter is enabled in a grid field and the hyperlink_default_display_text parameter is configured with the value "Click Here". The entered label is then clickable and redirects the user to the provided URL.
A reference column is configured; in this case, the relation between the hyperlink and the reference column is defined using the hyperlink_id_display_field parameter that must inform the ID of the table view field.
Working with hyperlinks in grids
The following table details various behaviors when using grid features if a hyperlink column is configured in the grid.
| Grid Feature | Behavior |
|---|---|
| Sort | Sorting a grid by hyperlink column is possible if the hyperlink_default_display_text parameter parameter is configured with a label. |
| Filter | Filtering a grid by hyperlink column is possible if the hyperlink_default_display_text parameter parameter is configured with a label. |
| Add new row | When adding a new row in a grid configured with a hyperlink column, the column is always in read-only mode. |
| Excel export/import | When exporting/importing a grid with a hyperlink column, the column is always read-only in the Excel file, and the hyperlink is always displayed as an URL. |
Possible error scenarios
The following error cases can occur:
Missing URL: the display value is shown but without any hyperlink
Missing display value: only the URL is displayed
Missing URL and display value: nothing is displayed
The reference column doesn't exist: an exception is returned when loading the grid and blocks the method
Configuring a document download hyperlink
This section describes the procedure to be followed in order to configure a document download link from a data grid. This feature, enables document owners to download their documents directly from a link in a data grid column. For this configuration to work properly, the following requirement must be met:
Documents have already been generated using the subscription service and are available in the rps_file. The download document feature supports all types of documents (PDF, Word, Excel, etc.).
A dedicated NVARCHAR column exists in the data grid for the document download hyperlink.
This is an note/information message.
The operations described herein must be performed in the beqom database; no user interface exists to configure the feature.
Roadmap
To configure the download document feature in a data grid, follow the roadmap outlined below:
| Step # | Description | Comment |
|---|---|---|
| 1. | Create a new column in the data grid in which you want to insert the document. Set this column as NVARCHAR type. | This step is not described herein. |
| 2. | Enable the hyperlink feature for the data grid column. | |
| 3. | Define the hyperlink type to document download. | |
| 4. | Define the display name of the download link in the data grid. | |
| 5. | Generate the documents using the subscription service. | This step is not described herein. |
| 6. | Link generated documents to the field in the data grid. |
Enabling the hyperlink feature for a data grid
To enable the hyperlink feature for a data grid, proceed as follows:
In k_referential_grids_fields, set the hyperlink_enabled parameter to true for the column in which you want the download link to be displayed in the data grid.
Defining the hyperlink type
To define the type of hyperlink in order to use the document download feature, proceed as follows:
In k_referential_grids_fields, set the hyperlink_type parameter to 2 for the column in which you want the download link to be displayed in the data grid.
Defining the display name of the download link in the grid
Once you have defined set a column as a hyperlink and have defined the right type of hyperlink, you need to define how the download link will be displayed in the Web Application interface of the beqom application. There are two possible options to do this
Define a static name: in k_referential_grids_fields, enter the display name of the download link in the hyperlink_display_column_name parameter of the column in which you want the download link to be displayed in the data grid. The display name will be used as the name of the downloaded file.
Point to another column in customer data: in k_referential_grids_fields, enter the ID of the column you want to point to in the hyperlink_id_display_field parameter. You can get the ID from k_referential_grids_fields as well.
This is an attention message.
The display name of the link determines the name of the downloaded file. Therefore, if you define a static name, consider using the actual name of the file instead of a generic value such as "Click Here" or a simple ID.
This is a warning message.
When using either of the operations described above, the link name will be inserted in all cells of the column in which the document download is activated, even if no document is generated for one or several payees. To avoid any confusion, there should be no rows in which there is no document.
Linking generated documents to the grid
Once you have generated the documents that you want to link in the data grid, you need to map the data grid column to the documents, as follows:
Populate the data grid column created in step 1 of the procedure with the id_file of the document(s) that you want to link in the grid. You can find the id_file value of the documents in the rps_file table.
Security
When using the document download feature in Web App, the following security principles are applied:
Users can only download their own documents. To make sure that this is possible, the id_payee value of a given document in rps_file must match the id_payee of the currently logged in payee.
It is not possible to use hierarchy security to access the documents of other payees.
Only download is possible. It is not possible to upload documents or to delete documents.
Limitations
The following list details the limitations associated with the use of hyperlinks in grids:
Hyperlinks are only supported in Web App, not in Admin Portal
The document download feature is only supported in data grids (i.e. not in process grids or in ad hoc reports)
All configurations for hyperlinks need to be performed in the environment database
It is not possible to automatically generate a file name for downloaded documents when using document download hyperlinks. This has to be configured.
If document download is activated on a column and a link name is defined, the same link is displayed in all cells of the column, even when no documents are available.