Notifications
Notifications are built into Cortex to help users stay on top of changes within their environments and the platform. Admins can configure notifications for the entire workspace, while users can configure their personal notification subscriptions.
See the full list of notification options under Notification subscription options in Cortex.
Notification markdown limitations
It is possible to use markdown in some fields in Cortex. Some of these fields, such as the description field for an entity verification policy, appear in notifications. While Cortex will render markdown as expected in the UI, Slack and email notifications may have issues rendering some markdown.
Markdown limitations include, but are not limited to, the following:
- The first element in the description cannot start with
#. - Slack supports basic lists, but nested lists are not supported.
- Multi-line code blocks will lose formatting in Slack.
- Inline images with standard markdown (
) will not be displayed in Slack. - Strike-through syntax does not render in Slack.
- Line breaks may not render in Slack.
- Hyperlinks may not be clickable in emails.
To read about other Slack limitations, please see Markdown Guide's documentation on using Markdown in Slack.
Setting notifications for the entire workspace
In the Notifications settings page in Cortex, admins can enable notifications and refine the types of notifications received by users and teams across the workspace.
Admins can also enable some notifications to be sent to entity Slack channels.
By default, all notification methods and types will be enabled.
Configure how users receive notifications
Notifications availability settings determine how notifications go out to users. Admins can enable Slack, Microsoft Teams, or email notifications and can enable notifications for users outside of Cortex who own entities.
Define notifications for team members in the entity descriptor
If you are configuring the members list for a team entity via an entity descriptor, you can define the notificationsEnabled field as true or false.
When notificationsEnabled=true, users/teams will receive all enabled notification types that apply to them.
When notificationsEnabled=false, affected users/teams will not receive the following notification types:
- Initiative creation and upcoming deadlines
- Scheduled Scorecard rule creation and activation
- Verification period initiation and reminders
- Weekly report
Certain notifications can also be disabled at the entity level. If notificationsEnabled=false for a non-user/team entity, Cortex will not send the following notifications:
- Broken Open API spec
- Entity evaluation
- Workflow status updates and pending approvals
Regardless of whether notificationsEnabled is true or false, entities will receive most notifications types determined by an admin when an update occurs:
- API token expiration
- Entitlement expirations
- Integration configuration errors
- On-call assistant
- On-call rotation changes and reminders
- Onboarding messages
- Pending Scorecard rule exemptions
- Team inivations
Adjusting your personal notification subscriptions
Notification subscriptions allow users to further refine the notifications they receive. These settings will override workspace notifications, effectively allowing a user to "unsubscribe" from a given notification type.
For example, if a workspace admin has enabled Entity evaluation in workspace notifications, but a user has disabled Entity evaluation in Notification subscriptions, the user will not receive updates when Scorecard scores change for their entities.
To adjust which notifications you receive:
- Click your avatar in the lower left corner of Cortex, then click Settings.
- Under "Preferences," click Notification subscriptions.
- For each option, use the toggle switch to enable or disable notifications. Users can determine which notifications they receive from Notification subscriptions in the Preferences section of settings.
If an admin has disabled a notification type in workspace notifications, users will not be able to enable it. Disabled notification subscriptions will be grayed out. You'll also see "NOTE: This notification has been disabled by your Admin" appear below disabled subscriptions.
If a notification type has been enabled, but the notification method (e.g., Slack, MS Teams, or email) is disabled, the same note will appear under the notification method toggle for each notification type.
Notification subscription options in Cortex
Workspace notification subscriptions determine the types of notifications that are sent to users. For each subscription, admins can enable or disable notifications via Slack, MS Teams, and email.
If an entity channel and owner channel are the same, Cortex will not send duplicate notifications; in this case, Cortex will only send the owner a notification.
Onboarding tips (users only)
Onboarding tip notifications send out important information about getting started with Cortex. This notification can be enabled or disabled for the workspace and your personal notification settings.
Entity evaluation (users only)
Entity evaluation notifications go out to users when an entity they own is re-evaluated by a Scorecard due to changes in its cortex.yaml file. This alert will tell you whether the score for that entity has increased or decreased.
You will not receive a notification if the score is unchanged after Cortex processes the changes.
Initiative creation (users, teams, and entities)
Initiative creation notifications alert teams when at least one entity they own is included in a recently created Initiative. These notifications include action items associated with entities owned by that team.
Initiative creation notifications are sent to users when entities they own are included in a recently created Initiative. Initiative creation notifications will go to users when an entity is not owned by a team, and/or when the Initiative creation - Teams notification is disabled.
Initiative creation notifications are sent to entity channels when the entity is included in a recently created Initiative. Cortex checks for created Initiatives and sends relevant notifications every 10 minutes.
Initiative custom scheduled reminders (users and teams)
Initiative custom scheduled reminders send progress notifications to users that are part of a given Initiative. The Initiative owner can determine the cadence of these reminders when creating or editing an Initiative.
Initiative reminders (users and teams)
Initiative reminders alert users 7 days and 1 day before an Initiative's target date. The notification will include the amount of time that remains for an Initiative and a given user's uncompleted action items.
Integration configuration errors (admins only)
Integration configuration error notifications notify users with Configure settings permissions when the configuration for an integration has been changed and is no longer valid.
Cortex runs a nightly cron job that checks to ensure configurations are valid; when it detects a change that makes the configuration invalid, admins will receive a notification around 2 p.m. UTC alerting them to fix it.
On-call changes (users, teams, and entities)
On-call change notifications are sent to users, teams, and/or entities when the appointed user on call changes. These notifications will go out about 1 hour before an on-call shift.
On-call reminder (users only)
On-call reminder notifications notify the user on call for a given entity 7 days and 1 day before an on-call shift. Reminder notifications don’t have to go to a designated entity owner.
Rule exemption request (users only)
Rule exemption request notifications alert users with Configure Scorecards permissions when a rule exemption is requested for a given Scorecard.
Cortex checks for requested rule exemptions and sends relevant notifications every 10 minutes.
New scheduled rules created (users, teams, and entities)
New scheduled rules created notifications go to users, teams, and/or entities when a scheduled rule is added to a Scorecard evaluating an entity they own.
Scheduled rules reminder (users, teams, and entities)
Scheduled rules reminders are sent to users, teams, and/or entities 7 days and 1 day before a scheduled Scorecard rule impacting one of their owned entities goes into effect.
Score drop (teams and entities)
Score drop notifications go to teams and entities after an entity is evaluated by a Scorecard, if its score dropped.
Verification period started (users only)
Verification period started notifications go out to users when a verification period begins that impacts one of their entities.
Verification period reminder (users only)
Verification period reminders go out to users on Mondays with information about entities that require verification during ongoing verification periods.
Weekly report (users, teams, and entities)
Weekly report notifications go out to users, teams, and/or entities on Mondays with information about entities associated with that user. These notifications will let users know how their entities are performing against Scorecards and Initiatives. This will include scores that improved or dropped, pull requests that are open and waiting for your review, and Jira tickets assigned to you.
The team-based weekly report notification also includes information about who is on call for entities owned by that team.
Workflow status (users only)
Workflow status updates go out to users if a workflow fails or if someone runs a workflow that requires approval.
How notifications are triggered
| Notification type | Cortex will notify you: |
|---|---|
| Entity evaluation | When Scorecard scores for a given entity are re-evaluated because of changes to that entity's cortex.yaml |
| Initiative creation | With information about recently created Initiatives you are a part of |
| Initiative custom scheduled reminders | Information about a given Initiative's progress at a cadence defined by the Initiative owner |
| Initiative reminders | Reminders a few days before a given Initiative expires with the remaining action items |
| Integration configuration errors | If any of your integration configurations are invalid and need to be updated |
| Onboarding tips | With a welcome message and important information, including a set of onboarding tips |
| On-call changes | When on-call changes for an entity you own |
| On-call reminder | With a reminder a few days before you're on call |
| Rule exemption request | When a Scorecard rule exemption is requested |
| Weekly report | Details about how your entities are tracking against Scorecards and Initiatives (sent on Mondays) |
| Workflow status | When a workflow fails or someone runs a workflow that requires approval |