Configuring a data source to use in a form

This article details the configuration methods to follow in order to reference data from processes or external tables/views in attached forms in the Process component of the the Web App interface of v10.

There are two types of references that you can use in attached forms:

• Mentions: these references use process information or indicator fields and replace a generic placeholder (field name) with the value from the source

• External references: these reference are based on external table/views imported into the system. They are specifically related to a form block.

Configuring a data source to use in mentions

In the context of attached forms, mentions are used to reference process, process steps or payee data such as payee information (name, title, etc.) in a form. For instance, this enables you to use a placeholder such as PayeeName that will then be replaced by the actual values when used in a process.

The data sources to be used must be specified using the data service.

Two different types of data sources can be defined:

• Physical data source: a physical data source is based on a table/view from the beqom Admin Portal and configured in the k_referential_tables_views table.

• Plan data source: a plan data source (process data source) is based on k_m_values and is configured in the k_m_plans table.

This is an attention message.

In both cases, the data source must contain the idStep column because this field enables the system to filter out the data. This column is always present in plan data sources because these correspond to processes.

The name of this column is case sensitive; always make sure that the column is called idStep with a capital S.

Importing the data source

The registration of a table/view as a data source is performed by synchronizing the table/view in the Admin Portal interface of v10.

To import an external data source, proceed as follows:

1. Log into v10 and go to the Admin Portal interface.

2. Open the ADMIN component, and then navigate to Technical Admin > Synchronization & Data Security. A grid containing all the tables/views already imported in the system is displayed.

3. Click the Import button, located in the lower-left corner of the grid. A secondary panel is opened under the grid.

4. Select the table/view that you want to import among the available items. The list contains all the items available in the database that have not yet been synchronized.

5. In the Select Type drop-down, select Import.

6. Click the + icon in the lower-left corner of the secondary panel. A success message is displayed and the table/view is imported and sychronized in the beqom application.

Synchronizing an already imported data source

If the data source that you want to use has already been imported in the system, you can, as a precaution, synchronize the data source to make sure that it is up-to-date.

This is an attention message.

This operation will remove all references to the data source in the system.

To synchronize an already imported data source, proceed as follows:

1. In Admin Portal, open the ADMIN component, and then navigate to Technical Admin > Synchronization & Data Security. A grid containing all the tables/views already imported in the system is displayed.

2. Locate, in the grid, the item that you want to synchronize. Required, perform a search in the Name field.

3. Check the box located on the left of the record corresponding to the data source to be synchronized. You can select several items simultaneously.

4. Click the synchronization icon, located in the lower-left corner of the grid, as illustrated in the following figure:

Synchronization button in Admin Portal

5. Click Yes in the warning message that is displayed. The data source is synchronized.

Associating a physical data source to a form

It is possible to use for mentions a data source other than a process. However, to do so, you need to manually assign it to the process in which you want to use it. There is no application UI to perform this operation; it must be done via API.

Please note that the following SQL field types are not supported for payee information:

• numeric (equal, not equal, greater than, greater than equal, lower than, lower than equal)

• int (equal, not equal, greater than, greater than equal, lower than, lower than equal)

• nvarchar (minimum number of characters is, maximum number of characters is, minimum number of words is, maximum number of words is)

• datetime (greater than, lower than, equal, not equal)

Retrieving the data source ID

Once the table/view has been imported, you need to retrieve the ID of the data source. You can do so using the following API method:

Data source ID retrieval method

Service	Action	Endpoint
Data	GET	/api/datasources

The method returns all the data sources defined in the system. You need to locate the item corresponding to the table/view in the list. Use the name of the table/view to find it more easily.

When you have located the item that you need, retrieve the UID of the data source, which is located in the id parameter of the response body, as illustrated in the following example (for a table named x_countries:

Get data source method output

Linking the data source to the form

Use the following API method to configure the data source:

Data source linking method

Service	Action	Endpoint	Body Sample
Data	POST	/api/datasource/{id}/object	Copy { "uidObject": "string", "aggregated": true, }

The following table details the parameters to be used in body of the API call:

Data source linking method parameters

Parameter	Description
{id}	Data source for the payee information. This is the object created in k_referential_tables_views, with an idStep column
uidObject	ID of the form created in the application
aggregated	Not considered; always true

Using a process data source

Plan data sources (process data) are automatically made available when you associate a form to a process. However, when process data are used as the reference data source, two important rules related to the indicator fields visibility must be considered by the implementation team:

• Access to all indicator fields must be granted to the profile designing forms.

• Access to all indicator fields must be granted to users intending to use the form.

This is an note/information message.

For more information on form access, refer to Permissions of the (Web App) and (Admin Portal).

Using a data source in a form Web App

In the v10 Web Application, internal data sources are associated to a form and used in the form of mentions.

This is an attention message.

Mentions can only be used in form blocks of type Information Field. For more information, see XREFForm Block Types and XREFUsing Rich Text Fields.

To use an internal data source in a form, proceed as follows:

1. Create a form using the procedure described in XREFCreating a Form.

2. Click the icon located in the upper-right corner of the application window. The Form Properties panel is opened.

3. In the Assign Form to Process field, select the process to which you want to assign the form.

4. Open the edition interface of the form, by clicking Edit, at the top of the application window.

5. Add an Information Field block to the form using the procedure described in XREFAdding one or Several Blocks to a Form.

6. Enter your description and use the @ character to mention fields from the data source.

Configuring an external data source to use in form fields

It is possible to use an external data source such as a table or view from Admin Portal to fetch possible answers for single answer selection, single answer and multiple answers blocks in attached forms. External data sources are tables/views that are imported into the v10 application using Admin Portal and then linked to a form.

This is an attention message.

Any table/view used as a data source must contain the idStep column.

Importing the data source

To import an external data source, proceed as follows:

1. In Admin Portal, open the ADMIN component, and then navigate to Technical Admin > Synchronization & Data Security. A grid containing all the tables/views already imported in the system is displayed.

2. Click the Import button, located in the lower-left corner of the grid. A secondary panel is opened under the grid.

3. Select the table/view that you want to import among the available items.

4. In the Select Type drop-down, select Import.

5. Click the + icon in the lower-left corner of the secondary panel. A success message is displayed and the table/view is imported and sychronized in the beqom application.

Retrieving the data source ID

Once the table/view has been imported, you need to retrieve the ID of the data source. You can do so using the following API method:

Data source ID retrieval method

Service	Action	Endpoint
Data	GET	/api/datasources

The method returns all the data sources defined in the system. You need to locate the item corresponding to the table/view in the list. Use the name of the table/view to find it more easily.

When you have located the item that you need, retrieve the UID of the data source, which is located in the id parameter of the response body, as illustrated in the following example (for a table named "x_countries":

Get data source method output

Retrieving the details of the data source

Now that you have retrieved the ID of the data source, you need to retrieve the full details of the table/view in order to obtain the alias and the name of the columns in the data source. This information is then used in the application dictionary.

To do so, execute the following API method:

Data source detail retrieval method

Service	Action	Endpoint	Description
Data	GET	/api/datasource/{id}	In this call, {id} corresponds to the ID of the data source that you obtained in the previous step.

The following figure illustrates an example of field name and alias that you need to the properly configure the data source:

Data source configuration example

Editing the data source

Now the data source needs to be edited in order to include the information obtained in the previous step.

To do so, execute the following API method

Data source edition method

Action	Endpoint	Description
PUT	/api/datasource/{id}	In this call, {id} corresponds to the ID of the data source.

Below is an example of the call for this step:

Data source edition API call

Using an external data source in a form in Web App

In the beqom Web Application, external data sources are associated to individual form blocks. This operation is available only for certain block types, namely: Drop-Down Selection, Single Answer and Multiple Answers (for more information, see XREFForm Block Types).

To use an internal data source in a form in Web App, proceed as follows:

1. Create a form using the procedure described in XREFCreating a Form.

2. Add a block to the form using the procedure described in XREFAdding one or Several Blocks to a Form.

3. Click the icon in the lower-right corner of the form block. The Block Settings panel is opened.

4. Open the "Block Settings" section of the panel.

5. Switch the state of the Select Options from a Source toggle to enabled (blue). A new drop-down is displayed.

6. Select your data source in the drop-down.

7. Click Save in the bottom right corner of the panel. The data source is now used to retrieve values.