1. Overview 

Integration field is a form field that lets users reference and associate records from external services directly within Creator forms. while submitting the data. It acts as a dynamic lookup that retrieves information in real time from the connected services. Rather than manually entering data, the integration field allows users to search for existing records from the connected service and link them to form submissions, helping maintain consistency across systems and avoid duplicate data in your Creator application.

Note:

This field is read-only, which only allows users to choose from the list of records.

The integration field fetches data from a selected module in an external service and displays it within the form which works by using a connection and data source. You can select an existing connection/data source or create a new one while configuring the field.

When to use an integration field

Integration field can be used to:

1. Extend modules in your Creator application by referencing records from external services
   
2. Avoid entering the same data again in both products
   
3. Run workflows based on the value selected on connected services.
   

Info: To link related records from applications within Creator, lookup field can be used.

1.1 Supported fields of target services

The Integration field can display data from all types of fields of the target service except the following:

1. Fields that contain multiple lines of text, URLs, media (image, file, etc.)
   
2. Fields that display choices in dropdown menus, as radio buttons or checkboxes 

Check the list of services supported for the integration field.   

2. Use case    

Consider an organization that has built a service management application in Zoho Creator to handle customer support requests. Its customer information is maintained outside Zoho Creator in an external systems such as CRM, ERP, or HRMS platforms (for example, Zoho CRM).

1. Duplicate records must be maintained in both systems
   
2. Support agents have to manually enter customer details while creating support tickets
   
3. Chances of outdated information in one system when the other is updated 
   

With an integration field:

1. To address these challenges, an integration field can be added in the support ticket form, which fetches customer records from the connected service. While creating a ticket, the agents can search and select the appropriate customer instead of manually entering the details. This ensures every ticket is linked to an active customer record, as the integration field displays only relevant customers based on configured filters, thus maintaining data consistency across multiple systems.
   

3. How to add an integration field to a form      

Prerequisite: You must create a form before adding an integration field to a form.

1. Go to the edit mode of the application and choose any required form in the left pane.
2. Click the Open Form Builder button. 
3. Drag and drop or double-click the Integration field under Special Fields from the left pane to the middle.
   
4. In the Integration pop-up, choose the below details:
   
1. Service: Choose the external service from which data must be retrieved.
   
2. Datasource: If you've an existing datasource, you can use them and go to step c. If not, click Add Datasource to create a new datasource.
   In the Add Datasource pop-up, choose the below:
1. Connection: Choose from an existing connection or create a new connection
   . Note: You'll be redirected to login to your account in the selected service for authorization if you create a new connection or select an existing connection that is not yet authorized.
   
   
   
   Note: The data displayed depends on the connection type. With an admin-authorized connection, data is fetched from the external service using admin authorization. With the logged-in user connection, data is fetched using the respective user’s authorization.
   
   
2. Module: Select the target module of the service from which the data must be fetched.
3. Name the datasource: A name for the datasource will be auto-populated. You can edit as you require. Click Create. 
   
3. Select the required field in the Integration pop-up.
   
5. Click Done.
   
   After adding the integration field, you can configure various properties such as setting the field name, customizing display fields, making it mandatory, defining filter criteria, adding a description, and more.
   

Note: The same data source can be used for multiple integration fields.

4. Customize display fields    

An integration field can display multiple fields at a time from the target module, with a maximum of up to three fields.

1. You can add a separator between the displayed field values.
   
2. The separator can be plain text or special characters, with a maximum length of 10 characters.
   
3. Hyphen (-) is the default separator.
   
4. The selected fields are displayed together as a single combined value.
   

For example, the below integration field fetches three fields: first name, last name and email from the Contacts module of Zoho CRM. The field value is customized with separators and will be displayed in the reports in this format: First name Last name / Email.

Note: When display fields are changed, existing records will be updated to reflect the new display format. However, previously stored values will not be automatically updated. To update them, you can run integration field data sync in live mode. 

Steps to customize display field 

1. Select the required integration field in the form builder. It's field properties will appear in the right pane.
2. Choose the required field (the field from the target module of the integrated service) under Display fields section.
3. Click the add icon   to add another display field. A new display field will be added, in which you can choose the required field from the dropdown.
   
4. Add a separator in the textbox before the display field (if required). You can preview the format in which the value will be stored under Preview section. The separator can be plain text/special character with up to 10 characters.
5. To remove a selected display field, click the remove icon  .  To change the order of the selected fields,  click the reorder icon . Changes are auto-saved.
   
   

5. Filter records for an integration field     

You can define filter criteria for an integration field to control which records are displayed. As a result, app users will only see and select records that meet the defined conditions. Rather than displaying all records from the connected service, the field can be configured to show only the records that meet the specified conditions.

Filtering helps:

1. Narrow down the list of records
   
2. Display only relevant data for selection
   
3. Improve user experience by reducing clutter
   
4. Ensure users select appropriate and permitted records
   

This filter must be configured in the edit mode and is applied to the data of the integration field in the live mode.

Types of filter criteria     

You can define filter conditions in two ways:

Note: Filtering is currently supported only for select services, including Zoho CRM, Zoho Recruit, QuickBooks, and Salesforce. Support for additional services will be added over time.

Steps to set filter  

1. Select the required integration field in the form builder. It's field properties will appear in the right pane.
2. Click the Set filter checkbox under the Choices section.  The Set filter pop-up will appear.
3. Set the criteria in the pop-up by selecting the field from the target module in the dropdown, operator and value. For example you can set a filter as Status equals Active. Learn how to set various criteria. You can add multiple criteria by clicking +Add New.
   
   

   Note: The criteria operators and conditional operators (AND, OR) are based on the selected service.
   
   
   You can set dynamic criteria by using the field of the current form.  For example, input.product_name. Additionally, system variables and global variables can also be used to set a dynamic criteria.
4. Click Done. The summary of the filter will be visible in the right pane. The integration field in the live mode will now show only the fields that satisfy the criteria.
   
   

6. See how to configure integration field  

The video below demonstrates how to add an integration field to a form and how it works in live mode.

7. See how integration field works 

In the live mode of the application, the integration field behaves as follows:

Users can search and select a value from the list of records fetched from the connected service. Only one value can be selected, and users cannot add or edit values from within the field.

The records displayed depend on the connection type used. For example, admin-authorized connections fetch data using admin authorization, while user-specific connections fetch data based on the logged-in user’s authorization.

Display of values  

The field shows values based on the configured display fields. Multiple fields (up to three) can be viewed together.

Data in form submissions and reports  

The selected value is stored after the form submission and can be viewed in reports along with other form data. This value can also be used in workflows, such as form rules, approvals, and integrations, to drive actions based on the selected record.

Behavior with filters  

If filters are configured, only records that meet the defined criteria (static or dynamic) are displayed, ensuring users can select only relevant records.

Ordering of records  

Records are displayed in the default order returned by the connected service, typically with the most recent records appearing first.

Behavior when source data is updated  

When a record is updated in the connected service, the integration field reflects the updated value for new selections. Records created or updated after the change will capture the latest value. However, existing records retain the previously stored value and are not updated automatically. To update these records, you can run integration field data sync.

Search records  

With regard to searching the integration field:

1. Your users can search in all the display fields you set
   
2. At least two characters are to be entered to initiate search
   
3. Searching more than one display fields is supported. Records that match the inputs in all display fields will be displayed.
   
4. The kind of search that will happen depends on the target service and the type of data the fields store.
   

The image below shows an integration field fetching records from Zoho CRM and displaying values from three fields.

8. Supported properties of integration field 

You can set the below properties for an integration field.

9. Points to note  

1. The integration field is read-only and only allows users to select values from the listed records. Adding or editing data is not supported.
   
2. Records are displayed based on data fetched from the connected external service.
   
3. The values listed in the dropdown cannot be custom sorted and follow the default order returned by the connected service, typically with recent records appearing first.
   
4. If filters are configured, only records that meet the defined criteria are displayed.
   
5. When a record is updated in the connected service, only records created or edited after the change reflect the updated value; existing records retain previously stored values unless data sync is performed.
   
6. The availability and structure of data depend on the configuration and permissions of the connected service.
   
7. Search results within the field are based on the data retrieved from the external service and the configured display fields.
   
8. The integration field will display data only when your subscription to the target service (eg: Salesforce, Zoho CRM) allows accessing the target module. For example, imagine that you've subscribed to Zoho CRM's Standard edition and that you've added an integration field that displays data from Zoho CRM's Purchase Orders  module. This integration field will not display any data as the Purchase Order module isn't available in Zoho CRM's Standard edition.
   
   

10. Related topics    

1. Adding and managing fields
   
2. Lookup field