SfSkills Domains Docs GitHub

Home / omnistudio / industries-api-extensions

industries-api-extensions

Endpoint path, payload and error handling for a named Salesforce Industries API — Insurance Policy Business Connect, Communications Cloud TM Forum Open APIs (TMF679, TMF680), Energy and Utilities Update Asset Status, Service Process Studio Connect.

Open the skill folder on GitHub

Industries API Extensions

This skill activates when a practitioner needs to call or design integrations against industry-vertical REST APIs provided by Salesforce Industries — specifically the Insurance Policy Business Connect API, Communications Cloud TM Forum Open APIs, Energy and Utilities Update Asset Status API, and Service Process Studio Connect APIs. It does NOT cover the standard Salesforce REST API, Bulk API, or generic platform integration.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Insurance Policy Business Connect API

The Insurance Policy Business Connect API exposes atomic lifecycle transaction endpoints for the Insurance Cloud. Each endpoint performs a combined, consistency-guaranteed operation across InsurancePolicy, InsurancePolicyCoverage, InsurancePolicyParticipant, and related objects in a single transaction. The available operations are:

The resource family is rooted at a single policies collection, with lifecycle operations expressed as verb sub-resources on an individual policy — not as separate pluralised transaction collections:

For a parent policy with children of different product types there is a separate multi-root family, which is asynchronous:

All endpoints are versioned Connect APIs accessed via /services/data/vXX.0/connect/insurance/.... They are not available in non-Insurance-Cloud orgs. The body is a JSON representation of the policy transaction keyed by a context ID, not a raw sObject payload and not a flat policy document. Read the Requests section of the Insurance Policy Business API reference for the exact body field names before writing a client — do not infer them from the object model.

Communications Cloud TM Forum Open APIs

Communications Cloud exposes industry-standard TM Forum Open API specifications as inbound REST endpoints within the Salesforce platform. The key APIs include:

Critical behavior: TM Forum APIs in Salesforce are ID-driven, not name-driven. Requests must reference Salesforce record IDs for products, offerings, and accounts. Passing product names or catalog codes results in a 404 or validation error. The implementation delegate for each TMF API operation is an OmniScript or Integration Procedure configured in Communications Cloud setup.

Access model: Direct Access only. The MuleSoft gateway integration that previously surfaced TM Forum APIs is deprecated as of Winter '27 and will not be supported in future releases. New implementations must use Direct Access, where the TM Forum API endpoints are served directly by the Salesforce org on its instance URL.

Energy and Utilities Update Asset Status API

The E&U Cloud exposes an Update Asset Status API (POST /connect/energy/asset-status-updates) that changes the operational status of a ServicePoint or related energy asset (for example, from Active to Inactive or from Inactive to Disconnected). This API delegates internally to the sfiEnergy_UpdateAssetStatus Integration Procedure, which applies validation rules and orchestrates the downstream sObject updates.

Calling the standard REST API to update the Status field on a ServicePoint record directly bypasses this Integration Procedure and skips E&U-specific business rule validation, including disconnection sequencing and metering notifications.

Service Process Studio Connect APIs

Service Process Studio Connect APIs allow external systems and OmniScripts to invoke Service Process definitions as REST calls. The endpoint pattern is:

POST /services/data/vXX.X/connect/service-processes/{processApiName}/runs

The body carries input parameters defined in the Service Process definition. Service Process APIs are cross-vertical: they work in Insurance Cloud, Communications Cloud, and E&U Cloud where Service Process Studio is licensed. Response shape is defined by the Service Process output parameters, not a fixed schema.

Common Patterns

Pattern 1: Atomic Policy Issuance (Insurance Cloud)

When to use: An external system or OmniScript needs to create a new insurance policy including coverages, participants, and policy period in a single transaction.

How it works:

  1. Authenticate with a Connected App using OAuth 2.0 (JWT or web-server flow).
  2. POST to /services/data/v67.0/connect/insurance/policies (not policy-issuances — that resource does not exist). Salesforce describes the operation as "use the context ID provided in the request body to generate a new insurance policy", so the payload is context-driven. Take the exact request body field names from the Requests section of the Insurance Policy Business API reference for your API version rather than reconstructing them from InsurancePolicy field names.
  3. The API creates InsurancePolicy and InsurancePolicyCoverage records atomically.
  4. Handle non-2xx responses from the reference's documented error list; do not assume a particular status code for duplicate detection without confirming it.
  5. On failure, no partial records are committed — the transaction rolls back entirely. This atomicity is the reason to use the API over DML.
  6. If the policy is a parent with children of different product types, use POST /connect/insurance/policies/multi-root instead. It is asynchronous, so the client must handle a deferred completion rather than reading the policy back immediately.

Why not the alternative: A direct insert InsurancePolicy DML followed by separate insert InsurancePolicyCoverage DML allows a partial commit if the coverage insert fails. This leaves orphaned policy records and violates Insurance Cloud referential integrity rules.

Pattern 2: TM Forum Order Submission (Communications Cloud — Direct Access)

When to use: A BSS system submits a commercial product order to Communications Cloud using the TMF622 API.

How it works:

  1. Verify Direct Access is enabled in Setup > Communications Cloud > TM Forum API Settings. Confirm the API version endpoint is active.
  2. POST to https://<org-instance>.my.salesforce.com/services/apexrest/tmf-api/productOrderingManagement/v4/productOrder with the TMF622 JSON body. The productOffering.id field must be the Salesforce ID of the ProductOffering__c record, not the product catalog code.
  3. The platform routes the request to the configured Integration Procedure for order processing. The response returns a productOrder.id (Salesforce record ID) and state: acknowledged.
  4. Poll GET .../productOrder/{id} for state transitions (inProgress → completed or failed).
  5. Error responses follow the TM Forum error schema: { "code": "...", "reason": "...", "message": "..." }.

Why not the alternative: Routing through the legacy MuleSoft gateway creates a dependency on a deprecated integration path. Winter '27 deprecation means orgs relying on the MuleSoft path will lose connectivity and require emergency re-architecture. Direct Access aligns with the Salesforce-supported roadmap.

Pattern 3: Asset Status Update (Energy and Utilities Cloud)

When to use: A field management system or meter operations process needs to change a ServicePoint's operational status.

How it works:

  1. POST to /services/data/v62.0/connect/energy/asset-status-updates with body { "assetId": "<ServicePoint_ID>", "newStatus": "Inactive", "reason": "CustomerRequest" }.
  2. The API delegates to the sfiEnergy_UpdateAssetStatus Integration Procedure, which validates transition rules (e.g., Active → Inactive is permitted; Inactive → Active requires a re-energization reason code).
  3. On success, the ServicePoint Status field is updated and a StatusChange event record is created.
  4. On validation failure, the API returns a 422 Unprocessable Entity with an errorCode from the Integration Procedure output.

Decision Guidance

SituationRecommended ApproachReason
Creating a new insurance policy with coveragesInsurance Policy Business Connect API — POST /connect/insurance/policiesGuarantees atomic creation across InsurancePolicy and InsurancePolicyCoverage; standard DML does not
Creating a parent policy with child policies of different product typesPOST /connect/insurance/policies/multi-rootThe only resource that models a multi-root policy; note it is asynchronous, so design for deferred completion
Modifying an in-force insurance policy mid-termPOST /connect/insurance/policies/{policyId}/endorse (or /out-of-sequence-endorsement for retroactive changes)Ensures endorsement audit trail and coverage consistency are maintained
Submitting a product order from a BSS system to Comms CloudTMF622 via Direct AccessMuleSoft gateway is deprecated Winter '27; Direct Access is the only supported path
Querying product offering availability for an addressTMF679 via Direct Access (ID-driven)Pass Salesforce record IDs, not product names; name-based lookups are not supported
Changing a ServicePoint's operational statusE&U Update Asset Status Connect APIBypassing via direct DML skips Integration Procedure validation and business rules
Invoking a cross-vertical service process from an external systemService Process Studio Connect API (/connect/service-processes/{name}/runs)Standard for orchestrating multi-step industry processes; returns process-defined output schema
Standard Salesforce CRUD on non-industry objects in an Industries orgStandard REST API (/sobjects/)Industry API extensions are only required for industry-specific objects and lifecycle transactions

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Identify the vertical and operation — confirm the Salesforce Industries license (Insurance, Communications, or E&U) and the specific lifecycle operation (issuance, endorsement, renewal, cancellation, asset status update, TM Forum order, or service process execution). This determines which endpoint family to use.
  2. Verify the access model and API version — for Communications Cloud, confirm Direct Access is enabled and the MuleSoft gateway is not in use. For Insurance and E&U, confirm the org is on the API version that supports the target endpoint (Spring '25+ for current endpoint paths).
  3. Obtain record IDs for all referenced entities — industry APIs are ID-driven. Resolve Salesforce record IDs for products, offerings, policies, and assets before constructing the request body. Do not use names, codes, or catalog identifiers as primary keys in the payload.
  4. Construct and validate the request payload — follow the Connect API request schema for Insurance/E&U, or the TM Forum JSON schema for Comms Cloud. For insurance operations, include all required coverage array entries; partial payloads fail validation before any DML occurs.
  5. Handle vertical-specific error codes — industry APIs return structured error responses distinct from standard Salesforce REST error responses. Map 409 Conflict (insurance duplicate), 422 Unprocessable Entity (E&U validation failure), and TM Forum error schema (code/reason/message) to retry or escalation logic.
  6. Test with a scratch org that has the industry feature flag — industry API endpoints are not present in standard Developer Edition orgs. Use a partner developer org provisioned with the relevant industry feature, or an industry scratch org with the feature enabled in project-scratch-def.json.
  7. Confirm no direct DML is used for industry objects — verify that no Apex, Flow, or REST CRUD operates directly on InsurancePolicy, InsurancePolicyCoverage, or ServicePoint status fields. All mutations must flow through the industry Connect API or Integration Procedure layer.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. TM Forum API product lookup is ID-only — Passing a product catalog code or product name in a TMF679 or TMF622 request body results in a 404 or silent validation failure. The TM Forum endpoint implementations in Salesforce resolve all product and offering references by Salesforce record ID exclusively. There is no name-to-ID resolution built into the API layer.
  2. Insurance Connect API does not fall back to DML on error — If the Connect API call fails (e.g., missing coverage type), the entire transaction is rolled back, including parent policy records. No partial records are persisted. Practitioners who check InsurancePolicy for a record after a failed API call and find none often incorrectly conclude the API did not attempt the operation.
  3. MuleSoft gateway deprecation is a breaking change in Winter '27 — Orgs that integrated with Communications Cloud through the legacy MuleSoft gateway endpoint will lose connectivity after the deprecation date. The error will surface as an unreachable endpoint, not a Salesforce API error, making diagnosis difficult at the time of failure.

Output Artifacts

ArtifactDescription
Endpoint and payload specificationCorrect URL path, HTTP method, and JSON body structure for the target industry API operation
Error handling matrixMapping of HTTP status codes and error code values to retry/escalation logic
Integration Procedure delegation diagramShows the Connect API → Integration Procedure chain for E&U and Service Process operations
Access model confirmationDirect Access vs deprecated gateway assessment for Communications Cloud

Package files