Skip to content

forcedotcom/sf-skills / plugins/builder/integration/skills/integration-connectivity-generate

integration-connectivity-generate

Verified

Salesforce integration architecture and runtime plumbing with 120-point scoring. Use this skill to set up Named Credentials, External Credentials, External Services, REST/SOAP callout patterns, Platform Events, and Change Data Capture. TRIGGER when: user sets up Named Credentials, External Services, REST/SOAP callouts, Platform Events, CDC, or touches .namedCredential-meta.xml files. DO NOT TRIGGER when: Connected App/OAuth config (use integration-connectivity-connected-app-configure), Apex-only logic (use platform-apex-generate), data import/export (use platform-data-manage), or CDC channel-membership metadata such as PlatformEventChannel, PlatformEventChannelMember, or EnrichedField (use integration-eventing-cdc-configure).

FileKindSize
README.mdmarkdown3.5 KB
SKILL.mdskill md8.8 KB
assets/callouts/callout-retry-handler.clsother6.0 KB
assets/callouts/http-response-handler.clsother8.5 KB
assets/callouts/rest-queueable-callout.clsother8.8 KB
assets/callouts/rest-sync-callout.clsother7.4 KB
assets/cdc/cdc-handler.clsother8.4 KB
assets/cdc/cdc-subscriber-trigger.triggerother5.3 KB
assets/endpoint-security/example.cspTrustedSite-meta.xmlconfig1.8 KB
assets/endpoint-security/example.remoteSite-meta.xmlconfig1.3 KB
assets/external-credentials/jwt-external-credential.externalCredential-meta.xmlconfig3.2 KB
assets/external-credentials/oauth-external-credential.externalCredential-meta.xmlconfig3.0 KB
assets/external-services/external-service-operations.mdmarkdown5.5 KB
assets/external-services/openapi-registration.externalServiceRegistration-meta.xmlconfig4.8 KB
assets/named-credentials/certificate-auth.namedCredential-meta.xmlconfig2.2 KB
assets/named-credentials/custom-auth.namedCredential-meta.xmlconfig2.2 KB
assets/named-credentials/oauth-client-credentials.namedCredential-meta.xmlconfig1.8 KB
assets/named-credentials/oauth-jwt-bearer.namedCredential-meta.xmlconfig2.2 KB
assets/platform-events/event-publisher.clsother6.4 KB
assets/platform-events/event-subscriber-action.clsother9.5 KB
assets/platform-events/event-subscriber-trigger.triggerother3.9 KB
assets/platform-events/platform-event-definition.object-meta.xmlconfig3.7 KB
assets/soap/soap-callout-service.clsother6.4 KB
assets/soap/wsdl2apex-guide.mdmarkdown6.2 KB
references/callout-patterns.mdmarkdown21.8 KB
references/cdc-guide.mdmarkdown8.2 KB
references/cli-reference.mdmarkdown2.9 KB
references/event-driven-architecture-guide.mdmarkdown10.1 KB
references/event-patterns.mdmarkdown27.2 KB
references/external-services-guide.mdmarkdown8.4 KB
references/messaging-api-v2.mdmarkdown17.9 KB
references/named-credentials-automation.mdmarkdown6.2 KB
references/named-credentials-guide.mdmarkdown7.1 KB
references/platform-events-guide.mdmarkdown6.6 KB
references/rest-callout-patterns.mdmarkdown8.8 KB
references/scoring-rubric.mdmarkdown2.4 KB
references/security-best-practices.mdmarkdown5.9 KB
scripts/README.mdmarkdown2.9 KB
scripts/configure-named-credential.shexecutablescript9.2 KB
scripts/set-api-credential.shexecutablescript4.9 KB
scripts/suggest_credential_setup.pyscript9.3 KB
scripts/templates/setup-credentials-with-csp.shexecutablescript5.9 KB
scripts/validate_integration.pyscript13.4 KB

references/external-services-guide.md

View on GitHub
<!-- Parent: integration-connectivity-generate/SKILL.md -->
# External Services Guide

## Overview

External Services in Salesforce automatically generate Apex classes from OpenAPI (Swagger) specifications, enabling type-safe REST API integrations without writing HTTP code.

## How It Works

```text
┌─────────────────────────────────────────────────────────────────┐
│  EXTERNAL SERVICE FLOW                                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. OpenAPI Spec (JSON/YAML)                                    │
│     ↓                                                           │
│  2. External Service Registration (Metadata)                    │
│     ↓                                                           │
│  3. Auto-generated Apex Classes                                 │
│     ↓                                                           │
│  4. Type-safe API calls from Apex                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Prerequisites

1. **Named Credential** configured for authentication
2. **OpenAPI Specification** (2.0 or 3.0) for the API
3. **API Version 48.0+** (Winter '20)

## Creating External Service

### Via Setup UI

1. Go to **Setup → External Services**
2. Click **New External Service**
3. Provide name and description
4. Select **Named Credential**
5. Upload or paste OpenAPI spec
6. Review operations
7. Save

### Via Metadata API

**Template**: `assets/external-services/openapi-registration.externalServiceRegistration-meta.xml`
**Reference**: `assets/external-services/external-service-operations.md`

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Stripe API</label>
    <description>Stripe payment processing API</description>
    <namedCredential>Stripe_API</namedCredential>
    <schemaType>OpenApi3</schemaType>
    <schema>
{
  "openapi": "3.0.0",
  "info": { "title": "Stripe API", "version": "1.0" },
  "paths": { ... }
}
    </schema>
    <status>Complete</status>
</ExternalServiceRegistration>
```

## Generated Classes

For an External Service named "StripeAPI":

| Class | Purpose |
|-------|---------|
| `ExternalService.StripeAPI` | Main service class with operation methods |
| `ExternalService.StripeAPI_createCustomer_Request` | Request wrapper |
| `ExternalService.StripeAPI_createCustomer_Response` | Response wrapper |
| `ExternalService.StripeAPI_Customer` | DTO matching schema |

## Usage Patterns

### Basic GET Request

```apex
// Instantiate service
ExternalService.StripeAPI stripe = new ExternalService.StripeAPI();

// Call GET operation
ExternalService.StripeAPI_getCustomer_Response response =
    stripe.getCustomer('cus_ABC123');

// Access response data
String email = response.email;
```

### POST with Request Body

```apex
// Create request object
ExternalService.StripeAPI_createCustomer_Request request =
    new ExternalService.StripeAPI_createCustomer_Request();
request.email = 'customer@example.com';
request.name = 'John Doe';

// Make call
ExternalService.StripeAPI_createCustomer_Response response =
    stripe.createCustomer(request);

// Get created resource ID
String customerId = response.id;
```

### Handling Nested Objects

```apex
// Access nested data
ExternalService.StripeAPI_Address address = response.address;
String city = address.city;
String postalCode = address.postalCode;
```

## Error Handling

```apex
try {
    ExternalService.StripeAPI stripe = new ExternalService.StripeAPI();
    response = stripe.getCustomer('invalid_id');

} catch (ExternalService.ExternalServiceException e) {
    // API returned error response
    System.debug('Status Code: ' + e.getStatusCode());
    System.debug('Error Body: ' + e.getBody());
    System.debug('Error Message: ' + e.getMessage());

} catch (CalloutException e) {
    // Network/connection error
    System.debug('Connection failed: ' + e.getMessage());
}
```

## Async Calls (Queueable)

Use Queueable for calls from triggers:

```apex
public class StripeCustomerSync implements Queueable, Database.AllowsCallouts {

    private Account account;

    public StripeCustomerSync(Account account) {
        this.account = account;
    }

    public void execute(QueueableContext context) {
        ExternalService.StripeAPI stripe = new ExternalService.StripeAPI();

        ExternalService.StripeAPI_createCustomer_Request req =
            new ExternalService.StripeAPI_createCustomer_Request();
        req.email = account.Email__c;
        req.name = account.Name;

        try {
            ExternalService.StripeAPI_createCustomer_Response resp =
                stripe.createCustomer(req);

            account.Stripe_Customer_Id__c = resp.id;
            update account;
        } catch (Exception e) {
            System.debug('Sync failed: ' + e.getMessage());
        }
    }
}
```

## OpenAPI Schema Tips

### Supported Features

- GET, POST, PUT, PATCH, DELETE methods
- Path and query parameters
- Request and response bodies
- JSON schema types (string, number, boolean, object, array)
- References ($ref)
- Basic authentication headers

### Limitations

- **No file uploads** (multipart/form-data limited)
- **No WebSockets** (HTTP only)
- **No streaming responses**
- **Some complex schemas** may not parse
- **Maximum schema size** limited

### Schema Best Practices

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/customers/{id}": {
      "get": {
        "operationId": "getCustomer",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Customer" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Customer": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "email": { "type": "string" }
        }
      }
    }
  }
}
```

## Updating External Service

When API changes:

1. Get updated OpenAPI spec
2. Go to Setup → External Services
3. Edit service
4. Upload new schema
5. Review changes to operations
6. Save and validate
7. Update calling code if signatures changed

## Testing

```apex
@isTest
private class StripeIntegrationTest {

    @isTest
    static void testCreateCustomer() {
        // Set mock
        Test.setMock(HttpCalloutMock.class, new StripeMock());

        Test.startTest();

        ExternalService.StripeAPI stripe = new ExternalService.StripeAPI();
        ExternalService.StripeAPI_createCustomer_Request req =
            new ExternalService.StripeAPI_createCustomer_Request();
        req.email = 'test@example.com';

        ExternalService.StripeAPI_createCustomer_Response resp =
            stripe.createCustomer(req);

        Test.stopTest();

        System.assertEquals('cus_test123', resp.id);
    }

    private class StripeMock implements HttpCalloutMock {
        public HttpResponse respond(HttpRequest request) {
            HttpResponse response = new HttpResponse();
            response.setStatusCode(201);
            response.setBody('{"id": "cus_test123", "email": "test@example.com"}');
            return response;
        }
    }
}
```

## Use with Agentforce

External Services are ideal for Agent Actions:

1. Create External Service from API spec
2. Create Flow that calls External Service
3. Reference Flow in Agent Script action

```agentscript
actions:
    lookup_customer:
        description: "Looks up customer in payment system"
        inputs:
            customer_email: string
        outputs:
            customer_id: string
        target: "flow://Lookup_Stripe_Customer"
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall