How to use the Blendr SaaS API to replace an embedded template with setup flow

[LauraLangenaken]

In this article we'll describe how you can migrate from an embedded template with setup flow, to a solution which solely uses our SaaS API. By leveraging our SaaS API, you can fully control the look-and-feel of every input and screen, and include each part exactly where you like in your application.

Template structure - Embedded iFrame

Let's first take a simple example of a template structure. The image below shows a common flow, which makes an API call to present a list of options to a customer that is specific to their situation (List Forms in their Hubspot instance).

In the embedded iFrame solution, the customer would first be asked to connect their datasources. On the second screen, they will be shown a dropdown of their relevant Hubspot forms to choose from. This form-id will be kept as a "persisted input" for every execution of the Start flow of the blend.

Template structure - SaaS API

If we want to use the SaaS API, to provide the same logic to the customers, our template needs to be configured slightly differently. In this case we recommend to create a bundle including two templates:

- The first template (Bundle Setup question) will allow you to fetch the relevant Hubspot forms, which you can then display to your user to allow them to select the correct one.

- The second template (Bundle- Execution Flow) will be your main blend which handles all the logic (the equivalent to the current start block flow).

SaaS API Endpoints

The SaaS API offers a number of endpoints which we can leverage to automate this process from within your own application.

Step 1: Create relevant datasources in the customer account

We firstly need to use the 'Create datasource' endpoint to create the relevant datasource(s) (e.g. Hubspot). The exact execution of this step will be covered in a subsequent article. The response of this API call should return a datasource guid.

Step 2: Install the Bundle in the customer account

Next we'll install this bundle in the customer account, so we have a unique instance in their account. For this we need to know the bundle guid in your SaaS Admin Hub. We also need the customer account Id and the GUID(s) of the relevant datasources created in Step 1.

An instance of this bundle and its containing blends will be created in the customer account, and the response of this API call will return the unique GUID of the bundle in that customer's account, and the GUIDs of the two individual blends in that bundle (Bundle Setup question and Bundle- Execution Flow respectively).

Step 3: Run the initial setup blend

The next API call 'Execute Integration in Account' will retrieve all Hubspot forms by triggering the 'Bundle Setup Question' blend in the customer's account. As I'm expecting a response from the API (the list of my Hubspot forms), I need to run this blend synchronously. I'll pass the blend GUID of the 'Bundle Setup question' blend as part of the endpoint URL.

The response of this API call will be a list of relevant Hubspot forms for my account. I can then create a UI element on my site, allowing customers to choose the relevant form, or choose it based on any custom logic I implement.

Step 4: Set the persisted inputs for the main blend

Almost there. We now want to populate the chosen form_id from step 3 as a persisted input for the 'Bundle- Execution Flow' blend. In this blend, we had one input block in the setup flow, which has the input parameter 'form_id'. By using the 'Set Persisted Inputs of Integration' endpoint, we can populate this input in the setup flow, so that it is stored for any subsequent integration run.

Step 5: Run the integration

Finally we can execute the integration of the 'Bundle- Execution Flow' blend, similar to what we did for the setup flow blend in step 3. The frequency of when this is triggered is completely dependent on your business logic. An optional extra step is to set the schedule through the 'Update Integration in Account' endpoint.

The form id is persistently stored since Step 4, so we don't have to provide any inputs directly in the start flow.

The response of this API call will be a list of relevant form submissions in Hubspot, for this specific form id.

Conclusion

The Blendr SaaS API allows you to work around limitations provided by the iFrame solution, enabling you to completely tailor the user experience to your liking. It's advised to design your templates and bundles already keeping in mind which embedding approach you will choose, especially when it comes to chosing your setup and setting flows.

The information in this article is provided as-is and to be used at own discretion. Depending on tool(s) used, customization(s), and/or other factors ongoing support on the solution below may not be provided by Qlik Support.