Vendor catalog import

Hi Guys, this is my first blog post and I have started with the Procurement section. In this blog you will be going through a complete cycle of the Vendor catalog import process in Microsoft Dynamics AX.

Creating and maintaining procurement catalogs that company employees can use when they order items or services for internal use is one of the major tasks in Procurement and Sourcing. This can be done in several ways.

1. Vendor catalog data can be added to the product master manually;

1. The catalog can be hosted externally or

1. It can be imported from a Catalog Maintenance Request (CMR) file.

We will be looking into the CMR file import process in AX 2012.

Parameter setups

Vendor catalog import parameters

• Create a root folder where the CMR files will be stored (e.g. c:\temp\CMR).
• Click Procurement and sourcing > Setup >Vendors > Vendor catalog import parameters .
• In the Vendor catalog import parameters form, in the Root folder path field, enter the location of the root folder that you created for storing CMR files.
• The CatalogImportPickup folder is created automatically inside the folder you specified.

 

 Configuring an inbound integration port for catalog import

To create and maintain procurement catalogs on your procurement site, you can allow vendors to submit catalog maintenance request (CMR) files by using the vendor self-service portal. Before a vendor can use the vendor self-service portal to import catalog files, you must set up an integration port by using Application Integration Framework (AIF). Only users who are assigned to the System Administrator role can configure integration ports.

Process involved to configure an integration port to receive CMR files-

• Initialize AIF
• Create the integration port
• Add the service operation
• Add the pipeline component

 

Initialize AIF

• Click System administration > Setup > Checklists > Initialization checklist.
• Expand the Initialize system node.
• Click Set up Application Integration Framework.
• Adapters, basic ports, and services are registered. This operation can take some time to be completed.
• [This step might have already been performed on your environment]

 

Create the integration port

Use this procedure to set up the inbound port and to specify the location where the AIF service can find the CMR file that has been submitted for import.

• Click System administration > Setup > Services and Application Integration Framework > Inbound ports.
• Click New to create a new enhanced inbound port. Enter a name and an optional description to identify the port that is used to import catalogs.
• In the Adapter list, select File system adapter. In the URI field, enter the path of the CatalogImportPickup subfolder in the root folder that you created to receive the vendor’s catalog files.

 

Create the integration port

 

Add the service operation

Inbound integration ports must be associated with a service operation. To enable the processing of imported catalogs, you must select the CatImpService.create service operation.

• In the Inbound ports form, on the Service contract customizations tab, click Service operations.
• In the Select service operations form, in the Remaining service operations list, select CatImpService.create.
• Click the arrow button to move the service operation to the Selected service operations list. Close the form.

 

Add the pipeline component

The catalog import service requires a special component that processes CMR documents. To enable this component, follow these steps.

• In the Inbound ports form, on the Processing options tab, select the Preprocess service operation requests check box, and then click Inbound pipelines.
• In the Inbound pipelines form, click Add. Then, in the Class name list, select CatVendorXmlTransform.
• In the Purpose field, enter an optional description, such as “Transform vendor XML files,” and then close the Inbound pipelines form.

 

Additional configuration steps

• When setting up the file adapter click the Configure button, mark both checkboxes and specify the administrator user in the lookup. Not doing this will lead to an error during the import.
• If you can’t see the CatImpService.create in the service selection dialog you can go to the AOT, find the CatImpService under the Services node and click Addins\Register service. The alternative is to go to System administration > Setup > Checklists > Initialization checklist and click Set up Application Integration Framework in the Initialize system group.

 

Activating the integration port

 

Setup catalog import processing job

It is required to run the catalog import service. Normally this is done by setting up recurring batch jobs responsible for executing business logic through integration ports. To learn more about it read the Configure and start the AIF batch services section of this MSDN article.

This standard approach is intended for production. However it’s not very convenient for testing/learning purposes since the catalog import processing will be done asynchronously and the minimum recurrence interval is 1 minute. So its recommended to use the x++ job below which performs the import catalog processing instantly:

static void runAIFReceive(Args _args)

{

new AifGatewayReceiveService().run();

new AifInboundProcessingService().run();

info(‘AIF processing done’);

}

 

Enable a vendor for catalog import

In order to be able to import catalogs for a particular vendor it has to be enabled for catalog import. There are two ways to achieve that:

• Click Procurement and sourcing > Vendors > All Vendors.
• Select the Vendor and click on edit. Click Procurement tab > Set up > Configure vendor for catalog import
• If you don’t do this you will be prompted if you want to enable the vendor for catalog import when creating a new catalog for the vendor.(from AX client)

After you do this a subfolder in the catalog import root folder is created. The name of the folder is the RecId of the vendor.

Inside the folder you will find an archive folder with all the CMR files that have been imported for this vendor. You will also find a folder that is used for importing images of the vendor’s products.

 

Setup procurement hierarchy

• You won’t be able to import products from categories where the vendor is not approved for procurement. To approve the vendor:
• Go to Procurement and sourcing > Setup > Categories > Procurement categories.
• Select the category.
• Add the vendor to the list of approved vendors in the Vendors fast tab.

 

 Workflow

Setup workflow

The import vendor catalog functionality is leveraging another powerful feature of AX: workflow processing. You are allowed to setup rules for automated approval of vendor catalogs and specify one or more reviewers if manual approval is required. To enable the vendor catalog import functionality it is required to set up two types of workflows:

• Catalog import product approval (line-level)
• Catalog import approval (catalog-level).

 

Catalog import product approval workflow

This type of workflow processes all the products that are included in the CMR file. Completion of all of the individual line-level workflow completes the overall catalog import workflow. In order to create a product approval workflow:

• Click Procurement and sourcing > Setup > Procurement and sourcing workflows.
• On the Action Pane, click New.
• Select Catalog import product approval and then click Create workflow.

 

General setup

The common catalog import product approval workflow should look like this:

 

Set up approvers

• 1. Double click the Catalog import product approval element.
• 2. Click the Step 1 element.
• 3. Click Assignment in the action pane.
• 4. The simplest assignment would be User->Admin.

 

Set up automatic actions

Automatic actions allow the workflow framework to automatically approve or reject the products in the imported vendor catalog which meet certain conditions. In order to set up an automatic action you need to:

• Select the Catalog import product approval element.
• Click Automatic actions in the action pane.
• Click the Enable automatic actions check box
• Setup the conditions for auto approval/rejection and select the type of automatic action (approve/reject)

 

Catalog import approval workflow

This type of workflow is used for setting up the rules for approving the whole catalog. When you configure this workflow, you can reference the Catalog import product approval workflow that you configured earlier. The common setup would be to automatically approve the whole catalog import after all the products have been approved:

In the properties of the Vendor catalog lines (products) element you need to reference the catalog import product approval that you created earlier.

• Click Procurement and sourcing > Setup > Procurement and sourcing workflows.
• On the Action Pane, click New.
• Select Catalog import approval and then click Create workflow.
• Select “Invoke a single workflow for all line-items” and select the Catalog import product approval workflow from drop down.

 

Working with Vendor catalog import process
(AX client)

Create a vendor catalog

First of all a vendor catalog needs to be created.

• Go to Procurement and sourcing > Common > Catalogs > Vendor catalogs.
• Create a new record.
• Select the vendor in the vendor field.

You can enable/disable the catalog for auto approval by clicking the corresponding button in the action pane. This flag can be used to setup workflow automatic actions.

 

Create a sample catalog maintenance request (CMR) file

CMR file is an XML file which contains the information about the products which are available for purchase from the vendor. You can use the CMR file to create a new catalog, replace an existing catalog, or modify an existing catalog. In order to create a sample CMR file you need to generate a catalog import file template first.

 

Generate a catalog import file template

The catalog import file template is an industry-standard XSD file that you use to create a CMR file for vendor’s products. In order to create the XSD file you need to:

• Click Procurement and sourcing > Common > Catalogs > Vendor catalogs.
• On the Vendor catalogs list page, double-click the catalog that you want to work with.
• To download a current catalog import template (XSD file), in the Update catalog form, on the Action Pane, on the Catalogs tab, in the Related information group, click Generate catalog template.

 

Generate a catalog import file template

Select one of the following options:

Procurement category – Generate a catalog template that includes the procurement categories in which the vendor is authorized to provide products.

Commodity code – Generate a catalog template that includes industry-standard commodity codes.

In the Save as dialog box, select the location where you want to store the catalog file template and save the file.

 

Generate a sample CMR file

One thing to note about the catalog import template XSD file is that for each procurement category where the vendor is approved there will be a separate product definition with a separate set of attributes so it is important to use the current version of the XSD file for producing the sample CMR file. In order to create a sample CMR file you can:

• Open the XSD file in Visual Studio.
• Go to the Schema explorer view.
• Right click the VendorCatalog node.
• Click the Generate sample XML item.

Modify the auto-generated contents with the valid data: vendor name, product name, price and other attributes.

Some of the attributes like product name can be filled with any string value. Other attributes (like currency) will only accept a fixed set of values which can be found by navigating the XSD file.

 

 

Upload the CMR file using AX Windows client

Having generated the sample CMR file you can proceed with the import.

Click Procurement and sourcing > Common > Catalogs > Vendor catalogs.

On the Vendor catalogs list page, double-click the catalog that you want to work with.

In the Update catalog form, on the Catalog file history tab, click Upload file.

In the Upload file dialog box, browse to the location of the CMR file that you created.

Enter an effective date and an expiration date. These dates define the date range in which the pricing for the products in the CMR file is valid.

Select one of the following update types for the CMR file:

• Add updates to the existing vendor catalog
• Replace the existing vendor catalog with a new catalog

Click OK to start the upload process for the CMR file.

To view the details about the processing status of the CMR file, on the Catalog file history tab, click Event log.

In the Event log form, the status of the CMR file is updated as the file is processed. The status of the catalog import will be ”New” (unless an error occurred).

A new XML file will be placed in the catalog import pickup folder. This file is a WSDL message for the CatImpService.create service for which a file adapter-based inbound integration port has been set up previously. This message contains all the information from the CMR file that we just uploaded plus the WSDL ”envelope”.

 

Process the CMR file

After the WSDL message has been placed in the catalog import pickup folder the catalog import service needs to be called. The service will copy the data from the CMR file to the vendor catalog staging tables.

Click “Enable automated approval” button under maintain action pane in Vendor catalog form.

Run the AIF vendor catalog import processing job which has been setup previously.

After you do that the status of the catalog import will change to ”In progress”.

 

 

Submit the catalog import

In this example we will assume that the workflow has been set up for manual approval, i.e. there are no automated actions setup in the Catalog import product approval workflow.

• After the status of the catalog has changed to ”In progress” the workflow bar will appear in the top of the Vendor Catalog form.
• Click the submit button.
• Refresh the Vendor Catalog form.

 

 

Approve the catalog import

• The status of the catalog import has changed to ”Pending approval”.
• Click the Details button on the Catalog file history fast tab.
• Select all products and click the Actions > Approve button in the workflow bar. If automated action has been setup in the workflow then Approval will not be required.
• The status of the products has changed to ”Approved”.

• Go back to the Vendor Catalog form.
• The status of the import has changed to ”Succeeded”.
• After the imported product candidates have been approved they are added to the product master.
• After the product candidates have been approved they can be released to legal entities by clicking the Release approved products button on the Vendor Catalog form.

 

 

 

 

Catalog import through VSS

Create an AX user for the vendor party

First of all you need to associate an AX user with the vendor account.

1. Go to System administration > Common > Users > Users.
2. Grant the user that you want to associate with the vendor the Vendor (external) role.
3. Click the Relations button in the action pane.
4. Set the Relation type = Vendor and select the vendor which you want to enable for uploading catalogs using the Vendor portal.

 

Configure the user profiles

After setting up the user-vendor association you can proceed with opening the Vendor portal and uploading the CMR file.

1. Go to System administration > Common > Users > Users.

1. Select the user that you have configured to represent the vendor party.

1. Click the profiles button. Click the view role centers button.

1. In the enterprise portal make sure that the correct user is active (if not click the login as a different user button and login as the user which has been configured to represent the vendor party).

 

Login to enterprise portal

If you logged on as an admin or have multiple vendors associated with your account then make sure that the correct vendor association is active. The current vendor association can be changed by clicking the vendor dropdown box in the top right corner of the screen.

 

 

Create Vendor catalog

 

 

Generate catalog template

 

 

Upload xml file of Vendor Catalog

 

 

 

Process the CMR file

After the WSDL message has been placed in the catalog import pickup folder the catalog import service needs to be called. The service will copy the data from the CMR file to the vendor catalog staging tables.

Click “Enable automated approval” button under maintain action pane in Vendor catalog form from AX client.

Run the AIF vendor catalog import processing job which has been setup previously.

After you do that the status of the catalog import will change to ”In progress”.

 

 

Submit the catalog import

In this example we will assume that the workflow has been set up for manual approval, i.e. there are no automated actions setup in the Catalog import product approval workflow. This process needs to be done from AX client only.

• After the status of the catalog has changed to ”In progress” the workflow bar will appear in the top of the Vendor Catalog form.
• Click the submit button.
• Refresh the Vendor Catalog form.

 

 

Approve the catalog import

• The status of the catalog import has changed to ”Pending approval”.
• Click the Details button on the Catalog file history fast tab.
• Select all products and click the Actions > Approve button in the workflow bar. If automated action has been setup in the workflow then Approval will not be required.
• The status of the products has changed to ”Approved”.

 

 

Release the catalog import product

 

• Go back to the Vendor Catalog form.
  

 

• The status of the import has changed to ”Succeeded”.
• After the imported product candidates have been approved they are added to the product master.
• After the product candidates have been approved they can be released to legal entities by clicking the Release approved products button under Maintain action pane on the Vendor Catalog form. This step can only be done from AX client.

 

 

Vendor imported product