Groove Data Source

The Groove connector enables you to ingest support ticket data, customer records, agent information, knowledge base content, and widget configurations from your Groove account into Nexla. Follow the instructions below to create a new data flow that ingests data from a Groove source in Nexla.

Groove

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Groove connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Groove instance, and click Next; or, create a new Groove credential for use in this flow.

3. In Nexla, Groove data sources can be created using pre-built endpoint templates, which expedite source setup for common Groove endpoints. Each template is designed specifically for the corresponding Groove endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Groove sources can also be configured manually, allowing you to ingest data from Groove endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Groove endpoints. Each template is designed specifically for the corresponding Groove endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

List Tickets

Retrieves a paginated list of support tickets from your Groove account. Use this endpoint to pull a full or filtered collection of tickets for reporting, analysis, or synchronization with other systems.

• This endpoint returns tickets in pages of 25 records. Nexla automatically handles pagination to retrieve all available tickets.
• Assignee (optional): Enter the Groove agent ID to filter tickets assigned to a specific agent. Leave blank to retrieve tickets for all agents.
• Customer (optional): Enter the Groove customer ID to retrieve only tickets associated with that customer.
• State (optional): Enter a ticket state to filter results. Supported values include open, closed, and pending. Leave blank to retrieve tickets in all states.
• Folder (optional): Enter a Groove folder ID to return only tickets in that folder. Folders in Groove are used to organize tickets by category or team.

Agent IDs, customer IDs, and folder IDs can be retrieved using the List Agents, List Customers, and other Groove endpoints. For more information about Groove ticket fields, see the Groove Tickets API documentation.

Get Ticket

Retrieves the full details of a single support ticket by its ticket number. Use this endpoint when you need complete information about a specific ticket, including its status, assignee, customer, and conversation history.

• Ticket Number (required): Enter the ticket number for the ticket you want to retrieve. Ticket numbers are visible in the Groove inbox and in the ticket URL. For example, for the URL https://app.groovehq.com/tickets/1234, the ticket number is 1234.

This endpoint returns a single ticket record rather than a paginated list. For bulk ticket retrieval, use the List Tickets endpoint instead.

List Ticket Messages

Retrieves all messages (replies and notes) in the conversation thread of a specific ticket. Use this endpoint to extract the full message history for a ticket, which is useful for auditing, analysis, or exporting conversation data.

• Ticket Number (required): Enter the ticket number whose messages you want to retrieve. Messages are returned as a paginated list with 25 records per page, and Nexla automatically fetches all pages.

Messages include both customer-facing replies and internal agent notes. For more information about Groove message fields, see the Groove Tickets API documentation.

List Customers

Retrieves a paginated list of all customers in your Groove account. Use this endpoint to export your customer directory for CRM synchronization, analysis, or integration with other business systems.

• This endpoint returns all customers with no required configuration. Nexla automatically handles pagination to retrieve all available customer records (25 per page).

Customer records in Groove include contact information, ticket history links, and custom properties. For more details, see the Groove Customers API documentation.

List Agents

Retrieves a list of all support agents in your Groove account. Use this endpoint to synchronize your agent roster with other systems or to obtain agent IDs needed for filtering tickets by assignee.

• Group (optional): Enter a Groove agent group ID to return only agents belonging to that group. Leave blank to retrieve all agents across all groups.

The response includes each agent's ID, name, email address, and role. Agent IDs can be used as the Assignee filter in the List Tickets endpoint. For more information, see the Groove Agents API documentation.

List Groups

Retrieves all agent groups defined in your Groove account. Groups in Groove are used to organize agents by team, department, or function, and can be assigned to tickets for team-based routing.

• This endpoint returns all groups with no required configuration. No pagination is applied — all groups are returned in a single response.

List Knowledge Bases

Retrieves all knowledge bases configured in your Groove account. Use this endpoint to discover available knowledge bases and their IDs, which are required as input parameters for other knowledge base endpoints such as Get Knowledge Base, Search Articles, and Search Categories.

• This endpoint returns all knowledge bases with no required configuration. All records are returned in a single response without pagination.

Get Knowledge Base

Retrieves the details of a specific knowledge base by its ID. Use this endpoint to access knowledge base metadata including its name, configuration, and associated settings.

• Knowledge Base ID (required): Enter the ID of the knowledge base to retrieve. Knowledge base IDs can be obtained using the List Knowledge Bases endpoint.

Get Knowledge Base Settings

Retrieves the display and customization settings for a specific knowledge base, including branding, layout, and visibility settings. Use this endpoint to audit or back up knowledge base configuration.

• Knowledge Base ID (required): Enter the ID of the knowledge base whose settings you want to retrieve. Knowledge base IDs can be obtained using the List Knowledge Bases endpoint.

Search Categories

Searches for categories within a specific knowledge base. Categories in Groove organize knowledge base articles by topic, making it easier for customers to navigate self-service content. Use this endpoint to retrieve category metadata or to find specific categories by keyword or state.

• Knowledge Base ID (required): Enter the ID of the knowledge base in which to search. Knowledge base IDs can be obtained using the List Knowledge Bases endpoint.

• Keyword (optional): Enter a search term to filter categories by name or content.
• Author ID (optional): Enter an author ID to return only categories created by that author.
• Sort Order (optional): Enter a field name to sort results, such as created_at or name.
• State (optional): Enter a state value to filter categories. Supported values include published and draft.
• Unpaginated (optional): Set to true to return all results in a single response without pagination. By default, results are paginated at 10 per page.

For more information about Groove knowledge base categories, see the Groove KB Categories API documentation.

Search Articles

Searches for articles within a specific knowledge base using multiple filter options. Use this endpoint to retrieve published or draft articles, filter by author or category, or find specific articles by tag or ID.

• Knowledge Base ID (required): Enter the ID of the knowledge base in which to search for articles.

• Keyword (optional): Enter a search term to filter articles by title, body, or content.
• Author ID (optional): Enter an author ID to return only articles created by that author.
• Category ID (optional): Enter a category ID to return only articles belonging to that category.
• Featured (optional): Set to true to return only articles marked as featured in the knowledge base.
• IDs (optional): Enter a comma-separated list of article IDs to retrieve specific articles by ID.
• Sort Order (optional): Enter a field name to sort results, such as created_at or title.
• State (optional): Enter a state value to filter articles. Supported values include published and draft.
• Tag (optional): Enter a tag to filter articles associated with that tag.
• Unpaginated (optional): Set to true to return all matching articles in a single response without pagination. By default, results are paginated at 10 per page.

For more information about Groove knowledge base articles, see the Groove KB Articles API documentation.

Get Article

Retrieves a specific knowledge base article by its ID. Use this endpoint to access the full content of an individual article, including its title, body, category, tags, and publication status.

• Knowledge Base ID (required): Enter the ID of the knowledge base that contains the article. Knowledge base IDs can be obtained using the List Knowledge Bases endpoint.

• Article ID (required): Enter the ID of the article to retrieve. Article IDs can be obtained using the Search Articles endpoint.

List Widgets

Retrieves all widgets configured in your Groove account. Groove widgets are embeddable chat or contact forms that appear on your website to enable customer interactions. Use this endpoint to audit your widget configurations or retrieve widget IDs for use with other widget endpoints.

• This endpoint returns all widgets with no required configuration. All records are returned in a single response without pagination.

For more information about Groove widgets, see the Groove Widgets API documentation.

Get Widget

Retrieves the details of a specific widget by its ID. Use this endpoint to access the full configuration of an individual Groove widget, including its type, settings, and display options.

• Widget ID (required): Enter the ID of the widget to retrieve. Widget IDs can be obtained using the List Widgets endpoint.

List Widget Settings

Retrieves all configuration settings for a specific Groove widget. Use this endpoint to audit or export the detailed settings of a widget, such as its appearance, behavior, and knowledge base association.

• Widget ID (required): Enter the ID of the widget whose settings you want to retrieve. Widget IDs can be obtained using the List Widgets endpoint.

Search Articles (Public)

Searches for publicly accessible articles in a knowledge base using the public Groove API endpoint. This endpoint is intended for retrieving articles as they appear to end customers (i.e., published articles only), making it suitable for integrating public knowledge base content into other customer-facing tools.

• Knowledge Base ID (optional): Enter the ID of the knowledge base to search. If not specified, all public knowledge bases are searched.
• Keyword (optional): Enter a search keyword to filter articles by title or content.
• Category ID (optional): Enter a category ID to limit results to articles in that category.
• Featured (optional): Set to true to return only featured articles.
• Article IDs (optional): Enter a comma-separated list of article IDs to retrieve specific articles.
• Tag (optional): Enter a tag to filter articles associated with that tag.

This endpoint accesses Groove's public API at https://api.groovehq.com/v1/kb/public/{'{kb_id}'}/articles/search and returns only published articles visible to customers. For administrative access to draft and published articles, use the Search Articles endpoint instead.

Get Widget (Public)

Retrieves a specific Groove widget by its UUID using the public API endpoint. Use this endpoint to access public-facing widget configuration details.

• Widget UUID (optional): Enter the UUID of the widget to retrieve. Widget UUIDs can be found in your Groove widget settings.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Groove data sources can be manually configured to ingest data from any valid Groove API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Groove sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom request parameters.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Groove API from the Method pulldown menu. The most common methods are:

   • GET: For retrieving data from the API
   • POST: For sending data to the API or triggering actions
   • PUT: For updating existing data
   • PATCH: For partial updates to existing data
   • DELETE: For removing data

API Endpoint URL

3. Enter the URL of the Groove API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters.

   All Groove API v1 endpoints follow the base URL format https://api.groovehq.com/v1/. For example, to list tickets the full URL would be https://api.groovehq.com/v1/tickets.

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL. For a complete list of available Groove API endpoints, see the Groove Developer documentation.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Macros are particularly useful for Groove APIs that support date range filtering, enabling you to retrieve only tickets or articles created or updated within a specific time window.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when building Groove sources that iterate over a list of ticket numbers, knowledge base IDs, or other identifiers retrieved from a prior data source.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by the Groove API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

For example, the Groove List Tickets endpoint returns a JSON object with a top-level tickets array. By specifying the path $.tickets[*], you instruct Nexla to treat each element of that array as an individual record rather than treating the entire response as one record.

Path to Data is essential when Groove API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.tickets[*] to access the tickets array, or $.articles[*] to access articles).
  Path to Data Example:

  If the Groove API response is in JSON format and includes a top-level array named tickets that contains the relevant data, the path to the response would be entered as $.tickets[*].

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful for preserving important contextual information that applies to all records.

For example, many Groove API list endpoints return pagination metadata alongside the records array. If you have specified $.tickets[*] as the path to data, any top-level fields such as total_count or meta can be included as metadata in each record by specifying the appropriate metadata path.

Metadata paths are particularly useful for preserving Groove API response context like pagination metadata, total record counts, or request timestamps that apply to all records in the response.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers may be required for Groove API versioning or custom request requirements.

  You do not need to include the Authorization header here — it is automatically provided by the Groove credential you selected. The Groove API key is passed as a Bearer token in the Authorization header by Nexla on every request.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Groove data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.