IIndividualPartyManagementPOST Apex Interface

The IIndividualPartyManagementPOST Apex interface provides extensibility for POST 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

Create Operation Use Cases

Use Case	Hook(s)	Description	Example Scenarios	Benefit
Default or Normalize Request Fields	`transformRequest`	Transforms the incoming request before validation and mutation processing. It can supply default values, normalize formats, and map client-specific fields to the canonical Account request structure.	- Apply a default Account status or type<br>- Normalize names, phone numbers, and website URLs<br>- Standardize country and region codes <br>- Map legacy fields to TMF632 fields	Ensures consistent, standardized Account data at the point of creation.
Carry Custom Validation Flags	`configureDefaultValidations`	Adds organization-specific validation flags to the validation context. These flags are subsequently read by `applyCustomValidations` to determine which policies should be enforced for the create request.	- Enable duplicate-Account checks <br>- Require tax or registration identifiers<br>- Activate stricter address validation <br>- Require additional checks for regulated Account types	Supports per-organization creation policies by carrying configurable validation flags into custom validation processing.
Enforce Custom Business Rules	`applyCustomValidations`	Reads the configured validation flags and evaluates organization-specific business rules before the Account mutation is built. Invalid payloads are rejected early with an HTTP `400` response and a clear validation message.	- Reject duplicate Accounts based on organization rules <br>- Require registration details for business Accounts <br>- Validate permitted Account types or lifecycle states <br>- Require additional fields for specific regions	Rejects invalid payloads early and prevents inconsistent or noncompliant Account records from being created.
Set Organization-Specific Account Fields	`customiseMutationPayload`	Adds or modifies organization-specific Account fields in the GraphQL mutation payload before execution. This supports fields that extend beyond the standard TMF632 schema.	- Set an internal customer segment <br>- Add a source-system identifier <br>- Populate custom risk or compliance fields <br>- Store organization-specific classification data	Persists custom Account fields beyond the TMF632 data model while preserving the shared API contract.
Audit or Integrate After Creation	`handlePostOperation`	Runs after the Account creation mutation completes and performs post-operation side effects using the creation result. It can write audit records, publish events, or invoke downstream integrations.	- Write an Account-creation audit record <br>- Publish an Account-created event<br>- Synchronize the Account with billing, CRM, or analytics systems <br>- Trigger onboarding or compliance workflows	Enables reliable auditing and downstream processing after successful creation while keeping side effects separate from the core operation.

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

Default a missing organizationType and normalize the country code.

global class OrganizationPostTransformRequestExt implements comms_apex_ext.IOrganizationPartyManagementPOST {
    global static Map<String, Object> transformRequest(Map<String, Object> context) {
        if (context == null || !(context.get('requestBody') instanceof Map<String, Object>)) {
            return context;
        }
        Map<String, Object> body = (Map<String, Object>) context.get('requestBody');


        if (body.get('organizationType') == null) {
            body.put('organizationType', 'Customer');
        }


        if (body.get('contactMedium') instanceof List<Object>) {
            for (Object cmObj : (List<Object>) body.get('contactMedium')) {
                if (cmObj instanceof Map<String, Object>) {
                    Map<String, Object> cm = (Map<String, Object>) cmObj;
                    if ('GeographicAddressContactMedium'.equals(cm.get('@type'))
                        && cm.get('country') instanceof String) {
                        cm.put('country', ((String) cm.get('country')).toUpperCase());
                    }
                }
            }
        }
        return context;
    }
    // ... other hooks return null / empty map ...
}

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.

global class OrganizationPostConfigValidationsExt implements comms_apex_ext.IOrganizationPartyManagementPOST {
    global static Map<String, Boolean> configureDefaultValidations(
        Map<String, Boolean> defaultValidationConfiguration,
        Map<String, Object> context
    ) {
        Map<String, Boolean> overrides = defaultValidationConfiguration != null
            ? defaultValidationConfiguration.clone()
            : new Map<String, Boolean>();
        overrides.put('nameUniquenessCheck', true);   // your own flag, read in applyCustomValidations
        return overrides;
    }
    // ... other hooks return null / empty map ...
}

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

Require an approved organizationType.

global class OrganizationPostValidationExt implements comms_apex_ext.IOrganizationPartyManagementPOST {
    private static final Set<String> ALLOWED_TYPES = new Set<String>{ 'Customer', 'Partner', 'Prospect' };
    global static Map<String, Object> applyCustomValidations(Map<String, Object> context) {
        Map<String, Object> result = new Map<String, Object>();
        if (!(context.get('requestBody') instanceof Map<String, Object>)) {
            return result;
        }
        Map<String, Object> body = (Map<String, Object>) context.get('requestBody');


        Object typeObj = body.get('organizationType');
        if (typeObj instanceof String && !ALLOWED_TYPES.contains((String) typeObj)) {
            result.put('validationStatus', 'fail');
            result.put('validationMessage',
                'organizationType must be one of: Customer, Partner, Prospect.');
        }
        return result;   // empty => proceed; validationStatus="fail" => HTTP 400
    }
    // ... other hooks return null / empty map ...
}

customiseMutationPayload

This hook modifies the mutation payload before deleting a customer record. Use this to add deletion metadata, set soft-delete flags, or apply business logic transformations.

Hook Method

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

Sample Apex Implementation

Add custom Account fields on creation.

global class OrganizationPostCustomMutationExt implements comms_apex_ext.IOrganizationPartyManagementPOST {
    global static Map<String, Object> customiseMutationPayload(
        Map<String, Object> graphQLAsMap,
        Map<String, Object> context
    ) {
        Map<String, Object> node = new Map<String, Object>{
            'path' => 'organizationData',
            'addFields' => new Map<String, Object>{
                'Industry'       => 'Telecommunications',
                'AccountSource'  => 'Web',
                'Segment__c'     => 'Enterprise'
            }
        };
        return new Map<String, Object>{
            'nodes' => new List<Object>{ node }
        };
    }
    // ... other hooks return null / empty map ...
}

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

Publish a platform event after creation.

global class OrganizationPostHandlePostOpExt implements comms_apex_ext.IOrganizationPartyManagementPOST {
    global static Map<String, Object> handlePostOperation(
        Map<String, Object> graphQLQueryResultAsMap,
        Map<String, Object> constructedTMFResponse,
        Map<String, Object> context
    ) {
        // Read the created Account Id from the mutation result (organizationData alias).
        String newId = extractCreatedId(graphQLQueryResultAsMap);
        if (newId != null) {
            EventBus.publish(new Organization_Created__e(Account_Id__c = newId));
        }
        return null;   // ignored for POST
    }


    @SuppressWarnings('PMD')
    private static String extractCreatedId(Map<String, Object> resultMap) {
        try {
            Map<String, Object> data = (Map<String, Object>) resultMap.get('data');
            Map<String, Object> uiapi = (Map<String, Object>) data.get('uiapi');
            Map<String, Object> org = (Map<String, Object>) uiapi.get('organizationData');
            Map<String, Object> record = (Map<String, Object>) org.get('Record');
            return (String) record.get('Id');
        } catch (Exception e) {
            return null;
        }
    }
    // ... other hooks return null / empty map ...
}

Full Implementation Example

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

/**
 * Complete TMF632 Organization (Party Management) POST API extension,
 * demonstrating all hooks with business logic.
 */
global class OrganizationPartyManagementPOSTExtension implements comms_apex_ext.IOrganizationPartyManagementPOST {


    private static final Set<String> ALLOWED_TYPES = new Set<String>{ 'Customer', 'Partner', 'Prospect' };


    // Hook 1: normalize the request body.
    global static Map<String, Object> transformRequest(Map<String, Object> context) {
        if (context != null && context.get('requestBody') instanceof Map<String, Object>) {
            Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
            if (body.get('organizationType') == null) {
                body.put('organizationType', 'Customer');
            }
        }
        return context;
    }


    // Hook 2: the built-in checks are always enforced; return empty (no custom flags).
    global static Map<String, Boolean> configureDefaultValidations(
        Map<String, Boolean> defaultValidationConfiguration,
        Map<String, Object> context
    ) {
        return new Map<String, Boolean>();
    }


    // Hook 3: enforce an approved organizationType.
    global static Map<String, Object> applyCustomValidations(Map<String, Object> context) {
        Map<String, Object> result = new Map<String, Object>();
        if (context.get('requestBody') instanceof Map<String, Object>) {
            Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
            Object typeObj = body.get('organizationType');
            if (typeObj instanceof String && !ALLOWED_TYPES.contains((String) typeObj)) {
                result.put('validationStatus', 'fail');
                result.put('validationMessage',
                    'organizationType must be one of: Customer, Partner, Prospect.');
            }
        }
        return result;
    }


    // Hook 4: add custom Account fields to the create mutation.
    global static Map<String, Object> customiseMutationPayload(
        Map<String, Object> graphQLAsMap,
        Map<String, Object> context
    ) {
        Map<String, Object> node = new Map<String, Object>{
            'path' => 'organizationData',
            'addFields' => new Map<String, Object>{ 'Industry' => 'Telecommunications', 'AccountSource' => 'Web' }
        };
        return new Map<String, Object>{ 'nodes' => new List<Object>{ node } };
    }


    // Hook 5: side effect only (return ignored).
    global static Map<String, Object> handlePostOperation(
        Map<String, Object> graphQLQueryResultAsMap,
        Map<String, Object> constructedTMFResponse,
        Map<String, Object> context
    ) {
        return null;
    }
}

Response Structure

Request Body

A TMF632 Individual create payload supports the following input fields:

Scalars:@type (must be Organization), name (required), organizationType.
contactMedium[]: Each item includes an @type discriminator and a corresponding value field:
- PhoneContactMedium → phoneNumber
- FaxContactMedium → faxNumber
- GeographicAddressContactMedium → street1, city, stateOrProvince, postCode, country
relatedParty[]: Each item includes a role, @type, and partyOrPartyRole (id + @referredType).
@referredType = "Individual": Creates an AccountContactRelation, or links Contact.AccountId when Shared Contacts is disabled.
@referredType = "Organization": Creates an AccountAccountRelation. This requires PartyRoleRelation configuration, and the role must match a configured RoleName.

{
  "@type": "Organization",
  "name": "Acme Corporation",
  "organizationType": "Customer",
  "contactMedium": [
    {
      "@type": "GeographicAddressContactMedium",
      "street1": "1 Market St",
      "city": "San Francisco",
      "stateOrProvince": "CA",
      "postCode": "94105",
      "country": "US"
    },
    { "@type": "PhoneContactMedium", "phoneNumber": "+1-555-0100" },
    { "@type": "FaxContactMedium", "faxNumber": "+1-555-0101" }
  ],
  "organizationParentRelationship": {
    "@type": "OrganizationParentRelationship",
    "organization": { "@type": "OrganizationRef", "id": "001xx000003DEF" }
  },
  "relatedParty": [
    {
      "@type": "RelatedPartyRefOrPartyRoleRef",
      "role": "Decision Maker",
      "partyOrPartyRole": { "@type": "PartyRef", "@referredType": "Individual", "id": "003xx000004MZZ" }
    },
    {
      "@type": "RelatedPartyRefOrPartyRoleRef",
      "role": "Supplier",
      "partyOrPartyRole": { "@type": "PartyRef", "@referredType": "Organization", "id": "001xx000003DaB" }
    }
  ]
}

Response (HTTP 201 Created)

The created Organization, in the same representation returned by GET (relative href, @type = "Organization", @baseType = "Party"):

{
  "id": "001xx000003DHP",
  "href": "/connect/comms/partymanagement/v5/organization/001xx000003DHP",
  "@type": "Organization",
  "@baseType": "Party",
  "name": "Acme Corporation",
  "organizationType": "Customer",
  "contactMedium": [
    {
      "@type": "GeographicAddressContactMedium",
      "street1": "1 Market St",
      "city": "San Francisco",
      "stateOrProvince": "CA",
      "postCode": "94105",
      "country": "US"
    },
    { "@type": "PhoneContactMedium", "phoneNumber": "+1-555-0100" },
    { "@type": "FaxContactMedium", "faxNumber": "+1-555-0101" }
  ],
  "organizationParentRelationship": {
    "@type": "OrganizationParentRelationship",
    "organization": {
      "id": "001xx000003DEF",
      "href": "/connect/comms/partymanagement/v5/organization/001xx000003DEF",
      "name": "Acme Holdings",
      "@type": "OrganizationRef"
    }
  },
  "relatedParty": [
    {
      "@type": "RelatedPartyRefOrPartyRoleRef",
      "role": "Decision Maker",
      "partyOrPartyRole": {
        "id": "003xx000004MZZ",
        "href": "/connect/comms/partymanagement/v5/individual/003xx000004MZZ",
        "name": "John Smith",
        "@type": "PartyRef",
        "@referredType": "Individual"
      }
    },
    {
      "@type": "RelatedPartyRefOrPartyRoleRef",
      "role": "Supplier",
      "partyOrPartyRole": {
        "id": "001xx000003DaB",
        "href": "/connect/comms/partymanagement/v5/organization/001xx000003DaB",
        "name": "Globex Supplies",
        "@type": "PartyRef",
        "@referredType": "Organization"
      }
    }
  ]
}