IProductOrderPOST Apex Interface

The IProductOrderPOST Apex interface enables customization of POST operations using Apex lifecycle hooks. One handler routes into four mutually exclusive sub-flows from productOrderItem[].action (and product.id). Implementations can validate and enrich creation, amendment, renewal, or cancellation payloads, and run side effects after the pipeline, while the client-visible order is re-fetched via GET.

This interface supports the following hooks.

• transformRequest
• configureDefaultValidations
• applyCustomValidations
• preServiceHook
• handlePostOperation

Note

These hooks are not used for Product Order POST. If implemented, the methods are required to compile, but they are never invoked (constructGraphQL / constructMutationGraphQL return null).

• customiseGraphQLQuery
• customiseMutationPayload

Rewrite the outbound payload in preServiceHook via modifiedPayload.

Sub-flows

Mixed actions (add+renew, cancel+anything, and similar) are rejected by validateSingleActionType before any Apex hook.

preServiceHook fires up to three times per request (once per step) using finalPayload re-invocation: build payload → Apex → execute with modifiedPayload. Switch on serviceName.

Creation Lifecycle Use Cases and Hook Mapping

The following table lists common use cases for the POST operation.

transformRequest

This hook transforms the request context before processing any operation. It is invoked before sub-flow detection.

Hook Method

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

Sample Apex Implementation

global static Map<String, Object> transformRequest(Map<String, Object> context) {
    Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
    if (body == null || !(body.get('productOrderItem') instanceof List<Object>)) {
        return context;
    }
    for (Object itemObj : (List<Object>) body.get('productOrderItem')) {
        Map<String, Object> item = (Map<String, Object>) itemObj;
        Map<String, Object> product = (Map<String, Object>) item.get('product');
        if (product != null && product.get('id') != null && item.get('action') == null) {
            item.put('action', 'amend');
        }
    }
    return context;
}

configureDefaultValidations

Default spec (all true): orderLevelAttributesValidation, relatedPartyValidation, productOrderItemsValidation. Return a map toggling those flags.

Handler validateAmendmentItems / validateRenewalItems / validateCancellationItems do not run in the normal request flow (isXRequest is still false during validation). Duplicate critical checks in applyCustomValidations. Missing product.id is enforced later in payload builders as HTTP 400.

Hook Method

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

applyCustomValidations

This hook validates custom business logic before the service-call pipeline. 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 any value other than "fail" (case-insensitive), or an empty map.
• The API request continues normally.

Failure

• Return a top-level map with validationStatus set to "fail". Nested "result" is silently dropped.
• The API request is terminated immediately (ValidationException). Default mapping is HTTP 422 unless validationDetails overrides.

Hook Method

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

Sample Apex Implementation

global static Map<String, Object> applyCustomValidations(Map<String, Object> context) {
    Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
    if (body == null) {
        return new Map<String, Object>();
    }
    Object items = body.get('productOrderItem');
    if (items instanceof List<Object> && body.get('requestedStartDate') == null) {
        for (Object itemObj : (List<Object>) items) {
            Map<String, Object> item = (Map<String, Object>) itemObj;
            if ('add' == item.get('action') || item.get('action') == null) {
                return new Map<String, Object>{
                    'validationStatus'  => 'fail',
                    'validationMessage' => 'requestedStartDate is required when adding new items'
                };
            }
        }
    }
    return new Map<String, Object>();
}

preServiceHook

This hook runs once per pipeline step (up to three times). Return {skipCall, modifiedPayload}. Exceptions are swallowed per step (WARNING); the original payload is used. skipCall is not an HTTP error.

Hook Method

Map<String, Object> preServiceHook(String serviceName, Map<String, Object> payload, Map<String, Object> executionContext, Map<String, Object> metadata)

Sample Apex Implementation

global static Map<String, Object> preServiceHook(String serviceName, Map<String, Object> payload,
        Map<String, Object> executionContext, Map<String, Object> metadata) {
    if (serviceName == 'orderIngestion' && payload != null) {
        payload.put('pricingPref', 'CatalogRates');
        payload.put('taxPref', 'SkipSync');
        return new Map<String, Object>{ 'skipCall' => false, 'modifiedPayload' => payload };
    }
    if (serviceName == 'initiateAmendment' && payload != null
            && payload.get('quantityChanges') instanceof Map<String, Object>) {
        Map<String, Object> changes = (Map<String, Object>) payload.get('quantityChanges');
        payload.put('quantityChanges', changes);
        return new Map<String, Object>{ 'skipCall' => false, 'modifiedPayload' => payload };
    }
    if (serviceName == 'submitOrder') {
        return new Map<String, Object>{ 'skipCall' => true }; // hold for nightly batch
    }
    return new Map<String, Object>{ 'skipCall' => false, 'modifiedPayload' => payload };
}

handlePostOperation

graphQLQueryResultAsMap is synthetic {"data": flowResult} from orderIngestionResult / initiateAmendmentResult / initiateRenewalResult / initiateCancellationResult. constructedTMFResponse is the request body. Return is discarded. The client representation is GET retrieveResource.

Hook Method

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

Sample Apex Implementation

global static Map<String, Object> handlePostOperation(
        Map<String, Object> graphQLQueryResultAsMap,
        Map<String, Object> constructedTMFResponse,
        Map<String, Object> context) {
    System.debug('ProductOrder POST completed by ' + UserInfo.getName());
    return null; // discarded; client body is GET re-fetch
}

Full Implementation Example

global class ProductOrderPOSTExtension implements comms_apex_ext.IProductOrderPOST {

    global static Map<String, Object> transformRequest(Map<String, Object> context) {
        Map<String, Object> body = (Map<String, Object>) context.get('requestBody');
        if (body == null || !(body.get('productOrderItem') instanceof List<Object>)) {
            return context;
        }
        for (Object itemObj : (List<Object>) body.get('productOrderItem')) {
            Map<String, Object> item = (Map<String, Object>) itemObj;
            Map<String, Object> product = (Map<String, Object>) item.get('product');
            if (product != null && product.get('id') != null && item.get('action') == null) {
                item.put('action', 'amend');
            }
        }
        return context;
    }

    global static Map<String, Boolean> configureDefaultValidations(
            Map<String, Boolean> defaultValidationConfiguration, Map<String, Object> context) {
        return defaultValidationConfiguration;
    }

    global static Map<String, Object> applyCustomValidations(Map<String, Object> context) {
        return new Map<String, Object>();
    }

    global static Map<String, Object> customiseGraphQLQuery(
            Map<String, Object> graphQLAsMap, Map<String, Object> context) {
        return new Map<String, Object>(); // never invoked
    }

    global static Map<String, Object> customiseMutationPayload(
            Map<String, Object> mutationGraphQLPayload, Map<String, Object> context) {
        return new Map<String, Object>(); // never invoked
    }

    global static Map<String, Object> preServiceHook(String serviceName, Map<String, Object> payload,
            Map<String, Object> executionContext, Map<String, Object> metadata) {
        if (serviceName == 'orderIngestion' && payload != null) {
            payload.put('pricingPref', 'CatalogRates');
            return new Map<String, Object>{ 'skipCall' => false, 'modifiedPayload' => payload };
        }
        return new Map<String, Object>{ 'skipCall' => false, 'modifiedPayload' => payload };
    }

    global static Map<String, Object> handlePostOperation(
            Map<String, Object> graphQLQueryResultAsMap,
            Map<String, Object> constructedTMFResponse,
            Map<String, Object> context) {
        return null;
    }
}

See Also

• Extensibility for TMF622 v5 Product Ordering Management API
• IProductOrderGET Apex Interface
• IProductOrderPATCH Apex Interface
• IProductOrderDELETE Apex Interface