Retrieving purchase order from Microsoft Dynamics AX 2012 using custom built Application Integration Framework (AIF) service

I recently got a call from one of my client who told me that they have an urgent request to pull out all purchase orders from Microsoft Dynamics AX using Application Integration Framework (AIF). Unfortunately, the out-of-box Dynamics AX AIF services does not have a built-in services which can be used to extract all purchase orders from Dynamics AX. In order to do this, we decide to build a custom service to achieve the goal.

An AIF service can be inbound or outbound. An inbound service is used when you want to send data to an external system and outbound services are used when you want to retrieve data. This document will guide you in creating this custom AIF services in Microsoft Dynamics AX 2012.

Before we get started, there are key points to consider:

Service operations are class methods that expose any business logic in a service. To define a service operation, we need to add the SysEntryPointAttribute attribute at the top of a method. Any existing method can be converted to a service operation by adding this attribute at the beginning of the method. The most common operations for a service include but not limited to Create, Update, Find, Read, and Delete etc. Any customized operation can also be built from ground.

SysEntryPointAttribute defines the authorization checks that will be performed when a method is called from the server. This attribute must be set on all the service operations. If the value is “true”, it means that authorization checks will be performed for all the tables accessed in the method and if set to “false”, no authorization checks will be performed.

AifCollectionTypeAttribute is used when you want to use a collection as a return type or in a parameter of a service operation. This attribute defines the type of data a collection contains.

Building the service

1. Create a new class – first we will create a new class in AX which will contain the service operations.
2. Launch Dynamics AX and open AOT. Go to Classes and create a new class. Let’s name it MCG_PurchOrderService, and also set the RunOn property of the class to Server. This will make sure the class always executes on the server.
3. Add a new method and name it as getPurchOrderList. This method will query purchase orders and return a list of purchase orders. Write the following code in the method. Please note that the SysEntryPointAttribute tells AX that this method is a service operation method.
4. Create a new service – now we will create a new service and add the above created service operation to it.
5. Go to Services, right click and select New Service, and Name it as MCG_PurchOrderService.
6. Open the properties of the newly created service and select the MCG_PurchOrderService class in the Class field.
7. Now expand the MCG_PurchOrderService service node and add a new Operation by right clicking on Operations and selecting Add Operation.
   

   

8. Create a new service group – the next step is to create a service group and deploy the service to the Inbound Port
9. Go to Service Groups, right click and select New Service group, and Name it as MCG_PurchOrderServiceGroup.
   
10. Set the AutoDeploy to Yes and set the Description as Purchase Order Service. Please note that the AutoDeploy = Yes means that this AIF Service will start automatically when AOS is started.
11. Right click the newly created service group and select New Service Node Reference.
12. In the newly created service node, set the Service property to MCG_PurchOrderService. The Name property will automatically default to the Service name.
    
13. Now right click the service group and select Deploy Service Group.
14. A success message will appear if the service group is successfully deployed.

Verify the service

1. To verify it, go to System administration > Setup > Services and Application Integration Framework > Inbound ports. The Service group name MCG_PurchOrderServiceGroup will appear here as Port name with a green check mark. This shows that service group is deployed and active. If a red ‘x’ is appearing, select Activate from the action pane to activate the port.
2. The WSDL URI is the URL of the service which can be used by external systems to access the service.

Consume the service

We had built the service, and now it’s time to test the service. There are several ways to consume the service, and here we use Microsoft Visual Studio to build a .NET Framework application to consume the service exposed by the AIF.

1. In Visual Studio, create a new project of type Windows Form Application and name it TestPurchOrderService.
2. In Solution Explorer, expand the node for your project. Right-click the References node, and then click Add Service Reference.
   
3. Then add the web URL we created in part I step 4.2:http://XXXXXXX:8101/DynamicsAx/Services/MCG_PurchOrderServiceGroup
4. Click Go.
5. The form becomes populated with a node for your service. Click the option button for your service.
6. In the Namespace field, enter the namespace name mcgPurchOrderServiceRef that you would like for the proxy C# code that Visual Studio generates.
   
7. Click OK, and the service reference will be added as below.
   
8. Now we are now ready to use the proxy classes in our program.
9. Run the form – open the form and add a button and a list box control to the form.
10. Add the below code to the Get Purchase Order List button click event:
11. Click Get Purchase Order List button and the output will be like below:

RSM is a nationally recognized partner in the mid-market ERP and CRM market.  We provide a full suite of services for Microsoft Dynamics AX. To learn more about our success stories, visit our Microsoft Dynamics ERP Case Studies page.  If you like more information about the services we can provide your organization to extend your Dynamics AX solution, contact our professionals at erp@rsmus.com.

By: Andy Cheng – New York Microsoft Dynamics AX partner

Andy Cheng