Get CX Actions
Do you want access to this new feature? Contact your Zingtree Account Manager or our Support Team.
Introduction
The Universal Connector Framework allows Zingtree to integrate with external systems, whether standard or custom-built. This feature empowers users to perform CRUD operations and other tasks by connecting to external services via HTTP interfaces (REST or otherwise). This article explains how to set up and use the Universal Connector Framework, along with its components and supported authentication mechanisms.
Components of the Universal Connector Framework
The framework consists of multiple components that enable seamless interactions with external systems. These components are designed for different user personas, including Solution Architects and Authors.
Key Components
-
External Sources
- Provides authentication for accessing external systems and services.
- Supports various authentication mechanisms, including API Key, Basic Auth, Bearer Token, and OAuth2 and more.
-
Connected Objects
- Defines references to external objects or endpoints for use in flows.
- Supports HTTP verbs such as GET, POST, PUT, PATCH, and DELETE.
Setting Up External Sources
Step 1: Define an External Source
- Navigate to Apps & Integrations > External Sources > Data Sources in Zingtree.
- Click Add Source.
- Fill in the following fields:
- Name: A unique identifier for the connection.
- Description: (Optional) Add details about the purpose of the connection.
Step 2: Configure Authentication
Zingtree supports multiple authentication mechanisms. Select the appropriate method based on your requirements:
-
API Key:
- Enter the API key and specify whether to include it in the header or query parameters.
- Optionally, provide a username if required by the external system.
-
Basic Auth:
- Input the username and password for authentication.
-
Bearer Token:
- Provide the token and optional prefix for Bearer authentication.
-
OAuth2:
- Choose between Password Credentials or Client Credentials.
- Fill in fields like Access Token URL, Client ID, Client Secret, and Scope.
- No Auth: Coming soon.
Configuring Connected Objects
Connected Objects are references to external endpoints that can be used within flows.
Step 1: Create a Connected Object
- Navigate to Apps & Integrations > Connected Objects.
- Click Add New Object.
- Enter the following details:
- Name: An identifier.
- Alias: An Alias will be generated using the name of the Connected Object. You can edit it manually but the Alias must be unique. Note: once the Connected Object is created, you cannot edit it later.
- Description: (Optional) Describe the object's functionality.
- Endpoint URL: The full URL of the endpoint.
Step 2: Set Up Request Parameters
- Request Headers: Add custom headers as needed.
- Query Parameters: Configure dynamic or static parameters for the request.
Step 3: Define HTTP Methods
Connected Objects support the following actions:
- Retrieve (GET)
- Create (POST)
- Update (PUT)
- Modify (PATCH)
- Delete (DELETE)
Using Connected Objects in Flows
After configuration, Connected Objects can be integrated into Zingtree flows. Use the Data Connected Node to:
- Retrieve data from external systems.
- Create or update records dynamically.
- Display information in real-time during flows.
Step 1: Add a Data Connected Node
- Add a new node to your tree and choose the Data Connected Node type.
- Configure the Data Connected Node by first selecting the name of your Connected Object from the drop-down list.
- Select which node should be displayed next:
Dynamic Views
Once configured, Dynamic Views allow you to create a customized display of the retrieved data for the end user.
Step 1: Create a New Dynamic View
- Navigate to Apps & Integrations > Dynamic Views.
- Click Add Dynamic View.
Step 2: Configure the General Settings
- Enter the following details:
- Name: A unique name for the Dynamic View
- Description: A description of the Dynamic View
- Toggle the switch to Active if you wish to have this View available for Authors to use in Content Nodes.
Step 3: Configure the Widget Settings
- Select the Connected Object you'll be using to display the data. In the Schema section, select the records that you want included in the display.
Step 4: Configure the Designer Settings
- Choose how you would like your data displayed. As a Grid or Card:
- A Grid will display as a table of records:
- A Card will display the records as individual cards:
- A Grid will display as a table of records:
- Toggle on or off your desired options:
- Searchable: Allows the user to search the displayed records.
- Sortable: Allows the user to sort the displayed records.
- Selectable: Allows the user to select an individual record.
- Multi-Select: Allows the user to select multiple records.
- Page Size: The number of results to display per page.
- Configure the order of your Fields:
- Your selected fields are listed in the Fields section. Drag their handles to move them into the order that you would like them to display.
- Save your configured Dynamic Display.
Step 5: Adding your Dynamic View to a Content Node
Once your Dynamic View is configured and enabled, Authors can use the display in content nodes. Typically a Dynamic View is shown in a node following the Data Connected Node.
- In a Content Node, choose the Dynamic Views button from the editor toolbar:
- All Dynamic Views that are available to the Author will be shown in the list. Choose the View that you would like to display. Note: The Dynamic View will only be available if the Connected Object that it is tied to has been used in a flow (current flow or any other flow in the organization).
- Once a View has been added to the node, it can be edited or removed by clicking inside the View's parameters:
Syntax
Passing dynamic values in/from Actions uses a different Syntax than the standard Zingtree form data variables.
Dynamic fields in Connected Objects:
${varA}
Variables returned from a Connected Object (whether in the authoring tool or a Connected Object):
${actions.alias.fields[0].field_name}
Variables returned from a selection made in Dynamic Views (whether in the authoring tool or a Connected Object):
${views.alias.field_name}
Variables in the authoring tool collected in form data fields or via the URL:
#varA#
Personas and Use Cases
-
Solution Architect:
- Designs and configures External Sources and Connected Objects.
- Understands HTTP and security protocols.
-
Author:
- Uses Connected Objects to enhance flow functionality.
- Integrates external data dynamically into Zingtree flows.
Additional Notes
- Data security is ensured with AES-256 encryption for sensitive credentials.
- Zingtree supports dynamic variable substitution using
{{ }}
syntax to customize parameters at runtime.