How to: Integrate an external tax service to Ax retail online storefront

Further reading
Microsoft Dynamics AX 2012 for Developers [AX 2012] SDK Download RunOperation Method

Note: this tutorial assumes that user has the required information to replace a service in Commerce runtime environment. For further detail, see how to Replacing a service in the CRT (by SABAN)

Tutorial
It is quite a common scenario for customer to offload tax computation. Ax retail online store front has the necessary extensibility point to integrate with an external tax provider. Below is the list of steps to follow to achieve:

A. Implementing the interface

Like any other service in commerce runtime, tax service must also satisfy certain requirements. Service base and IService must be implemented to hook up with the system. Below is an exemplary code to illustrate. Execute method is responsible for the actual business logic.
/// <summary> /// Represents the base class for services. /// </summary> public abstract class Service : IService { } /// <summary> /// Interface for Tax service. /// </summary> public interface ITax : IService { } public interface IService { /// <summary> /// Execute method for a service request.

/// </summary> /// <typeparam name="TResponse">The response type.</typeparam> /// <param name="request">The request object as a subtype of the <see cref="ServiceRequest"/> class.</param> /// <returns>The response object as a subtype of the <see cref="ServiceResponse"/> class.</returns> TResponse Execute<TResponse>(ServiceRequest request) where TResponse : ServiceResponse; }

Below is a sample implementation of Execute method. The first mandatory step a service implementation must do is to check the inbound message type. As commerce runtime is designed in a message based api in mind, if the service receives unrecognized messages, this should be an adequate reason to fail fast as opposed proceed further and fail later. The real crux of the implementation is shown in CallExternalTaxProvider utility method. This is no different than any other code, calling a web service out in the cloud. Firstly, service client proxy is initialized and configured with necessary information, and then afterwards actual invocation takes place. As in any other web service interaction, calling code should be careful about the returned exceptions, error codes and other validations might be necessary. Please keep in mind that each external service has different api and different requirements in integration. Please refer to document for your external tax provider. This code is just meant as a sample.
protected override TResponse ExecuteRequest<TResponse>(ServiceRequest request) { if (request == null) { throw new ArgumentNullException("request"); } Type requestType = request.GetType(); object response; if (requestType == typeof(CalculateTaxFromExternalProvider)) { response = this.CallExternalTaxProvider ((CalculateTaxFromExternalProvider)request); } else { throw new NotSupportedException(string.Format("Request '{0}' is not supported.", request.GetType().ToString())); } return (TResponse)response; } /// <summary> /// Calculates the tax by calling the external service provider for the last item. /// </summary> /// <param name="request">The request.</param> private CalculateTaxResponse CallExternalTaxProvider(CalculateTaxRequest request) {

decimal taxAmount = 0; // check the inbound arguments if (request != null && request.Context != null && request.Context.SalesTransaction != null) { // Initialize the service proxy and configure accordingly. using (ExternalTaxProvider eTaxProvider = new ExternalTaxProvider()) { // assign the URL to call. This is fetched from a configuration source eTaxProvider.Url = GetUrlFromConfiguration(); if (string.IsNullOrWhiteSpace(eTaxProvider.Url)) { throw new ArgumentNullException("ExternalTaxProvider.Url", "URL is not specified in config for tax provider."); } eTaxProvider.Config = GetTaxProviderConfigration(); // Create external request object and populate it with tax specific information. ExternalTaxRequest taxRequest = new ExternalTaxRequest(); taxRequest.ShipTo = GetAddress(request.DeliveryAddress); // determine what type of item is purchased. taxRequest.PurchaseType = GetPurchaseCategory(request);

// this is the actual call to web service outside. ExternalTaxResponse webServiceResponse = eTaxProvider.ProcessRequest(taxRequest); if (webServiceResponse == null) { throw new CommunicationException(CommunicationErrors.ExternalProviderError, "Query to external service yielded no result."); } // Some post processing goes here. Simplified for sake of brevity // Process response to extract charge value taxAmount = webServiceResponse.TotalTaxAmount; } } else { NetTracer.Error("Invalid request received: CallExternalTaxProvider "); } return new CalculateTaxResponse(taxAmount); }

B. Update the manifest for replace the existing out-of-the-box tax service
As seen in referenced how to document, Replacing a service in the CRT, replacing a component in commerce runtime requires some modification in configuration file. This is no different for Tax service and user need update the manifest and replace out of the box tax service with the new implementation.