9.3 External API Integrations, HTTP Actions & Named Credentials

9.3 External API Integrations, HTTP Actions & Named Credentials

Exam Focus: Modern government agencies do not operate in technical isolation. Public Sector Solutions must interoperate with a sprawling ecosystem of external state, federal, municipal, and commercial systems—ranging from criminal history checks and DMV registries to GIS parcel boundaries and tax clearance databases. On the AP-222 exam, candidates are evaluated on their ability to configure secure, declarative external integrations using Integration Procedure HTTP Actions, implement Enhanced Named Credentials and External Credentials in compliance with zero-trust public security standards, and architecturally justify when to use Integration Procedures versus enterprise platforms like MuleSoft or custom Apex.

---

The Public Sector Integration Ecosystem

In public sector solution architecture, external integrations typically fulfill mandatory statutory verification requirements before an agency can legally grant a license, issue a permit, or disburse public funds. Common external touchpoints include:

• Identity & Licensing Verifications: Connecting to state Departments of Motor Vehicles (DMV) or National Driver Registries to validate commercial driver qualifications.
• Criminal Justice & Background Screenings: Integrating with State Police or Federal Bureau of Investigation (FBI) Criminal Justice Information Services (CJIS) databases for live-scan fingerprint background checks.
• Geographic Information Systems (GIS): Interfacing with municipal Esri ArcGIS servers to validate real property parcel boundaries, flood zones, and zoning ordinances during building permit reviews.
• Tax Compliance & Wage Verification: Connecting to state Departments of Revenue or the IRS (under strict IRS Publication 1075 safeguards) to verify constituent income eligibility for social safety net programs.
• Statutory Fee Collections: Calling certified government payment gateways (such as Pay.gov or municipal merchant providers) to process non-refundable application and renewal fees.

Government Security Baselines: The Mandate Against Hardcoding

Public sector architectures deployed within Salesforce Government Cloud (FedRAMP High, DoD Impact Level 4/5) are subject to stringent cybersecurity audits. Storing external endpoint URLs, basic authentication usernames, API passwords, or OAuth client secrets directly in Apex code, custom metadata, or OmniStudio elements is a severe security violation. Integration architectures must utilize Salesforce Named Credentials to ensure all secrets are encrypted at rest, rotated centrally, and inaccessible to unauthorized users or client-side inspection tools.

---

Configuring HTTP Actions in Integration Procedures

The HTTP Action element inside an Integration Procedure enables declarative outbound web service callouts without requiring custom Apex HttpRequest classes.

+-----------------------------------------------------------------------------------+
|                         HTTP Action Configuration Architecture                    |
+-----------------------------------------------------------------------------------+
| [Integration Procedure: HTTP Action Element]                                      |
|   • HTTP Method:          GET / POST / PUT / PATCH / DELETE                       |
|   • HTTP Path (Endpoint): callout:State_DMV_Credential/api/v2/drivers/verify     |
|   • Timeout:              Up to 120,000 milliseconds (120 seconds)                |
|   • Headers:              Content-Type: application/json                          |
|   • Input JSON Path:      %SanitizedDriverPayload%                                |
|   • Output JSON Path:     %DMVVerificationResult%                                 |
+-----------------------------------------------------------------------------------+
|                                    │                                              |
|                                    ▼                                              |
|                       [Enhanced Named Credential]                                 |
|                       • URL: https://api.dmv.state.gov                            |
|                       • Links to: State_DMV_External_Credential                   |
|                                    │                                              |
|                                    ▼                                              |
|                       [External Credential Tier]                                  |
|                       • Protocol: OAuth 2.0 (Client Credentials)                  |
|                       • Principal: DMV_Machine_Integration                        |
|                       • Access Granted via: PSS_Caseworker_PermSet                |
+-----------------------------------------------------------------------------------+

REST/JSON vs. Legacy SOAP/XML Handling in Government Systems

While modern cloud services expose RESTful JSON endpoints, many public sector agencies still rely on legacy mainframes exposing SOAP 1.1/1.2 or raw XML web services. Candidates must understand how OmniStudio handles both data paradigms:

1. Native REST/JSON Callouts

For REST/JSON web services, the HTTP Action works seamlessly without intermediate translation:

• Set the HTTP Method to POST or GET.
• Point the endpoint to the Named Credential: callout:State_Tax_Service/v1/status.
• Pass the relevant JSON branch via Input JSON Path.
• The HTTP Action parses the incoming JSON response directly into the Integration Procedure's data tree at the specified Output JSON Path.

2. Bridging Legacy SOAP/XML via Data Mapper Transform

When connecting to a state legacy mainframe that requires an XML envelope:

1. Inbound Transformation: The IP executes a Data Mapper Transform that maps the constituent's JSON data into a structured SOAP/XML request body (including statutory SOAP headers, envelopes, and namespaces).
2. HTTP Action Callout: The HTTP Action sends the XML string with an HTTP Header of Content-Type: text/xml or application/soap+xml.
3. Outbound Transformation: The legacy system returns a raw SOAP/XML response. The IP routes this XML string into a second Data Mapper Transform that parses the XML tags, extracts the operational status codes, and outputs a clean, flat JSON object for downstream processing.

This pattern allows the public sector agency to modernize its citizen frontend with OmniStudio while maintaining compatibility with 30-year-old state mainframes.

---

Enhanced Named Credentials & External Credentials Architecture

In modern Salesforce architectures, the legacy Named Credentials model has been replaced by the Enhanced Named Credentials framework. This architecture decouples the physical endpoint URL from the authentication protocol, introducing granular, zero-trust security administration.

+-----------------------------------------------------------------------------------+
|                 Enhanced Named Credentials Component Hierarchy                    |
+-----------------------------------------------------------------------------------+
| 1. External Credential (Authentication Specification):                            |
|    • Protocol: OAuth 2.0, Custom (API Key), Mutual TLS (mTLS), or AWS Signature   |
|    • Authentication Flow: Client Credentials, JWT Bearer, Authorization Code      |
|    • Principals: Defines identities (e.g., 'Named Principal' or 'Per-User')        |
|                                                                                   |
| 2. Named Credential (Endpoint & Policy Specification):                            |
|    • URL: https://secure-api.fbi-cjis.gov/records/v3                              |
|    • External Credential Reference: Points to CJIS_Auth_External_Cred             |
|    • Options: Generate Auth Header, Allow Merge Fields in Header/Body             |
|                                                                                   |
| 3. Permission Set (Authorization Enforcement):                                    |
|    • 'External Credential Principal Access' assigned to Profiles/PermSets         |
|    • Guarantees that only authorized caseworkers or guest users can call endpoint |
+-----------------------------------------------------------------------------------+

The Three Tiers of Enhanced Named Credentials:

1. External Credential (The Authentication Contract)

The External Credential defines how authentication occurs. It encapsulates:

• Authentication Protocol: OAuth 2.0, Custom Authentication, Mutual TLS (mTLS) with client certificates, or AWS Signature Version 4.
• Authentication Flow: In machine-to-machine public sector integrations, OAuth 2.0 Client Credentials Grant or JWT Bearer Token flows are standard. Client IDs, Client Secrets, Token Endpoints, and Scopes are configured securely at this tier.
• Principals: Defines the credential identity. A Named Principal uses a single, shared system identity for all callouts (standard for background checks or GIS lookups). A Per-User Principal requires each individual Salesforce user to authenticate via their personal account.

2. Named Credential (The Endpoint Definition)

The Named Credential specifies where the callout is routed. It links directly to the External Credential and defines:

• URL Endpoint: The base URL of the external government service (e.g., https://api.gis.county.gov).
• Callout Options: Enables Generate Authorization Header (which automatically injects the Authorization: Bearer <token> header without developer intervention).

3. Permission Set Mapping (Zero-Trust Enforcement)

Configuring an External Credential and Named Credential does not automatically allow users to execute callouts. In alignment with zero-trust government security models:

• Administrators must edit the Permission Set assigned to the calling users (e.g., Public Sector Intake Worker or the Experience Cloud Portal Guest User).
• Under External Credential Principal Access, the administrator explicitly grants access to the designated External Credential Principal.
• Exam Tip: If an Integration Procedure HTTP Action fails with an HTTP 403 Forbidden or authorization failure despite correct credentials, verify whether the executing user's Permission Set has been granted access to the External Credential Principal!

Callout Protocol Syntax in HTTP Actions

When referencing a Named Credential within an OmniStudio HTTP Action, always utilize the standard callout prefix syntax:

callout:Name_Of_Named_Credential/relative/path/endpoint

Example: callout:State_DMV_Service/api/v1/license/validate

The platform's runtime engine automatically intercepts the callout: schema, queries the associated External Credential, manages token caching and renewal, signs the request, and dispatches it over an encrypted TLS 1.3 channel.

---

Architectural Decision Matrix: Integration Procedures vs. MuleSoft vs. Custom Apex

Enterprise architects designing solutions for large public sector agencies frequently face the strategic choice of which integration tool to deploy. The AP-222 blueprint rigorously tests candidate judgment on selecting the appropriate tool for specific operational profiles.

Strategic Selection Rules of Thumb for the AP-222 Exam:

1. Select Integration Procedures when:
   • The integration directly supports an OmniScript, FlexCard, or citizen portal workflow;
   • The data format is REST/JSON or standard SOAP/XML;
   • The requirement is real-time, low-latency, and operates within standard platform governor limits (payloads < 6MB, callout time < 120s);
   • Low-code, declarative maintainability within the Salesforce core stack is prioritized.
2. Select MuleSoft when:
   • Connecting to heterogeneous legacy systems requiring specialized protocol adapters (e.g., SAP, IBM MQ, AS400, HL7 medical records, EDIFACT);
   • Requiring enterprise API Gateway capabilities: token rate-limiting, traffic throttling, multi-agency API monetization, or centralized SLA monitoring;
   • Implementing asynchronous publish-subscribe message queuing across dozens of disparate state and federal agencies;
   • Transforming millions of complex records nightly where Salesforce platform heap and CPU limits would be exceeded.
3. Select Custom Apex Callouts when:
   • Handling non-standard authentication schemes not supported by Enhanced Named Credentials (e.g., custom hashing algorithms or multi-step challenge-response handshakes);
   • Parsing or streaming large multipart binary files (such as raw geospatial LIDAR data or high-resolution surveillance video) requiring byte-level manipulation.

---

💡 Real-World Exam Scenarios & Case Analysis

Scenario 1: State Business Licensing Portal with GIS and SOS Integrations

A state department of commerce builds an online portal for commercial aquaculture permits. During the intake OmniScript, the system must: (1) verify that the applicant corporation is in good standing with the Secretary of State (SOS) corporate registry via a REST API; (2) query a state environmental GIS server to verify that the proposed marine coordinates do not overlap protected wildlife zones; and (3) record all credentials securely without exposing keys to portal users.

A junior developer suggests using an external JavaScript library embedded in the OmniScript to execute direct browser fetch() requests to the GIS and SOS endpoints using hardcoded API tokens in the script.

Why is this proposal unacceptable in a government architecture, and how should it be structured according to AP-222 best practices?

• Security Flaw: Executing callouts directly from the browser exposes confidential agency API keys in client-side developer tools, violates CORS policies, and fails state cybersecurity audits.
• AP-222 Best Practice Architecture:
  1. Create two External Credentials in Salesforce setup specifying Custom or OAuth 2.0 authentication for the SOS and GIS systems.
  2. Create two Named Credentials (callout:State_SOS_Service and callout:State_GIS_Service) linking to their respective External Credentials.
  3. Grant the Experience Cloud site user profile access to the External Credential Principals via a dedicated Permission Set.
  4. Build an Integration Procedure containing two HTTP Actions pointing to the Named Credentials. The IP executes server-side, keeping all credentials confidential, and returns only the verified status and geospatial coordinates to the OmniScript.

Scenario 2: High-Security FBI CJIS Background Check with Mutual TLS

A state child welfare agency requires mandatory criminal background checks for all foster parent applicants. The agency must integrate with the FBI Criminal Justice Information Services (CJIS) database, which enforces mutual TLS (mTLS) certificate authentication and returns data formatted as an encrypted SOAP/XML response. The system must parse this response, extract the applicant's clearance status, and update the Foster_Parent_Application__c record without creating custom Apex code.

How should the Enterprise Architect design this integration?

• Upload the agency's state-issued digital client certificate into Salesforce Certificate and Key Management.
• Configure an External Credential using Mutual TLS protocol and link the uploaded client certificate to the Named Principal.
• Create a Named Credential pointing to the FBI CJIS secure endpoint URL.
• In the Integration Procedure, configure:
  • Step 1: A Data Mapper Transform converting the applicant's PSS demographic data into the required FBI SOAP XML envelope.
  • Step 2: An HTTP Action calling callout:FBI_CJIS_Service/backgroundCheck with Content-Type: text/xml.
  • Step 3: A second Data Mapper Transform parsing the returned XML, extracting the ClearanceStatus tag, and converting it to JSON.
  • Step 4: A Data Mapper Load updating the applicant's record.
• This solution achieves 100% declarative compliance with federal CJIS security baselines.