Use REST API Resource

  • Updated on Jun 2, 2025
  • Published on Feb 13, 2025
  • 7 minute(s) read
  • CW
 Prev Next

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 have been divided into two steps for simplification.

Topics covered:

  • Get LiveDesign Projects component
  • Get LiveDesign Folders component
  • Send Options to SWAPP 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. 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

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 previosuly 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

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 parammeter 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

Set the input type and dependency in the gadget

Follow the same steps 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= correponding to the protocols parameter.

The protocol could be saved like this, but as mentionned 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