Catalio logo
Sign in

Core Concepts

Mapping Requirements to External Systems

In Catalio, a Component represents a technical implementation in an external system that fulfills one or more business requirements. Components bridge the gap between business needs and actual code, enabling traceability from requirement specification through implementation and verification.

Think of components as the building blocks of your software architecture: APIs, microservices, database tables, libraries, tools, and third-party integrations. By linking components to requirements, you create a comprehensive map showing exactly where each business capability is implemented.

What is a Component?

A component is any technical artifact that implements business functionality:

  • External API: Salesforce REST API, ServiceNow Table API, Workday HCM API
  • Microservice: User Service, Order Processing Service, Payment Gateway
  • Database: PostgreSQL users table, MongoDB orders collection, Redis cache
  • Library: Authentication SDK, Payment Processing Library, Reporting Framework
  • Tool: CI/CD pipeline, Monitoring Dashboard, Data Warehouse ETL job
  • Other: Custom integrations, scripts, configuration files

Components live in external systems—Salesforce, ServiceNow, GitHub, Jira, AWS—and Catalio maintains references to them, enabling deep linking and future automated synchronization.

Why Component Tracking Matters

Traceability

Answer critical questions instantly:

  • “Which Salesforce objects implement our customer management requirements?”
  • “If we deprecate this ServiceNow workflow, which requirements are affected?”
  • “What components implement authentication requirements?”

Impact Analysis

When requirements change, immediately identify affected components:

  • Scope technical work before committing to changes
  • Communicate impact to engineering teams
  • Estimate effort and risk accurately

System Integration

Track implementations across your entire technology landscape:

  • Map requirements to multiple systems (Salesforce + ServiceNow + custom APIs)
  • Understand cross-platform dependencies
  • Plan integration testing scenarios

Compliance and Audit

Demonstrate that requirements are implemented and verified:

  • Trace regulatory requirements to actual implementations
  • Prove compliance with industry standards
  • Maintain audit trails for change management

Architecture Visibility

Understand your system architecture through business requirements:

  • Identify which requirements have no implementations (gaps)
  • Find over-engineered requirements with too many components
  • Detect architectural patterns and anti-patterns

Component Types

Catalio supports six component types, each representing a different architectural element:

External API

REST APIs, GraphQL endpoints, SOAP services, webhooks from external platforms.

Example: Salesforce REST API v52.0

  • Name: Salesforce REST API - Account Object
  • Type: External API
  • External System: Salesforce
  • External ID: Account
  • URL: https://yourinstance.salesforce.com/services/data/v52.0/sobjects/Account
  • Version: v52.0
  • Status: Active

Microservice

Internal services, background workers, event processors, domain services.

Example: User Authentication Service

  • Name: User Authentication Service
  • Type: Microservice
  • External System: GitHub
  • External ID: catalio-auth-service
  • URL: https://github.com/yourorg/catalio-auth-service
  • Version: v2.3.1
  • Status: Active

Database

Tables, collections, views, stored procedures, indexes.

Example: ServiceNow Incident Table

  • Name: ServiceNow Incident Table
  • Type: Database
  • External System: ServiceNow
  • External ID: incident
  • URL: https://yourinstance.service-now.com/incident.do
  • Status: Active

Library

Shared libraries, SDKs, frameworks, internal packages.

Example: Payment Processing SDK

  • Name: Stripe Payment SDK
  • Type: Library
  • External System: GitHub
  • External ID: stripe-sdk-v3
  • URL: https://github.com/stripe/stripe-node
  • Version: v3.12.0
  • Status: Active

Tool

Build tools, CI/CD pipelines, monitoring systems, data pipelines.

Example: Azure DevOps Build Pipeline

  • Name: Production Deployment Pipeline
  • Type: Tool
  • External System: Azure DevOps
  • External ID: catalio-prod-deploy
  • URL: https://dev.azure.com/yourorg/_build?definitionId=42
  • Status: Active

Other

Custom integrations, scripts, configuration files, or anything that doesn’t fit the standard types.

Supported External Systems

Catalio integrates with nine major enterprise platforms, plus custom systems:

Salesforce

CRM platform components: objects, fields, flows, validation rules, Apex classes.

Use Case: Track which Salesforce objects and flows implement customer management requirements.

ServiceNow

ITSM platform components: tables, workflows, business rules, UI actions.

Use Case: Link incident management requirements to ServiceNow incident table and workflows.

Workday

HCM/Financial platform components: business processes, reports, integrations.

Use Case: Map HR requirements to Workday business processes and custom reports.

SAP

ERP platform components: modules, transactions, BAPIs, custom developments.

Use Case: Trace financial requirements to SAP Finance modules and custom transactions.

Jira

Project management components: workflows, custom fields, automation rules, apps.

Use Case: Link development process requirements to Jira workflows and automation.

GitHub

Code repository components: repositories, branches, workflows, GitHub Actions.

Use Case: Connect CI/CD requirements to GitHub Actions workflows and repositories.

Azure DevOps

DevOps platform components: pipelines, repos, work items, test plans.

Use Case: Map deployment requirements to Azure DevOps pipelines and release definitions.

AWS

Cloud infrastructure components: Lambda functions, API Gateway, S3 buckets, CloudFormation stacks.

Use Case: Link infrastructure requirements to AWS resources and automation.

Custom

Internal systems, proprietary platforms, legacy applications, custom integrations.

Use Case: Track components in internal systems not covered by standard integrations.

Component Attributes

Core Metadata

Name - Clear, descriptive component name

  • Good: “Salesforce Account Validation Rule - Email Format”
  • Bad: “Rule_001”

Description - Purpose and functionality (optional but recommended)

  • Explain what the component does
  • Note any special behavior or limitations
  • Include context for future maintainers

Component Type - Classification (required)

  • Choose the type that best represents the component’s role
  • Consistent typing enables meaningful analytics

Status - Current lifecycle state (required, defaults to Active)

  • Active: Currently in use and maintained
  • Deprecated: Planned for removal, but still functioning
  • Retired: No longer active, kept for historical reference

Version - Component version identifier (optional)

  • Use semantic versioning when applicable: v2.1.3
  • For dated releases: 2024-Q1
  • For external systems without versions, use date discovered

External System Linking

External System Type - Platform where component lives (optional)

  • Select from nine supported systems or “Custom”
  • Enables filtering and future automated sync

External System ID - Unique identifier in source system (optional)

  • Salesforce: API name (e.g., “Account”, “Opportunity”)
  • ServiceNow: Table name (e.g., “incident”, “cmdb_ci_server”)
  • GitHub: Repository slug (e.g., “yourorg/repo-name”)
  • Jira: Project key or workflow name
  • Use IDs that remain stable over time

External System URL - Deep link to component (optional but highly recommended)

  • Direct link to view/edit the component
  • Enables one-click navigation from requirement to implementation
  • Example: https://yourinstance.salesforce.com/lightning/setup/ObjectManager/Account/FieldsAndRelationships/view

Pro Tip: Always include the external URL. It saves countless hours searching for components in external systems.

Discovery Tracking

Discovery Method - How the component was identified (optional)

  • Manual: Manually created by a team member
  • API Discovery: Found via automated system scanning
  • AI Suggested: Identified by AI analysis
  • Imported: Loaded from external tool or spreadsheet
  • Automated Scan: Discovered via integration scanning

AI Features

AI Accessible - Control AI agent access (defaults to true)

  • True: AI can analyze and suggest this component for requirements
  • False: Exclude sensitive components from AI processing

AI Summary - AI-generated description (auto-generated)

  • Concise summary of component purpose
  • Used in AI agent context windows
  • Updated when component details change

AI Tags - AI-generated categorization tags (auto-generated)

  • Semantic tags for advanced search and filtering
  • Technical concepts: api, database, workflow, security
  • Functional areas: authentication, reporting, integration
  • System categories: salesforce-object, servicenow-table, aws-lambda

Synchronization and Integration

Catalio tracks synchronization status for components linked to external systems, enabling future automated updates.

Sync Status

Manual (default)

  • Manually created, no external system integration
  • Use for one-off components or systems without APIs

Not Synced

  • Linked to external system but not yet synchronized
  • Waiting for sync job to run or manual trigger

Syncing

  • Actively synchronizing with external system
  • Fetching latest metadata and updates

Synced

  • Successfully synchronized with external system
  • Component metadata is current

Sync Failed

  • Sync attempt encountered errors
  • Check sync metadata for error details
  • May require manual intervention

Sync Disabled

  • Synchronization intentionally disabled
  • Use when external system changes shouldn’t propagate

Sync Metadata

The sync_metadata field stores synchronization details:

{

  "last_sync_attempt": "2025-01-15T14:30:00Z",

  "error_message": "Authentication failed: Invalid API token",

  "warnings": ["Field 'external_id' format changed in external system"],

  "changes_detected": {

    "description": "Updated from external system",

    "version": "Changed from v1.2.0 to v1.3.0"

  }

}

Use sync metadata to troubleshoot integration issues and understand what changed during sync.

Last Synced At

Timestamp of last successful synchronization. Use this to:

  • Identify components that haven’t synced recently
  • Detect drift between Catalio and external systems
  • Audit synchronization patterns

Pro Tip: Filter components by “sync failed” status weekly to catch integration issues early.

Linking Components to Requirements

The power of components comes from linking them to requirements. Each link tracks implementation status through a complete lifecycle.

When you link a component to a requirement, you establish traceability:

  1. Select Requirement: Choose the business requirement being implemented
  2. Select Component: Choose the technical component that implements it
  3. Set Status: Track implementation progress (defaults to “Planned”)

A single requirement can have multiple components (complex implementation), and a single component can implement multiple requirements (shared infrastructure).

Implementation Status Lifecycle

Each component-requirement link tracks where implementation stands:

Planned

Component identified, work not started

  • Design phase complete
  • Component selected as implementation approach
  • Development not yet begun

Use Case: “We’ve decided to implement the authentication requirement using Auth0, but development hasn’t started.”

In Progress

Active development underway

  • Developers actively building
  • Code being written and tested
  • Not ready for verification

Use Case: “The Auth0 integration is 60% complete, currently implementing MFA flow.”

Implemented

Code complete, ready for verification

  • Development finished
  • Unit tests passing
  • Waiting for business validation

Use Case: “Auth0 integration is deployed to staging, ready for QA team.”

Verified

Tested and confirmed to meet requirement

  • Business stakeholders validated functionality
  • Acceptance criteria met
  • Approved for production

Use Case: “QA confirmed Auth0 integration meets all authentication requirements.”

Deprecated

No longer active implementation

  • Replaced by newer implementation
  • Superseded by different approach
  • Retained for audit trail

Use Case: “We replaced custom OAuth implementation with Auth0. Old component marked deprecated.”

Many-to-Many Relationships

Components and requirements have a many-to-many relationship:

One Requirement, Multiple Components

  • Complex requirements often need multiple technical pieces
  • Example: “User authentication” requirement might link to:
    • Auth0 OAuth Integration (External API)
    • User Authentication Service (Microservice)
    • Users Database Table (Database)
    • JWT Token Library (Library)

One Component, Multiple Requirements

  • Shared components implement multiple capabilities
  • Example: “Salesforce Account Object” component might implement:
    • Customer data management requirement
    • Account hierarchy requirement
    • Account ownership assignment requirement

Impact Analysis Workflow

When requirements change, use component links to assess impact:

  1. Identify Affected Components: View all components implementing the requirement
  2. Check Implementation Status: Determine which components are verified (production) vs. in progress
  3. Estimate Effort: Count components and review complexity
  4. Notify Teams: Share component list with relevant engineering teams
  5. Update Status: After changes, update implementation status accordingly

Example: A requirement change affects three components in different stages:

  • Salesforce Account Object (Verified) → Needs production update
  • Account Sync Service (In Progress) → Needs design change before completion
  • Account Validation Library (Planned) → Can incorporate change before development starts

AI-Powered Features

Catalio’s AI capabilities help discover, categorize, and manage components intelligently.

AI Summary Generation

AI creates concise component summaries by analyzing:

  • Component name and description
  • Component type and external system
  • Linked requirements and their context
  • Technical metadata and version information

Example AI Summary: “Salesforce validation rule ensuring email addresses follow proper format on Account object. Implements data quality requirements for customer management.”

AI Tag Generation

AI generates semantic tags enabling advanced search and filtering:

  • Technical Tags: api, rest-endpoint, database-table, microservice, workflow, validation-rule
  • System Tags: salesforce-object, servicenow-table, aws-lambda, github-action
  • Functional Tags: authentication, data-validation, reporting, integration, automation
  • Domain Tags: customer-management, order-processing, inventory, financial

Search for all “authentication”-tagged components across systems to understand your auth architecture.

AI-Powered Discovery

When creating requirements, AI can suggest existing components:

  • Analyzes requirement text to understand technical needs
  • Searches existing components using semantic similarity
  • Suggests relevant components with confidence scores
  • Prevents duplicate component creation

Future Enhancement: AI will automatically discover components by scanning external systems and suggesting requirement links.

Privacy and Control

The AI accessible toggle controls whether AI can process a component:

  • Enabled (default): AI can analyze, summarize, and suggest this component
  • Disabled: Component excluded from AI processing (sensitive systems)

Use this for proprietary algorithms, confidential integrations, or security-critical components.

Best Practices

Component Naming Conventions

Do:

  • ✅ Use descriptive, specific names: “Salesforce Account Validation Rule - Email Format”
  • ✅ Include system context: “ServiceNow - Incident Assignment Business Rule”
  • ✅ Add version when relevant: “Payment API v3”
  • ✅ Distinguish similar components: “User Service - Authentication” vs “User Service - Profile”

Don’t:

  • ❌ Use internal IDs: “Rule_00123”
  • ❌ Be vague: “API”
  • ❌ Mix naming styles: Pick a pattern and stick to it
  • ❌ Skip system context: “Validation Rule” (which system?)

External System Linking

Always provide:

  • External System Type (if applicable)
  • External System ID (stable identifier)
  • External System URL (deep link)

Even if automated sync isn’t available yet, these fields enable:

  • Manual navigation to component
  • Future automated integration
  • Cross-reference with external documentation

Component Organization

Create components at the right granularity:

Too Granular: Individual Salesforce fields

  • Problem: Hundreds of component records, hard-to-manage
  • Better: Link to the Salesforce object, document fields in description

Too Coarse: “Entire Salesforce Org”

  • Problem: No useful traceability or impact analysis
  • Better: Break down into objects, flows, and major components

Just Right: Meaningful architectural elements

  • Salesforce objects (Account, Opportunity, Custom__c)
  • ServiceNow tables and workflows
  • Microservices and major APIs
  • Shared libraries with clear boundaries

Implementation Status Tracking

Update status regularly:

  • Move to “In Progress” when development starts
  • Move to “Implemented” when code is complete
  • Move to “Verified” after business validation
  • Never leave in “Planned” indefinitely

Use status for reporting:

  • Filter by “Verified” to see production-ready implementations
  • Filter by “In Progress” to track active development
  • Filter by “Planned” to understand upcoming work

Component Descriptions

Write descriptions that help future maintainers understand:

Include:

  • Purpose and business context
  • Key functionality or behavior
  • Important constraints or limitations
  • Dependencies on other components
  • Known issues or technical debt

Example Description:

Salesforce validation rule enforcing email format on Account object.

Prevents invalid email addresses from being saved.



Requirements:

- Must contain @ symbol

- Must have valid domain extension

- Case-insensitive validation



Note: This rule blocks saves, consider making asynchronous if

performance issues arise with bulk operations.



Last updated: 2024-Q1 to support new TLD extensions.

Regular Component Audits

Quarterly Review:

  • Identify deprecated components (mark status appropriately)
  • Verify external URLs still work (systems move components)
  • Update versions for components that changed
  • Check sync status for failed synchronizations
  • Remove duplicate components

Before Major Releases:

  • Confirm all high-priority requirement components are “Verified”
  • Validate external system links for release documentation
  • Update implementation status for changed components

Real-World Examples

Example 1: Salesforce Validation Rule

Component Details:

  • Name: Salesforce Account Email Validation
  • Description: Validation rule on Account object ensuring email addresses follow standard format (contains @, valid domain). Prevents data quality issues in customer communications.
  • Type: External API
  • Status: Active
  • External System: Salesforce
  • External ID: Account_Email_Validation
  • URL: https://catalio.lightning.force.com/lightning/setup/ObjectManager/Account/ValidationRules/Account_Email_Validation/view
  • Version: v1.2 (updated 2024-Q1)
  • Sync Status: Synced
  • Last Synced: 2025-01-15 10:30 AM

Linked Requirements:

  1. REQ-042: “As a Sales Rep, I want valid customer email addresses so that automated communications aren’t rejected” - Status: Verified
  2. REQ-089: “As a Marketing Manager, I want data quality rules preventing invalid emails so that campaign metrics are accurate” - Status: Verified

AI Summary: “Salesforce validation rule ensuring proper email format on Account records. Implements data quality requirements for customer communication.”

AI Tags: salesforce-object, validation-rule, data-quality, email-validation, customer-management

Example 2: ServiceNow Workflow

Component Details:

  • Name: ServiceNow Incident Assignment Workflow
  • Description: Business rule automatically assigning incidents to appropriate support team based on category, priority, and SLA. Includes escalation logic for P1 incidents. Updated monthly with team capacity data.
  • Type: Tool
  • Status: Active
  • External System: ServiceNow
  • External ID: incident_auto_assign
  • URL: https://catalio.service-now.com/nav_to.do?uri=sys_script_13579.do
  • Sync Status: Synced
  • Last Synced: 2025-01-14 6:00 AM

Linked Requirements:

  1. REQ-156: “As an IT Manager, I want automated incident assignment so that tickets reach the right team within 5 minutes” - Status: Verified
  2. REQ-178: “As a Support Team Lead, I want P1 incidents immediately escalated so that critical issues get immediate attention” - Status: Verified
  3. REQ-203: “As an Operations Director, I want assignment load balanced across teams so that no team becomes overwhelmed” - Status: In Progress

AI Summary: “ServiceNow workflow automatically routing incident tickets to support teams with SLA-based escalation logic.”

AI Tags: servicenow-workflow, incident-management, automation, escalation, itsm

Example 3: Custom Microservice API

Component Details:

  • Name: Customer Data Sync API
  • Description: Internal REST API synchronizing customer data between Salesforce and internal data warehouse. Runs every 15 minutes via scheduled job. Handles incremental updates using Salesforce Change Data Capture. Includes retry logic and dead letter queue for failures.
  • Type: Microservice
  • Status: Active
  • External System: GitHub
  • External ID: catalio/customer-sync-api
  • URL: https://github.com/catalio/customer-sync-api
  • Version: v2.3.5
  • Sync Status: Manual
  • Discovery Method: Manual

Linked Requirements:

  1. REQ-245: “As a Data Analyst, I want customer data synchronized to the warehouse within 30 minutes so that reports reflect current state” - Status: Verified
  2. REQ-267: “As a Business Intelligence Lead, I want reliable data sync with automatic retry so that missing data doesn’t corrupt analytics” - Status: Verified
  3. REQ-301: “As a Data Engineer, I want incremental sync using CDC so that full loads don’t impact system performance” - Status: Implemented

AI Summary: “REST API service synchronizing Salesforce customer data to data warehouse with CDC-based incremental updates.”

AI Tags: microservice, rest-api, data-integration, salesforce-integration, data-warehouse, cdc

Next Steps

Now that you understand components, explore related concepts:

  • Requirements - Learn about business requirements that components implement
  • Use Cases - Define scenarios showing how components fulfill requirements
  • Personas - Understand users who benefit from component implementations

Getting Started with Components

  1. Identify Top 10 Critical Components: Start with components implementing your highest-priority requirements
  2. Document External System Links: Add URLs for easy navigation
  3. Link to Requirements: Establish traceability for critical paths
  4. Set Implementation Status: Track where implementation stands
  5. Enable AI Features: Let AI generate summaries and tags to improve discoverability
  6. Schedule Regular Reviews: Quarterly audits keep component data current

Pro Tip: Start by mapping components for your top 10 requirements. This creates immediate value for impact analysis without overwhelming your team with data entry.

Support

Questions about components and system integration? We’re here to help:

  • Documentation: Continue reading about Requirements, Use Cases, and Personas
  • In-App Help: Look for the 🤖 AI assistant in the components interface
  • Email: support@catalio.com
  • Community: Share integration patterns with other Catalio users
Next
Organizing Your Implementers with Teams