Guides

Use an External Query in a Playbook

Suggest Edits

This guide walks you through the steps to implement a pre-configured External Query in a Playbook. This involves attaching the query to a specific question group, defining its trigger, and controlling how the returned data is handled.

Prerequisites:

Before you begin, ensure you have:

Step 1: Attach the Query to a Question Group

First, you need to tell DealHub which question group will trigger the query and receive the returned data.

  1. Navigate to Version Settings and select the same DRAFT version where you created your query object when following the How to Create an External Query guide.
  2. Open the Playbook editor.
  3. Identify or create the question group where you want the data from the external system to be populated. Each question group can only have one query attached to it.
  4. Open the settings for that question group and navigate to the Integrate external object tab.
  5. Check the box to Enable Use external object.
  6. From the dropdown list that appears, select the name of the External Query object you previously created.

Step 2: Configure Query Triggers

After attaching the query, you must define what action will cause it to run. You can choose from manual or automatic triggers.

Manual Trigger

This option adds a button to the UI that the sales representative must click to run the query.

  1. In the query settings for the question group, locate the manual trigger section.
  2. Set the condition for the button's visibility to True to always show it, or define a rule to control when the button should appear.
  3. Enter a descriptive text in the Button label field (e.g., "Get Shipping Rates").

📘

Note

External queries that include product data must use a manual trigger. This is the only supported trigger type for such queries.

🚧

Default Behavior

When the query returns data, a pop-up modal appears showing the results. The user must select a row (or multiple rows) and click Done to populate the data into the question group.

Automatic Triggers

With automatic trigger, the external query runs automatically without user intervention. You can use two different triggers:

  • Trigger on Render: The query runs as soon as the question group becomes visible in the Playbook. To enable this option, check the Run automatically option.
  • Trigger on Change: The query re-runs automatically whenever a specific, related question in the Playbook is modified. This is useful when the query's input depends on another field. To enable this option:
    1. Check the box for Run refresh automatically.
    2. From the dropdown list, select the question(s) that should trigger the refresh when their value changes.

Step 3: Handle the API Response

The final step involves configuring how the data returned from the external query is presented to the user. Here, you have two options, you can either use direct injection or allow the user to select the data returned from the external query. Additionally, you can choose to hide fields received from the external query response, preventing them from appearing in the Playbook.

Direct Injection vs. Selection Modal

You can control whether data is injected directly into the playbook or if the user is prompted to select from the results. This is controlled by the Automatically integrate external data checkbox.

  • If unchecked (Default): When the query returns data, a pop-up modal appears showing the results. The user must select a row and click "Done" to populate the data into the question group.
  • If checked: The data is injected directly into the question group's fields as soon as the response is received, with no pop-up modal.

📘

Handling Repeatable Question Data

If your external system returns an array with multiple objects in the response, DealHub will populate them as multiple rows in the user interface. For this to work correctly, the target question group in your Playbook must be a repeatable question group (indicated by a + icon).

Hiding Returned Fields

Sometimes, your external system returns data that is necessary for system logic (like an external ID) but should not be visible to the sales representative.

  1. In the Fields to hide from user section, select any question from your group whose value you want to receive and store, but not display in the UI.
  2. Even though the field is hidden from the user, its value is still populated and can be used in other calculations or synced to your CRM.

After saving your settings, your External Query is fully implemented. The final step is to create a test quote to ensure the entire workflow functions as expected.

Next Steps

Want to learn more about External Queries? Read the API Reference page or move forward to the Callouts API Section.

Updated 14 days ago