CS Platform Wiki

Core · Service · Active

platform-connectors-service

Shared datasource boundary used by product backends and MCP tools to reach Salesforce through source-based, service-to-service connector contracts.

  • TypeScript
  • NestJS 11
  • PostgreSQL
  • jsforce
  • HTTP internal APIs

Spec sheet

Boundary

Core / Datasource

Runtime

NestJS 11 HTTP service

Default port

3200

Security

Internal-only surface guarded by x-platform-internal-token

Primary connector

Salesforce via jsforce

Persistence

PostgreSQL via CONNECTORS_DATABASE_URL

Responsibilities

  • Keep vendor SDK logic out of product BFFs.
  • Expose connector health, source configuration and capability discovery.
  • Support Salesforce object describe, structured query, raw read-only SOQL, SOSL and cursor pagination.
  • Expose single-record CRUD, batch record operations and controlled Apex REST invocation for product BFFs.

Interfaces and contract surface

  • GET /health
  • GET /internal/connectors/health
  • GET /internal/connectors/sources
  • POST /internal/connectors/sources/:sourceId/test
  • POST /internal/connectors/sources/:sourceId/configure
  • GET /internal/connectors/sources/:sourceId/status
  • GET /internal/connectors/sources/:sourceId/capabilities
  • GET /internal/connectors/sources/:sourceId/describe/objects
  • GET /internal/connectors/sources/:sourceId/describe/objects/:objectName
  • GET /internal/connectors/sources/:sourceId/describe/objects/:objectName/fields
  • POST /internal/connectors/sources/:sourceId/query/run
  • POST /internal/connectors/sources/:sourceId/query/page
  • POST /internal/connectors/sources/:sourceId/query/more
  • POST /internal/connectors/sources/:sourceId/query/raw
  • POST /internal/connectors/sources/:sourceId/query/raw/page
  • POST /internal/connectors/sources/:sourceId/query/raw/more
  • POST /internal/connectors/sources/:sourceId/query/sosl
  • POST /internal/connectors/sources/:sourceId/records/:objectName
  • POST /internal/connectors/sources/:sourceId/records/:objectName/create-many
  • POST /internal/connectors/sources/:sourceId/records/:objectName/update-many
  • POST /internal/connectors/sources/:sourceId/records/:objectName/upsert-many
  • POST /internal/connectors/sources/:sourceId/records/:objectName/delete-many
  • PUT /internal/connectors/sources/:sourceId/records/:objectName/:recordId
  • DELETE /internal/connectors/sources/:sourceId/records/:objectName/:recordId
  • POST /internal/connectors/sources/:sourceId/apex/invoke

Consumers

Dependencies and external touchpoints

Notes

  • Frontend applications must never call this service directly.
  • The current public proxy does not expose a dedicated host for this service in local stack.
  • The legacy /internal/connectors/salesforce/* controller has been removed; consumers should use source-based endpoints under /internal/connectors/sources/:sourceId.

Source references

  • platform-connectors-service/README.md
  • docs/core-services-integration.md
  • platform-connectors-service/package.json

Come integrarsi davvero ​

platform-connectors-service e un boundary esclusivamente service-to-service. I frontend non devono chiamarlo mai direttamente: un backend/BFF di prodotto traduce il contratto tecnico in un contratto pubblico piu adatto al dominio applicativo.

Variabili utili ​

bash
export CONNECTORS_URL=http://127.0.0.1:3200
export INTERNAL_TOKEN=platform-local-stack-internal-token
export SOURCE_ID=salesforce-default

salesforce-default e il sourceId locale standard usato dai BFF quando non devono gestire piu sorgenti.

1. Discovery rapida di sorgenti e stato ​

bash
curl -sS "$CONNECTORS_URL/internal/connectors/sources" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"
bash
curl -sS "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/status" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

2. Test e configurazione di una sorgente Salesforce ​

Prima puoi validare le credenziali senza persisterle:

bash
curl -sS -X POST "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/test" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "providerKey": "salesforce",
    "config": {
      "mode": "username-password",
      "loginUrl": "https://login.salesforce.com",
      "username": "integration@example.com",
      "password": "super-secret-password",
      "securityToken": "security-token"
    }
  }'

Quando il probe e corretto, usa lo stesso payload su /configure per salvarlo:

bash
curl -sS -X POST "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/configure" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "providerKey": "salesforce",
    "config": {
      "mode": "username-password",
      "loginUrl": "https://login.salesforce.com",
      "username": "integration@example.com",
      "password": "super-secret-password",
      "securityToken": "security-token"
    }
  }'

3. Describe e query strutturata ​

Campi di un oggetto:

bash
curl -sS \
  "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/describe/objects/Contact/fields" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

Per i BFF che hanno gia template SOQL/SOSL propri, il contratto source-based espone anche:

  • POST /internal/connectors/sources/$SOURCE_ID/query/raw
  • POST /internal/connectors/sources/$SOURCE_ID/query/raw/page
  • POST /internal/connectors/sources/$SOURCE_ID/query/raw/more
  • POST /internal/connectors/sources/$SOURCE_ID/query/sosl

Query strutturata paginata:

bash
curl -sS -X POST "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/query/page" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "pageSize": 100,
    "query": {
      "kind": "structured",
      "query": {
        "objectName": "Contact",
        "select": ["Id", "Name", "Email"],
        "sort": [
          {
            "field": "Name",
            "direction": "ASC"
          }
        ],
        "limit": 100
      }
    }
  }'

Se la risposta contiene nextCursor, la pagina successiva si legge cosi:

bash
curl -sS -X POST "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/query/more" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "cursor": "<NEXT_CURSOR>",
    "pageSize": 100
  }'

4. Operazioni record e Apex controllato ​

Creazione singola:

bash
curl -sS -X POST "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/records/Contact" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "record": {
      "LastName": "Rossi",
      "Email": "mario.rossi@example.com"
    }
  }'

Operazioni batch:

  • POST /internal/connectors/sources/$SOURCE_ID/records/:objectName/create-many
  • POST /internal/connectors/sources/$SOURCE_ID/records/:objectName/update-many
  • POST /internal/connectors/sources/$SOURCE_ID/records/:objectName/upsert-many
  • POST /internal/connectors/sources/$SOURCE_ID/records/:objectName/delete-many

Apex REST controllato:

bash
curl -sS -X POST "$CONNECTORS_URL/internal/connectors/sources/$SOURCE_ID/apex/invoke" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "method": "GET",
    "path": "/services/apexrest/example"
  }'

La vecchia surface /internal/connectors/salesforce/* e stata rimossa: i consumer devono passare dagli endpoint source-based.

Un consumer reale lato backend e sfdc-external/backend/src/platform/platform-clients.ts.

Workspace reference: /Users/jeanpaul/projects/cs-repository

Internal documentation scaffold