sfdc-servicenow-integ

Purpose

Provide a repository-level orientation and navigation guide for contributors and operators.

Audience

Contributors, architects, operators, admins

Scope

Repository structure, key workflows, and links to detailed documentation sets.

Related Documents

• Documentation Master Index; Architecture Index

Operational Notes

• Treat this document as part of the enterprise documentation system defined on 2026-03-24.
• Escalate conflicting guidance to architecture owners before implementation changes.

Revision Considerations

• Update links and examples whenever repository structure or package boundaries change.
• Record substantial directional changes via ADRs and cross-link from this document.

Core Content

A Salesforce DX repository for building a metadata-driven, modular Apex REST integration framework that synchronizes Salesforce Cases with ServiceNow Incidents for enterprise healthcare use cases.

Repository structure

repo-root/
  force-app/
    core/
      main/
        default/          # reusable runtime framework metadata and code
    config/
      main/
        default/          # configuration schema and secure connection metadata
    admin/
      main/
        default/          # admin app, tabs, layouts, permissions, and operator UX
    sample-config/
      main/
        default/          # sample custom metadata records for example org setups
  docs/
    adr/
    architecture/
    runbooks/
    process/
  scripts/
  manifests/
  .codex/
    config.toml
  README.md

Packaging model

• Core runtime package: Apex orchestration, async processing, runtime custom objects, and the reusable observability model.
• Config base package: custom metadata type definitions plus Named Credential / External Credential metadata that define the reusable configuration contract.
• Admin package: internal operational console metadata such as tabs, layouts, permission sets, and the admin application shell.
• Sample config package: non-production example custom metadata records demonstrating how different orgs can configure request types, routing, endpoint keys, and org definitions.

This split keeps executable runtime behavior separate from configuration schema, isolates admin/support UX from runtime metadata, and keeps org-specific samples out of the reusable product layers.

Centralized incident visibility design

The repository now includes a normalized ServiceNow_Incident_Link__c model intended to support future centralized reporting patterns across multiple Salesforce orgs.

Normalization principles:

• store the Salesforce org code and business unit alongside each link
• snapshot the Salesforce source object API name and source record label rather than relying on org-specific field layouts
• preserve the ServiceNow incident ID and incident number independently
• link each normalized record back to the originating Integration_Transaction__c for observability and retry analysis

These hooks support future aggregation in an admin org without assuming every source org uses the same exact field configuration.

Working principles

• Treat the repository as an enterprise healthcare integration framework.
• Keep business rules, field mappings, routing, and credentials out of code.
• Prefer metadata-driven configuration and modular packageable design.
• Avoid logging sensitive payloads.
• Keep orchestration separate from transport and transformation.
• Generate tests with every Apex implementation.
• Do not make destructive changes without explicit instruction.

Existing Salesforce DX configuration

• sfdx-project.json defines four package directories: force-app/core, force-app/config, force-app/admin, and force-app/sample-config.
• manifests/package.xml and manifest/package.xml provide starter deployment manifests.
• config/project-scratch-def.json remains available for scratch org creation.

Common commands

sf org login web --alias devhub
sf org create scratch --definition-file config/project-scratch-def.json --alias sn-integ-scratch --set-default --duration-days 7
sf project deploy start --source-dir force-app/core
sf project deploy start --source-dir force-app/config
sf project deploy start --source-dir force-app/admin
sf project deploy start --source-dir force-app/sample-config
sf project retrieve start --manifest manifests/package.xml

A lightweight metadata guardrail script is also available:

python3 scripts/ci/validate-config-metadata.py

CI/CD quality gates

Repo-native CI/CD helpers now live in scripts/ci/ with a matching GitHub Actions example in .github/workflows/quality-gates.yml. The gates cover static analysis, Apex tests, metadata validation, and package readiness checks without hardcoding environment-specific org names. See docs/runbooks/ci-cd-quality-gates.md for setup and usage details.

Codex repository instruction

Use this as the baseline instruction for Codex in this repo:

Read this Salesforce DX project and treat it as an enterprise healthcare integration framework. All code must be metadata-driven, modular, packageable, and suitable for multi-org deployment. Do not hardcode business rules, routing, field mappings, or credentials. Generate secure Apex, Custom Metadata Types, tests, and documentation. Assume ServiceNow field mappings and process rules will evolve over time.