Slack

Slack is a communications platform that makes it easy to message team members and collaborate on projects. By integrating Slack with Cortex, you can conveniently access information from Cortex without opening the app.

In this guide, you’ll learn how to set up and use the Slack integration. The Cortex app in Slack has the following capabilities:

• Onboarding management and guidance

• On-call assistant (PagerDuty only)

• Notifications:

• Weekly summaries of entity performance

• Querying entity metadata through the Cortex bot

Setup and configuration

Getting started

Users must have admin permissions in Cortex to set up the Slack integration, and must be designated as an administrator in Slack to install Cortex's app.

Configuration

You can connect your Slack workspace directly from Slack settings in Cortex. If your workspace isn't already linked, you'll see the option to connect with Slack. Follow the prompts in the modal to set up the integration.

If you're using a self-managed Cortex instance, you'll need to follow a manual configuration process to use Cortex's app for Slack. Reach out to the support team to receive instructions.

Managing Slack notifications

Admins can enable or disable notifications for users and teams by toggling Enable Slack notifications under Notifications availability in notifications settings.

From this page, you can enable or disable specific notification types for all users in your organization.

Note that notifications can be sent to private Slack channels, but the Cortex Slack Bot must be a member of the channel in order for the notification to be delivered to the channel.

You can also define a CQL query that will limit the notifications you receive. Any entities that do not match your query will be excluded from all notifications, while those that do match the query will continue triggering notifications for owners.

These queries cannot use third-party integrations. Common allowed queries include groups and custom data filters.

Registration

Entity descriptor

Define one of the following blocks in an entity descriptor for any entity type to add Slack channels by name or ID. Defining a Slack channel will enable direct access to the channel from the entity's page in Cortex.

You can define a channel with either the name or ID blocks below. When you define by name, it'll be immediately recognizable in the entity's YAML. However, if a Slack channel's name is likely to change, it's better to define by ID, because it won't break during renames.

You can manually add any Slack channels this way without setting up the integration via the API. Slack uses a redirect feature based on the channel's name to find the channel after directly logging in: slack.com/app_redirect?channel=.

All of the following definitions include a notificationsEnabled field. If notificationsEnabled=true, owners will receive relevant notifications, unless they have disabled notifications.

Defining notificationsEnabled=false will exclude an entity from certain notifications.

Defining by channel names

x-cortex-slack:
  channels:
  - name: team-engineering
    notificationsEnabled: true
    description: A description for this Slack channel.

Field	Description	Required
name	Slack channel name	✓
notificationsEnabled	Boolean to enable/disable notifications in Slack	✓
description	Description for the Slack channel

Defining by channel IDs

We recommend registering Slack channels by ID, as channel names may change.

x-cortex-slack:
  channels:
  - id: ABCDEF123
    notificationsEnabled: true
    description: This is a description for this Slack channel

Field	Description	Required
id	Slack channel ID	✓
notificationsEnabled	Boolean to enable/disable notifications in Slack	✓
description	Description for the Slack channel

Ownership

You can also define Slack channels for an entity in the x-cortex-owners block:

x-cortex-owners:
  - type: SLACK
    channel: entity-channel
    notificationsEnabled: true

Field	Description	Required
type	Type of message method (e.g. Slack, email)	✓
channel	Slack channel name	✓
notificationsEnabled	Boolean to enable/disable notifications in Slack	✓

This approach makes more sense for Slack channels that are dedicated to specific projects or entities, rather than channels that are associated with teams, since those channels are less likely to be renamed.

Identity mappings

Cortex maps email addresses in your organization's Slack workspace to email addresses that belong to team members, so you never need to define email addresses in the entity descriptor.

You can confirm that users' Slack accounts are connected from the Onboarding management tool or from the identity mappings section in settings.

Expected results

Entity pages

Once the integration with Slack is set up, you'll be able to find registered Slack channels from a given entity's details page. Slack channels will appear at the top of the Overview page in a Slack channels block. You can click any channel name to go directly to that channel in Slack.

Scorecards and CQL

With the Slack integration, you can create Scorecard rules and write CQL queries based on Slack channels.

See more examples in the CQL Explorer in Cortex.

Check if Slack channel is set

Checks if an entity has a registered Slack channel in its entity descriptor.

Definition: slack (==/!=) null

Example

For a Scorecard focused on onboarding entities, you can define a rule to make sure each entity has a registered Slack channel:

slack != null

Defining a rule to make sure a Slack channel is set is a good way to make sure that users can reach out to entity owners for more information or if an issue arises.

Number of Slack channels

Counts the number of Slack channels registered for a given entity.

Definition: slack.channels().length

Example

Similar to slack != null, you can use this expression to write a rule checking that entities are linked to a Slack channnel:

slack.channels().length > 0

This rule makes sure that there is at least one Slack channel set.

Total number of members across Slack channel

Counts the total number of members across all registered Slack channels.

Definition: slack.numOfMembers()

Example

You can use this expression in the Query Builder to find entities linked to empty Slack channels:

slack.numOfMembers() < 1

If an entity is linked to an empty Slack channel, it might indicate a gap in your notification process.

Cortex bot

After configuring the Slack integration, you can message the Cortex bot from your Slack workspace.

You'll also begin receiving notifications from the Cortex bot:

The following notifications are dependent upon permission levels:

• Integration configurations are invalid and need to be updated (workspace admins)

• A Scorecard rule exemption has been requested (users with 'configure Scorecard' permissions)

In addition, the Cortex app will send user- and team-based weekly reports. The weekly report for users summarizes how their entities are tracking against Scorecards and initiatives; the report for teams delivers the same summary for entities owned by that team.

Depending on the other integrations you've set up, you may also receive notifications though Slack from the PagerDuty-enabled on-call assistant.

Commands

Using the below commands in Slack, you can quickly query entity metadata and Scorecard scores. The `` refers to the entity tag.

Command	Result
/cortex dependencies	List all incoming and outgoing first-level dependencies
/cortex deploys	List recent deploys
/cortex docs	List all documentation links
/cortex domain	List domain information, such as owners, on-call, links, and timeline events
/cortex entity	List information for any entity, combining the behavior of service, team, domain and resource
/cortex help	Display the full list of commands
/cortex links	List all links
/cortex links [type]	List all links of a type parameter, such as metrics or openapi
/cortex logs	List all logs links
/cortex oncall	Find current on-call info
/cortex owners	List all owners and their email addresses
/cortex resource	List resource information, such as owners, on-call, links, and timeline events
/cortex runbooks	List all runbook links
/cortex scores	List all Scorecard scores
/cortex search	Query for entities using Lucene queries
/cortex sentry	List recent Sentry issues
/cortex service	List service information, such as owners, on-call, links, and timeline events
/cortex team	List team information, such as owned entities, links, and timeline events
/cortex timeline	List recent timeline events

AI assistant

The AI assistant is in a closed beta. Please contact your customer success manager if you're interested in participating in our public beta.

As with all Large Language Models (LLM), the AI Assistant may not provide accurate responses. Please reach out to Cortex Customer Engineering if you encounter any issues.

The Cortex AI assistant is a conversational interface that helps you navigate Cortex. You can ask the assistant questions about entities, Scorecards, and more.

Background sync

Cortex conducts a background sync of Slack identities every day at 10 a.m. UTC.

FAQs and troubleshooting

What if I use a different secret manager?

If you use something other than the K8s secret manager, you don't need to base64 encode your credentials.

Where do I set my credentials?

You only need to set credentials in the backend.

Can users access information via the Slackbot if they haven't logged in to our Cortex instance?

Yes, this is possible, depending on the settings you configured for the Slack Bot in your workspace. To allow users to use the Slack Bot without logging in to Cortex, navigate to the Slack integration settings page in Cortex and disable the toggle next to Require Cortex account to use Cortex's Slack app.

Privacy policy

Cortex retains basic Slack metadata like user IDs for the period necessary to fulfill the purposes outlined in our Privacy Policy unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.

To request to access, transfer, or delete data, you can reach out to the Cortex support team.

Still need help?​

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: [e-mail], or open a support ticket in the in app Resource Center

• Chat: Available in the Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.