--- title: "Use REST API Resource" slug: "connector-ld-pp-tutorials-rest" updated: 2026-11-09T13:24:57Z published: 2026-11-09T13:24:57Z canonical: "docs.discngine.com/connector-ld-pp-tutorials-rest" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.discngine.com/llms.txt > Use this file to discover all available pages before exploring further. # Use REST API Resource In this tutorial you will learn how to use the REST API Resource input type to have dynamic inputs in a main protocol's form of the gadget using REST endpoints. The endpoint will be implemented as a Pipeline Pilot protocol, which will be called utility protocol, but it could be any other endpoint, provided the CORS requirements are met. Note that the same utility protocol can be reused for several main protocols having the same input. The use case is the following: get the list of LiveDesign projects and corresponding folders as parameter for a protocol registered in the gadget. Retrieval of projects and folders has been divided into two steps for simplification. Topics covered: - `Get LiveDesign Projects` component - `Get LiveDesign Folders` component - `Send Options to Gadget Form` component - REST API Resource input type - REST API Resource dependency fields ## Create the main Pipeline Pilot protocol The main protocol is the protocol which will be launched from the gadget and for which the form should contain a dynamic input. For this tutorial the main protocol will be the "Create a LiveReport" protocol created in the previous tutorial [Create LiveReport](/public/docs/connector-ld-pp-tutorials-create). As a reminder, this protocol creates a LiveReport with example data in a given LiveDesign project, based on the project identifier that the user needs to manually type in the gadget for the parameter Project ID. The protocol can also be extended and provides the possibility to the user to define a folder in which to create the LiveReport. As for the project identifier, the folder identifier is a number which needs to be manually typed by the user. However this identifer cannot be retrieved from the LiveDesign interface. Thus the objective will be to have two dynamic inputs providing the list of LiveDesign projects for the Project ID parameter to have a better user interface (name instead of identifier) and avoid typing mistakes, and the list of folders for the Folder ID parameter to extend the protocol. ## Get projects ### Create the utility Pipeline Pilot protocol The utility protocol is the protocol used to populate a parameter of the main protocol with dynamic inputs. It must expose through an HTTP call a JSON object containing an array of values, or an array of objects containing at least a value field and optionally a label field. e.g.: `[{ label: 'My label', value: 'val1'}, {value: 'val2' }]` or `['val1', 'val2']`. When using an array of values or when label is missing, the value itself will be used as label. In this tutorial the utility protocol will generate the list of LiveDesign projects, with names and descriptions as labels and identifiers as values. Note that this protocol is already available as an example in the Connector Pipeline Pilot collection under `Protocols\Discngine\LiveDesign Connector\Examples\Utilities\Get Projects - REST Resource`. - Create the new protocol - Open the Pipeline Pilot client. - Create a new protocol. - Save it somewhere in `Protocols` as "Get Projects - REST Resource". - Get list of projects and associated metadata - Add the `Get LiveDesign Projects` component to your protocol. - Create a label of shape "name of project (description of project)", which will be the displayed value in the form - Add the `Custom Manipulator` component from the BIOVIA Generic collection to your protocol. - Set the `Expression` parameter to `label := name.' ('.description.')'`. - Rename the property id to name, which will be the value sent to the main protocol - Add the `Rename Properties` component from the BIOVIA Generic collection to your protocol. - Set the `Original Property Names` parameter to "id". - Set the `New Property Names` parameter to "value". - Keep the properties value and label - Add the `Keep or Reorder Properties` component from the BIOVIA Generic collection to your protocol. - Set the `PropertyList` parameter to "value | label". - Format options to be sent to input of type "REST API Resource" as a JSON and expose it in a global property - Add the `Send Options to Gadget Form` component to your protocol. - Leave the `Result Property Name` parameter to the default value "Response". - Declare the Web Service response of the protocol - Go in the Web Service tab. - In the Results section, click on "Edit". - Add the property "Response" of type "Byte Array". ![Get Projects - REST Resource protocol](https://connector.discngine.com/images-doc360/ld_pp/tutorials/rest_projects_protocol.png) ### Set the input type in the gadget - Get the utility protocol link (endpoint URL) - In Pipeline Pilot, right click on the "Get Projects - REST Resource" utility protocol in the explorer tab and click on "Create Protocol Link". - In the popup window, check Show Data Result and select "Response". This will define the "Response" global property defined earlier as the output data. - Copy the protocol link which should look like `https://pp.yourcompany.com/protocols/Discngine/LiveDesign%20Connector/Examples/Utilities/Get%20Projects%20-%20REST%20Resource?$streamdata=Response`. It will be used later. - Edit the registered main protocol "Create a LiveReport" in the gadget - Open LiveDesign and the gadget. - Click on the icon in the gadget menu to manage the registered protocols. - Look for the previously registered "Create a LiveReport" protocol and click on the icon to edit it. - Set REST API Resource parameter type for main protocol - Set the type of the `Project ID` parameter to "REST API Resource". - Set the utility protocol link previously copied in the Endpoint URL configuration option. - Leave the configuration option Send Pipeline Pilot credentials selected. Since a Pipeline Pilot protocol is called, the credentials must also be sent. - Leave the configuration option Send LiveDesign credentials selected. Since a component retrieving information from LiveDesign is used in the protocol, authentication is required. - Complete the registration - Click on "Save Protocol". - Click on "Save Menu". - Test form in gadget - Select the "Create a LiveReport" protocol in the gadget menu. - The Project ID parameter should be populated with the list generated by the utility protocol. ![Get projects register protocol](https://connector.discngine.com/images-doc360/ld_pp/tutorials/rest_projects_register.png) ## Get folders ### Create the utility Pipeline Pilot protocol In this tutorial the utility protocol will generate the list of LiveDesign folders and subfolders, with paths as labels and identifiers as values. Note that this protocol is already available as an example in the Connector Pipeline Pilot collection under `Protocols\Discngine\LiveDesign Connector\Examples\Utilities\Get Folders - REST Resource`. - Create the new protocol - Open the Pipeline Pilot client. - Create a new protocol. - Save it somewhere in `Protocols` as "Get Folders - REST Resource". - Get list of folders and associated metadata - Add the `Get LiveDesign Folders` component to your protocol. - Promote the `Project ID` parameter to the protocol level. Note that this parameter is not required and if it is left empty, the full list of folders for all projects will be retrieved. - Send records to fail port if no folder is found - Add the `Is Property Defined Filter` component from the BIOVIA Generic collection to your protocol. - Set the `Property Name` parameter to "Folder Path". - Create a label using the path of the folders and subfolders, which will be the displayed value in the form - Add the `Custom Manipulator` component from the BIOVIA Generic collection to your protocol. - Set the `Expression` parameter to `label := %'Folder Path';`. - Rename the property Folder ID to name, which will be the value sent to the main protocol - Add the `Rename Properties` component from the BIOVIA Generic collection to your protocol. - Set the `Original Property Names` parameter to "Folder ID". - Set the `New Property Names` parameter to "value". - Keep the properties value and label - Add the `Keep or Reorder Properties` component from the BIOVIA Generic collection to your protocol. - Set the `PropertyList` parameter to "value | label". - Sort the records alphabetically to have subfolders under their parent folders - Add the `Sort Data` component from the BIOVIA Generic collection to your protocol. - Set the `Sort By > Property 1` parameter to "label". - Set the `Sort By > Property 1 > Sort As` parameter to "Text". - Format options to be sent to input of type "REST API Resource" as a JSON and expose it in a global property - Add the `Send Options to Gadget Form` component to your protocol. - Leave the `Result Property Name` parameter to the default value "Response". - Declare the Web Service response of the protocol - Go in the Web Service tab. - In the Results section, click on "Edit". - Add the property "Response" of type "Byte Array". ![Get Folders - REST Resource protocol](https://connector.discngine.com/images-doc360/ld_pp/tutorials/rest_folders_protocol.png) ### Set the input type and dependency in the gadget Follow the same [steps](/public/docs/connector-ld-pp-tutorials-rest#set-the-input-type-in-the-gadget) than for the `Project ID` parameter but using the "Get Folders - REST Resource" utility protocol as Endpoint URL for the `Folder ID` parameter. The utility protocol link should look like `https://pp.yourcompany.com/protocols/Discngine/LiveDesign%20Connector/Examples/Utilities/Get%20Folders%20-%20REST%20Resource?$streamdata=Response&Project+ID=`. Remove the last part `&Project+ID=` corresponding to the protocols parameter. The protocol could be saved like this, but as mentioned earlier, if a project identifier is not provided to the "Get Folders - REST Resource" utility protocol, the full list of folders, no matter the project, will be proposed as options in the form. However this would not make sense as the user will already have selected the project in which the LiveReport should be created in another parameter of the form. This is the purpose of the Dependency Fields option. When defining an input of type REST API Resource in the gadget, any other input of the form can be used as a Dependency field. It is even possible to pass multiple dependency fields. The values of all dependency fields will be passed to the Endpoint URL as query params. To use them in the utility protocol, make sure they are properly defined as protocol parameters and/or read them as global properties. Set the configuration option Dependency Fields to `Project ID` and complete the registration. When testing the form in the gadget, first select a project, and this will make folders of the corresponding project available. The folder input will stay empty if there is no folder in the selected project. ![Get folders register protocol](https://connector.discngine.com/images-doc360/ld_pp/tutorials/rest_folders_register.png)