Configuring Data Exchange with External Systems During Order Flow

Among the available order flow configuration capabilities, you can configure CloudBlue Commerce to exchange data with external systems during the order processing. This may be helpful in such cases as, for example:

• Fraud screening, validation and eligibility checks: A new customer completes the customer details and orders a service. Before provisioning the service, provider wants to make sure the customer is not blacklisted, provided a valid credit card details and is eligible to make such a purchase based on other applicable criteria. To ensure this, CloudBlue Commerce submits the order details to one or several third-party systems between the Payment and Provisioning phases. The service is not provisioned until all external systems return positive results.
• Eligibility checks, integration with a third-party billing system: Before charging the end customer, provider wants to check the reseller's balance in a third-party billing system. The end customer is charged only if the reseller's balance is sufficient.
• Integration with a third-party information hub: Before completing an order, provider wants CloudBlue Commerce to notify a third-party information hub system about the amount to charge the customer for the purchased services. The order is not completed until the third-party system accepts the information.
• Integration with a third-party billing system: When an order is ready to complete, provider wants CloudBlue Commerce to notify a third-party billing system about the order details. The order is completed only after the third-party billing system approves the request.

This capability is available for all order types (sales order, billing order, change order, renewal order, and cancellation order) for both default and custom order flows.

Important notes

1. External data exchange can be configured in particular order flow points only. New data exchange points cannot be created. The existing data exchange points cannot be changed. The default order flow transitions cannot be changed either.
   
2. The default order flow transitions related to remote order flow handlers (that is, transitions from statuses coded C1–C5, M1–M5, W1–W5, F1–F5 and transitions to statuses coded W1–W5) cannot be changed.
   
3. If you need to create a custom order flow with remote handlers, copy the default order flow and customize it to make sure it works correctly.
   
4. Do not import an order flow if it was previously exported from system versions earlier than 7.2. Configure such order flows manually in your current system to make sure all your order flows work correctly in external data exchange points.

Viewing the order flow points in which data exchange with external systems can be configured

To view the available data exchange points:

1. Go to the default order flow: System > Settings. Click Order Processing in the Operations section. Click All Order Flows in the Flow section. Click Default Order Flow.
2. Choose the necessary order type by clicking it in the list.
3. Switch to the Remote Handlers tab. The configurable data exchange points available for this order type are listed.

How to configure

To configure data exchange with an external system/web service:

1. Obtain the necessary information about each remote web service you want to configure data exchange with:
   • Web service base URL
   • SSL certificate for the Web service
   • Relative paths of all necessary services
   • How the web service responds to data exchange requests, synchronously or asynchronously.

   • Whether the web service, if responds asynchronously, can call the Billing callback method RemoteRequestCallback_API to send the asynchronous processing result.

     Important: If a web service processes requests asynchronously, make sure the web service can call the Billing callback method RemoteRequestCallback_API to report the result to Billing after the asynchronous data processing is complete.

2. Configure the necessary remote event receivers to represent the necessary web services in CloudBlue Commerce:
   1. Log in to Provider Control Panel. Go to Billing > System > Settings. Click Remote Event Receivers in the System section. Press Add New Remote Event Receiver. Complete the fields:
      • Name: receiver name
      • Base URL: Web service base URL
      • Certificate in .pem format: SSL certificate used by Billing to verify the external web service
   2. Repeat for all the necessary web services.
3. Configure CloudBlue Commerce to exchange data with the necessary web services in the respective order flow points:
   1. Go to the necessary order flow: System > Settings. Click Order Processing in the Operations section. Click All Order Flows in the Flow section. Click the necessary order flow in the list (either the default or a custom order flow).
   2. Choose order type: click the necessary order type in the list.

   3. Switch to the Remote Handlers tab. Click the necessary data exchange points among the available. Configure a Remote Order Flow Handler for this data exchange point:

      Note: To be able to complete the fields below, you will need some specific information about the associated remote web service.

      • Remote Event Receiver: choose a remote event receiver from the configured ones
      • Relative URL: enter the necessary relative path to define the exact web service location.
      • Synchronous: check/uncheck depending on how the web service processes requests.

      • Request data format: Choose one of the options to define the type of request:

        • Order data
        • Order and customer data
        • Order, customer and payment data

        Depending on the option selected, necessary set of data will be sent from Billing to the remote event receiver (i.e., external system) in the JSON format. For details on the data to be sent in requests, refer to the respective section.

      • Max attempts: How many times to retry a request, if unsuccessful. Can be zero. If the number of retry attempts is exceeded, the order is suspended in its current status.
      • Repeat interval (seconds): Minimum interval between attempts to send a data package to the remote order flow handler.
      • Timeout (ms): Interval during which Billing will wait for a response from the remote server. When this interval is exceeded, the request can be repeated, if such repetition is configured and if the Max attempts value is not exceeded.
4. Repeat for all the necessary order flow points, order types, and order flows.

Tracking the results

You can view the results of remote requests:

• In the order history: Go to the necessary order: Operations > Orders. Switch to the Status History tab.
• In the list of failed or pending remote requests: Go to System > Settings. Click Remote Requests in the Operations section.

Note: Successful remote requests are deleted from the database and, therefore, are not displayed in the list.