Microsoft Dynamics AX

Import commodity codes into a category hierarchy

White Paper This white paper describes how to create and use an XML file to import commodity codes from an external classification system into a product category hierarchy in Microsoft Dynamics AX.

Donna Daem September 2013 http://go.microsoft.com/fwlink/?LinkID=313695&clcid=0x409

Table of Contents
Overview and definitions ............................................................................ 3 Prerequisites .............................................................................................. 3 Prepare the XML file for import .................................................................. 4 Use Excel to create the XML import file ...................................................... 5 Import the commodity codes ...................................................................... 8

2 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

Overview and definitions

In Microsoft Dynamics AX 2012, you can use category hierarchies to classify products or transactions for reporting and analysis. An organization can create more than one category hierarchy. For example, your organization might create one category hierarchy to classify products that it buys, and another category hierarchy for products that it sells. The number of category hierarchies that your organization uses, and the structure and number of subcategories in each category hierarchy, depend on the reporting needs of your organization. There are several industry-standard classification systems and commodity code systems for reporting to government agencies and industry organizations. Some of the more common examples are Intrastat, UNSPSC, NAICS, eCl@ss, eOTD, and NIGP. Some of these classification systems are available for download to a Microsoft Excel file or other file type from the website of the applicable government or industry organization. You can import all or part of an external classification system into AX 2012 to create or update a category hierarchy. There are a several methods available in AX 2012 that you can use to import commodity codes. This white paper specifically describes how to import commodity codes from an XML file by using the Application Integration Framework (AIF) service in AX 2012. To use the AIF service, the contents of the import file must conform to an acceptable format for the tables in Microsoft Dynamics AX. The process that is described in this white paper uses an XML file format and a schema that maps to specific fields and tables in the category hierarchy features. A sample XML schema is also provided.

Prerequisites
Before you can import an external classification system to a category hierarchy in AX 2012, the following tasks must be completed: 1. An integration port must be set up by using AIF. Only users who are assigned to the System Administrator role can configure integration ports. For information about how to set up an integration port for the category import service, see Walkthrough: Configuring an inbound integration port for category hierarchies. 2. A category manager must create a category hierarchy and add at least one category to the hierarchy. The first category that is created is automatically assigned as the top level in the hierarchy. This first category is the parent of all other categories in the hierarchy. For more information, see Key tasks: Set up a category hierarchy. 3. In the Category hierarchy form, the category that you want to use as the parent for the imported commodity codes must be assigned a code number. When you create an XML import file, the code number of the parent category is assigned to all the commodity codes in the import file.

3 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

Prepare the XML file for import

Some standard classification systems can be downloaded from the website of the applicable industry organization or government agency. If the information is downloaded to an Excel file, you must convert the information to an XML schema that is valid for AX 2012. If the information is already available in an XML file format, you must add specific XML tags to enable the import into AX 2012. The following procedure describes how to create an XML schema that is valid for importing data into a category hierarchy in AX 2012. 1. Insert the following XML heading and tags at the beginning of the file. The indentation at the beginning of each row must be exactly as it is displayed here.
<?xml version="1.0" encoding="utf-8"?> <EcoResCategoryDoc xmlns="http://schemas.microsoft.com/dynamics/2008/01/documents/EcoResCategoryDoc"> <DocPurpose></DocPurpose> <SenderId></SenderId> <EcoResCategoryData class="entity"> <Code></Code> <Name></Name> <Parent></Parent> </EcoResCategoryData> </EcoResCategoryDoc>

2. Between the <DocPurpose> and </DocPurpose> tags, enter one of the following: Enter Original if you are importing commodity codes into a new category hierarchy. Enter Updated if you are modifying an existing category hierarchy.

3. Between the <SenderId> and </SenderId> tags, enter the company code for the legal entity that uses this category hierarchy. If all legal entities use it, enter a company code for any one of your legal entities. 4. Between the <Code> and </Code> tags, enter the identification number for a commodity code. This number might already be assigned by an external classification system. 5. Between the <Name> and </Name> tags, enter the name for a commodity code. This name might already be assigned by an external classification system. 6. Between the <Parent> and </Parent> tags, enter the identification number for the parent node of the commodity code. This is the code number of the parent category in the category hierarchy. 7. To add another commodity code, insert the following lines of tags just before the line that contains the </EcoResCategoryDoc> tag, and then repeat steps 4 through 6 for the new commodity code.
<EcoResCategoryData class="entity"> <Code></Code> <Name></Name> <Parent></Parent> </EcoResCategoryData>

4 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

The following image shows an example of a valid XML schema. In this example, the category hierarchy parent code number is 999999, and the legal entity is named DAT. Five commodity codes are ready to be imported into parent category 999999. The five commodity codes are named CategoryA, CategoryB, CategoryC, CategoryD, and CategoryE. The commodity codes numbers are 10001, 10002, 10003, 10004, and 10005, respectively.

Use Excel to create the XML import file

If the list of commodity codes is stored in an Excel file, you can convert the information to an XML schema that is valid for AX 2012. This procedure uses features that are available in Excel. Use this procedure if you want to import a small number of commodity codes. If you want to import a large number of commodity codes, we recommend that you work with a system administrator to create an XML file by using an automated process. 1. In a new Excel workbook, in the first four rows of column D, enter the following XML heading tags. Each of the following lines must be a new row in the workbook. The indentation at the beginning of each row must be exactly as it is displayed here.
<?xml version="1.0" encoding="utf-8"?> <EcoResCategoryDoc xmlns="http://schemas.microsoft.com/dynamics/2008/01/documents/EcoResCategoryDoc"> <DocPurpose></DocPurpose> <SenderId></SenderId>

2. Beginning in the fifth row, in columns A through C, enter the following tags for the first commodity code. Row
5 6 7 8 9

Column A
<EcoResCategoryData class=entity> <Code> <Name> <Parent> </EcoResCategoryData>

Column B
##### NNNNN PPPPPP

Column C
</Code> </Name> </Parent>

5 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

In column B, replace the placeholders that are used in the table as follows: 1. Replace ##### with the assigned code number for the commodity code. 2. Replace NNNNN with the name of the commodity code. 3. Replace PPPPPP with the code number of the parent category of the commodity code. 3. For each additional commodity code that you want to import, copy the five rows of tags in columns A and C to an additional five-row set. Then add the information for the commodity code as in step 2. The following image shows an example of the XML information in Excel. In this example, five commodity codes are ready to be imported into a parent category that is assigned code number 999999.

4. After you have entered the commodity code information, use the concatenate formula in Excel to merge the XML tags and the data into one cell. For example, in the following table, the information for commodity code 10001 in step 2 has been concatenated into column D. Row
5 6 7 8 9

Column D
<EcoResCategoryData class=entity> <Code>10004</Code> <Name>CategoryA</Name> <Parent>999999</Parent> </EcoResCategoryData>

6 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

5. After the last row of tags for the final commodity code, enter </EcoResCategoryDoc> as the closing tag on the last row of the worksheet. This tag signifies the end of the XML schema. In the following image, the sample file is ready to be converted to an XML file.

6. Select all the information in the concatenated column, and then press Ctrl+C to copy the information. 7. In Notepad or another text editor, open a new text file. Paste the copied information into the text file. 8. Click File > Save As, and then select a location for this file. Enter a name for the file. In the Save as type field, select Text (Tab delimited).

7 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

Import the commodity codes

Use the following procedure to import the commodity codes in the XML file into a category hierarchy in Microsoft Dynamics AX. 1. In Microsoft Dynamics AX, click Product information management > Setup > Categories > Category hierarchies. 2. Select a category hierarchy to import the commodity codes into, or create a new category hierarchy. For more information about how to create a category hierarchy, see Key tasks: Set up a category hierarchy. 3. In the Category hierarchy form, in the left pane, select the category that is the parent of the commodity codes to import. On the Action Pane, click Categories from file. 4. In the Import categories form, in the Inbound port field, select the integration port that was created for commodity code imports. If you are uncertain about the name of the port, contact a system administrator. For more information, see Import categories (form). 5. In the File name field, enter the path of the folder where the XML import file is located. To browse to the location, click the folder icon. In the Select a category file to import form, select the file, and then click Open. 6. In the Import categories form, click Import. You receive a message that indicates that the process might take a few minutes. 7. When the import is completed, you receive a message that lists the number of commodity codes that were imported. If no commodity codes were imported, correct any issues in the XML file. For example, verify that the tags and indentations in the XML file are valid.

8 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY

Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a way that helps you drive business success. U.S. and Canada Toll Free 1-888-477-7989 Worldwide +1-701-281-6500 www.microsoft.com/dynamics

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This white paper is for informational purposes only. Microsoft makes no warranties, express or implied, in this document. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. 2013 Microsoft Corporation. All rights reserved. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Microsoft, Microsoft Dynamics, and Excel are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

9 IMPORT COMMODITY CODES INTO A CATEGORY HIERARCHY