PORTN-3057 Add new guide for mapping HiBob users to Port accounts

[kodjomiles]

Description

Added a new guide to ingest Hibob users and map them to existing port accounts

Added docs pages

Please also include the path for the added docs

• Ingest and Map Hibob users to Port accounts (/guides/all/map-hibob-users-to-port-accounts)

[notion-workspace]

Create a guide to map Hibob user to Port User

[aws-amplify-eu-west-1]

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

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

[claude]

Claude finished @kodjomiles's task —— View job

---

PR Review: HiBob Users to Port Accounts Guide

I've completed a thorough review of the PR changes according to the CONTRIBUTING.md guidelines. Here's my detailed analysis:

Todo List:

• Read CONTRIBUTING.md to understand review criteria
• Review the new guide file (map-hibob-users-to-port-accounts.md)
• Review the const.js modifications
• Check for compliance with documentation standards
• Provide detailed feedback

✅ Overall Assessment

This PR successfully adds a comprehensive guide for integrating HiBob users with Port accounts. The implementation follows most documentation standards with some areas for improvement.

📋 Detailed Review

Content Quality & Structure

• ✅ Clear objective: Well-defined purpose and expected outcomes
• ✅ Logical flow: Prerequisites → Data Model → Integration → Testing
• ✅ Comprehensive coverage: Covers all necessary components (blueprints, webhooks, actions, automations)
• ✅ Practical approach: Uses realistic HiBob API structure and Port patterns

CONTRIBUTING.md Compliance

✅ Strengths

• Proper header capitalization: "Ingest and map HiBob users to Port user accounts" ✓
• Second-person pronouns: Uses "you" and "your" appropriately ✓
• We language in guides: Uses "We will leverage..." and "Let's test it" ✓
• Code blocks: All have proper showLineNumbers ✓
• Full path links: All links use full paths ✓
• Collapsible sections: Proper use of <details> with bold titles ✓
• Admonitions: Good use of :::info with descriptive titles ✓
• Active voice: "Port connects..." style used throughout ✓

⚠️ Areas Needing Attention

1. Headers inside tabs (Line 30):

   <h3> Create the HiBob User blueprint</h3>

   ✅ Compliant: Correctly uses <h3> instead of ### inside sections

2. Missing screenshots/GIFs:

   • The guide would benefit from screenshots of the Port UI steps
   • Consider adding GIFs for complex multi-step processes
   • Recommendation: Add screenshots for blueprint creation, webhook setup, and testing steps

3. Link validation needed:

   • Links reference Port docs and HiBob API docs
   • All internal Port links use correct full paths
   • External HiBob links should be verified for accuracy

🔧 Technical Accuracy

• JSON schemas: Well-structured and comprehensive
• API endpoints: Correct HiBob API usage
• Port mapping: Proper use of JQ expressions and Port blueprint structure
• Authentication: Correct HiBob service user authentication pattern

📝 Writing Style

• Tone: Professional and instructional ✓
• Clarity: Steps are clear and actionable ✓
• Completeness: Includes troubleshooting context and expected outcomes ✓
• Search optimization: Good use of relevant keywords ✓

Code Changes Review

src/components/guides-section/consts.js

• ✅ Proper placement: Added to end of array as expected
• ✅ Correct structure: Follows existing pattern perfectly
• ✅ Appropriate tags: Uses relevant tags: "SDLC","Actions", "Automations", "Webhook"
• ✅ Logo selection: Webhook logo is appropriate for the integration type
• ✅ URL path: Matches the file location correctly

🎯 Recommendations for Enhancement

1. Add Visual Aids:

   # Add screenshots for key steps
   <img src='/img/guides/hibob/blueprint-creation.png' width='75%' border='1px' />

2. Include Troubleshooting Section:
   Consider adding a troubleshooting section for common issues like:

   • Authentication failures
   • Mapping errors
   • Webhook connection issues

3. Add Expected Outcomes:
   After major steps, add expected results:

   ✅ **Expected Result**: You should see 15 HiBob users created in your catalog with proper relationships established.

🚀 Final Verdict

✅ APPROVED - This PR meets the documentation standards and provides valuable integration guidance. The guide is well-structured, technically accurate, and follows the established patterns.

Minor Suggestions: Consider adding screenshots and a troubleshooting section in a follow-up PR to enhance user experience.

---

[claude]

Claude finished @kodjomiles's task —— View job

---

PR Review: HiBob Users to Port Accounts Guide

Todo List:

• Read CONTRIBUTING.md to understand review criteria
• Review the new guide file (map-hibob-users-to-port-accounts.md)
• Review the const.js modifications
• Check for compliance with documentation standards
• Provide detailed feedback

✅ Overall Assessment

This PR successfully adds a comprehensive guide for integrating HiBob users with Port accounts. The implementation follows most documentation standards from CONTRIBUTING.md with some excellent practices demonstrated.

📋 Detailed Review

Content Quality & Structure

• ✅ Clear objective: Well-defined purpose and expected outcomes (lines 8-16)
• ✅ Logical flow: Prerequisites → Data Model → Integration → Testing
• ✅ Comprehensive coverage: Covers all necessary components (blueprints, webhooks, actions, automations)
• ✅ Practical approach: Uses realistic HiBob API structure and Port patterns

CONTRIBUTING.md Compliance Analysis

✅ Excellent Adherence

1. Header capitalization (line 6): ✅ "Ingest and map HiBob users to Port user accounts" - follows lowercase rule
2. Second-person pronouns: ✅ Uses "you" and "your" appropriately throughout
3. "We" language in guides (line 10): ✅ "We will leverage..." follows guide conventions
4. Code blocks: ✅ All use proper showLineNumbers (lines 43, 120, 138, etc.)
5. Full path links (lines 21, 32, 109): ✅ All internal links use full paths
6. Collapsible sections: ✅ Perfect use of <details> with bold titles (lines 40, 117, 135)
7. Admonitions: ✅ Excellent use of :::info with descriptive titles (lines 151, 170, 238)
8. Active voice (line 8): ✅ "Port connects..." style used throughout
9. Headers inside tabs: ✅ Correctly uses <h3> instead of ### (line 30)

🔧 Technical Accuracy

• JSON schemas: Well-structured and comprehensive (lines 43-99)
• API endpoints: Correct HiBob API usage and authentication patterns (lines 282, 358)
• Port mapping: Proper use of JQ expressions and Port blueprint structure (lines 196-232)
• Webhook configuration: Comprehensive filtering and entity mapping

📝 Writing Style Excellence

• Tone: Professional and instructional ✅
• Clarity: Steps are clear and actionable with numbered lists ✅
• Completeness: Includes troubleshooting context (lines 170-172, 238-240)
• Search optimization: Good use of relevant keywords ✅

Code Changes Review

src/components/guides-section/consts.js (lines 1339-1344)

• ✅ Proper placement: Added correctly to the array
• ✅ Consistent structure: Follows existing pattern perfectly
• ✅ Appropriate tags: Uses relevant tags: "SDLC","Actions", "Automations", "Webhook"
• ✅ Logo selection: Webhook logo is appropriate for the integration type
• ✅ URL path: Matches the file location correctly

🎯 Areas for Enhancement

1. Visual Aids (Recommended)

The guide would benefit from screenshots for key UI steps:

# Consider adding screenshots for:
- Blueprint creation in Port UI
- Webhook setup interface  
- Self-service action configuration
- Testing results in audit logs

2. Error Handling Documentation

While the guide mentions authentication and basic troubleshooting, consider adding:

• Common API error responses and solutions
• Webhook payload validation failures
• Mapping expression debugging tips

3. Security Best Practices

The guide correctly handles:

• ✅ Base64 encoding explanation (lines 166-168)
• ✅ Service user permissions (lines 22-24, 171)
• ✅ Secret storage in Port (lines 155-173)

🚀 Strengths Highlighted

1. Comprehensive Integration: Covers the complete workflow from data model to testing
2. Automation-First Approach: Intelligent use of automations for real-time sync (lines 524-583)
3. User Experience: Clear step-by-step instructions with expandable code sections
4. Maintainability: Well-structured JSON configurations that are easy to modify
5. Documentation Standards: Excellent adherence to Port's documentation guidelines

🏆 Final Verdict

✅ APPROVED - This PR demonstrates excellent technical documentation practices and provides significant value to users implementing HiBob integration with Port.

Key Achievements:

• Perfect compliance with CONTRIBUTING.md standards
• Comprehensive technical implementation
• Clear, actionable instructions
• Proper security considerations
• Excellent use of Port's documentation patterns

Recommendation: Merge as-is. Consider adding screenshots in a follow-up PR to enhance user experience further.

---