You are here:
Asynchronous Integration with a Downstream System
Use asynchronous integration with a downstream system to send a request to that system with the expectation of getting a response sometime in the future, but not immediately.
For example, you may use a callout orchestration item type to send a request to a workforce management system to have a technician to do some work, such as an installation, on a customer's premises. Order Management does not know when the technician will complete this work, and therefore must wait for a response indicating completion of the work at future point in time.
As another example, a request is sent to a delivery system to ship an order item to a customer. The shipment preparation process may take from a few days to a few weeks. The Order Management system needs to receive a confirmation from the delivery system that the item has been shipped to further provision the order.
If the asynchronous response for the event is short, you can use the same callout to wait for the response. However, if the callout takes a long time, such as days, then it is best to use a push event to receive the response.
For more information on orchestration item types, including push events, see Orchestration Item TypesOrchestration Item Types.
Using the XOMAsyncSystemInterface
The asynchronous integration uses the XOMAsyncSystemInterface interface with the Callout orchestration item and leverages DataRaptor-Based IntegrationIntegrating with a Downstream System Using DataRaptor to create a JSON request to a downstream system.
The callbackUrl parameter is automatically added to the JSON by the system interface implementation. The downstream system uses this parameter to call back to Industries Order Management with the response.
The callbackUrl includes the following properties:
orgNamespace
orchItemId
For example,/services/apexrest/<orgNamespace>/asyncCallback/<orchItemId>
When the downstream system receives a request, it acknowledges the receipt with an HTTP response:
HTTP status code 200 — the request has succeeded
HTTP status code 500 — the request has failed with an Internal Server Error.
Once the downstream system processes the request, it notifies Industries Order Management of the completion of the operation. The response is processed using the DataRaptor and the orchestration item is marked complete.
XOMAsyncSystemInterface supports an additional REST-based interface: XOMCallbackRESTService. The downstream system responds to Order Management through the XOMCallbackRESTService. To facilitate this, the following additional input parameters are provided to Vlocity DataRaptor Bundle if is specified on the OrchestrationItemDefinition:
callbackUrl: Tells the downstream system to notify Order Management about the completion of the operation by posting the response to the callbackUri. The response is processed using DataRaptor support enhancements in DefaultSystemInterface functionality.
orchItemId: Customizes the callbackUri to use custom REST service
orgNamespace: Customizes the callbackUri to use custom REST service
Using asynchronous integration with a downstream system involves:
For long response times, see Using Asynchronous Callouts for Long Response TimesUsing Asynchronous Callouts for Long Response Times.
- Creating DataRaptor Bundles for Asynchronous Integration
The asynchronous integration leverages DataRaptor-based integration to create a JSON payload for a downstream system. - Using Asynchronous Callouts for Long Response Times
Asynchronous callouts are used when an external fulfillment system isn't expected to respond immediately. - Overview of Extending the Asynchronous System Interface
Services and customers can extend the functionality of the XOMAsyncSystemInterface class to add more functionality, such as applying logic to determine if a response is good or bad. - Extend the Asynchronous System Interface
You can extend the functionality of the XOMAsyncSystemInterface class to add more functionality, such as applying logic to determine if a response is good or bad.
