Consuming "CustomerService" Web Service
Version: Dynamics AX 4 SP2.
In Dynamics AX 4 SP2, basic framework support for update and delete functionality has been added to the pre-existing framework support for create, read and find functionality. This blog illustrates how the pre-existing functionality as well as the new update and delete functionality can be consumed from a sample C# web service client. The same functionality is accessible through any other transport supported by AIF, including the BizTalk adapter, the MSMQ adapter and the file system adapter.
The samples below use the Axd class AxdCustomer, which ships as part of Dynamics AX 4 SP2 and provides update and delete functionality out of the box. [For a full program sample see attachment "CustomerServiceTest.cs".]
0. Disclaimer
· All code used below is meant for illustration purposes only and not intended for use in production. The following disclaimer applied to all code used in this blog:
Copyright (c) Microsoft Corporation. All rights reserved. THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR WITHOUT MODIFICATION, IS HEREBY PERMITTED.
1. Prerequisites
· Install and configure Dynamics AX 4 SP2
· Install and configure AIF Web Services according to AIF documentation; this includes:
o IIS configuration (to host generated AIF web services)
o Configuration of AIF web site (AIF form "Web sites")
o Etc.
As a result of this configuration it must be possible to generate and deploy Dynamics AX web services.
2. Configure & Generate AIF Web Service "CustomerService"
· In the table on the “Action” form (Basic -> Setup -> Application Integration Framework -> Action), check “Enabled” and “Web Method Enabled” in the rows for the following actions:
o createListCustomer
o readListCustomer
o deleteListCustomer
· On the “Action” form, click “Generate” to generate web service(s)
· Verify that the WSDL for CustomerService is available (e.g. https://<host>:<port>/DynamicsWebService/CustomerService.asmx?wsdl; for details see AIF documentation)
3. Configure Additional AIF Parameters
· Create Local Endpoint "Contoso" (Basic -> Setup -> Application Integration Framework -> Local Endpoints)
· Create and configure Endpoint "NorthwindTraders" (Basic -> Setup -> Application Integration Framework -> Endpoints)
o Settings (for details and additional options for endpoint configuration see AIF documentation):
§ Name: “Nortwind Traders”
§ Constraints: No constraints
§ User: Valid Dynamics AX user
§ Local Endpoint: "Contoso"
o Save and activate Endpoint “NorthwindTraders”
o Configure action policies (enable createListCustomer, readListCustomer, deleteListCustomer)
o Configure data policies for these three actions (allow all data fields: Set -> Enable All)
4. Create Sample C# Web Service Client (Visual Studio 2005)
· Open Visual Studio 2005
· Create project “WebServiceTests” (console application)
· Add web reference to CustomerService to project (use URL for CustomerService WSDL, see above)
· Implement code to exercise customer service API (adjust names to actual names):
o Use code similar to the following snippet to create customer service proxy:
// assumes namespace “WebServiceTests”
using WebServiceTests.CustomerService;
...
CustomerService.CustomerService service =
new CustomerService.CustomerService();
if (null == this.service) {
throw new Exception(
"Cannot instantiate service.");
}
service.UseDefaultCredentials = true;
o Use code similar to the following snippet to a create customer (this has not changed in Dynamics AX 4 SP2).
AxdCustomer customer = new AxdCustomer();
// create & populate customer record (w/demo data)
customer.CustTable = new AxdEntity_CustTable[1];
customer.CustTable[0] = new AxdEntity_CustTable();
customer.CustTable[0].CustGroup = "40";
customer.CustTable[0].Name = "Customer";
// consume AX web service to create customer
EntityKey[] entityKey = null;
entityKey = service.createListCustomer(
getDocumentContext(), customer);
o Use code similar to the following snippet to read the newly created customer record (this has not changed in Dynamics AX 4 SP2):
customer = service.readListCustomer(
getDocumentContext(), entityKey);
o Use code similar to the following snippet to update name and zip code of the newly created customer record (this is new functionality, introduced on Dynamics AX 4 SP2).
Notes:
§ In Dynamics AX 4.0 SP2, create actions can be overloaded with update functionality; in other words, create and createList actions can be used to update existing records. Explicit update actions are not generated by the Axd wizard nor are they shipped as part of any Dynamics AX 4.0 Axd classes out of the box. For Axd classes that ship out of the box, create and createList actions are used to implement update functionality instead (where updates are supported).
§ Update actions are implemented with document-centric service semantics; they assume the “whole documents” to be submitted as part of update requests – in the sample these documents are customer documents. Fields that are not set in the document will be reset in Dynamics AX to the equivalent of the “null” value for the respective type. If this is not desirable, it is recommended to read the whole document before updating it. Also note that the definition of a “whole document” depends on the respective endpoint that submits the document as part of an update request. Fields that the endpoint is not allowed to send as part of the update request (as per data policy definition), need not/cannot be sent as part of update requests. Thus, it is further recommended to synchronize the data policies for read and update (i.e. create) actions.
// modify customer name: append name with “X”
customer.CustTable[0].Name += "X";
// set customer zip code (using demo data)
customer.CustTable[0].ZipCode = "DK-3600";
// apply changes
service.***createList***Customer(getDocumentContext(),
customer);
o Use code similar to the following snippet to delete the newly created customer record (this is new functionality, introduced on Dynamics AX 4 SP2).
service.deleteListCustomer(getDocumentContext(),
entityKey);
5. Try it out...
Comments
- Anonymous
April 28, 2008
mmerz would it be possible to start up a conversation with yourself (and the rest of the community if anyone else is interested) regarding the use of the BizTalk Adapter for AIF in comparison to communicating through AIF Web Services and the pros and cons of each? On our current project we are just trying to define the best approach for communicating with Dynamics AX 4.0 SP2 through AIF and I can't seem to find any legitimate Microsoft best practie for which approach to take or any BizTalk adapter documentation in general.Many Thanks,Lloyd - Anonymous
November 17, 2009
The comment has been removed