Microsoft Dynamics AX 2012 Application Integration Framework – Custom Web Service (Strongly typed)

Microsoft Dynamics AX 2012 Application Integration Framework – Custom Web Service (Strongly typed)

Purpose: The purpose of this document is to illustrate how to create and use Microsoft Dynamics AX 2012 AIF Custom Web Service in integration scenarios for certain type of custom data.

Challenge: Data model changes in Microsoft Dynamics AX 2012 related to high normalization and introduction of surrogate keys made some integrations more complex. In fact the process of custom AIF Web Service creation remains the same. Generic Document AIF Web Service can be used in Microsoft Dynamics AX 2012 to synchronize different (may be similar) types of custom data in dynamic, loosely typed fashion. However in the case when you need to synchronize certain types of custom data with complex data sets or where a lot of custom business logic and validations is involved it makes sense to create dedicated AIF Web Service(s) which increases code readability and facilitates maintenance effort.

Solution: Microsoft Dynamics AX 2012 out-of-the-box ships with number of AIF Web Services which can be used in integration scenarios. In this simple example I'm going to synchronize Customer groups information with Microsoft Dynamics AX 2012 from external .NET application. Please note that there is no Customer groups AIF Web Service in Microsoft Dynamics AX 2012 out-of-the-box. That's why in this walkthrough I'll demonstrate how to create and call custom Customer groups AIF Web Service in C#.NET Console application in order to create a customer group in Microsoft Dynamics AX 2012. Similar logic can be used to create another custom AIF Web Service for any particular type of custom data. 

Data Model:

Table Name	Table Description
CustGroup	The CustGroup table contains a list of groups into which customers can be added. Every customer must specify a customer group with which it is associated. The group contains information such as default payment terms and settlement periods, and is also used for reporting.

Data Model Diagram:

Please note that I'm going to synchronize Customer groups information with Microsoft Dynamics AX 2012 from external .NET application and I only want to expose 2 fields: CustGroup and Name

Walkthrough:

Custom AIF Web Service in Microsoft Dynamics AX 2012 is based on static query. That's why the first step in creating custom AIF Web Service is data set (query) definition.

Query

After query has been defined you can launch "Create document service" Wizard in Development workspace by going to Tools > Integration Application Framework > Create document service

AIF Document Service Wizard: Select document parameters

Please note that AxdCustomerGroup query is specified as a basis for custom AIF Web Service creation

AIF Document Service Wizard: Select code generation parameters

Please note that create operation will be enabled for custom CustomerGroupService AIF Web Service

AIF Document Service Wizard: Generate code

AIF Document Service Wizard: Completed

Project

Please note that upon completion of Create document service Wizard the system generated AxdCustomerGroup X++ project

Namespace

By default custom CustomerGroupService AIF Web Service namespace is empty, that's why I define it right after AIF Web Service creation

Service group

In order to deploy custom CustomerGroupService AIF Web Service I included it into AccountsReceivableServices Service group

Inbound port

After you deploy AccountsReceivableServices Service group corresponding AccountsReceivableServices port will be activated

Service Reference:

After successful deployment you can consume custom Customer groups AIF Web Service from .NET application by adding Service reference to it. Please note that CustomerGroupService AIF Web Service exposes create operation which will be used to create Customer groups information in Microsoft Dynamics AX 2012.

Source code:

using System; using System.Collections.Generic; using System.Linq; using System.Text; using ConsoleApplication1.ServiceReference1; namespace ConsoleApplication1 {     class Program     {         static void Main(string[] args)         {             CustomerGroupServiceClient client = new CustomerGroupServiceClient();             CallContext context = new CallContext();             context.Company = "ceu";             AxdCustomerGroup document = new AxdCustomerGroup();             document.CustGroup = new AxdEntity_CustGroup[1];             document.CustGroup[0] = new AxdEntity_CustGroup();             document.CustGroup[0].CustGroup = "Alex";             document.CustGroup[0].Name = "Alex";             try             {                 EntityKey[] entityKey = client.create(context, document);                 Console.WriteLine("Done!");             }             catch (Exception e)             {                 Console.WriteLine("Error:" + e.Message);                            }             Console.ReadLine();         }     } }

Result:

Dynamics AX – Customer group

Summary: For the purposes of complex integration scenarios dedicated custom AIF Web Services in Microsoft Dynamics AX 2012 can be created in order to synchronize custom data. In this walkthrough I used simple example of Customer groups AIF Web Service to illustrate the process of custom AIF Web Services creation in Microsoft Dynamics AX 2012. Custom AIF Web Service data set is defined based on static query in Microsoft Dynamics AX 2012.  For example, in order to synchronize Customer groups and Vendor groups information with Microsoft Dynamics AX 2012 from external .NET application you may implement static, strongly typed integration scenarios meaning that you may create dedicated custom AIF Web Services for each type of custom data which increases development effort. However it makes perfect sense to do so for complex data sets and in the case where a lot of custom business logic and validations is involved. As the result by having dedicated AIF Web Services code readability will be increased and maintenance effort will be facilitated. Alternatively for relatively simple integrations with simple data sets Generic Document AIF Web Service can be used which allows for dynamic, loosely typed integration scenarios.

Author: Alex Anikiev, PhD, MCP

Tags: Microsoft Dynamics ERP, Microsoft Dynamics AX 2012, Integration, Application Integration Framework, Custom Data, Custom AIF Web Service.

Note: This document is intended for information purposes only, presented as it is with no warranties from the author. This document may be updated with more content to better outline the concepts and describe the examples.