XOMAsyncSystemInterface

Overview of Capabilities

Capabilities include:

• In the JSON, includes the hierarchy of the order item or FRL. That is, it notes the parents and children of the item.

• Can accept DataRaptors to change the default JSON payload.

• Sends POST requests.

• Processes the response and updates Salesforce records.

• Is extendable.

• Understands standard HTTP response codes:

  • Success codes: 200, 201, 202, 203, 204, 205, 206, 302, 304

  • Error codes: 408, 426, 500, 502, 503, 504, 440, 444, 520, 522, 523, 524, 525

Sample Payload

By default, XOMAsyncSystemInterface adapter prepares the following JSON payload, which is logged to the Request field of the orchestration item record.

{
    "order_items": [
        {
            "order_item_id": "a1f3i000000UcNUAA0",
            "action": "Add",
            "specified_by": {
                "specification_name": "Mobile Billing specification",
                "specification_id": "01t3i000001NCngAAG"
            },
            "described_by": [
                {
                    "value": "VLO_MOB_PLAN",
                    "characteristic": "Billing code"
                }
            ],
            "order_items": [
                {
                    "described_by": [
                        {
                            "value": "VLO_SIM",
                           "characteristic": "Billing code"
                        }
                   ],
                    "specified_by": {
                        "specification_name": "Billing item",
                        "specification_id": "01t3i000005LAQKAA4"
                    },
                    "action": "Add",
                   "order_item_id": "a1f3i000000UcNVAA0"
                },
                ...
            ]
        }
    ],
    "account_id": "0013i00000OXjoVAAT",
    "order_id": "a1g3i000000t1RhAAI",
    "responseUri": "/services/apexrest/vlocity_cmt/asyncCallback/a2L3i000000DWUyEAO"
}

The payload uses the following parameters:

• Each node within the order_items array represents a corresponding fulfillment request line (FRL) or order item.

• order_item_id : the Salesforce record ID of the corresponding FR Line or Order Item.

• action : The Action field for the corresponding FRL or order item.

• specified_by :

  • specification_name : The name of the corresponding product specification.

  • specification_id : The record ID of the corresponding product specification.

• described_by : Attribute values for the corresponding FRL or order item, with the following name-value pairs:

  • characteristic : attribute name

  • value : attribute value. Empty values aren't included in the payload.

    

    Note

    The Callout Parameters field on the orchestration item, which configures the callout to send empty values, is ignored by XOMAsyncSystemInterface. That field is only respected by the synchronous adapters.

• order_items : An array of child FRLs or order items.

• account_id : The account record ID of the order.

• order_id : Contains the ID of the corresponding fulfillment request (for callouts that link to FRLs), or the ID of the order (for callouts that link to order items).

• responseURI : A predefined callback URL where the last part (ID) represents the orchestration item ID.

Response Processing

Acknowledgment

Although XOMAsyncSystemInterface is designed to wait for a response, it expects the external system to send an HTTP code as an acknowledgment that it has received a request.

• If the acknowledgment is one of the expected success codes (200, 201, 202, 203, 204, 205, 206, 302, or 30): The callout remains in the Running state.

• If the acknowledgment is one of the expected error codes (408, 426, 500, 502, 503, 504, 440, 444, 520, 522, 523, 524, or 525): The callout moves to the Failed state, and is retried according to the retry policy.

  For information about retry policies, see: Set Up Retry Policies for Failed Callouts

• If the acknowledgment is any unexpected code: The callout moves to the Fatally Failed state and isn't retried again, regardless of the retry policy.

Response Payload

By default, responses are logged in the Response field of the FRL or order item. Then the adapter analyzes the response HTTP code, and completes or fails the callout accordingly. You can change where, or if, responses are stored (see OM Standard: Configure Request and Response Storage in Custom Settings).

The response is validated against the following rules. If any of these conditions fail, then the callout fails:

• The incoming ID points to the callout that made the request.

• The callout is in the Running state.

• The response doesn't contain the errorCode message.

• The order_id name-value pair is present, and matches the Order Id associated with the callout.

Failure - Callback Sample

PayloadJSON
{ 
   "order_id": "801xx000003Gh2JAAS", 
   "errorCode": "500", 
   "errorMsg": "Downstream Failure" 
}

If an asynchronous callout fails, the fulfillment step transitions immediately to the Fatally Failed state because asynchronous callouts do not support automatic retries. The system populates the error message in the ExecutionLog__c field.

Success - Callback Sample

PayloadJSON
{ 
    "order_id": "801xx000003Gh2JAAS"
}

When the callback is successful, the fulfillment step transitions to the Completed state.