Create a new transportation management engine

This article describes how to create a new transportation management engine in Microsoft Dynamics 365 for Finance and Operations.

Transportation management (TMS) engines define the logic that is used to generate and process transportation rates in Transportation management. Microsoft Dynamics 365 for Finance and Operations provides several different engine types that calculate different parameters, such as rates, transit times, and the number of zones that will be crossed during transit. This article explains how to use the Microsoft Visual Studio development environment together with Finance and Operations development tools to create and deploy a new TMS engine, and then how to set up the engine in Operations. For more information about the engines that Finance and Operations provides, see Transportation management engines.

Create a new TMS engine

This section explains how to create a class library that has a TMS engine implementation, and how to reference it from a Finance and Operations model.

  1. To deploy your new engines, you must have a Finance and Operations model that will contain the engines. On the Dynamics 365 > Model Management menu, click Create model to create a new model. On the first page of the Create model wizard, name the model TMSEngines.

    Creating a model

  2. On the next page, select Create new package.

    Creating a new package

  3. On the next page, select the ApplicationSuite model to reference. (The ApplicationPlatform model is preselected.)

    Selecting the model to reference

  4. On the next page, click Finish to confirm the creation of a new model.

    Completing model creation

  5. In a new solution, create a new Finance and Operations project, and name it TMSThirdParty. In the project properties, set the project's model to TMSEngines.

  6. Add a new C# class library to your solution, and name it ThirdPartyTMSEngines.
  7. In the ThirdPartyTMSEngines project, add references to Finance and Operations–specific assemblies:

    • Application assemblies that enable X++ types to be referenced. These assemblies can be found in the following locations. [Packages root] is the path of the location where all the deployed Dynamics 365 for Finance and Operations assemblies are placed, such as C:\Packages.

      [Packages root]\ApplicationPlatform\bin\Dynamics.AX.ApplicationPlatform.dll
      [Packages root]\ApplicationFoundation\bin\Dynamics.AX.ApplicationFoundation.dll
      [Packages root]\ApplicationSuite\bin\Dynamics.AX.ApplicationSuite.dll
      
    • Framework assemblies that enable access to data, LINQ, and auxiliary functions. All these assembles can be found in [Packages root]\bin.

      Microsoft.Dynamics.ApplicationPlatform.Environment.dll
      Microsoft.Dynamics.AX.Data.Core.dll
      Microsoft.Dynamics.AX.Framework.Linq.Data.AdoNet.dll
      Microsoft.Dynamics.AX.Framework.Linq.Data.dll
      Microsoft.Dynamics.AX.Framework.Linq.Data.Interface.dll
      Microsoft.Dynamics.AX.Framework.Linq.Data.Msil.dll
      Microsoft.Dynamics.AX.Server.Core.dll
      Microsoft.Dynamics.AX.Xpp.AxShared.dll
      Microsoft.Dynamics.AX.Xpp.Support.dll
      
    • The core TMS assembly (which contains engines) and the TMS base assembly (which contains helpers, constants, data transfer class definitions, and so on). These assemblies can be found in the following locations.

      [Packages root]\ApplicationSuite\bin\Microsoft.Dynamics.AX.Tms.dll
      [Packages root]\ApplicationSuite\bin\Microsoft.Dynamics.AX.Tms.Base.dll
      
  8. Rename the C# class that is automatically generated in the ThirdPartyTMSEngines project to SampleRatingEngine.

  9. Implement the engine. Because we are creating a rate engine in this example, we inherit from the base class for rate engines. The base class implements most of the rate engine interface (TMSFwkIRateEngine). We just have to implement the rate method. To keep this example simple, we will make this method register a hard-coded rate of 100. You can create engines that implement any of the engine interfaces, such as TMSFwkIAccessorialEngine. All the engine interfaces are defined in X++.

    namespace ThirdPartyTMSEngines
    {
        using Dynamics.AX.Application;
        using Microsoft.Dynamics.Ax.Tms.Base.Data;
        using Microsoft.Dynamics.Ax.Tms.Base.Utility;
        using Microsoft.Dynamics.Ax.Tms.Bll;
        using System.Xml.Linq;
        public class SampleRatingEngine : BaseRateEngine
        {
            public override RatingDto rate(TmsTransactionFacade transactionFacade, XElement shipment, TMSRateMasterCode rateMasterCode)
            {
                XElement re = shipment.RetrieveOrCreateRatingEntity(this.RatingDto);
                re.AddRate(TmsRateType.Rate, 100);
                return this.RatingDto;
            }
        }
    }
    
  10. Build the solution.

  11. Add a new reference to the TMSThirdParty project. The reference should point to the ThirdPartyTMSEngines project. When you've finished, your solution should look like this.

    The solution, which includes a reference to the TMSThirdParty project

  12. Build the solution. Verify that the new library appears in the References node in Application Explorer.

    The new library in Application Explorer’s References node

Deploy the TMS engine as a package

One way to deploy third-party TMS engines is through a deployment package. This approach is recommended in a production environment. In a development environment, you can manually copy the assemblies, as described in the next section, "Set up a TMS engine in Finance and Operations." To deploy the engine as a package, follow these steps.

  1. On the Dynamics 365 **> **Deploy menu, click Create Deployment Package.
  2. In the Create Deployment Package dialog box, select the TMSEngines model, and enter the path where you want to store your package files.

    Selecting the TMSEngines model

  3. You can now deploy the package to the target environment. For a tutorial, see Install a deployable package.

Set up the TMS engine in Finance and Operations

This section explains how to set up Finance and Operations to use a TMS engine, and shows how the new engine that we have created is used in rate shopping. The example in this section uses the USMF demo data company.

  1. Create a new engine as described in the "Create a new TMS engine" section.
  2. Build your solution.
  3. Copy the resulting assembly into the binary location of the Finance and Operations server, [AOSWebRoot]bin. Note: This step is relevant only in a development environment. In a production environment, you should deploy through a deployment package. For instructions, see the previous section, "Deploy the TMS engine as a package."
  4. In Finance and Operations, on the Rate engines page, create a new rating engine. The engine should point to the engine assembly that is produced by building the engine class library and the engine class that you implemented.

    Creating a new rating engine on the Rate engines page

  5. Create a shipping carrier that uses the Sample rate engine. Because our engine doesn't use any data in Finance and Operations, you don’t have to assign a rate master.

    Creating a new shipping carrier

  6. On the Rate route workbench page, click Rate shop. You should see a rate of 100.00 from SampleCarrier, as shown in the following screen shot. In this example, we are rate shopping for a route from warehouse 24 to customer US-004. However, but because the rate is hard-coded, you will always see a rate of 100.00.

    Rate route workbench

Tips and tricks

  • If you’re using development tools for Finance and Operations, it's useful to add a new Finance and Operations project to your solution. If you set this project as your startup project and start a debugging session, you can debug both X++ and C# code in the same debugging session.
  • Every time that you change and recompile your ThirdPartyTMSEngines project, you must manually copy the resulting assembly to the Finance and Operations binary location or deploy through a deployment package. Otherwise, you might run by using a stale assembly.
  • After you execute TMS-specific operations in Finance and Operations, the Internet Information Services (IIS) worker process might lock the ThirdPartyTMSEngines assembly so that the assembly can’t be updated. In this case, restart the w3svc process.