IOrganizationPartyManagementPATCH Apex Interface

The IOrganizationPartyManagementPATCH Apex interface provides extensibility for PATCH 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.

transformRequest
configureDefaultValidations
applyCustomValidations
customiseMutationPayload
handlePostOperation

Account Update Operation Use Cases

Use Case	Hook(s)	Description	Example Scenarios	Benefit
Block Updates to Protected Fields	`transformRequest`	Examines and transforms the request before validation and mutation processing. Protected, read-only, or unauthorized fields can be removed from the update payload before the write occurs.	- Remove system-managed Account identifiers - Prevent clients from changing ownership fields - Strip restricted financial or compliance attributes - Remove fields that are read-only for the caller’s role	Protects controlled Account fields by stripping disallowed values before they can be persisted.
Enforce Value Policies on Update	`applyCustomValidations`	Applies organization-specific business rules to proposed Account field values before the update mutation is built. Invalid updates are rejected with an HTTP `400` response and a clear error message.	- Reject invalid Account lifecycle transitions - Enforce permitted values for type, status, or segment - Require dependent fields when Account status changes - Prevent updates that violate regional policies	Rejects invalid updates early and preserves business, compliance, and data integrity.
Add Custom Validation Flags	`configureDefaultValidations`	Enables, disables, or adds validation flags for Account update requests according to organization-specific policies.	- Require Account-existence validation - Enable optimistic concurrency or version checks - Require additional validation for protected Accounts - Apply stricter checks to regulated records	Supports per-organization update policies without changing the shared update implementation.
Stamp Audit Fields on Update	`customiseMutationPayload`	Adds audit and provenance fields to the GraphQL mutation payload before execution. This allows metadata beyond the TMF632 schema to be persisted with the Account update.	- Add `lastModifiedBy` and `lastModifiedAt` - Record the source channel or integration - Store a request or correlation ID - Capture the reason for the Account update	Persists provenance and audit information beyond the standard TMF632 data model.
Audit or Integrate After Update	`handlePostOperation`	Runs after the update mutation completes and performs post-operation side effects using the update result. It can write audit records, publish events, or invoke downstream integrations.	- Write an Account-update audit record - Publish an Account-updated event - Synchronize changes with billing or CRM systems - Invalidate related caches or search indexes - Trigger compliance or notification workflows	Enables reliable auditing and downstream processing after a successful update while keeping side effects separate from the core mutation.

transformRequest

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.

Hook Method

Map<String, Object> transformRequest(Map<String, Object> context)

Sample Apex Implementation

Prevent updates to name.

1global class OrganizationPatchTransformRequestExt implements comms_apex_ext.IOrganizationPartyManagementPATCH {
2    global static Map<String, Object> transformRequest(Map<String, Object> context) {
3        if (context != null && context.get('requestBody') instanceof Map<String, Object>) {
4            Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
5            // Business rule: legal-name changes must go through a separate governance flow.
6            body.remove('name');
7        }
8        return context;
9    }
10    // ... other hooks return null / empty map ...
11}

configureDefaultValidations

This hook enables, disables, or modifies the built-in validation rules before they execute.

Hook Method

Map<String, Boolean> configureDefaultValidations(Map<String, Boolean> defaultValidationConfiguration, Map<String, Object> context)

Sample Apex Implementation

Add a custom flag consumed by applyCustomValidations.

1global class OrganizationPatchConfigValidationsExt implements comms_apex_ext.IOrganizationPartyManagementPATCH {
2    global static Map<String, Boolean> configureDefaultValidations(
3        Map<String, Boolean> defaultValidationConfiguration,
4        Map<String, Object> context
5    ) {
6        Map<String, Boolean> overrides = defaultValidationConfiguration != null
7            ? defaultValidationConfiguration.clone()
8            : new Map<String, Boolean>();
9        overrides.put('typeTransitionCheck', true);   // your own flag, read in applyCustomValidations
10        return overrides;
11    }
12    // ... other hooks return null / empty map ...
13}

applyCustomValidations

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.

Hook Method

Map<String, Object> applyCustomValidations(Map<String, Object> context)

Sample Apex Implementation

Guard an organizationType transition.

1global class OrganizationPatchValidationExt implements comms_apex_ext.IOrganizationPartyManagementPATCH {
2    private static final Set<String> ALLOWED_TYPES = new Set<String>{ 'Customer', 'Partner', 'Prospect' };
3    global static Map<String, Object> applyCustomValidations(Map<String, Object> context) {
4        Map<String, Object> result = new Map<String, Object>();
5        if (!(context.get('requestBody') instanceof Map<String, Object>)) {
6            return result;
7        }
8        Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
9
10        Object typeObj = body.get('organizationType');
11        if (typeObj instanceof String && !ALLOWED_TYPES.contains((String) typeObj)) {
12            result.put('validationStatus', 'fail');
13            result.put('validationMessage',
14                'organizationType must be one of: Customer, Partner, Prospect.');
15        }
16        return result;   // empty => proceed; validationStatus="fail" => HTTP 400
17    }
18    // ... other hooks return null / empty map ...
19}

customiseMutationPayload

This hook modifies the GraphQL query before execution to add fields, filters, or transformations.

Hook Method

Map<String, Object> customiseMutationPayload(Map<String, Object> graphQLAsMap,Map<String, Object> context)

Sample Apex Implementation

Stamp an audit field on update.

1global class OrganizationPatchCustomMutationExt implements comms_apex_ext.IOrganizationPartyManagementPATCH {
2    global static Map<String, Object> customiseMutationPayload(
3        Map<String, Object> graphQLAsMap,
4        Map<String, Object> context
5    ) {
6        Map<String, Object> node = new Map<String, Object>{
7            'path' => 'organizationData',
8            'addFields' => new Map<String, Object>{
9                'Last_API_Update__c' => 'TMF632-PATCH'
10            }
11        };
12        return new Map<String, Object>{
13            'nodes' => new List<Object>{ node }
14        };
15    }
16    // ... other hooks return null / empty map ...
17}

handlePostOperation

This hook post-processes and transforms the API response after data retrieval.

Hook Method

Map<String, Object> handlePostOperation(Map<String, Object> graphQLQueryResultAsMap, Map<String, Object> constructedTMFResponse, Map<String, Object> context)

Sample Apex Implementation

Enrich the response in place.

1global class OrganizationPatchHandlePostOpExt implements comms_apex_ext.IOrganizationPartyManagementPATCH {
2    global static Map<String, Object> handlePostOperation(
3        Map<String, Object> graphQLQueryResultAsMap,
4        Map<String, Object> constructedTMFResponse,
5        Map<String, Object> context
6    ) {
7        String orgId = context != null ? (String) context.get('id') : null;
8        if (orgId != null) {
9            EventBus.publish(new Organization_Updated__e(Account_Id__c = orgId));
10        }
11        return null;   // ignored for PATCH
12    }
13    // ... other hooks return null / empty map ...
14}

Full Implementation Example

Here’s a complete sample Apex implementation using all supported hooks.

1/**
2 * Complete TMF632 Organization (Party Management) PATCH API extension,
3 * demonstrating all hooks with business logic.
4 */
5global class OrganizationPartyManagementPATCHExtension implements comms_apex_ext.IOrganizationPartyManagementPATCH {
6    private static final Set<String> ALLOWED_TYPES = new Set<String>{ 'Customer', 'Partner', 'Prospect' };
7
8
9    // Hook 1: prevent legal-name updates via the API.
10    global static Map<String, Object> transformRequest(Map<String, Object> context) {
11        if (context != null && context.get('requestBody') instanceof Map<String, Object>) {
12            ((Map<String, Object>) context.get('requestBody')).remove('name');
13        }
14        return context;
15    }
16
17
18    // Hook 2: PATCH has no default validators; keep it that way.
19    global static Map<String, Boolean> configureDefaultValidations(
20        Map<String, Boolean> defaultValidationConfiguration,
21        Map<String, Object> context
22    ) {
23        return new Map<String, Boolean>();
24    }
25
26
27    // Hook 3: guard the organizationType transition.
28    global static Map<String, Object> applyCustomValidations(Map<String, Object> context) {
29        Map<String, Object> result = new Map<String, Object>();
30        if (context.get('requestBody') instanceof Map<String, Object>) {
31            Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
32            Object typeObj = body.get('organizationType');
33            if (typeObj instanceof String && !ALLOWED_TYPES.contains((String) typeObj)) {
34                result.put('validationStatus', 'fail');
35                result.put('validationMessage',
36                    'organizationType must be one of: Customer, Partner, Prospect.');
37            }
38        }
39        return result;
40    }
41
42
43    // Hook 4: stamp an audit field on update.
44    global static Map<String, Object> customiseMutationPayload(
45        Map<String, Object> graphQLAsMap,
46        Map<String, Object> context
47    ) {
48        Map<String, Object> node = new Map<String, Object>{
49            'path' => 'organizationData',
50            'addFields' => new Map<String, Object>{ 'Last_API_Update__c' => 'TMF632-PATCH' }
51        };
52        return new Map<String, Object>{ 'nodes' => new List<Object>{ node } };
53    }
54
55
56    // Hook 5: side effect only (return ignored).
57    global static Map<String, Object> handlePostOperation(
58        Map<String, Object> graphQLQueryResultAsMap,
59        Map<String, Object> constructedTMFResponse,
60        Map<String, Object> context
61    ) {
62        return null;
63    }
64}