feat: [IDP-7726] platform integration for catalog discovery (#100795)

* e7ca72 docs: Add comprehensive documentation for Platform Integration, Aggregation Rules, and Hierarchy Entity Layouts

* d5e139 added

* 3c8bb0 alot of things

* 503b5f Update harness-cd.md

* d6d882 platform integration

Author: ShibamD

docs/internal-developer-portal/catalog/aggregation-rules.md

@@ -0,0 +1,209 @@
+---
+title: Aggregation Rules
+sidebar_label: Aggregation Rules
+sidebar_position: 8
+description: Learn how to create aggregation rules to roll up metrics from entities to hierarchy levels.
+keywords:
+  - aggregation rules
+  - metrics rollup
+  - hierarchy aggregation
+  - DORA metrics
+tags:
+  - catalog
+  - aggregation
+  - metrics
+---
+
+Aggregation rules allow you to roll up metrics from lower-level entities to higher levels in the organizational hierarchy. This enables you to view aggregated metrics at account, organization, and project levels, providing insights into performance across your entire platform.
+
+:::info
+Aggregation Rules are behind a feature flag. Contact your Harness representative to enable this feature.
+:::
+
+## Overview
+
+Aggregation rules compute aggregate values (sum, average, maximum, minimum, median) from entity properties and display them on hierarchy entities. 
+
+:::note
+Aggregations are always computed from the source entities (typically components) to hierarchy entities. When you select multiple roll-up scopes (project, organization, account), the aggregation is calculated from all matching source entities at each level, not by aggregating the already-aggregated values.
+:::
+
+**Example use cases:**
+
+- Aggregate DORA metrics (deployment frequency, change failure rate) from service components to project, organization, and account entities
+- Roll up test coverage metrics from service components to organization and account levels
+- Compute account-wide metrics by aggregating from all service components across the account
+
+:::note
+These are just examples. Aggregation rules work with any custom metric or property you've added to your entities, not just DORA or test coverage metrics.
+:::
+
+The aggregated values are stored as metadata properties on hierarchy entities and can be displayed using [hierarchy entity layouts](/docs/internal-developer-portal/layout-and-appearance/catalog#hierarchy-entity-layouts).
+
+## Accessing Aggregation Rules
+
+Navigate to **Configure** → **Integrations** → **Aggregation Rules** to view and manage your aggregation rules.
+
+![Aggregation Rules](./static/agg-rule.png)
+
+
+
+## Creating an Aggregation Rule
+
+
+Click **New Aggregation Rule** to open the aggregation rule form. The form is organized into two main sections:
+
+![rules-aggre](./static/rules-aggre.png)
+
+
+### Section 1: Basic Details
+
+Configure the metric and how it should be aggregated:
+
+#### Metric / Field to Aggregate
+
+Enter the property path in the entity YAML (e.g., `metadata.changeFailureRatePercent`).
+
+**Finding the field path:**
+
+To find the correct field path, view the YAML of an entity that has the property you want to aggregate. The field path is the dot-notation path to that property.
+
+Example: If your entity YAML has:
+```yaml
+metadata:
+  changeFailureRatePercent: 10
+```
+
+The field path is: `metadata.changeFailureRatePercent`
+
+#### Aggregation Formula
+
+Choose how multiple values should be combined:
+
+- **Average** - Calculate the mean of all values
+- **Sum** - Add all values together
+- **Median** - Take the middle value
+- **Min** - Take the lowest value
+- **Max** - Take the highest value
+
+#### Aggregation Property Name
+
+Enter a name for the aggregated property. This will become the property name on hierarchy entities (e.g., `Max Change Failure Rate`).
+
+#### Description (optional)
+
+Provide an optional description for the aggregation rule.
+
+### Section 2: At What Levels Should This Be Aggregated
+
+Configure where and from which entities the aggregation should be computed:
+
+#### Roll-up Scope
+
+Select at which hierarchy levels you want to see the aggregated value:
+
+- **Project** - Display aggregated value on project entities
+- **Organization** - Display aggregated value on organization entities
+- **Account** - Display aggregated value on account entities
+- **System** - Display aggregated value on system entities
+
+
+:::info
+You can select multiple levels. At each level, the aggregation is computed from all matching source entities (defined by your entity filters), not by aggregating the values from the level below.
+For example, if you select Project, Organization, and Account:
+- Project entities will show the aggregate of all matching components in that project
+- Organization entities will show the aggregate of all matching components across all projects in that organization
+- Account entities will show the aggregate of all matching components across the entire account
+:::
+
+#### Configure Entities to Aggregate Metric From
+
+Define which entities to include in the aggregation. All filters are combined with AND logic:
+
+- **Aggregation Scope** - Filter by scope (e.g., select specific account/org/project or leave as default for all)
+- **Entity Kind** - Select the kind of entities to aggregate (e.g., `Component` or `hierarchy`)
+- **Entity Type** - Filter by entity type (e.g., `service`, or select `all`)
+- **Owners** (optional) - Filter by entity owners
+- **Tags** (optional) - Filter by entity tags
+- **Lifecycle** (optional) - Filter by lifecycle stage
+
+
+## Aggregation Use Cases
+
+### Use Case 1: DORA Metrics from CD Integration
+
+Aggregate DORA metrics that are ingested from CD integration to hierarchy entities.
+
+**Example:** Roll up deployment frequency and change failure rate from service components to projects, organizations, and account.
+
+```yaml
+Field to Aggregate: metadata.changeFailureRatePercent
+Rule Name: Max Change Failure Rate
+Formula: Maximum
+Roll-up Scope: Project, Organization, Account
+Entity Kind: Component
+Type: service
+```
+
+**Result:** The maximum change failure rate across all services will be displayed on project, organization, and account entities as `metadata.Max Change Failure Rate`.
+
+### Use Case 2: Custom Ingested Properties
+
+Aggregate custom properties that you've ingested into entities using the [Catalog Ingestion API](/docs/internal-developer-portal/catalog/integrate-tools/catalog-ingestion-api).
+
+**Example:** Aggregate MTTR (Mean Time To Recovery) from service components.
+
+```yaml
+Field to Aggregate: metadata.mttr
+Rule Name: Max MTTR
+Formula: Maximum
+Roll-up Scope: Project, Organization
+Entity Kind: Component
+Type: service
+```
+
+**Result:** The maximum MTTR value will be available as `metadata.Max MTTR` on project and organization entities.
+
+### Use Case 3: Hierarchical Aggregation
+
+Aggregate properties from hierarchy entities (projects) to higher levels (organizations, account).
+
+**Example:** Roll up test coverage from projects to organizations.
+
+```yaml
+Field to Aggregate: metadata.qa.integrationTestCoverage
+Rule Name: Avg Unit Test Coverage
+Formula: Average
+Roll-up Scope: Organization, Account
+Entity Kind: hierarchy
+Type: project
+```
+
+**Result:** The average test coverage across all projects will be displayed on organization and account entities as `metadata.Avg Unit Test Coverage`.
+
+## Managing Aggregation Rules
+
+### Compute on Demand
+
+Click the **⋮** (three dots) menu next to an aggregation rule and select **Compute** to manually trigger computation. This is useful when you want to see updated values immediately.
+
+![Compute](./static/compute.png)
+
+### Edit an Aggregation Rule
+
+1. Click the **⋮** menu next to the rule
+2. Select **Edit**
+3. Make your changes
+4. Click **Save**
+
+The rule will be recomputed automatically after saving.
+
+### Delete an Aggregation Rule
+
+1. Click the **⋮** menu next to the rule
+2. Select **Delete**
+3. Confirm the deletion
+
+:::warning
+When you delete an aggregation rule, all aggregated values created by that rule will be removed from hierarchy entities. If you have layout components referencing the deleted property, they will show a dash (-) or empty value.
+:::

docs/internal-developer-portal/catalog/create-entity/catalog-discovery/harness-cd.md

@@ -1,6 +1,6 @@
 ---
 title: Catalog Auto-Discovery with Harness CD Services
-description: Steps to use Catalog Ingestion API to ingest metadata and use the information on catalog overview and workflows
+description: Steps to use Catalog Ingestion API to ingest metadata and use the information on the catalog overview and workflows
 sidebar_position: 1
 sidebar_label: Harness CD
 ---
@@ -14,6 +14,7 @@ Make sure the following prerequisites are met:
 
 1. The feature flag **`IDP_CATALOG_CD_AUTO_DISCOVERY`** is enabled. Contact [Harness Support](mailto:[email protected]) to enable it.
 2. **Harness CD** is enabled for your account. This must be the **same account** you use for Harness IDP.
+3. You have the required **RBAC permissions** to manage integrations. All operations for CD and Platform integrations require the **IDP Integration Edit** permission (`IDP_INTEGRATION_EDIT`) on the **IDP Integration** resource type (`IDP_INTEGRATION`).
 
 ---
 

docs/internal-developer-portal/catalog/create-entity/catalog-discovery/platform-cd.md

@@ -0,0 +1,150 @@
+---
+title: Catalog Auto-Discovery with Platform Integrations
+sidebar_position: 2
+sidebar_label: Platform Integration
+description: Discover services from Platform integrations and sync them to the IDP Catalog
+keywords:
+  - catalog auto-discovery
+  - platform integrations
+  - cd auto-discovery
+  - hierarchy entities
+tags:
+  - catalog-discovery
+  - platform-cd
+  - cd-auto-discovery
+---
+
+The Platform Integration feature in Harness IDP automatically syncs all scope-level entities from the Harness Platform as IDP catalog entities. This integration creates a hierarchical view of your Harness account structure, including accounts, organizations, and projects, making them discoverable and manageable within the IDP catalog.
+
+## Overview
+
+Platform Integration synchronizes your entire Harness Platform hierarchy into the IDP catalog as entities with a special `hierarchy` kind. This provides a unified view of your organizational structure and all associated services across accounts, organizations, and projects.
+
+**Key features:**
+
+- **Automatic synchronization** - Syncs all entities from the Harness Platform to IDP catalog
+- **Hierarchical structure** - Maintains account → organization → project relationships
+- **Scope-based filtering** - View entities by account, organization, or project scope
+- **Read-only entities** - Imported entities cannot be deleted from the catalog
+- **Continuous sync** - Keeps catalog entities up-to-date with Platform changes
+
+## Enabling Platform Integration
+
+To enable Platform Integration:
+
+1. Navigate to **Configure** → **Integrations** → **Platform Integration**
+2. If not already enabled, click **Enable** to activate the integration
+3. The integration will display an enable/disable toggle with minimal configuration required
+
+
+<DocImage path={require('./static/enable-pl-int.png')} alt="Enable Platform Integration" title="Click to view full size image" />
+
+:::info
+Once you import entities using Platform Integration, you won't be able to delete them from the catalog. They are managed by the Platform Integration sync process.
+:::
+
+After enabling, all scope-level entities (accounts, organizations, and projects) from the Harness Platform will be automatically imported into the IDP catalog.
+
+## Viewing Imported Entities
+
+Once the import is complete, you can view all imported entities in two ways:
+
+#### From Platform Integration Page
+
+Navigate to **Configure** → **Integrations** → **Platform Integration** to view the imported entities table:
+
+<DocImage path={require('./static/pl-int-list.png')} alt="Platform Integration List" title="Click to view full size image" />
+
+
+Clicking on an entity in this table will navigate you to the IDP catalog entity details page.
+
+#### From IDP Catalog
+
+Navigate to **Catalog** and filter by **Kind: hierarchy** to view all hierarchical entities. You can then select the specific type (account, organization, or project) to view entities at that level.
+
+<DocImage path={require('./static/hierarchy.png')} alt="Hierarchy entities" title="Click to view full size image" />
+
+## Hierarchy Entity Structure
+
+Platform Integration creates entities with `Kind: hierarchy`, which represents the organizational structure of your Harness Platform. These entities have different types based on their level in the hierarchy:
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs queryString="hierarchy-level">
+<TabItem value="account" label="Account-Level Entity">
+
+When you view an account entity:
+
+- **Kind:** `hierarchy`
+- **Type:** `account`
+
+<DocImage path={require('./static/acc-lvl-entity.png')} alt="Account Level Entity" title="Click to view full size image" />
+
+**The Overview tab displays two tables:**
+
+1. **Organizations belonging to this Account** - Lists all direct child organizations
+  
+2. **Entities belonging to this scope (account)** - Lists all entities at the account scope level
+
+</TabItem>
+<TabItem value="organization" label="Organization-Level Entity">
+
+When you view an organization entity:
+
+- **Kind:** `hierarchy`
+- **Type:** `organization`
+
+<DocImage path={require('./static/org-entity.png')} alt="Organization Level Entity" title="Click to view full size image" />
+
+**The Overview tab displays three sections:**
+
+1. **Projects belonging to this Organization** - Lists all direct child projects
+
+2. **Entities belonging to this scope (organization)** - Lists all entities at the organization scope level
+
+</TabItem>
+<TabItem value="project" label="Project-Level Entity">
+
+When you view a project entity:
+
+- **Kind:** `hierarchy`
+- **Type:** `project`
+
+<DocImage path={require('./static/pro-level.png')} alt="Project Level Entity" title="Click to view full size image" />
+
+**The Overview tab displays:**
+
+1. **Entities belonging to this scope (project)** - Lists all entities at the project scope level
+
+</TabItem>
+</Tabs>
+
+## Customizing Hierarchy Entity Views
+
+Beyond the default hierarchical relationships, you can customize the Overview tab of hierarchy entities to display additional metrics and insights using **Aggregation Rules** and **Layout Configuration**.
+
+<DocImage path={require('./static/layout.png')} alt="Layout" title="Click to view full size image" />
+
+#### What You Can Add
+
+- **Stats Cards** - Display aggregated metrics from child entities (e.g., average test coverage, deployment frequency)
+- **Aggregation Tables** - Show breakdowns of metrics with individual values from child entities
+
+#### How It Works
+
+1. **Create Aggregation Rules** - Define how to roll up metrics from lower-level entities (e.g., from components to projects, from projects to organizations)
+2. **Configure Layouts** - Add stats cards and tables to display the aggregated metrics on hierarchy entities
+3. **View Results** - Navigate to hierarchy entities to see your customized metrics and insights
+
+<DocImage path={require('./static/metric.png')} alt="Metric" title="Click to view full size image" />
+
+For example, you can aggregate DORA metrics from service components to project entities, then roll up test coverage from projects to organizations, and display these as cards on the Overview tab.
+
+## Next Steps
+
+- Learn about [Aggregation Rules](/docs/internal-developer-portal/catalog/aggregation-rules) to roll up metrics across hierarchy levels
+- Explore [Layout Configuration](/docs/internal-developer-portal/layout-and-appearance/catalog) to customize hierarchy entity views
+- Understand [Catalog Ingestion](/docs/internal-developer-portal/catalog/integrate-tools/catalog-ingestion-api) to add custom properties to entities
+