DynamicsAxSCM: Product-item data management services

[Blog bot]

Источник: http://blogs.msdn.com/b/dynamicsaxsc...-services.aspx
==============

Introduction

In this blog entry we will provide guidelines for the use of new and modified product-item data management services.

Product-item data management services

The following services have been created or modified in order to enable manipulation of product-item data. These services are AIF document services so they follow all the conventions applicable to the AIF document services:

Service

Purpose

EcoResProductService

Create products (all three types). The service can also be used to retrieve data that has already been created.

EcoResProductMasterDimValueService

Specify values of product dimensions for a product master. These values become available for the creation of product variants. The service can also be used to retrieve data that has already been created.

ItemService

Release distinct products and product masters. The service can also be used to retrieve data that has already been created.

InventDimCombinationService

Release product variants. The service can also be used to retrieve data that has already been created.

Setup of product services

Product-item services must be enabled on an AIF inbound port before they can be used. All services can be enabled on one port or several ports can be used.

An inbound port can be created in the Inbound ports form (System administration > Setup > Services and Application Integration Framework > Inbound ports). This article illustrates the creation of two ports:

• A port that uses a NetTcp adapter
• A port that uses a File system adapter.

A port that uses a NetTcp adapter can be used to access services programmatically; for example, from a C# application. A port that uses a File system adapter can be used when input data is in the format of an XML document. The following guidelines are based on the use of a default configuration of ports. Advanced configuration of ports is beyond the scope of this article.

Create a port that uses a NetTcp adapter

1. For a new port, specify name and adapter:





2. Click the Service operations button to specify the service operations that are going to be available on the port:



3. In the Select service operations form, select all the product-item service operations:



4. Click the Activate button in the action pane strip to activate the port.

When the port has been activated, a control appears which displays the URI of a WSDL document for the service. This value can then be used for adding a service reference in Visual Studio.



Create a port that uses File system adapter

1. Specify a port name, and from the list of adapters, select File system adapter:



2. In the URI field, specify a path to a folder for incoming XML documents that are to be picked up by the service:



3. Follow the guidelines in the previous procedure to specify the service operations that are going to be available on the port.

4. Click the Activate button in the action pane strip to activate the port.

Now you have two ports with product-item service operations available. Use the following guidelines to create and retrieve data.

Set up Visual Studio

In this article a C# console application project in Visual Studio is used. The only thing that is required here is to create a project and add a service reference for the services:



Create products

All types of products are created by using the EcoResProductService service. However, the methods to create a distinct product, a product master, and a product variant are different so each method is described separately.

Create a distinct product

To create a distinct product, use the EcoResProductService.create operation. First, create a product using C# code, and then create an XML document with data to create a product.

The following code creates a distinct product in Dynamics AX:

static void createDistinctProduct()
{
AxdEntity_Product_EcoResDistinctProduct distinctProduct = new AxdEntity_Product_EcoResDistinctProduct()
{
DisplayProductNumber = "Bulb60W",
ProductType = AxdEnum_EcoResProductType.Item,
SearchName = "Bulb60W"
};
distinctProduct.Translation = new AxdEntity_Translation[1];
distinctProduct.Translation[0] = new AxdEntity_Translation()
{
LanguageId = "en-us", Name = "Transparent Bulb 60W"
};
distinctProduct.Identifier = new AxdEntity_Identifier[1];
distinctProduct.Identifier[0] = new AxdEntity_Identifier()
{
ProductNumber = "Bulb60W"
};
distinctProduct.StorageDimGroup = new AxdEntity_StorageDimGroup[1];
distinctProduct.StorageDimGroup[0] = new AxdEntity_StorageDimGroup()
{
Product = "Bulb60W", StorageDimensionGroup = "Std-Dim"
};
distinctProduct.TrackingDimGroup = new AxdEntity_TrackingDimGroup[1];
distinctProduct.TrackingDimGroup[0] = new AxdEntity_TrackingDimGroup()
{
Product = "Bulb60W", TrackingDimensionGroup = "Std-Dim"
};

AxdEcoResProduct axdProduct = new AxdEcoResProduct()
{
Product = new AxdEntity_Product_EcoResProduct[1] { distinctProduct }
};

CallContext ctx = new CallContext();
EcoResProductServiceClient service = new EcoResProductServiceClient();
try
{
service.create(ctx, axdProduct);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

As it appears, the create operation accepts an array of products so it is possible to create multiple products in one call to the service.

The following XML code creates a distinct product. Note that storage and tracking dimension groups are specified. The storage and tracking dimension groups are not mandatory information to create a product so the C# code for the creation of a distinct product does not create these groups.

</span span style="color: #ff0000;"version/spanspan style="color: #0000ff;"="1.0"/span span style="color: #ff0000;"encoding/spanspan style="color: #0000ff;"="UTF-8"/span?span style="color: #0000ff;">


DMO
http://schemas.microsoft.com/dynamics/2008/01/services/EcoResProductService/create





Bulb40W
Bulb40W
Item

en-us
Transparent Bulb 40W


Bulb40W
Std-Dim


Bulb40W
Std-Dim


Bulb40W

The EcoResProduct element can contain multiple Product elements in order to create multiple products in one service call.

Create a product master and a related product variant

To create a product master, use the EcoResProductService.create operation. Then use the EcoResProductMasterDimValue.create operation to associate product dimension values with the product master. Finally, use the EcoResProductService.create operation again, this time to create a product variant.

The code to create a product master is basically similar to the code that creates a distinct product. One difference is the code that associates the product master with a product dimension group (in the following example: Size-Dim):

static void createMaster()
{
//master definition
AxdEntity_Product_EcoResProductMaster productMaster = new AxdEntity_Product_EcoResProductMaster()
{
DisplayProductNumber = "RunningShoe",
ProductType = AxdEnum_EcoResProductType.Item,
SearchName = "RunningShoe",
};
productMaster.Translation = new AxdEntity_Translation[1];
productMaster.Translation[0] = new AxdEntity_Translation()
{
LanguageId = "en-us", Name = "Comfortable running shoe"
};
productMaster.Identifier = new AxdEntity_Identifier[1];
productMaster.Identifier[0] = new AxdEntity_Identifier()
{
ProductNumber = "RunningShoe"
};

productMaster.ProductDimGroup = new AxdEntity_ProductDimGroup[1];
productMaster.ProductDimGroup[0] = new AxdEntity_ProductDimGroup()
{
Product = "RunningShoe", ProductDimensionGroup = "Size-Dim"
};
productMaster.VariantConfigurationTechnology = AxdEnum_EcoResVariantConfigurationTechnologyType.PredefinedVariants;

AxdEcoResProduct axdProduct = new AxdEcoResProduct()
{
Product = new AxdEntity_Product_EcoResProduct[1] { productMaster }
};

CallContext ctx = new CallContext();
EcoResProductServiceClient productService = new EcoResProductServiceClient();
try
{
productService.create(ctx, axdProduct);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

When the product master is created, associate two size dimension values with the product master (size L and M):

static void createMasterDimensions()
{
//master dimensions definition (two sizes, L and M)
AxdEntity_MasterDim_EcoResProductMasterSize sizeDimensionL = new AxdEntity_MasterDim_EcoResProductMasterSize()
{
SizeProductMaster = "RunningShoe",
Size = "L",
EcoResSize = new AxdEntity_EcoResSize[1]
{
new AxdEntity_EcoResSize() { Name = "L" }
}
};
AxdEntity_MasterDim_EcoResProductMasterSize sizeDimensionM = new AxdEntity_MasterDim_EcoResProductMasterSize()
{
SizeProductMaster = "RunningShoe",
Size = "M",
EcoResSize = new AxdEntity_EcoResSize[1]
{
new AxdEntity_EcoResSize() { Name = "M" }
}
};

AxdEcoResProductMasterDimValue axdDimValue = new AxdEcoResProductMasterDimValue()
{
MasterDim = new AxdEntity_MasterDim_EcoResProductMasterDimensionValue[2] { sizeDimensionL, sizeDimensionM }
};

CallContext ctx = new CallContext();
EcoResProductMasterDimValueServiceClient masterDimensionService = new EcoResProductMasterDimValueServiceClient();
try
{
masterDimensionService.create(ctx, axdDimValue);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

Create a product variant with the size L for the product master. One thing that may not be obvious is the value required for the ProductDimensionAttribute field of the AxdEntity_VariantDimValue_EcoResProductVariantConfiguration, the AxdEntity_VariantDimValue_EcoResProductVariantSize, and the AxdEntity_VariantDimValue_EcoResProductVariant entities. The value must correspond to the IDs of the EcoResConfiguration, the EcoResSize, and the EcoResColor tables, respectively.

static void createVariant()
{
//product variant definition
AxdEntity_Product_EcoResDistinctProductVariant productVariant = new AxdEntity_Product_EcoResDistinctProductVariant()
{
DisplayProductNumber = "RunningShoeL",
ProductType = AxdEnum_EcoResProductType.Item,
SearchName = "RunningShoeL",
ProductMaster = "RunningShoe"
};
productVariant.Translation = new AxdEntity_Translation[1];
productVariant.Translation[0] = new AxdEntity_Translation()
{
LanguageId = "en-us", Name = "Comfortable running shoe L size"
};
productVariant.VariantDimValue = new AxdEntity_VariantDimValue_EcoResProductVariantDimensionValue[1];
productVariant.VariantDimValue[0] = new AxdEntity_VariantDimValue_EcoResProductVariantSize()
{
DistinctProductVariant = "RunningShoeL",
ProductDimensionAttribute = 3173,//The ID of the EcoResSize table
Size = "L",
EcoResSize = new AxdEntity_EcoResSize1[1]
{
new AxdEntity_EcoResSize1() { Name = "L" }
}
};

AxdEcoResProduct axdProduct = new AxdEcoResProduct()
{
Product = new AxdEntity_Product_EcoResProduct[1] { productVariant }
};

CallContext ctx = new CallContext();
EcoResProductServiceClient productService = new EcoResProductServiceClient();
try
{
productService.create(ctx, axdProduct);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

The following XML code does almost the same thing. The only difference is that it creates a product master that is associated with a product dimension group where the Color dimension is active. At first, create a product master:

</span span style="color: #ff0000;"version/spanspan style="color: #0000ff;"="1.0"/span span style="color: #ff0000;"encoding/spanspan style="color: #0000ff;"="UTF-8"/span?span style="color: #0000ff;">


http://schemas.microsoft.com/dynamics/2008/01/services/EcoResProductService/create





BoardMarker
BoardMarker
Item

en-us
Whiteboard marker


BoardMarker
Col-Dim


BoardMarker

PredefinedVariants

Associate values of the Color dimension with the product master:

</span span style="color: #ff0000;"version/spanspan style="color: #0000ff;"="1.0"/span span style="color: #ff0000;"encoding/spanspan style="color: #0000ff;"="UTF-8"/span?span style="color: #0000ff;">


http://schemas.microsoft.com/dynamics/2008/01/services/EcoResProductMasterDimValueService/create





BoardMarker
Red

Red



BoardMarker
Blue

Blue

Create a product variant:

</span span style="color: #ff0000;"version/spanspan style="color: #0000ff;"="1.0"/span span style="color: #ff0000;"encoding/spanspan style="color: #0000ff;"="UTF-8"/span?span style="color: #0000ff;">


http://schemas.microsoft.com/dynamics/2008/01/services/EcoResProductService/create





BoardMarkerRed
BoardMarkerRed
Item

en-us
Whiteboard marker red


BoardMarkerRed

BoardMarker

BoardMarkerRed
3169
Red

Red

Release products

A product must be released to a company before it can be used in that company. The ItemService and InventDimCombinationService serve this purpose. The former can be used to release distinct products and product masters. The latter can be used to release product variants. A product master must be released before any of its product variants can be released.

Release a distinct product or a product master

The only information required to release a product to a company is the ID of the product and the ID by which it will be represented in the company (ItemId). It is possible to add information to the ItemService service. In the following example, information about units used for storage, purchasing, and selling is provided:

private static void releaseProduct()
{
AxdEntity_InventTable inventTable = new AxdEntity_InventTable()
{
ItemId = "Bulb60W",
Product = "Bulb60W",
Invent = new AxdEntity_Invent[1]
{
new AxdEntity_Invent()
{
ItemId = "Bulb60W", UnitId = "Box"
}
},
Purch = new AxdEntity_Purch[1]
{
new AxdEntity_Purch()
{
ItemId = "Bulb60W", UnitId = "Box"
}
},
Sales = new AxdEntity_Sales[1]
{
new AxdEntity_Sales()
{
ItemId = "Bulb60W", UnitId = "Pcs"
}
}
};

AxdItem item = new AxdItem()
{
InventTable = new AxdEntity_InventTable[1] { inventTable }
};

CallContext ctx = new CallContext() { Company = "DMO" };
ItemServiceClient itemService = new ItemServiceClient();
try
{
itemService.create(ctx, item);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

The following XML code releases a product master with the minimum amount of information required:

</span span style="color: #ff0000;"version/spanspan style="color: #0000ff;"="1.0"/span span style="color: #ff0000;"encoding/spanspan style="color: #0000ff;"="UTF-8"/span?span style="color: #0000ff;">


DMO
http://schemas.microsoft.com/dynamics/2008/01/services/ItemService/create





BoardMarker
BoardMarker

Release a product variant

A product variant can be released once a related product master has been released. When you release a product variant to a company, the product variant can be identified in two different ways.

• Use the product number of the product variant.
• Use the ID of the associated product master in the company (ItemId) and the InventDim structure with the relevant fields set to the dimension values for the variant (the ItemId/InventDim approach).

For details, see the following examples.

Use the product number of the product variant (DistinctProductVariant):

private static void releaseProductVariants()
{
AxdEntity_InventDimCombination releasedVariant = new AxdEntity_InventDimCombination()
{
DistinctProductVariant = "RunningShoeL",
ItemId = ""
};

AxdInventDimCombination inventDimCombination = new AxdInventDimCombination()
{
InventDimCombination = new AxdEntity_InventDimCombination[1] { releasedVariantL }
};

CallContext ctx = new CallContext() { Company = "DMO" };
InventDimCombinationServiceClient inventDimCombinationService = new InventDimCombinationServiceClient();
try
{
inventDimCombinationService.create(ctx, inventDimCombination);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

Use the ItemId/InventDim approach:

private static void releaseProductVariants()
{
AxdEntity_InventDimCombination releasedVariant = new AxdEntity_InventDimCombination()
{
DistinctProductVariant = "",
ItemId = "RunningShoe",
InventDim = new AxdEntity_InventDim[1]
{
new AxdEntity_InventDim()
{
InventSizeId = "M"
}
}
};

AxdInventDimCombination inventDimCombination = new AxdInventDimCombination()
{
InventDimCombination = new AxdEntity_InventDimCombination[2] { releasedVariantM }
};

CallContext ctx = new CallContext() { Company = "DMO" };
InventDimCombinationServiceClient inventDimCombinationService = new InventDimCombinationServiceClient();
try
{
inventDimCombinationService.create(ctx, inventDimCombination);
}
catch (Exception e)
{
System.Console.WriteLine(e.Message);
System.Console.ReadKey();
}
}

The following XML code releases two variants in one call and uses both approaches to identify a product variant:

</span span style="color: #ff0000;"version/spanspan style="color: #0000ff;"="1.0"/span span style="color: #ff0000;"encoding/spanspan style="color: #0000ff;"="UTF-8"/span?span style="color: #0000ff;">


DMO
http://schemas.microsoft.com/dynamics/2008/01/services/InventDimCombinationService/create





BoardMarkerRed




BoardMarker

Blue

Summary

We hope that this blog post will help developers to better understand and use the services for the new product-item data model.

More detailed information regarding the creation and release of products can be found in the Application user Help in the &ldquo;Product information management&rdquo; section.

Further developer information about AIF and services can be found on MSDN.

By Wojciech Bardzinski



Disclaimer

All the information about AX 2012 posted here is a pre-release. Any feature is a subject to be changed before the release without notice.
This disclaimer is applicable to all posts about AX 2012 in this blog.




Источник: http://blogs.msdn.com/b/dynamicsaxsc...-services.aspx