Chapter 3. AIF Document Services
When we think of services, we typically think about exposing business logic or consuming it. In many cases though, it's business data that needs to be exchanged. With Microsoft Dynamics AX 2012, the preferred method of exchanging business entities is by using document services.
In this chapter, we will discuss the AIF document services and learn about the components that make up a document service. By the end of this chapter, you will be able to create, deploy, and consume such a service.
The following topics are covered in this chapter:
What are document services?: We start by explaining why you would need document services in Microsoft Dynamics AX 2012.
Key components: There are some components that are specific to document services. It's important to know what these components are and what their role is in the concept of services, so we will discuss their function in detail.
Creating a document service: You will learn how to create a document service and how...
What are document services?
If you've worked with Microsoft Dynamics AX for a while, you will know that it contains many tables with a lot of data. These tables can be related to each other to form logical entities such as sales orders. Tables not only contain fields, indexes, and relations, but they also contain code that handles initialization, validation, and manipulation of data. When you send data from Microsoft Dynamics AX but especially when you receive data from external systems, you want all of the business logic that is contained in these tables and entities to be executed for data to be consistent. It would be troublesome to have to code all of this yourself when creating a service. Fortunately, AIF solves this by providing a framework and the tools to create these services.
So what are these tools and components? That's exactly what we will discuss next.
We will start by looking at the framework and its components. The key components of a document service are:
A query that is used in the AIF Document Service Wizard to create the document service
A document class that represents a business entity and contains the business logic for this entity
One or more AxBC classes that encapsulate a table and are used by the document class to create, modify, and delete data in tables
A service class that contains the service operations
Of course, there's more to these components than the few words we've used here to describe them. We will now look at these components one by one, starting with the query.
Each document service is based on a query defined in the AOT. By using the AIF Document Service Wizard, a document class is generated and XML schema definitions used for XML serialization are derived from the corresponding query. So the XML message will have a correlation to the query object. In the following screenshot, we can see...
Creating a document service
As you've read, there are a lot of components that have to be created when developing a document service. You might think that creating a document service is a daunting task because of that, but fortunately that is not the case.
Microsoft has provided us with the AIF Document Service Wizard
. This wizard allows you to create a document service fairly quickly based on a query you provide. In the next few pages, we will walk through all of the steps needed to create a document service using this wizard.
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
The document service we will build in this chapter will allow us to demonstrate all of the service operations that are available on a document service. We will need an entity...
Updating an existing document service
In some cases you will want to update an existing document service. For example, when you have added a data source to an existing document query, or when you want to add a service operation to an existing document service. To assist you with that, you can use the Update document service form.
To open this form, open the Development Workspace and click on Tools | Application Integration Framework | Update document service:
Adding service operations
As you can see in the previous screenshot, you can select new operations to add to the document service. Click on OK to add the selected service operations to the document service. This will update the document and service classes so that the new operations are supported.
The only thing left for the developer to do is to manually add the service operation to the service node. To do this, go to the Services node in the AOT, expand the node of the service that was updated, then right-click on the Operations node...
Deploying a document service
The development phase of the document service is complete, so now it is ready to be deployed. We need an enhanced integration port for this service because we will demonstrate how to use the getKeys and getChangedKeys operations. These operations require that document filters are enabled, a feature that is only available on enhanced ports.
The steps that need to be performed to create an enhanced port have already been described in Chapter 2, Service Architecture and Deployment. Look for the section on Enhanced ports and follow the steps in it to create one. Make sure the Port name field is set to CVRDocumentServicesEnhanced and that all of the service operations of the CVRTitleDocumentService service are added to the exposed service operations.
Consuming a document service
Let's head to Visual Studio and start consuming the document service that we created. You can open the Visual Studio project for this chapter, which is included in the code files for the book, to see the service in action.
If you are a more experienced Visual Studio user, you can create a project yourself. In Visual Studio, create a project for a console application by going to File | New | Project…. In the Installed Templates section, select Visual C# | Windows. Choose a project of type Console Application, insert a name and location for the project, and click on OK.
To add the service reference, in the Solution Explorer right-click on the Service References node of your project and click on Add Service Reference…. Enter the WSDL location in the address field and click on Go. Of course, you'll need to replace DYNAX01:8101 with the server and port of your installation. You should see a form similar to the following screenshot. Enter TitleServiceRef in the Namespace...
Asynchronous communication
So far in this chapter we have focused on synchronous communication using the NetTcp adapter. The file system adapter and the MSMQ adapter work asynchronously and differently to synchronous adapters.
Asynchronous adapters use two tables to store messages:
AifGatewayQueue: The AifGatewayQueue table is used in asynchronous processing of both inbound and outbound messages. Inbound messages are stored in this table after they are retrieved by the gateway receive service. Outbound messages are stored in this table after they are processed by the outbound processing service.
AifOutboundProcessingQueue: The
AifOutboundProcessingQueue table is used by the send service framework to store requests for outbound messages. These requests are then processed by the outbound processing service that stores a message in the AifGatewayQueue table.
The following flowchart displays the relationship between the tables and the classes that are used for asynchronous communication:
In this chapter we created our first document service in Microsoft Dynamics AX 2012. Document services distinguish themselves from other types of services because they can be created using a wizard. This wizard creates components that are specific to document services and uses them in AIF.
In doing this, the AIF Document Service Wizard allows developers to create services that are capable of CRUD (Create, Read, Update, Delete) operations on complex documents. The advantage of using document services operations over other solutions such as creating data using SQL statements is that the business logic that is contained in all of the components that make up the service are also executed, such as defaulting and validation of values.
Document services are great for exposing documents, but not so much for exposing pure business logic. In the next chapter, we will discuss a type of service that is ideal for this purpose: custom services.
