salesforce-integration-review-skill

Salesforce Integration Review Skill

Purpose

This skill reviews Salesforce integration designs for API choice, middleware positioning, retry/idempotency, error queue design, observability, secret handling, OAuth scope minimization, named credential patterns, and MuleSoft vs point-to-point architecture decisions. It surfaces risks, anti-patterns, and recommendations. It does not access live systems, test endpoints, or request credentials.

When to use

• An integration architecture is being designed or reviewed before build.
• An existing integration is being audited for security or reliability.
• A new API connection is being added and the design must be assessed.
• An incident has occurred and the integration design is under review.

When not to use

• Apex code quality is the focus — use salesforce-apex-lwc-code-review-skill.
• Marketing data flow consent review — use salesforce-marketing-consent-review-skill.
• Live integration change deployment — use salesforce-live-change-approval-protocol.
• Full org posture — use salesforce-org-assessment-skill.

Minimum payload (required inputs)

• Integration design description: systems involved, data flows, direction, frequency.
• API type(s) used (REST, SOAP, Bulk, Streaming, Platform Events, CDC, external services).
• Authentication method (OAuth, session ID, named credential, API key).
• Middleware presence: MuleSoft , other iPaaS, or point-to-point.
• Error handling and retry design (or note that it is undocumented).

Workflow

1. API choice review

• Assess whether the chosen API is appropriate for the use case:
  • REST API: appropriate for record CRUD and metadata; flag if used for bulk data (> configurable threshold records per batch) without Bulk API.
  • SOAP API: flag if used for new integrations (REST is preferred); acceptable for legacy systems.
  • Bulk API : verify serial vs parallel job selection; flag if used for real-time use cases requiring low latency.
  • Streaming API / Platform Events : verify subscriber durability; flag if subscriber does not handle replay.
  • Change Data Capture : verify object selection; flag if all-object CDC is enabled without consumption capacity planning.
  • External Services : verify OpenAPI spec version; flag if used for high-volume synchronous patterns.

2. Middleware position

• Assess middleware role: event broker, transformation, routing, error handling.
• Flag: point-to-point connections that bypass a middleware layer for non-trivial data transformation.
• Flag: middleware not present for integrations crossing security or compliance domains.
• MuleSoft : flag if the Anypoint platform is used but policies (rate limiting, IP allowlisting, threat protection) are not documented.

3. Retry and idempotency

• Verify that retry logic exists for transient failures (network timeouts, 5xx errors).
• Flag: retry without idempotency key (can create duplicate records on retry).
• Flag: exponential backoff absent (linear retry can cause thundering herd).
• Flag: infinite retry without a dead-letter or poison-message mechanism.

4. Error queue design

• Verify that failed messages are routed to an error queue or dead-letter topic.
• Flag: silent failure (errors logged but no queue, no alert, no human review).
• Flag: error queue not monitored or without a defined SLA for remediation.
• Flag: failed records re-inserted without deduplication logic.

5. Observability

• Verify that integration events are logged (at minimum: request ID, timestamp, direction, status, error code).
• Flag: logging that includes PII or credentials (over-logging).
• Flag: no alerting on error rate threshold breach.
• Flag: no end-to-end tracing that correlates Salesforce event to external system.

6. Secret handling

• Flag: API keys, client secrets, or passwords hardcoded in Apex, Flow, or integration configuration.
• Verify: Named Credentials or External Credentials used for all outbound callouts.
• Flag: session ID used as an API credential (session IDs expire and are not suitable for long-running integrations).
• Flag: client secrets stored in Custom Settings or Custom Metadata without encryption.

7. OAuth scope minimization

• Review the OAuth scopes requested by connected apps.
• Flag: full scope (grants all permissions; should never be used in production).
• Flag: api scope without specific object-level restriction where a more restricted scope is available.
• Flag: refresh_token scope on integrations that do not require long-lived access.
• Recommend: minimum-necessary scope per the integration's function.

8. Named credential vs direct callout

• Verify that outbound callouts use Named Credentials or External Credentials.
• Flag: callouts using hardcoded URLs or credentials in Apex code.
• Flag: callouts to endpoints not in the org's remote site settings ( CSP / remote site settings).

9. MuleSoft vs point-to-point assessment

• If MuleSoft is present: verify that it is used for all integration routing; flag bypasses.
• If point-to-point: flag integrations > configurable complexity threshold that should be routed through a middleware layer.
• Flag: fan-out from Salesforce to > configurable number of external systems without a message broker.

Evidence requirements

• Sanitized integration design document or description; no credentials, tokens, or customer data.
• List of API types, authentication methods, and middleware present.
• Error handling and retry design documentation (or note that it is absent).

Output format

integration_review_findings:
  api_choice:
    - finding: [description]
      severity: Critical | High | Medium | Low
      recommendation: [brief]
  middleware_position: [same structure]
  retry_idempotency: [same structure]
  error_queue_design: [same structure]
  observability: [same structure]
  secret_handling: [same structure]
  oauth_scope: [same structure]
  named_credential_usage: [same structure]
  middleware_vs_point_to_point: [same structure]

summary:
  total_findings: [count]
  critical_count: [count]
  high_count: [count]
escalation_gates_fired: [from salesforce-risk-taxonomy, or "none"]
assumptions: [list]
missing_evidence: [what would improve the review]

Redaction rules

• Never request secrets, credentials, OAuth tokens, refresh tokens, session IDs, MFA seeds, customer PII.
• Sanitize org IDs, user IDs (replace with placeholders) before sharing in outputs.
• If design documents contain real credentials or endpoint secrets, stop and ask for sanitized version.

Privilege / data handling rules

• Integration review is design-level only; do not carry actual API responses or payload samples.
• Integrations crossing regulated-data domains (HIPAA, PCI) must be flagged for compliance review.

Handoff rules

• Hands off to: salesforce-apex-lwc-code-review-skill (if callout Apex code needs review), salesforce-marketing-consent-review-skill (if integration involves Marketing Cloud data flows), salesforce-data-exposure-escalation-protocol (if integration creates data exposure risk).
• If escalation gate fires: salesforce-case-capsule with escalation_required = true.
• Required handoff fields: matter_id, critical_count, escalation_gates_fired, secret_handling summary.

Audit log fields

• matter_id, skill_id, skill_version, invoked_by, input_hash, evidence_quality, output_verdict, escalation_fired, timestamp

Stop conditions

• Design document contains live credentials, session tokens, or real API keys — stop and ask for sanitized version.
• Integration involves regulated-data cross-org transfer without a documented DPA — fire production-data-exposure gate.
• full OAuth scope detected in production — Critical finding; require immediate human review.

Security notes

• Read-only static design review; never tests endpoints or requests live credentials.
• full OAuth scope is always a Critical finding in production integrations.
• Named Credentials are the required pattern for outbound callouts; deviations require documented justification.
• DPA obligations for cross-org data transfers must be verified with legal counsel.