# Create a Scorecard
Use Scorecards to establish best practices, track migration, promote accountability among teams, enforce standardization across entities, or define maturity standards.
This page explains how to create a Scorecard from the Cortex UI. For instructions on creating Scorecards via GitOps, see [Scorecards as code](https://docs.cortex.io/standardize/scorecards/scorecards-as-code). You can also work with Scorecards via the [Cortex API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/scorecards).
Learn about reviewing, evaluating, and taking action on failed rules in [Review and evaluate Scorecards](https://docs.cortex.io/standardize/scorecards/evaluate).
### Common Scorecard use cases
For information about common use cases and examples, see [Scorecard examples](#scorecard-examples).
{% hint style="success" %}
Looking to dive deeper? Check out the [Cortex Academy course on Scorecards](https://academy.cortex.io/courses/understanding-scorecards), available to all Cortex customers and POVs.
{% endhint %}
## How to create Scorecards
### Prerequisites
* To create a Scorecard, you must have the admin or manager role, or you must have a custom role that includes the permission `Edit Scorecards`.
* Scorecards evaluate entities, so before using Scorecards, make sure you have [entities in your catalogs](https://docs.cortex.io/ingesting-data-into-cortex/entities).
* Make sure you have set up any [integrations](https://docs.cortex.io/ingesting-data-into-cortex/integrations) you want to write rules against.
### Step 1: Configure the basic Scorecard fields
When you create a new Scorecard, you can choose from the following options:
* **Use a Scorecard template**
* **Start from scratch**
#### Option 1: Use a template
Cortex offers the following templates:
Scorecard templates
* Onboarding Scorecard
* Production Readiness
* AI Maturity
* Service Maturity
* Incident Preparedness
* Incident Response Performance
* Security Scorecard
* SOC 2 Compliance
* Vulnerability Management
* Secrets Management
* Eng Intelligence metrics
* DORA Operational Readiness
* Velocity Scorecard
* Ownership Verification
* Entity Verification
* Code Quality
* JavaScript Best Practices
* Minimum Postgres version for Aurora
* Minimum version for ElastiCache for Redis
* Minimum Lambda runtime versions
* Empty Scorecard with Gold/Silver/Bronze levels pre-configured
Expand the tile below to learn how to create a Scorecard from a template.
Create Scorecard from template
To create a Scorecard using a template:
1. On the Scorecards page in Cortex, click **Create Scorecard**.
2. Click **Scorecard template**.
3. Click the template you want to use, then at the bottom of the page, click **Continue**.
* You will be redirected to a page that shows the default configuration for your Scorecard, including the integrations used by the Scorecard and the template's levels and rules. You will be able to modify the Scorecard on the next page.
4. Click **Continue** at the bottom of the Scorecard default configuration page.
5. Configure the basic fields for your Scorecard:
* **Name**: Enter a descriptive name for your Scorecard.
* **Identifier**: Enter a unique identifier for your Scorecard.
* **Description**: Enter a description for your Scorecard.
* **Evaluation window**: By default, Scorecards are evaluated every 4 hours. If you would like to evaluate Scorecards less frequently, you can override the evaluation window and enter a new number.
* If a Scorecard is evaluating such a large number of entities that it cannot complete the evaluation in a 4-hour window without invoking rate limits, then a longer evaluation window is recommended.
* You will also be able to [manually trigger an evaluation](#trigger-an-evaluation) when needed.
* **Enable notifications**: Choose whether to enable notifications.
* If notifications are enabled, users who own entities being evaluated by this Scorecard will receive alerts when there are relevant updates on the Scorecard and any corresponding initiatives.
* **Notify when scores drop**: When enabled, you will be notified any time a score drops from the last time the Scorecard was evaluated.
* **Enable exemptions**: Choose whether to enable Scorecard exemptions. If not set, it defaults to true.
* See [Scorecard rule exemptions](https://docs.cortex.io/standardize/scorecards/rule-exemptions) for more information.
* **Enable auto-approval exemptions**: Choose whether to enable auto-approving of Scorecard rule exemptions. If not set, it defaults to false.
* **Enable user-specific notifications:** Add a field to allow your users to notify a specific user to approve a rule exemption request rather than all Admins.
* If this field is enabled, Scorecard notifications will also be enabled automatically.
6. Select whether to apply this Scorecard to specific entities.
* You can choose to include or exclude specific entity types.
* Click **Advanced options** to see additional options for refining entity selection. You can include or exclude groups, and you can include a CQL expression to make your entity type selection.
* When including a CQL expression, you will have the option to [test the query](https://docs.cortex.io/cql/run#step-2-test-the-query) against specified entities to verify that it works as expected.
If you want to use all of the default rules from the template, you can skip ahead to [Step 4: Save the Scorecard](#step-4-save-the-scorecard). If you want to add any rules or levels, follow the next steps.
#### Option 2: Start from scratch
Create Scorecard from scratch
1. On the Scorecards page in Cortex, click **Start from scratch**, then at the bottom of the page, click **Continue**.
2. Configure the basic fields for your Scorecard:
* **Name**: Enter a descriptive name for your Scorecard.
* **Identifier**: Enter a unique identifier for your Scorecard.
* **Description**: Enter a description for your Scorecard.
* **Evaluation window**: By default, Scorecards are evaluated every 4 hours. If you would like to evaluate Scorecards less frequently, you can override the evaluation window and enter a new number.
* If a Scorecard is evaluating such a large number of entities that it cannot complete the evaluation in a 4-hour window without invoking rate limits, then a longer evaluation window is recommended.
* **Enable notifications**: Choose whether to enable notifications.
* If notifications are enabled, users who own entities being evaluated by this Scorecard will receive alerts when there are relevant updates on the Scorecard and any corresponding initiatives.
* **Notify when scores drop**: When enabled, you will be notified any time a score drops from the last time the Scorecard was evaluated.
* **Enable exemptions**: Choose whether allow users to request rule exemptions for evaluated entities. If not set, it defaults to enabled.
* See [Scorecard rule exemptions](https://docs.cortex.io/standardize/scorecards/rule-exemptions) for more information.
* **Enable auto-approval exemptions**: If exemptions are allowed, choose whether to enable auto-approval of Scorecard rule exemptions. If not set, it defaults to disabled.
3. Next to "Apply to specific entities," select whether to apply this Scorecard to specific entities:
* **Selection type** and **Entity types**: Choose to include or exclude specific entity types. By default, the Scorecard will apply to all entities of the selected type(s).
* Click **Advanced options** to see additional options for refining entity selection. You can include or exclude groups. For example, if you're creating a services-based Scorecard, you might choose to include those that belong in a "tier 1 services" group.
* You can also include a CQL expression to make your entity type selection.\
{% hint style="warning" %}
Advanced filtering only works with data that exist within Cortex, like entity groups, owners, and other custom data, but does not extend to third-party integrations.
{% endhint %}
See the next section for steps on choosing a scoring type and writing rules.
### Step 2: Add levels
When you [create a Scorecard](#create-a-scorecard), there are two options to set up your Scorecard's evaluation:
* **Level progression**
* Establish progressive levels as you add rules to make it obvious which set of rules are the highest priority. Levels allow you to set up a gamified system to encourage developers to make progress toward goals and improve entities' performance.
* Set your minimum requirements within the lowest level, and add increasingly higher priority rules to subsequent levels.
* For an example demonstrating how levels work, see [Guides > Measure DORA progress](https://app.gitbook.com/s/iu4HGhtyt7D4jcoIrCBE/dora/scorecard#understanding-scorecard-levels).
* **Point-based rules**
* Use points to assign weighted values to each rule you add to a Scorecard.
* You can use point-based rules to set minimum requirements while also encouraging teams to add more metadata. For example, you could assign 1 point for adding a single runbook to an entity, and another point for adding additional runbooks:
{% hint style="success" %}
If you choose to use only point-based rules in your Scorecard, then you do not need to create levels. You can skip to the next section: [Step 3: Create a rule](#step-3-create-a-rule).
{% endhint %}
#### Add a level
To add a level to a Scorecard:
1. While creating your Scorecard, in the "Define evaluation rules" section, click **Add level**.\
2. In the modal, configure your level:
* **Color**: Click the star icon to select a color for this level.
* **Name**: Enter a name that represents this level.
* You might choose to go with classic levels names, such as Bronze, Silver, and Gold, or you can choose something more unique to your organization.
* Levels are designed to inspire progress on important goals, so consider level names that will motivate your team members.
* **Description**: Enter a description for the level.
3. Click **Add level**.
You can add more levels to the Scorecard, or you can move on to the next step and add rules to each level.
#### **Reorder levels**
To reorder levels in a Scorecard:
You can reorder levels while creating or editing your Scorecard, if the Scorecard has more than one level. Click the arrows on the right side to reorder them:\
\
### Step 3: Create a rule
There are two methods for building a rule:
* Using the form builder
* Via the CQL editor
The form is the fastest option, as you can choose from pre-configured rules for each integration. The CQL editor is best when writing complex rules or accessing data from multiple sources.
Expand the tiles below for instructions on each option.
Use the form builder
1. While creating your Scorecard, in the "Define evaluation rules" section, click **Add rule**.
* **Level progression scoring type**: Click **Add rule** within a level.\
* When using the "Level progression" scoring type, we recommend including the most essential rules in the first level so developers know to prioritize them.
* **Point-based rule scoring type**: Enable the toggle next to **Point-based rules**, then click **Add rule:**\
2. The rule creation modal defaults to the **Form** type, where you can choose a pre-configured rule based on configured integrations. \\
3. Configure the basic fields in the form:
* **Integration**: Choose one of your configured integrations to apply this rule to.
* **Rule**: Choose a rule.
* The next fields vary depending on the type of rule you choose. For example, you may need to choose a boolean operation or set a file path.
* **Rule name**: Enter a descriptive name. Names make it easier to understand the outcome of the rule without having to read the CQL expression.\
4. Optionally configure the additional fields:
* **Description**: Enter a description for the rule.
* **Failure message**: Add links or instructions to tell users how they can remediate this rule if it's failing.
* **Restrict rule to specific groups**: Select groups to include or exclude.
* This option can be used when a group of entities should be evaluated by the Scorecard as a whole, but a specific rule in the Scorecard does not apply to that group.
* See [Scorecard rule filters](https://docs.cortex.io/standardize/scorecards/scorecard-filters) for more information on configuring a filter.
* **Points**: Enter how many points this rule is worth.
* You can use points to signify each rule's importance. Rules worth more points are more critical than those with fewer points.
* **Schedule evaluation start date**: If you want to schedule the evaluation of a rule to start on a specific date, schedule a start date here. When the field is blank, the rule will take effect immediately. If a start date is provided, the rule will take effect at the start of the specified day (UTC).
* This is helpful when you want users to be aware of an upcoming rule, but you do not want to evaluate the Scorecard yet based on that rule.
* Scheduled rules are visible to all users and will be included in the weekly team and user reports to help with socialization.
* Users can choose to [receive notifications](https://docs.cortex.io/configure/settings/notifications) when a scheduled rule is added to a Scorecard evaluating an entity they own, and they can receive reminders before a scheduled rule impacting an owned entity goes into effect.
5. Click **Save rule**.
Use the CQL editor
1. While creating your Scorecard, in the "Define evaluation rules" section, click **Add rule**.
* **Level progression scoring type**: Click **Add rule** within a level.\
* When using the "Level progression" scoring type, we recommend including the most essential rules in the first level so developers know to prioritize them.
* **Point-based rule scoring type**: Enable the toggle next to **Point-based rules**, then click **Add rule:**\
2. The rule creation modal defaults to the **Form** type, where you can choose a pre-configured rule based on configured integrations. To write a CQL expression instead, click **CQL:**\
3. Configure the basic fields in the form:
* **CQL expression**: Enter your CQL rule. On the right side of the modal, you can use CQL Explorer for help.
* Note: If writing an expression that references a Jira issues, Cortex will not append new filter logic to your default JQL query. See [Adding filter logic to the default JQL query in a Scorecard](https://docs.cortex.io/ingesting-data-into-cortex/integrations/jira#adding-filter-logic-to-the-default-jql-query-in-a-scorecard) for more information.
* **Rule name**: Enter a descriptive name. Names make it easier to understand the rule without having to read the CQL expression.
4. Optionally configure the additional fields:
* **Description**: Enter a description for the rule.
* **Failure message**: Add links or instructions to tell users how they can remediate this rule if it's failing.
* **Restrict rule to specific groups**: Select groups to include or exclude.
* This option can be used when a group of entities should be evaluated by the Scorecard as a whole, but a specific rule in the Scorecard does not apply to that group.
* See [Scorecard rule filters](https://docs.cortex.io/standardize/scorecards/scorecard-filters) for more information on configuring a filter.
* **Points**: Enter how many points this rule is worth.
* You can use points to signify each rule's importance. Rules worth more points are more critical than those with fewer points.
* **Schedule evaluation start date**: If you want to schedule the evaluation of a rule to start on a specific date, schedule a start date here. When the field is blank, the rule will take effect immediately. If a start date is provided, the rule will take effect at the start of the specified day (UTC).
* This is helpful when you want users to be aware of an upcoming rule, but you do not want to evaluate the Scorecard yet based on that rule.
* Scheduled rules are visible to all users and will be included in the weekly team and user reports to help with socialization.
* Users can choose to [receive notifications](https://docs.cortex.io/configure/settings/notifications) when a scheduled rule is added to a Scorecard evaluating an entity they own, and they can receive reminders before a scheduled rule impacting an owned entity goes into effect.
5. Click **Save rule**.
You can repeat the steps above to continue adding rules to your Scorecard. You cannot duplicate a rule across levels, since developers will have already completed that task earlier. It is common, however, to have similar rules with different thresholds if you want developers to progress in stages. For example, a base level might require that the P50 latency for API requests is under 5 seconds, while a higher level may required that the same P50 is under 2 seconds.
### Step 4: Save the Scorecard
After you have finished adding levels and rules to your Scorecard, you are ready to save it as a draft or publish it.
1. Choose whether to keep your Scorecard in draft form, visible only to users with permission to configure Scorecards. To keep it in draft form, enable the toggle next to **Save as draft**.
* If you choose to keep your Scorecard in draft status, it will not appear in reports or send notifications.
* If you choose to publish your Scorecard, it will be visible to all users who have the `View Scorecards` permission. Notifications, if enabled, will be triggered.
2. Click **Create Scorecard**.
After you save the Scorecard, it will automatically evaluate all the entities that apply based on the rules you have configured, and you will be redirected to the Scorecard's page in Cortex.
## Next steps
After you have established Scorecards, there are different steps you can take to continuously improve:
* **Evaluate progress and take action**: Review the Scorecard via reports or by using Cortex MCP, identify trends, and figure out how to take action on the issues you've identified. Learn more in [Review and evaluate Scorecards](https://docs.cortex.io/standardize/scorecards/evaluate).
* **Target goals with Initiatives**: If you have failing rules, or if you have rules that are a higher priority, you can start using [Initiatives](https://docs.cortex.io/improve/initiatives) to drive progress across the organization. Initiatives allow you to prioritize specific rules within a Scorecard and set deadlines for team members to accomplish tasks. Learn more below.
### Create Initiative from Scorecard
[Initiatives](https://docs.cortex.io/improve/initiatives) allow you to prioritize specific rules and set deadlines, making sure your team members complete higher priority tasks on time. In a level-based Scorecard, you can set an Initiative that asks your team to complete all rules within a level by a certain date.
You can create an Initiative while viewing a Scorecard. Note that the Scorecard must be published - i.e., not in draft mode - in order to create an Initiative for it.
1. In the upper right corner, click **+Create initiative**.
2. Configure the Initiative form.
* For detailed instructions and examples, see the [Initiatives documentation](https://docs.cortex.io/improve/initiatives).
You can also create an Initiative while viewing reports for the Scorecard under its [**Reports** tab](https://docs.cortex.io/standardize/scorecards/..#reports).
