Leveraging external data in questionnaires by using a BMC Helix Innovation Studio process

As a catalog administrator, leverage data from external systems in service questionnaires by calling a BMC Helix Innovation Studio process. Configure a BMC Helix Innovation Studio process to retrieve data from any external system, provided that you have integrated BMC Helix Digital Workplace Catalog with this system through service connectors. After that, use this external data to create selection menus for responses to single-select and multi-select dropdown questions in single-user questionnaires, multi-user questionnaires, and a repeatable group of questions.

Important

Creating selection menus with external data retrieved through the BMC Helix Innovation Studio process is not supported for other question types.

When you use the BMC Helix Innovation Studio process, you save time and effort because it provides a unified approach to retrieving data from various external systems and using this data in service questionnaires. Furthermore, as companies expand and integrate more external systems, a streamlined data retrieval process facilitates scalability. With this capability, you give your users the option to select from a defined set of answers from any external system instead of entering their answers manually.

Required license

DWP Advanced icon.png BMC Helix Digital Workplace Advanced

Scenario

Employees at Apex Global frequently require IT equipment like laptops, monitors, and printers for their workstations. To streamline this process, the IT department integrates an external system that contains a comprehensive list of IT equipment with BMC Helix Digital Workplace Catalog through the REST connector. Hannah, the Catalog admin, creates an BMC Helix Innovation Studio process to retrieve the IT equipment list from this external system. Then, while creating a questionnaire, she builds selection menus that use this list of IT equipment.

Employees who open a service for IT equipment see the list of available options. Employees can then browse through this list and select the items they need. After the selection is made and the request is submitted, the IT department coordinates the procurement and delivery of the requested equipment.

Before you begin

Make sure you have administrator privileges to set up configurations in BMC Helix Innovation Studio and catalog administrator privileges to configure services in BMC Helix Digital Workplace Catalog.
Establish the connection to an external system through BMC Helix Digital Workplace Catalog service connectors. For more information, see Connecting-your-catalog-to-external-systems.

Process to populate data from an external data source in a questionnaire

The following image shows the configuration steps to leverage external data in questionnaires by using a BMC Helix Innovation Studio process:

The following table provides the sequence of steps that you need to perform:

Step	Product	Task	Description	Reference
1	BMC Helix Innovation Studio	Create a document definition	Define the fields to be available for selection as the Stored and Display values when designing a questionnaire, and specify the format of these fields. The structure of the document definition must match the response of the external system from which the data is to be retrieved. The document definition must include an Array node named data. Within this array node, define the JSON schema by specifying fields and their format. The JSON schema may contain simple or complex data types. However, only the String, Integer, and Float data types are supported for retrieval. Their input can be selected as Stored and Display values for single-select and multi-select dropdown fields when creating a questionnaire. Important: Other primitive data types, such as Boolean and Null, or complex data types (such as Objects or Arrays) are not supported for retrieval and their inputs won't be available for selection when you design the questionnaire. The sample document definition is as follows: { "data":[{ "empid":"EMP_NO", "first_name":"FIRST_NAME", "last_name":"LAST_NAME", "gender":"GENDER" }] } Click to see an example:	Defining a document schema
2	BMC Helix Digital Workplace Catalog	Configure a BMC Helix Innovation Studio process	In BMC Helix Digital Workplace Catalog, create an BMC Helix Innovation Studio process to retrieve data from an external system with which you have established a connection through service connectors. Click to see an example:	Designing-a-BMC-Helix-Innovation-Studio-process-to-retrieve-data-from-external-systems
3	BMC Helix Digital Workplace Catalog	Create the service in BMC Helix Digital Workplace	Create a service that will use the external data. Click to see an example:	Adding-and-updating-services
4	BMC Helix Digital Workplace Catalog	Configure a questionnaire for the service	Add a questionnaire for the service. Click to see an example:	Adding-questions-to-a-questionnaire
5	BMC Helix Digital Workplace Catalog	Add a single-select or multi-select dropdown type question and map question values to a process	Add a single-select or multi-select dropdown question and create a selection menu for question responses that consist of external data obtained via the BMC Helix Innovation Studio process. Important: Creating selection menus with external data retrieved through the BMC Helix Innovation Studio process is not supported for other question types. Click to see an example:	Creating-selection-menus-for-question-responses
6	BMC Helix Innovation Studio	(Optional) Verify or modify the default timeout and record count settings for the BMC Helix Innovation Studio process	BMC defines the following timeout and record count settings for the BMC Helix Innovation Studio process: The default timeout value to terminate the execution of the BMC Helix Innovation Studio process is five seconds. The default record count value to determine the number of records the BMC Helix Innovation Studio process can fetch at the time of initialization without any keyword is 2000 records. Additionally, BMC Helix Digital Workplace Catalog doesn't consider data beyond 2000 rows, by default. You can change these default values if needed. Click to see an example:	To modify timeout and record count settings

(Optional) To modify timeout and record count settings

Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
Select Digital Workplace Catalog > Service Request.
On the General tab, verify or modify the following settings:
1. Lookup Process Timeout (in seconds)—Timeout value in seconds to terminate the execution of the BMC Helix Innovation Studio process if it takes too long. The default value is five. The minimum supported value is one, and the maximum value is 120.
2. Lookup Process Max Output Rows—The number of records the BMC Helix Innovation Studio process can fetch at the time of initialization without any keyword and the number of rows for which data is to be considered. The default value is 2000. The minimum supported value is one, and the maximum value is 10000.
Click Save.

Results

The following image shows the service in the end-user console:

Export and import of the created service

You can export a service that utilizes external data and then import it into a different BMC Helix Digital Workplace Catalog environment. You just need to export the service, and BMC will handle the associated document definition, BMC Helix Innovation Studio process, and questionnaire. While importing a service into a different system, determine how to handle the document definition:

To establish a connection to the external system after importing, ensure the destination environment has a matching service connector with the same name and settings as in the original environment. For information about importing services, see Copying-services-from-another-system.

Troubleshooting

The following table provides information that can help troubleshoot issues with retrieving data from the external system through the BMC Helix Innovation Studio process:

Issue	Possible reason and solution
No external data is available in the selection menu.	The data from the external system might not be available because the connection can't be established to the external system. The Catalog administrator must troubleshoot the service connector that integrates BMC Helix Digital Workplace Catalog with the external system. For information about troubleshooting capabilities, see Troubleshooting-Connectors-in-BMC-Helix-Digital-Workplace-Catalog.
	The data from the external system might not be available due to a connection timeout. In this scenario, no error message is displayed to an end user. To troubleshoot a problem, the BMC Helix Digital Workplace administrator can check logs in the DEBUG mode. For more information, see Configuring-logs-for-BMC-Helix-Digital-Workplace. The data might be missing if the following connections time out: The service connector times out—To resolve this issue, increase the timeout value for the connector. The BMC Helix Innovation Studio process times out—To resolve this issue, increase the timeout value for the process. For more information, see To modify timeout and record count settings. Best practice: We recommend that you set the connector timeout to a value larger than the BMC Helix Innovation Studio process timeout value.
	The created BMC Helix Innovation Studio process doesn't have the Public permissions assigned. For information about how to properly configure the BMC Helix Innovation Studio process, see Designing-a-BMC-Helix-Innovation-Studio-process-to-retrieve-data-from-external-systems.
	Different document definitions have been selected for the input and output process variables in the BMC Helix Innovation Studio process. For information about how to properly configure the BMC Helix Innovation Studio process, see Designing-a-BMC-Helix-Innovation-Studio-process-to-retrieve-data-from-external-systems.
Some external data is not available in the selection menu.	Data is not retrieved from the external system because the BMC Helix Innovation Studio process has already fetched the maximum number of records as determined by the Lookup Process Max Output Rows setting. To resolve this issue, increase the Lookup Process Max Output Rows value. For more information, see To configure timeout and record count settings.
The created BMC Helix Innovation Studio process is not visible in BMC Helix Digital Workplace Catalog after initially mapping question values to a process.	The possible reason is that the process was renamed. If you have already mapped question values to this process, the external data will remain available in the selection menus.
While mapping question values to a process and selecting the BMC Helix Innovation Studio process, the administrator receives the following error message: The workflow selected is incompatible with external process	The selected BMC Helix Innovation Studio process doesn't include any process output of the Object type.
Not all fields added to the document definition are available for selection as the Stored and Display values when designing a questionnaire.	Only fields of the String, Integer, or Float data type are supported for retrieval. Other primitive data types, such as Boolean and Null, or complex data types (such as Objects or Arrays) are not supported for retrieval, and their inputs won't be available for selection as the Stored and Display values when designing a questionnaire.