> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/3.0/use-idp/software-catalog/aggregation-rules/aggregation-rules-scorecard.md).

# Scorecard Aggregation Rule

Scorecard aggregation rules let you roll up an existing scorecard's computed scores from source entities to higher levels in your hierarchy (account, org, project, or system) and display them on hierarchy entity pages.

{% hint style="warning" %}
**PREREQUISITE**

You need an active [scorecard](/internal-developer-portal/use-idp/scorecards/scorecard.md) that is already configured and running on your entities before creating a scorecard aggregation rule.
{% endhint %}

***

### Create a scorecard aggregation rule <a href="#create-a-scorecard-aggregation-rule" id="create-a-scorecard-aggregation-rule"></a>

#### Step 1: Confirm your scorecard is active and has run <a href="#step-1-confirm-your-scorecard-is-active-and-has-run" id="step-1-confirm-your-scorecard-is-active-and-has-run"></a>

Navigate to **Configure** → **Scorecards** and confirm the scorecard you want to aggregate is **Active** and has run at least once (a last-run timestamp is visible on the scorecard page).

If the scorecard has never computed scores, open the scorecard, navigate to an entity it applies to, go to the **Scorecard** tab, and click **Rerun Checks**. Then check **Ingested Properties** on that entity to confirm the score has been written there before proceeding.

#### Step 2: Fill in the rule form <a href="#step-2-fill-in-the-rule-form" id="step-2-fill-in-the-rule-form"></a>

Navigate to **Configure** → **Aggregation Rules** and click **+ New Aggregation Rule**.

| Field                         | Required | Description                                                                                                                          |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Aggregation Type**          | Yes      | Select `SCORECARD`                                                                                                                   |
| **Scorecard to Aggregate**    | Yes      | Select the scorecard from the dropdown                                                                                               |
| **Aggregation Formula**       | Yes      | Choose the operation: **Average** (mean across all), **Sum** (total), **Min** (lowest), **Max** (highest), **Median** (middle value) |
| **Aggregation Property Name** | Yes      | Name of the new property written to hierarchy entities, e.g. `service_maturity`                                                      |
| **Description**               | No       | Write a brief description about the rule you create                                                                                  |

**Roll-up scope**

Select the hierarchy levels where the aggregated value should be stored. You can select multiple levels simultaneously.

| Level            | Aggregates from                                            |
| ---------------- | ---------------------------------------------------------- |
| **Account**      | All matching entities in the entire account                |
| **Organization** | All matching entities within each organization             |
| **Project**      | All matching entities within each project                  |
| **System**       | All matching entities associated with each system          |
| **Team**         | All matching entities owned by each team and its sub-teams |

{% hint style="info" %}
Each level is computed independently from the source entities. The account value is never derived by averaging project values. It is always computed fresh from source entities directly.
{% endhint %}

**Configure entities to aggregate from**

All filters are combined with AND logic.

| Filter                | Required | Description                                                                                                                                         |
| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Aggregation Scope** | No       | Restrict to a specific account, org, or project. Leave blank (`*`) for all.                                                                         |
| **Entity Kind**       | No       | Can be a built-in kind, e.g. `Component` or a [custom kind](/internal-developer-portal/3.0/admin-and-customization/custom-entity-kinds/overview.md) |
| **Entity Type**       | No       | e.g. `service`                                                                                                                                      |
| **Owners**            | No       | Filter by owner                                                                                                                                     |
| **Tags**              | No       | Filter by tags                                                                                                                                      |
| **Lifecycle**         | No       | Filter by lifecycle stage                                                                                                                           |

Click **Save**. The rule appears in your Aggregation Rules list with a **SUCCESS** status once the first computation completes.

#### Step 3: Verify the value is ingested <a href="#step-3-verify-the-value-is-ingested" id="step-3-verify-the-value-is-ingested"></a>

Open the hierarchy entity where the aggregated value should appear (for example, the account entity). Click **View YAML** → **Ingested Properties** and confirm the new property is present.

```yaml
metadata:
  service_maturity: 17.5
```

If the property is missing, check that:

* The scorecard has run on source entities and scores are visible in their **Ingested Properties** (not just the Scorecard tab).
* The Entity Kind filter in your rule matches the kind of entities the scorecard is applied to.
* The Aggregation Scope shows `*` and is not restricted to a specific project or org that excludes your source entities.
* The rule status is **SUCCESS**. If it shows an error, click **Compute** from the three-dot menu to trigger a fresh run.

#### Step 4: Surface the value in the catalog layout <a href="#step-4-surface-the-value-in-the-catalog-layout" id="step-4-surface-the-value-in-the-catalog-layout"></a>

The aggregated value is stored as a metadata property but does not appear on the entity page automatically. Add a `StatsCard` to the hierarchy entity's catalog layout to display it.

{% hint style="info" %}
This is intentional. Harness IDP gives you control over which values appear on which pages and how they are labeled. The same property can appear on multiple layouts with different titles for different audiences.
{% endhint %}

* Navigate to **Configure** → **Layout** → **Catalog Entities** → **Hierarchy** → select the entity type → **Edit Layout**.
* Add a `StatsCard` referencing the aggregated property using `<+metadata.propertyName>` syntax given below:

  ```yaml
  - component: StatsCard
    specs:
      props:
        title: Service Maturity Score
        subtitle: Avg scorecard score across all services
        value: <+metadata.service_maturity>%
  ```
* Save the layout. The aggregated scorecard score now appears as a card on the hierarchy entity page.

***

### Use cases <a href="#use-cases" id="use-cases"></a>

#### Use case 1: Service maturity roll-up <a href="#use-case-1-service-maturity-roll-up" id="use-case-1-service-maturity-roll-up"></a>

```yaml
Aggregation Type: Scorecard
Scorecard to Aggregate: Service maturity scorecard
Aggregation Property Name: service_maturity
Formula: Average
Roll-up Scope: Organization, Account
Entity Kind: Component
Type: service
```

**Result:** `metadata.service_maturity` is available on organization and account entities.

#### Use case 2: Compliance posture across projects <a href="#use-case-2-compliance-posture-across-projects" id="use-case-2-compliance-posture-across-projects"></a>

```yaml
Aggregation Type: Scorecard
Scorecard to Aggregate: Compliance scorecard
Aggregation Property Name: avg_compliance_score
Formula: Average
Roll-up Scope: Project, Organization
Entity Kind: Component
Type: service
```

**Result:** `metadata.avg_compliance_score` is available on project and organization entities.

#### Use case 3: Production readiness by system <a href="#use-case-3-production-readiness-by-system" id="use-case-3-production-readiness-by-system"></a>

```yaml
Aggregation Type: Scorecard
Scorecard to Aggregate: Production readiness scorecard
Aggregation Property Name: min_production_readiness
Formula: Minimum
Roll-up Scope: System
Entity Kind: Component
Type: service
```

**Result:** `metadata.min_production_readiness` is available on system entities.

***

### Frequently asked questions <a href="#frequently-asked-questions" id="frequently-asked-questions"></a>

<details>

<summary>The scorecard score is visible on the entity's Scorecard tab but the aggregation rule writes nothing. Why?</summary>

The aggregation engine reads from **Ingested Properties**, not from the Scorecard tab. Open one of your source entities, click **View YAML** → **Ingested Properties**, and check whether the scorecard score appears there.

</details>

<details>

<summary>The scorecard score has not updated. Why?</summary>

Scorecard checks run twice a day. If you need a fresh value before the next automatic run, navigate to **Configure** → **Scorecards**, open the scorecard, go to an entity it covers, and click **Rerun Checks** on the Scorecard tab. Then return to **Aggregation Rules** and click **⋮** → **Compute** on the rule.

</details>

<details>

<summary>For more FAQs, see the <a href="https://github.com/iKettles/harness-gitbook/tree/main/docs/internal-developer-portal/catalog/aggregation-rules/README.md">Aggregation Rules Overview</a>.</summary>

The overview page covers shared questions including where aggregated values live, how to restrict aggregation to a subset of projects, and how to display values in the catalog layout.

</details>