Slack

CatalogNotificationsScorecards

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:
  • Entity score evaluation
  • Initiative creation and reminders
  • Integration configuration errors
  • API key expiration
  • Rule exemption request
• Weekly summaries of entity performance
• Querying entity metadata through the Cortex bot

Permissions

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.

caution

You need to be a Slack administrator in order to install Cortex's app for Slack.

Privacy policy

We will retain 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.

Setup and configuration

Configuration

You can connect your Slack instance directly from Settings in Cortex. If your instance isn't linked, you'll see the option to connect with Slack.

caution

If you do not see the Settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.

Follow the prompts in the modal window to set up the integration. If you've set up everything correctly, you'll see the option to Remove Integration in Settings.

You can also use the Test configuration button to confirm that the integration was successful. If your configuration is valid, you'll see a banner that says "Configuration is valid. If you see issues, please see documentation or reach out to Cortex support."

caution

If you're using Cortex Server, 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.

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.

x-cortex-slack:
  channels:
  # List Slack channel names, *without* the preceeding "#"
  - name: team-engineering
    notificationsEnabled: true
    description: This is a description for this Slack channel # optional

x-cortex-slack:
  channels:
  # List Slack channel IDs. People prefer using this option when Slack channels are likely to change names.
  - id: ABCDEF123
    notificationsEnabled: true
    description: This is a description for this Slack channel # optional

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={channel_name}

Identity mapping

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

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

Expected results

If everything works as expected, you'll be able to message the Cortex bot from your Slack instance.

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

• When scores for an entity you own are re-evaluated due to cortex.yaml changes
• Information about recently created initiatives you are included in
• Reminders a few days before an initiative expires, including remaining action items
• When your on-call for an entity changes
• When on-call for an entity owned by a team you belong to changes
• Reminders a few days before you are on call
• When a scheduled rule is added to a Scorecard
• Reminders that a scheduled rule is going into effect 7 days and 1 day before

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.

Limit notifications through CQL

From settings, you can 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.

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

Cortex bot commands

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

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

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.

Still need help?

The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

• Email: help@cortex.io, 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.