Adding queries to get data from a target server when running a flow

As a developer, you can add queries to your connector. When you use the connector in a flow, the query is triggered when the condition defined in the trigger is fulfilled. Field values defined in the query are sent to or received from the target application to use within the flow.

While developing the connector, you define the condition to run the query, and the input or output fields. In the query conditions, you can copy a field from the input or output fields defined for a trigger or action added to the connector. The query conditions are evaluated by the target application server, so the syntax of the query used must be readable by your target application.

To add or update a query

1. To open BMC Helix Connector Designer in your browser, navigate to https://localhost:3000/.
   1. On the Connectors tab, click the name of the connector in which you want to add or update a query. 
   2. On the Connector Properties tab, click the Queries tab, and perform one of the following actions:
      • If you are adding a query, click .
      • If you are updating a query, click the query name from the list.

2. Enter the query details as described in the following table:

   Field	Description
   Query Name	A short description of the data requested by the query.
   Definition Source	Select the source for defining the query fields. You can enter the information manually, or use an API definition file or JSON definition file to automatically generate the fields. The following options are available: Enter it manually—You manually add the query input and output fields, without any definition files. Swagger—The query input and output fields will be generated from a request endpoint (typically for GET) that is described in an API definition file. You can upload an API definition file from the API Definitions section under the General tab. For more information, see Adding an API definition file to generate fields related to the connector. JSON—The query input and output fields will be generated from a JSON snippet or file. For more information, review the steps to add input and output file.
   For JSON or Enter it manually
   URL	Enter the API endpoint for the query.
   Method	Select the HTTP method for the API endpoint. The allowed methods are: GET, POST, PATCH, PUT, DELETE.
   For Swagger
   Swagger File	Select the swagger file that contains the query definition. For more information, see Adding an API definition file to generate fields related to the connector.
   Request	Select the request to execute the query. Typically, this is a GET call. For more information see your connecting application's API reference.
   Create Fields	Click this option to automatically generate input and output fields for the selected request under the Input fields and Output fields tabs.

3. Depending on the query definition entry method selected, add or update the condition fields for the query. When a flow is run, the query is run when the conditions defined are fulfilled.  

   • If you selected Enter it manually as the query definition entry method, on the Conditions tab, click , and select the field type.

     Add or update the following details:

     Property	Description
     Display Name	Enter a display name for the field in BMC Helix Integration Studio.
     Field Name	The actual field name in the target application of the flow to be created by using this connector
     (Optional) Description	Enter a brief description of the field.
     Qualifiers	Enter valid qualifiers depending on your target application.

   • If you selected Swagger, all the condition fields for the request are automatically generated. Update the values as required (for example, you may want to use a different display name).
   • If you selected JSON, perform the following steps to add fields:
     1. Click .
     2. In the dialog box, paste a JSON snippet, or click Upload JSON File.
        The JSON code must describe one or more input fields for the API call for the query. The API reference documentation of the connector's target application should include the code that you can use.
     3. Click Create Fields to generate input fields from the JSON code.
     4. Update values as required (for example, you may want to use a different display name).

4. Depending on the query definition entry method selected, add or update the input fields for the query. 
   A query input field maps to a request field of the corresponding API call (typically a POST request). 

   Important

   • The field values for the input fields is the same for all query definition entry options.
   • If you are updating an existing connector, remember that:
     
     • If you remove a query input field, a default value for the field is used so that the query does not fail.
     • If you add a new input, existing flows based on the previous version of the connector will no longer work. You need to communicate the change to your users.

   • If you selected Enter it manually as the query definition entry method, on the Input Fields tab, click  and select the type. 

     Add or update the following details.

     Property	Description
     Display Name	The display name for the field in BMC Helix Integration Studio.
     Field Name	The actual field name in the connector's target application.
     (Optional) Description	A brief description of the field.
     Required	Indicates whether the field is required. Default value is set to true.
     Show by default	Indicates if the field will be displayed in BMC Helix Integration Studio.

   • If you selected Swagger, all the input fields for the request are automatically generated. Update the values as required (for example, you may want to use a different display name).
   • If you selected JSON, on the Input Field tab, perform the following steps to add fields:
     1. Click .
     2. In the dialog box, paste a JSON snippet, or click Upload JSON File.
        The JSON code must describe one or more input fields for the API call for the query. The API reference documentation of the connector's target application should include the code that you can use.
     3. Click Create Fields to generate input fields from the JSON code.
     4. Update values as required (for example, you may want to use a different display name).

5. Depending on the query definition entry method selected, add or update the output fields for the query. 
   A query output field maps to a response field of the corresponding API call.  

   Important

   When you remove an output field, a default value for the field is used so that the query does not fail.

   • If you selected Enter it manually as the query definition entry method, on the Output Fields tab, click  and select the type. Then add the field details.
     

     You can add or update the following fields:

     Property	Description
     Display Name	The display name for the field in BMC Helix Integration Studio.
     Field Name	The actual field name in the connector's target application.
     (Optional) Description	A brief description of the field.
     Always has data	Indicates whether the field will always be returned, regardless of its value. By default, this value is set to true.

   • If you selected Swagger, all the output fields for the request are auto-generated. Update the values as required (for example, you may want to use a different display name); 
   • If you selected JSON, on the Output Field tab, perform the following steps to add fields:
     1. Click .
     2. In the dialog box, paste a JSON snippet, or click Upload JSON File.
        The JSON code must describe one or more output fields for the API call for the query. The API reference documentation of the connector's target application should include the code that you can use.
     3. Click Create Fields to generate output fields from the JSON code.

     4. Update values as required (for example, you may want to use a different display name). 

   • Click Save. 

To delete a query

1. To open BMC Helix Connector Designer in your browser, navigate to https://localhost:3000/.
2. On the Connectors tab, click the name of the connector from which you want to delete a query.
3. On the Connector Properties tab, click the Queries tab.

4. Select the required query field, and click .

Where to go from here