Concept - D365 Finance and Operations Order Submission Connector

1 Introduction

This concept provides information about the order submission (micro) service which is used to transfer order information from ICM to Microsoft Dynamics 365. It shows the general data flow as well as gives an overview about the application architecture.

1.1 References

2 Order Submission Workflow

The following diagram shows how the different systems involved with the order submission process interact with each other:

order-submission-workflow

StepDescription
1The order export process is triggered by an external entity. This can either be a customer that created an order (in case an immediate export is configured); or a scheduled job that periodically exports recent orders.
2ICM looks up the configured export service and sends the OrderBO to the service.
3The OrderBO is transformed into an OrderRO that can be parsed by the microservice's REST API.
4The OrderRO is transferred to the order submission microservice.
5An immediate answer ("Accepted") is returned from the microservice to the managed service. At the same time an asynchronous process is triggered that exports the order to the Dynamics 365 system (see 8-14).
6The managed service notifies the ICM that the order submission has been started. This may trigger additional actions (e.g., change order status) on the ICM side depending on the export configuration.
7A response is returned to the caller.
8Order header information are read from the received OrderRO and mapped into a format that can be parsed by Microsoft's OData API.
9The header information is submitted to Dynamics 365.
10A response is returned that states whether the order header creation was successful or not.
11Order header information is read from the received OrderRO and mapped into a format that can be parsed by Microsoft's OData API.
12The item information is submitted to Dynamics 365.
13A response is returned that states whether the order item creation was successful or not.
14This process continues for all the order data that needs to be transferred.
15After all the data is submitted, a message is sent back to a REST resource in ICM stating whether the order was successfully exported.
16The order export status is updated accordingly.


3 Microservice Architecture

3.1 General Structure

The microservice is a RESTful Java web service using Jersey for implementing service resources and client requests. The following diagram shows the basic architecture:

microservice-architecture

The OrderSubmissionApplication registers itself at the cluster's Eureka instance so that it can be easily found by the ICM. When a request arrives, it is routed via Jersey to the REST resource in OrderSubmissionServiceImpl. The service triggers the order submission process asynchronously via executing an Executable (chain).

To achieve minimum coupling between different classes, Guice is used as a dependency injection tool which allows easy replacement of existing implementations in custom projects.

3.2 Executables and Chains

The order submission process is implemented by several Executable implementations. An Executable is a class that is executed in a given context and that returns a result containing information about the processing status:

Executable Interface
/**
 * An executable is an entity that processes the data from a given {@link ExecutionContext} and returns an
 * {@link ExecutionResult}.
 * 
 * @param <T>
 *            the type of context this executable can process
 */
public interface Executable<T extends ExecutionContext>
{
    /**
     * Triggers the execution with the given context.
     * 
     * @param context
     *            the context containing the information to process
     * @return a result stating if the execution was successful or not
     */
    ExecutionResult execute(T context);
}

There is currently one Executable for every request that is to be sent from the Microservice to Dynamics 365. The default execution context for the order submission process is OrderSubmissionExecutionContext which primarily holds the order to be submitted.

Multiple Executables can be chained together via special implementations:

  • AutoRevertibleExecutableChainImpl allows processing Executables in order and will, upon an error, automatically revert all Executables prior to the one throwing the error in reverse order. Note that an Executable can only be reverted if it implements the RevertibleExecutable interface.

  • ContinuingExecutableChainImpl allows processing Executables in order and will ignore execution errors. It will continue with subsequent Executables instead.

Executables and chains are registered via Guice. There are currently two modules containing all bindings:

  • OrderSubmissionInnerChainModule contains an AutoRevertibleExecutableChainImpl with all Executables that interact directly with the Dynamics 365 system. If an error occurs here, already submitted data will be reverted automatically.

    OrderSubmissionInnerChainModule
    public class OrderSubmissionInnerChainModule extends PrivateModule
    {
        @Override
        protected void configure()
        {
            MapBinder<Integer, Executable<OrderSubmissionExecutionContext>> executables = MapBinder
                            .newMapBinder(binder(), new TypeLiteral<Integer>() {},
                                            new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {});
            executables.addBinding(10).to(Key.get(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {}, 
                            Names.named("DeleteExistingSalesOrdersExecutable")));
            executables.addBinding(20).to(Key.get(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {}, 
                            Names.named("CreateSalesOrderHeaderExecutable")));
            executables.addBinding(30).to(Key.get(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {}, 
                            Names.named("CreateSalesOrderLinesExecutable")));
    
            bind(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {})
                            .annotatedWith(Names.named("AutoRevertibleExecutableChain"))
                            .to(new TypeLiteral<AutoRevertibleExecutableChainImpl<OrderSubmissionExecutionContext>>() {});
            expose(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {})
                            .annotatedWith(Names.named("AutoRevertibleExecutableChain"));
        }
    }
  • OrderSubmissionOuterChainModule contains a ContinuingExecutableChainImpl with the chain from the module above as well as an Executable that will report the success status back to the ICM.

    OrderSubmissionOuterChainModule
    public class OrderSubmissionOuterChainModule extends PrivateModule
    {
        @Override
        protected void configure()
        {
            MapBinder<Integer, Executable<OrderSubmissionExecutionContext>> executables = MapBinder
                            .newMapBinder(binder(), new TypeLiteral<Integer>() {},
                                            new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {});
            executables.addBinding(10).to(Key.get(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {}, 
                            Names.named("AutoRevertibleExecutableChain")));
            executables.addBinding(20).to(Key.get(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {}, 
                            Names.named("SendAcknowledgeExecutable")));
    
            bind(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {})
                            .to(new TypeLiteral<ContinuingExecutableChainImpl<OrderSubmissionExecutionContext>>() {});
            expose(new TypeLiteral<Executable<OrderSubmissionExecutionContext>>() {});
        }
    }

The following diagram shows the default chain structure:

default-executable-structure


Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets