Add or Edit a Slack Source

Index Content Coveo Relevance Cloud Developer System Administrator Product Documentation

Enterprise

Slack workspace administrators can index the content of a Slack workspace and make it searchable to workspace members through a Coveo-powered search interface. To do so, as a member of the Administrators or Content Managers built-in groups, you must create a Slack source in your Coveo organization.

You can index messages, including files and attachments, from specific public and private channels, and choose to index all channel information (separate from message data) and user-profile data. When a member of your Slack workspace clicks a query result in a Coveo-powered search interface, the user is redirected to the corresponding item in Slack.

Your Slack source provides the Coveo organization with authorization to access your Slack workspace items using an OAuth 2.0 access token. The access token is linked to the Slack bot that you create for your source. The Slack bot is installed in your workspace and added to the channels that you want to index.

Note

Coveo also offers a Coveo for Slack app that adds a Coveo-powered search interface directly in Slack. You can use the Coveo for Slack app to provide your Slack workspace members with access to your organization’s indexed content, including content indexed using your Slack source, directly in Slack.
Tip
Leading practice

The number of items that a source processes per hour (crawling speed) depends on various factors, such as network bandwidth and source configuration. See About Crawling Speed for information on what can impact crawling speed, as well as possible solutions.

Source Key Characteristics

Features Supported Additional information

Slack version

Latest version

Searchable content types

check

Messages, channels, user profiles, files, and attachments.

Content update operations

Refresh

check

To set an automatic refresh schedule, see Schedule a Source Update.

A rescan or rebuild is required to take account of deleted messages, channels, and user profiles, and to retrieve replies to messages.

Rescan

check

To set an automatic rescan schedule, see Schedule a Source Update.

Extracts all of the data and indexes new items and existing items with a modified date greater than the date in the index.

The data that your source scans depends on the Earliest message to index (in days) option.

Rebuild

check

The data that your source scans depends on the Earliest message to index (in days) option.

Content security options

Same users and groups as in your content system

check

Specific users and groups

check

Everyone

check

Requirements

Prior to creating a new Slack source:

  • Create a Slack bot and install it on your workspace and channels.

  • (Optional) Create a Slack export file that your Slack source uses for the initial build, as well as subsequent rescans and rebuilds, to index your Slack items.

    Note

    The use of a Slack export file adds a certain level of complexity to your integration and isn’t required or recommended in most cases. However, this may be a viable option in certain use cases to limit the amount of data that’s crawled by the Slack connector when indexing numerous channels with large numbers of items.

Add or Edit a Slack Source

  1. Before you create a new Slack source, ensure that you’ve performed the tasks detailed in the Requirements section.

  2. On the Sources (platform-ca | platform-eu | platform-au) page, do one of the following:

    • To create a new source, click Add source, and then click Slack.

    • To edit an existing source, click your Slack source, and then click Edit in the Action bar.

  3. Specify your source settings in the Add/Edit a Slack Source subpage. Refer to the following sections for detailed information on the source settings:

    Note

    You can save your source settings at any time by clicking Add and build source/Add source, or Save and rebuild source/Save.

  4. Build or rebuild your source.

"Configuration" Tab

In the Add/Edit a Slack Source subpage, the Configuration tab is selected by default. It contains your source’s general and content information, as well as other parameters.

Source Name

Enter a name for your source.

Tip
Leading practice

A source name can’t be modified once it’s saved, therefore be sure to use a short and descriptive name, using letters, numbers, hyphens (-), and underscores (_). Avoid spaces and other special characters.

Export Data URL

If you’re using a Slack export file, enter the direct URL of your hosted .zip file. You must modify the URL so that it’s a direct download link. This forces your Slack source to download the export file when indexing.

Examples

  • Dropbox

    If the original URL is https://www.dropbox.com/…​zip?dl=0, modify the URL by adding or replacing the dl parameter at the end of the URL so that it’s dl=1, such as https://www.dropbox.com/…​zip?dl=1.

  • Google Drive

    Use this URL format: https://drive.google.com/uc?export=download&id=<DRIVE_FILE_ID>, where DRIVE_FILE_ID is the unique id of your file. If the original URL is https://drive.google.com/file/d/123456789/view?usp=sharing, modify the URL so that it’s https://drive.google.com/file/uc?export=download&id=123456789.

Note

Your Slack source downloads the export file during each rescan/rebuild. If you delete the export file from your Cloud storage system, or remove the Export Data URL, your source won’t use the export file for subsequent rescans/rebuilds.

"Authentication" Section

Your Slack source authorizes the Coveo organization to access your workspace items using your Slack bot’s OAuth 2.0 access token.

  1. Get your Bot OAuth Token as follows:

    1. Access the Your Apps page of the Slack API website.

    2. Click the app that’s associated with your Slack bot.

    3. Click OAuth & Permissions in the left menu.

    4. Under OAuth Tokens for Your Workspace, copy the Bot User OAuth Token.

  2. In the Authentication section of your Slack source, paste the token in the Access token field.

"Content to Include" Section

Your Slack source automatically indexes the messages from the active public channels to which your Slack bot is added. However, you can modify your source to also index messages from private channels, only a subset of your message history, or other types of items using the options in this section.

Notes

  • To display message replies hierarchically below the parent message in your search interface result list, you must enable result folding in your search page.

  • The Channels to Index section lists all the channels to which your Slack bot is currently added.
Option Description

Earliest message to index (in days)

This option defines the maximum number of days for which your source indexes message data during a build/rebuild or rescan. The amount of message data present in your Slack channels can be quite large. Therefore, you can use this option to limit the amount of data that’s scanned and indexed/re-indexed in order to accelerate the indexing operation. If you choose to index Channels and Users, this option doesn’t limit the channel data (separate from messages) and user data that your source indexes.

Set the number of days for which to index message data based on when the message is created or modified. By default, this option is set to 0 to index all message data. For example, if you set a value of 5, your source indexes new and modified message data only for the last five days. This means that if a message was created six days ago, the message does not appear in query results in a Coveo search interface. Your source considers replies to messages to be new messages. If a Slack member replies to a message today, and the message was originally created six days ago, your source indexes the reply to the message as the reply’s creation date falls within the specified indexing timeline. If the value is 0, your source indexes all message data regardless of when the message was created or modified.

If you’re using a Slack export file in your source, be aware that this setting impacts the message data that your source indexes from your export file. For more information and examples, see Interaction With "Earliest Message To Index" Source Option.

Private channels

Select this option to index the messages from private channels to which your Slack bot is added.

Important

Select the Same users and groups as in your content system content security option to ensure that only members of the private channel have access to the channel’s content in a Coveo-powered search interface.
Note

To index the content of private channels, your Slack bot must include the groups:history and groups:read bot token scopes.

Channels

Select this option to index every channel in your workspace as a separate item. When a query matches the channel name, the channel appears as a separate result in a Coveo search interface.

Note

This option applies only to channel data and not to the indexing of channel messages. Your source automatically indexes the messages from public channels, and private channels if the Private channels option is selected, to which your Slack bot is added.

Files and attachments

Select this option to index the files and attachments in messages as separate items. This allows users to search for filenames or content within a file/attachment. When a query matches the filename or content of a file, the file appears as a separate result in a Coveo search interface. If this option is disabled, files and attachments aren’t indexed, and therefore aren’t searchable in a Coveo search interface.

Your source is configured to index the most common file types by default, such as .doc, .xls, .pdf, .txt, .html, and .json. We recommend that you review your source JSON configuration to view and modify the list of supported item types.

Bot messages

Select this option to index Slack bot and integration messages.

Users

Select this option to index the user profiles in your workspace. When a query matches a name or display name in Slack, the user appears as a separate result in a Coveo search interface. When combined with the Files and attachments option, users can filter search results based on the document author.

Deleted and archived users

This option appears only if you chose to index Users. If so, you can also choose to index the user profiles of deleted and archived users in your workspace.
Note

If you archive a previously indexed Slack channel, your source removes all corresponding data from the index following a rescan or rebuild.

"Channels to Index" Section

This section lists all the Slack channels to which your Slack bot is added.

Your Slack source indexes the messages for the channels that contain your Slack bot. Therefore, you can use this section as a reference to see which channels are indexed from your Slack workspace.

Note

The list of channels corresponds to the Slack bot that’s associated with the access token you entered in the Authentication section. The channel list populates only after you save the Slack source.

"Content Security" Tab

Select who will be able to access the source items through a Coveo-powered search interface. For details on this parameter, see Content Security.

Note

We recommend selecting the Same users and groups as in your content system option to ensure that workspace content is accessible only by intended users based on your Slack permission system. With this option enabled, an active Slack workspace member has access to message data for all public channels in the workspace, but only for private channels in which they’re a member.
Important

When using the Everyone content security option, see Safely Apply Content Filtering for information on how to ensure that your source content is safely filtered and only accessible by intended users.

"Access" Tab

In the Access tab, set whether each group and API key can view or edit the source configuration (see Resource Access):

  1. If available, in the left pane, click Groups or API Keys to select the appropriate list.

  2. In the Access Level column for groups or API keys with access to source content, select View or Edit.

Enable Result Folding for Slack Threads

To display replies from a Slack thread in your search results and group the replies with the original message, you must enable result folding in your search page. This enhances the end-user experience as users expect query results that belong to the same conversation to be displayed in such a way that the original message is represented as the parent of each subsequent reply.

Example

The following image shows replies in a Slack thread grouped under the parent message in a search page with result folding enabled.

Slack Message Thread
Note

The Coveo for Slack app search interface doesn’t support result folding, therefore replies appear as separate items in search results.

If you’re using a classic hosted search page or the JavaScript Search Framework for your search interface, you must use the FoldingForThread component to enable result folding in your search page.

Your Slack source includes default preconfigured fields (foldingcollection, foldingchild, and foldingparent) in your index for use with your result folding implementation.

Note

For hosted search pages, a CoveoFolding component is automatically added to your search page. Open the Interface Editor via the Search Pages (platform-ca | platform-eu | platform-au) page, and then, in the Code View tab, replace CoveoFolding with CoveoFoldingForThread. Folded results are automatically rendered when using the prebuilt Slack result template with hosted search pages.

If you’re using Headless or REST API for your search interface, refer to the corresponding documentation for information on how to implement result folding in search results:

Verify and Edit Your Source Fields and Mappings

Mappings define what Coveo index fields contain for each source item. Your Slack source automatically includes mapping rules for the fields that are indexed.

The default mapping rules are suitable in most instances, however you can modify the mappings as required.

Do one or both of the following to verify and edit your field mappings:

Create Additional Source Fields and Mappings (Optional)

In certain situations, you may want to create a field in addition to the fields that are created automatically by your source. For example, you may want to create a field that’s used across multiple sources and mapped to different metadata for each source, or you may want to create a field that aggregates multiple metadata for a single source.

To create additional fields and mappings:

  1. Add a field to the Coveo index manually.

  2. Create a mapping rule in each source that you want to use the new field.

  3. Build the sources that you modified.

Safely Apply Content Filtering

The best way to ensure that your indexed content is seen only by the intended users is to enforce content security by selecting the Same users and groups as in your content system option. Should this option be unavailable, select Specific users and groups instead.

However, if you need to configure your source so that the indexed source content is accessible to Everyone, you should adhere to the following leading practices to ensure that your source content is safely filtered and only accessible by the appropriate users:

Following the above leading practices results in a workflow whereby the user query is authenticated server side via a search token that enforces the search hub from which the query originates. Therefore, the query can’t be modified by users or client-side code. The query then passes through a specific query pipeline based on a search hub condition, and the query results are filtered using the filter rules.

Configure Query Filters

Filter rules allow you to enter hidden query expressions to be added to all queries going through a given query pipeline. They’re typically used to add a field-based expression to the constant query expression (cq).

Example

You apply the @objectType=="Solution" query filter to the pipeline to which the traffic of your public support portal is directed. As a result, the @objectType=="Solution" query expression is added to any query sent via this support portal.

Therefore, if a user types Speedbit watch wristband in the searchbox, the items returned are those that match these keywords and whose objectType has the Solution value. Items matching these keywords but having a different objectType value aren’t returned in the user’s search results.

To learn how to configure query pipeline filter rules, see Manage Filter Rules.

Note

You can also enforce a filter expression directly in the search token.

Use Condition-Based Query Pipeline Routing

The most recommended and flexible query pipeline routing mechanism is condition-based routing.

When using this routing mechanism, you ensure that search requests are routed to a specific query pipeline according to the search interface from which they originate, and the authentication is done server side.

To accomplish this:

  1. Apply a condition to a query pipeline based on a search hub value, such as Search Hub is Community Search or Search Hub is Agent Panel. This condition ensures that all queries that originate from a specific search hub go through that query pipeline.

  2. Authenticate user queries via a search token that’s generated server side and that contains the search hub parameter that you specified in the query pipeline.

Configure the Search Token

When using query filters to secure content, the safest way to enforce content security is to authenticate user queries using a search token that’s generated server side. For instance, when using this approach, you can enforce a search hub value in the search token. This makes every authenticated request that originates from a component use the specified search hub, and therefore be routed to the proper query pipeline. Because this configuration is stored server side and encrypted in the search token, it can’t be modified by users or client-side code.

Implementing search token authentication requires you to add server side logic to your web site or application. Therefore, the actual implementation details will vary from one project to another.

The following procedure provides general guidelines:

Note

If you’re using the Coveo In-Product Experience (IPX) feature, see Implementing Advanced Search Token Authentication.

  1. Authenticate the user.

  2. Call a service exposed through Coveo to request a search token for the authenticated user.

  3. Specify the userIDs for the search token, and enforce a searchHub parameter in the search token.

Note

You can specify other parameters in the search token, such as a query filter.

For more information and examples, see Search Token Authentication.

Build or Rebuild Your Source

You must build the source in order for Coveo to retrieve the source content and apply changes to your source settings. You can build or rebuild your source as follows:

  • You can choose to build when saving the source by clicking Add and build source/Save and rebuild source.

  • If you chose not to build when saving your source settings, you can build your source directly from the Sources (platform-ca | platform-eu | platform-au) page by clicking Launch build in the Status column for your source. If Launch build doesn’t appear on the Sources (platform-ca | platform-eu | platform-au) page for your source, click the source, and then click More > Rebuild in the Action bar.

Once the source is built, you can review its content in the Content Browser.