Components

In Catalio, a Component is a single, discrete piece of an Application’s implementation. What counts as a Component depends on the kind of Application:

• For business applications (Salesforce, ServiceNow, SAP, Workday, etc.): a Component is any piece of metadata in that platform — a field, a validation rule, a workflow, a permission set, an approval process, a page layout, a custom object, a script file, and so on.
• For custom applications (first-party code you own): a Component is a file in a source code repository — nothing more, nothing less.

A Component is the atomic unit Catalio tracks when it needs to answer “what actually exists in the system?” It is not a plan, a task, or a ticket — it is the thing itself.

One Component, Multiple Representations

A Component can exist in more than one place at the same time. The most common case is a business-application Component that is also tracked as a file in a source repository:

• A Salesforce field is a Component in the Salesforce org (visible in Setup, surfaced via the Metadata API)
• The same field has an XML definition in a GitHub repository that holds the org’s metadata
• Both are the same Component — just different representations of it

This matters because the representations can drift. The field in Salesforce can be edited in the UI without the repo being updated, and the file in the repo can be changed without being deployed. Catalio treats a Component as a single record and uses sync state to track whether the representations are aligned.

The external_system_type attribute identifies where the Component primarily lives (:salesforce, :servicenow, :workday, :sap, :github, :gitlab, :bitbucket, :azure_devops, and so on). The file_provider argument identifies which repository, if any, holds the file representation.

How Components Are Created

Components are almost always created by sync, not manual entry:

• From business-application metadata APIs. When you connect a Salesforce org, ServiceNow instance, or similar platform, Catalio pulls in its metadata — fields, validation rules, workflows, permission sets, page layouts, script files — and creates a Component for each one. Subsequent syncs update existing Components and surface new additions.
• From SCM providers. When a source code repository is connected (GitHub, GitLab, Bitbucket, Azure DevOps), Catalio walks the repo and creates a Component for each relevant file. Updates on subsequent syncs reflect commits.

Catalio manages Components externally — through Salesforce metadata sync and GitHub repository sync. The UI does not currently support manually adding, editing, or deleting Components; they flow in from the connected systems and stay in sync from there. If you need a Component to appear in Catalio, connect the system that owns it.

See the Synchronization and Integration section below for the sync-state lifecycle.

What a Component Is Not

• Not a GitHub issue, Jira ticket, or work item. Those are tracking artifacts about the work to change a Component, not the Component itself. A ticket may reference a Component, but it is not one.
• Not a business requirement. A Requirement describes what the system must do. A Component is the implementation — the thing that does it. Requirements and Components are linked, not equivalent.
• Not a deployment or environment. A Component’s state in a given environment may differ, but the Component identity is the same across environments.
• Not a whole service or Application. A microservice or external API as a whole is an Application (app_type: :service). The files and endpoints inside that microservice are Components.

Component Types

The component_type attribute classifies what kind of atomic artifact a Component is. The clean, atomic-level types are:

Legacy Types (Deprecated in Concept)

The one_of constraint currently also permits :external_api, :microservice, and :tool. These values mix levels: a whole microservice or external API is better modeled as an Application with app_type: :service, not as a single Component. :tool has similar ambiguity (it can describe a whole CI platform rather than a specific pipeline file).

Prefer the atomic types above when creating new Components. These legacy values remain in the enum for backward compatibility while the data model is refined — tracked in issue #1238.

Picking a Type

For business-application Components, the atomic type reflects what the metadata piece does:

• A Salesforce validation rule → :automation
• A Salesforce field → :database
• A Salesforce page layout → :ui
• A Salesforce Apex class or ServiceNow script include → :code
• A Salesforce permission set or ServiceNow role → :security

For custom-application Components (source files), the type reflects the file’s role in the codebase: a model is :code, a template/form is :ui, a migration file is :database, and so on.

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

Supported External Systems

Available today: Salesforce and GitHub. Additional integrations are on the roadmap — the external_system_type enum already accepts values for them so future connections will slot in without schema changes, but active sync is not yet wired up for these platforms.

Salesforce — Available

CRM platform components: objects, fields, flows, validation rules, Apex classes, permission sets, page layouts, and other metadata.

Use Case: Sync a Salesforce org and track which metadata items implement your customer-management requirements.

GitHub — Available

Source code repository components: files in a connected repo. Subsequent syncs reflect commits.

Use Case: Connect a custom-application repo and track which source files implement which requirements.

ServiceNow — Planned

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

Planned Use Case: Link incident-management requirements to ServiceNow incident tables and workflows.

Workday — Planned

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

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

SAP — Planned

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

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

Jira — Planned

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

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

GitLab / Bitbucket / Azure DevOps — Planned

Alternative SCM providers following the same file-sync model as GitHub.

Planned Use Case: Connect repos hosted outside GitHub without losing Component traceability.

AWS / Azure — Planned

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

Planned Use Case: Link infrastructure requirements to cloud resources and automation.

Custom — Planned

Manually-created Component records for internal systems, proprietary platforms, legacy applications, or any platform without a live integration. The :custom value is already present in the external_system_type enum on the Component model, so the data shape is ready — UI support for creating and managing custom Components is a planned feature.

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

The sync_status attribute has the following values (default :synced):

:not_synced

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

:syncing

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

:synced (default)

• Successfully synchronized with the external system — the Component’s metadata is current
• Also the baseline state for Components that don’t reference an external system

:sync_failed

• A sync attempt encountered errors
• Check sync_metadata for error details; may require operator attention

:sync_disabled

• Synchronization intentionally paused
• Use when external-system changes should not propagate into Catalio

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.

Creating Component-Requirement Links

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: :automation (validation rule that runs logic)
• 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: :automation (business rule with workflow logic)
• 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: Source File in a Custom Microservice

Whole microservices are modeled as Applications with app_type: :service, not as single Components. The individual source files inside a microservice are the Components. This example shows one such file.

Parent Application: “Customer Data Sync API” (app_type: :service, GitHub-synced repo catalio/customer-sync-api). The Application represents the microservice as a whole.

Component Details:

• Name: sync_scheduler.ex
• Description: Scheduler module that fires the customer-sync job every 15 minutes via Quantum cron. Handles retry logic and routes unrecoverable failures to the dead-letter queue. One of many source files inside the Customer Data Sync API Application.
• Type: :code (source file implementing scheduling logic)
• Status: Active
• External System: GitHub
• External ID: lib/customer_sync/sync_scheduler.ex
• URL: https://github.com/catalio/customer-sync-api/blob/main/lib/customer_sync/sync_scheduler.ex
• Sync Status: Synced
• Last Synced: 2025-01-15 02:00 AM

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

AI Summary: “Elixir scheduler module that runs the customer-sync cron, with retry handling and dead-letter queue routing.”

AI Tags: source-file, elixir, scheduler, cron, retry, data-integration

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.ai
• Community: Share integration patterns with other Catalio users