Microsoft Dynamics AX 2012 - A Dive into Document Services

Recently I wrote about Microsoft Dynamics AX 2012 and a Dive into services. This article focused specifically on the different types of services that exists now with Microsoft Dynamics AX 2012 and what their intended uses are.

I followed that post up, with a Dive into System Services; Metadata Service, where I showed how the Metadata service could be called, and made use of from example C# code. Now today I want to continue that dive, and focus on Document Services.

As I wrote previously, and based on Microsoft recomendations, Document Services should be used for any complex CRUD operations. This means, any Create, Read, Update or Delete operations that are needed on any dataset within Microsoft Dynamics AX 2012, that is beyond simple data contract needs.

Document Services are not new actually for AX, however in this release they are improved greatly, and the ability to create document services, and get them up and running fast, is what's going to make all the diference in the world, from a development stand point. Beyond that, to administrate them, and in speed in which these now operate has been greatly improved, along with removing size limits for messages coming through the AIF Document Services.

So Lets get started and dive right into creating a Document Service. In order to do that, we will need a project, and to keep things straight forward, lets create a custom table, with two fields in it. Call this idbTestTable, and create two string fields, called IDB1 and IDB2.



Now that we have our custom table, lets move to create a new Query object that wraps this custom table. The major things about this query object, is once we have it created, and drag our table over to be it's datasource.



Now we can take and click on the properties of that datasource, and make sure the property of Update is set to Yes. What this will allow is our create, update & delete operations, to work through this query object.



Now that we have that set, lets move forward to the fields, and on the properties of the fields node itself, make sure and change the Property Dynamics to Yes.



What this does, is takes and when we add a field, the Query object will be updated automatically for us, making it to where we do not need to come touch every query that maybe referencing our table here, to make sure the fields are added for use.

There could be a case to where you don't want this to take place, but for now, lets set this anyway.

Since we have our Query Object, we can now take and right click on it, and click on the "AIF Document Service Wizard".



From here we want to make sure and enter our service name, and description, as well as make sure and check the operations we want, which cover our CRUD operations. The Find and FindKeys, we will cover in a later post.





Now that we have this, lets click OK, and see that Microsoft Dynamics AX creates us some classes, and a private project.



Lets move the objects of that Private Project into our project we already have going. Make sure everything compiles, and move to our next step, which is creating our service group. We will need a new ServceGroup, Group in our project, so lets create that, and then create our idbServiceGroup under it. After doing that, simply drag and drop the service node under it, as seen below.



Now that we have this simply right click on the service group, and left click on deploy.



We should seen an info log messages, that look similar to the following. Make sure there were no errors, and we are now ready to make use of the service.



Now that we have our service, lets take and consume that as a service reference from a VS2010, Windows Form Project. Simply go to the project, add a new service reference. Keep in mind the format is http://server:port/DynamicsAX/Services/idbServiceGroup. This will render the WSDL, and be used to generate our reference and proxy objects for us. You should have now a service reference that looks like the following in your project.



Now lets take and add a button to our Windows Form, and within the code of the button, lets add the needed C# to take and

call the service and add a record to our custom table through this document service. Your code should look similar to the following.



So here, I'm working with the Entity object that represents my service as well as my data contract, that enables me to fill, with possible multiple records, for our idbTest table. Then simply, I open the client, call the create, with a null context (more on that in a later post), and bang! We have records in our table in AX, through the use of Document services!



Just to show off the power of this, the same service can be called from within X++ code, to create records as well. I want get into all the details of this, however you will notice the use of the AfStronglyTypeDataContainerList object being used, as well as the use of the Marco that was generated for us by the Document Services Wizard. (More on this kind of example in a later post).

There are several new complex data structures in Microsoft Dynamics AX 2012, and the best way to interact with these, within AX or outside is going to be through these document services. I realize that this in itself, for people that have been working with AX for a while, is a new concept. However this is the desired goal of such services, in that business logic make use of them, specifically custom business logic.

One of the area's is around the new EcoResProduct, or Product Information Management data ( PIM / PDM ). Even within X++ because EcoResProduct is an abstract table, you don't ever work directly with that object. It's better to work with the abstracted way of making use of Document Services.

Now there will be times, when you need to still perform X++ SQL statements (XppSQL). So, you have to use your brain, to help let context, as usual, drive what your doing. However, if your creating products for example, within AX or outside of AX, it's Highly recommended the new EcoResProductService be made use of to achieve this process. Also mixing this with the InventItemService, and a few others to release products to a given legal entity for use.

A great write up was done recently by someone from the Microsoft team that talks you through exactly this process, from C#. You can find that write up here.: Product-item data management services

Now keep in mind, this same process can be done within X++, and AX internally as well. This changes how we think about importing and creating Master data in general with AX project, and it's very important to understand.

Well that's all for now, but check back soon as more to come! Till next time!



"Visit the Dynamics AX Community Page today!"