IAccountManagementGET Apex Interface
The IAccountManagementGET Apex interface provides extensibility for GET operations through Apex pre- and post-hooks and GraphQL query customization. Implementations can validate incoming requests, modify query structures, and refine the response to support business-specific retrieval rules while maintaining TMF-compliant behavior.
This interface supports the following hooks.
| Use Case | Hook(s) | Description | Example Scenarios | Benefit |
|---|---|---|---|---|
| Role-Based Data Filtering | applyCustomValidations, handlePostOperation | Enforces access rules before execution and filters sensitive fields or records after retrieval. Access can be evaluated using the caller’s role, region, business unit, channel, or request context. | - Restrict access to strategic or high-value Accounts - Hide financial, risk, or compliance fields from frontline users - Enforce regional or business-unit access boundaries - Remove sensitive fields from partner-facing responses | Enforces data governance and security through both pre-query authorization and post-query response filtering. |
| Custom Field Enrichment | handlePostOperation | Adds calculated, derived, or externally sourced fields to the response without changing the base TMF632 schema. | - Add an Account health score - Flag preferred, strategic, or high-risk Accounts - Include aggregated revenue or usage insights - Attach hierarchy or entitlement information | Delivers richer and more contextual Account data without requiring changes to the shared schema. |
| Dynamic Query Customization | customiseGraphQLQuery | Modifies the GraphQL query before execution by adding fields, relationships, filters, or server-side constraints according to the client or request context. | - Return a minimal field set to mobile clients - Include hierarchy or entitlement fields for portals - Add organization-specific Account fields - Apply tenant, region, status, or channel filters automatically | Supports multiple client requirements through a single API and reduces the need for client-specific endpoints or API versions. |
| Business-Rule Validation | applyCustomValidations | Evaluates organization-specific business, eligibility, and access rules before the GraphQL query executes. Invalid requests are rejected early with a clear error response. | - Require an active Account before returning related services - Reject requests from unauthorized or unverified channels - Enforce lifecycle-state restrictions - Validate tenant or business-unit ownership | Rejects invalid requests early, maintains business consistency, and avoids unnecessary downstream processing. |
| External-ID Resolution | transformRequest | Resolves a business key, legacy identifier, or external-system reference to the canonical Salesforce Account ID and adds it to the shared request context as { id }. | - Retrieve an Account by customer number - Resolve an ERP or billing-system identifier - Map a partner-system key to a Salesforce Account ID - Translate a migrated legacy identifier | Allows clients to fetch Accounts by meaningful business keys instead of requiring a Salesforce ID. |
This hook transforms the request context before processing any operation. It is invoked early in the request lifecycle, allowing implementers to adjust the context for subsequent extensibility hooks.
Map<String, Object> transformRequest(Map<String, Object> context)
Resolve an external Account Number to a Billing Account ID.
This hook validates custom business logic before retrieving customer record. If validation fails, it rejects the request and returns an error response.
The handler processes return values as follows.
Success:
- Return a map with validationStatus set to “pass” (case-insensitive).
- The API request continues normally.
- Other fields in the map are logged but not used.
Failure:
- Return a map with validationStatus set to “fail” (case-insensitive).
- The API request is terminated immediately.
- Raise a ValidationException containing
- message: value from validationMessage key (or “Validation failed” by default)
- details: value from validationDetails key (optional)
- The client receives an HTTP 400 error response.
Map<String, Object> applyCustomValidations(Map<String, Object> context)
Restrict billing account visibility for customer service representatives.
This hook modifies the GraphQL query before execution to add fields, filters, or transformations.
Map<String, Object> customiseGraphQLQuery(Map<String, Object> graphQLAsMap, Map<String, Object> context)
Add custom fields, filter and ordering.
This hook post-processes and transforms the API response after data retrieval.
Map<String, Object> handlePostOperation(Map<String, Object> graphQLQueryResultAsMap, Map<String, Object> constructedTMFResponse, Map<String, Object> context)
Enrich responses with calculated fields (single and list-aware).
Here’s a complete sample Apex implementation using all supported hooks.
Default (without pageInfo) — a bare JSON array of Individual objects:
Query transformations provide the ability to enhance GraphQL queries by adding fields, applying filters, or modifying the sort order, while preserving the original query definition.
Original Query (GraphQL):
Transformation Instructions (JSON):
Result (GraphQL):
Original Query (GraphQL):
Transformation Instructions (JSON):
Result (GraphQL):
Original Query (GraphQL):
Transformation Instructions (JSON):
Result (GraphQL):
Original Query (GraphQL):
Transformation Instructions (JSON):
Result (GraphQL):