Added Custom Claude Integration

[kodjomiles]

User description

Description

Added a custom claude integration

Added docs pages

Please also include the path for the added docs

• Claude (/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/)

Updated docs pages

Please also include the path for the updated docs

• None

---

PR Type

Documentation, Enhancement

---

Description

• Added comprehensive Claude integration documentation with setup and configuration guides

• Created five blueprints for tracking Claude API usage metrics at organization, workspace, and model levels

• Included resource mappings for syncing Claude usage, cost, and Claude Code analytics data

• Provided dashboard visualization examples with multiple widget types for monitoring API performance

---

Diagram Walkthrough

flowchart LR
  A["Claude Integration Docs"] --> B["Category Configuration"]
  A --> C["Setup & Installation"]
  A --> D["Data Model Blueprints"]
  A --> E["Resource Mappings"]
  A --> F["Dashboard Visualizations"]
  D --> G["Usage Records"]
  D --> H["Cost Records"]
  D --> I["Workspace Usage"]
  D --> J["Model Usage"]
  D --> K["Code Analytics"]
  E --> L["API Endpoints"]
  F --> M["Metrics Charts"]

Loading

File Walkthrough

Relevant files

Documentation

_category_.json Add Claude integration category configuration                        docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/category.json Created new category configuration file for Claude integration documentation Set label to "Claude" and position to 2 in the navigation hierarchy +5/-0      claude.md Add complete Claude integration documentation with blueprints and mappings docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/claude.md Created comprehensive 1062-line documentation for Claude integration with Port Documented five supported metrics types: usage records, cost records, workspace usage, model usage, and Claude Code analytics Provided Helm and Docker installation instructions with detailed configuration parameters Included five complete blueprint JSON schemas for creating Port entities to store Claude metrics Added resource mapping configurations with JQ expressions for syncing data from Anthropic Admin API endpoints Provided step-by-step dashboard creation guide with nine different widget types for visualizing Claude metrics Included prerequisites, authentication setup, and customization guidance using the interactive builder +1062/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No audit logs: The added documentation provides configuration and usage instructions but does not introduce or reference any audit logging for critical actions in the integration. Referred Code ## Installation Choose one of the following installation methods to deploy the Ocean Custom Integration: <Tabs groupId="installation-methods" queryString="installation-methods"> <TabItem value="helm" label="Helm" default> <h2> Prerequisites </h2> <Prerequisites /> <h2> Installation </h2> 1. Add Port's Helm repo and install the Ocean Custom Integration: :::note Replace placeholders Remember to replace the placeholders for `YOUR_PORT_CLIENT_ID`, `YOUR_PORT_CLIENT_SECRET`, and `YOUR_ANTHROPIC_API_KEY`. ::: ```bash showLineNumbers ... (clipped 72 lines)
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Generic identifiers: Some example identifiers use broad names like breakdown and model_breakdown without schema specifics which may be insufficiently descriptive for self-documenting models. Referred Code "model_breakdown": { "type": "object", "title": "Model Usage Breakdown" }, "active_api_keys": { "type": "number", "title": "Active API Keys" }
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing errors doc: The documentation and sample configs do not cover handling API failures, pagination limits, or empty responses beyond a brief note, leaving edge-case behavior unspecified. Referred Code :::info Response structure The API returns data in buckets. Each bucket has starting_at, ending_at, and a results[] array. When using data_path: '.data[].results[]', you'll iterate over all results from all buckets. The actual field names in the results may vary - adjust the property mappings based on your actual API response. Pagination: The API supports pagination via has_more and next_page fields. For large date ranges, you may need to handle pagination by using the next_page token in subsequent requests. ::: </details></details></td></tr> <tr><td><details> <summary><strong>Generic: Secure Logging Practices</strong></summary><br> **Objective:** To ensure logs are useful for debugging and auditing without exposing sensitive <br>information like PII, PHI, or cardholder data.<br> **Status:** <br><a href='https://github.com/port-labs/port-docs/pull/2996/files#diff-db312b2422298bc262b2661120c26daa4431134b3ea01ada53175ba8cb478fa4R60-R75'><strong>Secrets in examples</strong></a>: Examples show environment variables and Helm values for API keys without guidance on <br>redaction or avoiding logging of tokens, risking insecure logging in real deployments.<br> <details open><summary>Referred Code</summary> ```markdown ```bash showLineNumbers helm repo add --force-update port-labs https://port-labs.github.io/helm-charts helm upgrade --install my-ocean-claude-integration port-labs/port-ocean \ --set port.clientId="YOUR_PORT_CLIENT_ID" \ --set port.clientSecret="YOUR_PORT_CLIENT_SECRET" \ --set port.baseUrl="https://api.getport.io" \ --set initializePortResources=true \ --set scheduledResyncInterval=120 \ --set integration.identifier="my-ocean-claude-integration" \ --set integration.type="custom" \ --set integration.eventListener.type="POLLING" \ --set integration.config.baseUrl="https://api.anthropic.com" \ --set integration.config.authType="bearer" \ --set integration.config.paginationType="none" \ --set integration.secrets.token="YOUR_ANTHROPIC_API_KEY" </details></details></td></tr> <tr><td><details> <summary><strong>Generic: Security-First Input Validation and Data Handling</strong></summary><br> **Objective:** Ensure all data inputs are validated, sanitized, and handled securely to prevent <br>vulnerabilities<br> **Status:** <br><a href='https://github.com/port-labs/port-docs/pull/2996/files#diff-db312b2422298bc262b2661120c26daa4431134b3ea01ada53175ba8cb478fa4R612-R677'><strong>Validation not covered</strong></a>: The documentation does not address validation/sanitization of external API responses or <br>safeguards for headers and query parameters in the example mappings.<br> <details open><summary>Referred Code</summary> ```markdown ```yaml showLineNumbers resources: - kind: /v1/organizations/usage_report/messages selector: query: 'true' data_path: '.data[].results[]' query_params: starting_at: '((now | floor) - (86400 * 30)) | strftime("%Y-%m-%dT00:00:00Z")' ending_at: '(now | floor) | strftime("%Y-%m-%dT00:00:00Z")' bucket_width: "1d" port: entity: mappings: identifier: '((.date // .starting_at // "unknown") | tostring) + "@org"' title: '"Claude Usage - " + ((.date // .starting_at // "unknown") | tostring)' blueprint: '"claude_usage_record"' properties: record_date: (.date // .starting_at // "") organization_id: .organization_id // "" organization_name: .organization_name // "" total_requests: .requests // 0 ... (clipped 45 lines)

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Automate setup using Ocean's configuration capabilities The current documentation requires extensive manual copy-pasting of JSON and YAML for setup. This should be automated by using the Ocean framework's capability to provision resources from a configuration file, simplifying the user's setup process. Examples: docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/claude.md [137-798] ## Set up data model Before the integration can sync data, you need to create the required blueprints in Port. These blueprints define the data model for your Claude metrics. **To create the blueprints:** 1. Go to your [Builder page](https://app.getport.io/settings/data-model). 2. Click on the `+ Blueprint` button. ... (clipped 652 lines) Solution Walkthrough: Before: // In claude.md, the user is instructed to perform many manual steps: ## Installation // 1. User runs helm/docker command... ## Set up data model // 2. User manually navigates UI. // 3. User manually copies & pastes 5 large JSON blueprint definitions. <details> <summary><b>Claude Usage Record Blueprint (Click to expand)</b></summary> ```json { ... 100+ lines of JSON ... } // ... repeats for 4 other blueprints Configuration // 4. User manually navigates UI again. // 5. User manually copies & pastes 5 YAML resource mappings. #### After: ```markdown // The documentation would be simplified to a single installation step. ## Installation // 1. User runs a single helm/docker command. // The `initializePortResources=true` flag, already present in the command, // should be leveraged to automatically create all blueprints and mappings // from a configuration file bundled with the integration. helm upgrade --install my-ocean-claude-integration port-labs/port-ocean \ ... --set initializePortResources=true \ ... // The "Set up data model" and "Configuration" sections, which require // manual copy-pasting, would be removed from the documentation. Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a major design flaw in the integration's setup process, which relies on extensive, error-prone manual configuration, and proposes a vastly superior, automated alternative that significantly improves user experience.	High
Organization best practice	Add alt text and confirm code fence options Add descriptive alt text to images and ensure all multi-line code fences include explicit language and showLineNumbers; add alt for images to meet accessibility and Pattern 13. docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/claude.md [11-818] ```json showLineNumbers { "identifier": "claude_usage_record", ... } ... resources: - kind: /v1/organizations/usage_report/messages ... ... helm repo add --force-update port-labs https://port-labs.github.io/helm-charts ... ... docker run -i --rm --platform=linux/amd64 \ ... ... - + ... - + `[To ensure code accuracy, apply this suggestion manually]` <details><summary>Suggestion importance[1-10]: 5</summary> __ Why: Relevant best practice - Pattern 14 and 4: Always specify code block language and add showLineNumbers to multi-line code blocks. </details></details></td><td align=center>Low </td></tr><tr><td rowspan=2>Typo</td> <td> <details><summary>Fix capitalization in section title</summary> ___ **Capitalize "analytics" to "Analytics" in the summary on line 498 for consistency <br>with the blueprint's title.** [docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/claude.md [497-498]](https://github.com/port-labs/port-docs/pull/2996/files#diff-db312b2422298bc262b2661120c26daa4431134b3ea01ada53175ba8cb478fa4R497-R498) ```diff <details> -<summary><b>Claude Code analytics Blueprint (Click to expand)</b></summary> +<summary><b>Claude Code Analytics Blueprint (Click to expand)</b></summary> Apply / Chat Suggestion importance[1-10]: 3 __ Why: The suggestion correctly points out a capitalization inconsistency between a summary title and the corresponding blueprint's title, improving documentation accuracy.	Low
Fix extra space in text Remove the extra space after the markdown link on line 36 for better formatting. docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/claude.md [36] -- An [Anthropic Admin API](https://docs.anthropic.com/en/api/administration-api) generated from the Admin section of the Anthropic Console. +- An [Anthropic Admin API](https://docs.anthropic.com/en/api/administration-api) generated from the Admin section of the Anthropic Console. Apply / Chat Suggestion importance[1-10]: 2 __ Why: The suggestion correctly identifies and fixes an extra space, which is a minor formatting improvement.	Low
Enhancement	Remove whitespace from HTML tags Remove unnecessary whitespace from the h2 tags on lines 48 and 52 to improve code consistency. docs/build-your-software-catalog/sync-data-to-catalog/ai-agents/claude/claude.md [48-52] -<h2> Prerequisites </h2> +<h2>Prerequisites</h2> <Prerequisites /> -<h2> Installation </h2> +<h2>Installation</h2> Apply / Chat Suggestion importance[1-10]: 2 __ Why: This is a valid stylistic suggestion that removes unnecessary whitespace within HTML tags, improving code consistency. The impact is minor.	Low
More

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2996.d2ngvl90zqbob8.amplifyapp.com