Importing customers into Dynamics AX 2012 using AIF/,Creating a Custom Inbound AIF Service in Microsoft Dynamics AX 2012

Importing customers into Dynamics AX 2012 using AIF

This article will show you step-by-step how to do a basic customer import (including corresponding GAB and address data) using AIF in AX 2012. It’s assumed that you’ve already completed the basic setup necessary to create customers manually through the AX client user interface.

Beginning with Dynamics AX 2009, the Global Address Book (GAB) feature was integrated into various business objects (e.g. customers, vendors, etc.). This presented some new challenges with respect to data imports involving those business objects. Specifically, customer imports became a bit more complicated because the new GAB data relationships had to be handled during the import process.

The GAB continued to evolve with the release of Dynamics AX 2012. As would be expected, these GAB updates are incorporated into the customer document available in the Application Integration Framework (AIF). However, importing customers successfully via AIF can be a bit tricky if you miss some key points.

Configuration

Active Directory (AD) account

For audit trail purposes, create a dedicated AD user account for integration purposes. This will help you distinguish between data created by your normal business users vs. data imported automatically by AIF.

Example: <DOMAIN>\ax_aif_integration
(where <DOMAIN> is your Active Directory domain name)

This account should be added as a user within AX and be assigned the appropriate security rights to allow it the ability to create customer, GAB, and address records. It should NOT be given elevated privileges (i.e. local administrator on host machine operating system or System administrator role within AX).

File location

For this example, we’ll be using the File System Adapter for AIF. Create the following local folders:

C:\TestAIF\Customers\Inbound
C:\TestAIF\Customers\Outbound

On the TestAIF folder, set read/write access for the ax_aif_integration account that you created in the previous step.

Inbound port

Log into AX 2012 with an account belonging to the System administrator role. Configure a new Inbound port. Navigate to:

System administration > Setup > Services and Application Integration Framework > Inbound ports

Click the New button.

Enter the following settings.

Next, set up the Service operations.

Select the CustCustomerService.create service and click the Close button to save your selection.

Now configure the Data policies.

Set the attributes as follows:

Then click the View schema button.

Click the Save as button.

Save the XML schema to C:\workspot\Customer_TestCustomerImport.xsd.

Next click the View imported schemas button on the main Schema form.

Click the Save as button.

Save the XML schema to C:\workspot\SharedTypes.xsd.

Close the Schema forms and the Document data policies form.

On the Inbound ports form, select your newly created port (TestCustomerImport) and click the Activate button.

After a few seconds, an Infolog will appear.

Batch jobs

Navigate to:

System administration > Inquiries > Batch jobs > Batch jobs

Set up the following batch job and click the View tasks button.

You’ll need to set up these 4 Batch tasks:

The Company accounts and Class name fields are mandatory. The Task description,Has conditions and Batch group fields are optional but recommended. If you set up conditions, execute the tasks in this order:

1. AifGatewayReceiveService
2. AifInboundProcessingService
3. AifOutboundProcessingService
4. AifGatewaySendService

XML data

You will need to create a sample customer data file in XML format to test the import. Log into your desktop using your ax_aif_integration account so that the file ownership of the XML file gets set to that account. Be sure your ax_aif_integration account does NOT have local admin privileges as that will interfere with the default file ownership assignment in newer operating systems (e.g. Windows Server 2008, Windows 7).

You can use Visual Studio 2010 to assist with the creation and validation of your sample XML data file. Use the 2 XML schema files (Customer_TestCustomerImport.xsd andSharedTypes.xsd) that you previously saved to your C:\workspot folder to validate your sample XML file in Visual Studio.

Open Visual Studio 2010 and select File > Open > File.

Choose the Customer_TestCustomerImport.xsd file.

Notice the nodes with the yellow + sign that are related to the GAB. These are a bit tricky. You have to set the element attributes properly for these nodes to validate successfully (more info on that in a moment).

Create a new XML file in Visual Studio by selecting File > New > File and select XML File.

Copy and paste this sample XML data that conforms to the previously defined Data policies configuration.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34


<?xml version="1.0" encoding="utf-8"?>

<Envelope  xmlns="http://schemas.microsoft.com/dynamics/2011/01/documents/Message">http://schemas.microsoft.com/dynamics/2011/01/documents/Message">

   <Header>

     <MessageId>{A923D03A-E441-F222-C21B-1AC9D9F7D13E}</MessageId>

     <Action>http://schemas.microsoft.com/dynamics/2008/01/services/CustomerService/create</Action>

   </Header>

   <Body>

     <MessageParts>

       <Customer  xmlns="http://schemas.microsoft.com/dynamics/2008/01/documents/Customer">http://schemas.microsoft.com/dynamics/2008/01/documents/Customer">

         <CustTable>

           <AccountNum>_CUST888</AccountNum>

           <CustGroup>_DEFAULT</CustGroup>

           <DirParty xsi:type="AxdEntity_DirParty_DirOrganization"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance">

             <LanguageId>en-us</LanguageId>

             <Name>Test customer 888</Name>

             <DirPartyPostalAddressView>

               <City>Seattle</City>

               <CountryRegionId>USA</CountryRegionId>

               <IsPrimary>Yes</IsPrimary>

               <LocationName>Test customer 888</LocationName>

               <Roles>Business</Roles>

               <State>WA</State>

               <Street>123 Main Street</Street>

               <ZipCode>98101</ZipCode>

             </DirPartyPostalAddressView>

             <OrganizationName>

               <Name>Test customer 888</Name>

             </OrganizationName>

           </DirParty>

         </CustTable>

       </Customer>

     </MessageParts>

   </Body>

</Envelope>






Any errors in the XML file will be indicated with a blue or red underline within the Visual Studio editor. Note the xsi:type and xmlns:xsi attributes in the DirParty element. Those attributes are critical for getting the GAB portion of the customer import to work properly (remember the yellow + signs mentioned earlier?). After you finish editing your sample XML data file, save it to the Inbound port file location you defined:

C:\TestAIF\Customers\Inbound

Test the integration

Now you should test your customer import. Navigate to:

System administration > Inquiries > Batch jobs > Batch jobs

Select your AIF batch job and click Functions > Change status.



Select Waiting.



Within approximately 1 minute, the batch job will execute. Once it’s completed, its status will return to Ended (you might need to refresh the form manually to see the updated status). Navigate to:

Accounts receivable > Common > All customers

Your new customer will now be present!



*****************************************************************


Creating a Custom Inbound AIF Service in Microsoft Dynamics AX 2012




Overview

Application Integration Framework (AIF) services are used to communicate with external systems or applications. Microsoft Dynamics AX 2012 has the following types of services:

Document services
Custom services
System services


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 tutorial will guide you in creating Custom Inbound AIF services in Microsoft Dynamics AX 2012. Custom services are used when:

The complexity of the entities is relatively low.
When you want to have full control of the service contract.
When data contracts needs to be shared with different entities.


Pre-requisites

Microsoft Dynamics AX 2012
AIF services must be installed and configured on IIS


Important Concepts


Service operation

Service operations are class methods that expose any business logic in a service. To define a service operation, 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. 
&absp;
Note: The service operation name cannot include Create, Find, Update or Delete. These names are reserved to be used by AIF Document services. AX will make an exception when they are called from a client.


SysEntryPointAttribute

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

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.



Scenario

As part of this tutorial the service will return the list of customer names in Dynamics AX.

Steps

First we will create a new class which will contain Service operations.



Open AOT. Go to Classes and create a new class. Let’s name it CustomerServiceDemo.



Set the RunOn property of the class to Server. This will make sure the class always executes on the server.

 
 
Add a new method and name it as getCustomerNameList. This method will query customers’ names and return a Type list string. Write the following code in the method:

































1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17



[SysEntryPointAttribute(true),

AifCollectionTypeAttribute('return', Types::String)]

//return denotes the parameter type and String specifies the type of data the collection will hold

public List getCustomerNameList()

{      

    CustTable       custTable;    

    List list = new List(Types::String);    

    

    //select all customers

    while select * from custTable        

    {

        //add customer name in the list

        list.addEnd(custTable.name());

    }

    

    return list;

}







The SysEntryPointAttribute tells AX that this method is a service operation method.



Now we will create a new service and add the above created service operation to it.



Go to Services, right click and select New Service.





Name it as CustomerServiceDemo.



Open the properties of the newly created service and select the CustomerServiceDemo class in the Class field.





Now expand the CustomerServiceDemo service node and add a new Operation by right clicking on Operationsand selecting Add Operation.





All service operations present in the class will be listed. Select the getCustomerNameList service operation by checking the Add field in the grid and press OK.





The next step is to create a service group and deploy the service to the Inbound Port.



Go to Service Groups, right click and select New Service group.





Name it as CustomerServiceDemoGroup.



Set the AutoDeploy to Yes (Service will start automatically when AOS is started) and set the Description asCustomer name service.





Right click the newly created service group and select New Service Node Reference.





In the newly created service node, set the Service property to CustomerServiceDemo. The Name property will automatically default to the Service name.





Now right click the service group and select Deploy Service Group.





A success message will appear if the service group is successfully deployed.



To verify it, go to System administration à Setup à Services and Application Integration Framework à Inbound ports.



The Service group name CustomerServiceDemoGroup 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.





The WSDL URI is the URL of the service which can be used by external systems to access the service.



To test whether the service is running properly, open the Visual Studio Command Prompt by going to All Programs à Microsoft Visual Studio 2010 à Visual Studio Tools à Visual Studio Command Prompt.



Write wcftestclient and press enter. WCF Test Client will open.



Now, go to File àAdd Service.





In the Add Service dialog box, paste the WSDL URI of the port and press OK.





The WCF Test Client will open the service with the list of operations available.



Double click the getCustomerNameList. It will open the operation details in the right hand side pane.





Click the Invoke button. The result of the service will appear in the Response pane.





Pat yourself on the back. You are finished!