Added a note about .run and tracking actions

[sivanel97]

Description

Added a note about .run and tracking actions section.

[notion-workspace]

Add “Action-Run Catalog” guide & clarify .run payload

[claude]

Claude finished @sivanel97's task —— View job

---

PR Review Progress

Reviewing PR: "Added a note about .run and tracking actions"

Todo List:

• Read CONTRIBUTING.md guidelines
• Review changed file: create-self-service-experiences.md (+183/-1)
• Review changed file: setup-the-backend.md (+4/-0)
• Review changed file: setup-action.md (+5/-1)
• Provide detailed review feedback in markdown format
• Final summary and recommendations

---

Detailed Review

Overview

This PR adds valuable content about tracking self-service actions and clarifies information about .run payload values. The changes span 3 documentation files and add 192 lines primarily focused on:

1. Adding comprehensive tracking documentation for action runs
2. Clarifying that .run contains only the run ID at invocation
3. Minor typo fixes

File-by-File Review

1. create-self-service-experiences.md (+183/-1)

✅ Strengths:

• Comprehensive new section: The "Tracking self-service actions" section provides a complete, practical guide for implementing action run tracking
• Well-structured content: Clear step-by-step instructions with proper use of numbered lists and expandable details sections
• Good use of admonitions: Uses <details> sections appropriately for lengthy JSON configurations
• Consistent formatting: Follows the project's formatting standards with showLineNumbers for code blocks
• Practical value: Addresses a real need for monitoring and auditing self-service actions

⚠️ Issues Found:

• Missing reference: Line 350 mentions "refer to the create ROI dashboard guide" but no link is provided. This should be either linked properly or the reference should be removed
• Hardcoded URL: Line 289 contains a hardcoded Port URL https://app.port.io/organization/run?runId={{...}} - consider if this should be more generic or documented as configurable
• Blueprint icon choice: Uses "Microservice" icon for action runs (line 195) - consider if a more appropriate icon like "Action" or "Run" would be better

2. setup-the-backend.md (+4/-0)

✅ Strengths:

• Important clarification: The added info block about .run available values addresses a common source of confusion
• Consistent placement: Added in the logical location right after the payload example
• Proper formatting: Uses the correct admonition type (:::info)

📝 Suggestions:

• Consider adding similar clarifications in other locations where .run is referenced

3. setup-action.md (+5/-1)

✅ Strengths:

• Consistency: Adds the same .run clarification as in the other file
• Typo fix: Corrects "autmation" to "automation" (line 53)
• Proper formatting: Uses consistent admonition style

Code Quality & Standards Compliance

✅ Follows CONTRIBUTING.md Guidelines:

• Uses proper capitalization in headers (first word capitalized)
• Uses "We" language in instructional content
• Includes proper showLineNumbers for multi-line code blocks
• Uses consistent markdown formatting
• Proper use of admonitions with titles
• Uses - for bullet points with periods
• Uses full paths for internal links

✅ Technical Writing Best Practices:

• Clear, step-by-step instructions
• Real-world practical examples
• Consistent terminology
• Proper context provided for each step

Security & Accuracy Review

✅ Security:

• No security concerns identified
• Uses proper entity identifiers and safe URL patterns
• No exposure of sensitive information

✅ Accuracy:

• JSON configurations appear syntactically correct
• Automation triggers and mappings are properly structured
• Blueprint schema follows Port's conventions

Recommendations

High Priority:

1. Fix broken reference (Line 350): Either add the proper link to the ROI dashboard guide or remove the reference

Medium Priority:

2. Consider icon choice: Evaluate if "Microservice" is the most appropriate icon for action run entities
3. URL documentation: Add a note about customizing the run URL for different Port instances if applicable

Low Priority:

4. Expand cross-references: Consider adding similar .run clarifications in other documentation files where applicable

Final Assessment

Overall Quality: ⭐⭐⭐⭐⭐ Excellent

This PR significantly enhances the Port documentation by:

• Adding comprehensive tracking capabilities that many users will find valuable
• Clarifying a common point of confusion about .run payload contents
• Maintaining high documentation standards throughout

The content is well-written, technically accurate, and follows all established guidelines. The only significant issue is the broken reference to the ROI dashboard guide, which should be addressed before merging.

Recommendation: ✅ Approve with minor fixes

---

[aws-amplify-eu-west-1]

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

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

[hadar-co]

Suggested change

	To gain visibility into how your self-service actions are being used and their performance, you can set up tracking for action runs. This allows you to monitor execution patterns, track success rates, and maintain audit trails what actions were executed and when.
	The following tracking system works by creating a dedicated blueprint for action runs and setting up an automation that captures execution details whenever a specific self-service action is triggered as well as an automation that updates the action run's status. This approach can give you a centralized view of all action executions in your software catalog.
	To gain visibility into how your self-service actions are being used and their performance, you can set up tracking for action runs. This allows you to monitor execution patterns, track success rates, and maintain audit trails to follow what actions were executed and when.
	The following tracking system works by creating a dedicated blueprint for action runs and setting up an automation that captures execution details whenever a specific self-service action is triggered as well as an automation that updates the action run's status.

[hadar-co]

this is repetitive, pretty much the same as what was written in the beginning of the section.
Instead of this, let's write here something more practical, like "Once implemented, you can do X..."