Service deployment
Microsoft Dynamics AX 2012 does a lot to simplify service deployment; not so much by reducing the number of concepts, but by gradually presenting these concepts to users when needed. This is immediately obvious when you look at the setup menu for services and AIF. When you navigate to System administration | Setup | Services and Application Integration Framework, you only see four options. The first two are the most important: inbound ports and outbound ports. These two types of ports are known as integration ports.
Integration ports provide a way to group services and manage them together. They have at least the following properties:
- One or more service operations
- A direction that is inbound or outbound
- A category that is either basic or enhanced
- An adapter
- The address of the port
We will discuss these properties and others in detail.
Service operations
An integration port contains one or more service operations. These must be operations from services that all have the same type. This means that you shouldn't mix operations from document services and custom services because this can cause problems with the WSDL generation.
Inbound versus outbound ports
Integration ports can be thought of as destinations for messages. Services within these ports either receive messages from external applications or send messages to them. This gives them a direction. Microsoft Dynamics AX 2012 arranges integration ports based on this direction into inbound and outbound ports.
Inbound ports are identified as integration ports that receive messages that originate outside of Microsoft Dynamics AX 2012. In other words, the destination for the message is Microsoft Dynamics AX 2012. One example of when to use an inbound port (discussed later in this book) is when we create a WCF service and consume it in a .NET application.
An outbound port is a destination for a message that originates from inside Microsoft Dynamics AX. In other words, it is used when you want to send a message to an external application based on an action in Microsoft Dynamics AX 2012. You can use outbound ports with asynchronous adapters such as the MSMQ and filesystem adapter.
Basic versus enhanced ports
Integration ports can exist in two categories: basic and enhanced. Outbound ports are always enhanced ports. Inbound ports can be either basic or enhanced.
Basic ports can only be created by developers because they are linked to a service group. They are created in the Service Groups node in the Application Object Tree (AOT). Services are added to the group, and after the service group has been deployed, a basic integration port is created, which exposes all of the service operations from the group. All basic ports are inbound ports that are hosted on the AOS and use the NetTcp adapter. The WCF configuration editor allows you to change the WCF options; but apart from that, there are few options you can set up. Although this makes basic ports somewhat limited in their functionality, it has the advantage of getting your services up and running in no time.
There are a number of services that come with Microsoft Dynamics AX 2012 that are deployed by default. You can find these in the Inbound Ports form.
If you were to press the New button in the Inbound Ports form, you would not create a basic port, but an enhanced port. To create a basic port, we will have to open a developer workspace and perform the following steps:
- Open the AOT.
- Go to the Service Groups node, right-click on it, and click on New Service Group.
- A new service group will be created. Right-click on it and select Properties.
- In the Properties screen, change the name to
SRVTestBasicServiceGroup. - In the Description property, you can specify a meaningful label. This won't show up anywhere, so this is not mandatory.
- Next, right-click on the service group and then click on New Service Node Reference.
- In the Properties screen, click on the Service property and select a service you want to deploy from the list.
- Click on Save All in the AOT to save your changes.
- To deploy the service group, right-click on the service group and then click on Deploy Service Group.
After a few moments, you will see an Infolog message letting you know that all service artifacts have been generated and that your service group is deployed and activated. Your service is now visible in the Inbound ports form and is ready to be consumed.
As the name suggests, enhanced ports provide more options than basic ports. Unlike basic ports, they are not tied to service groups, but can be created in the Inbound Ports and Outbound Ports forms. Before we take a look at the options that are available on enhanced ports, let us first create an enhanced port.
Almost all options that are available on outbound ports are available on inbound ports too. Inbound ports have more options, so for this demonstration, we will create an inbound port.
Before we create the port, we need to ensure that all services are registered within the system. Registering services will insert a record in the AifService table for each service and insert a record in the AifAction table for each service operation. These records are then used to populate lookups and lists on the forms while setting up services.
To register services, perform the following steps:
- Navigate to System administration | Setup | Checklists | Initialization checklist.
- Expand the Initialize system section.
- Click on Set up Application Integration Framework to register services and adapters.
You should register services if you are using AIF for the first time or if you've added new services or service operations in the AOT. This process will also register all adapters and basic ports.
Now, to create an enhanced inbound port, let's perform the following steps:
- Navigate to System administration | Setup | Services and Application Integration Framework | Inbound ports.
- Click on the New button or press Ctrl + N to create a new enhanced port.
- In the Port name field, enter
SRVTestEnhancedInboundPort. - Enter a description in the Description field so that you can easily identify the port later.
- On the Service contract customizations FastTab, click on Service operations. The Select service operations form opens.
- From the Remaining service operations list, select the DocumentHandlingService.create operation and click on the arrow pointing to the left to add this operation to the Selected service operations list.
- Close the form.
- Click on the Activate button to deploy the port.
Your enhanced port is now successfully created and activated. You cannot modify the configuration of activated ports. To modify the configuration, first deactivate the port by clicking on the Deactivate button.
Now that we've created an enhanced port, let's look at the options that are available on the form.
While basic ports only support the NetTcp adapter, enhanced ports allow you to specify which adapter you want to use. There are three WCF adapters to choose from: the NetTcp, HTTP, and MSMQ adapters. To exchange messages using filesystem directories, the filesystem adapter is also available. We will go into more detail about these adapters later in this chapter.
With enhanced ports, you can manually select which service operations are to be exposed. This is unlike basic ports, where all service operations of the services within the service group are exposed.
For custom services, the developer defines the parameters that are exposed in the data contract. This is reflected in WSDL when the data contract is used to generate the XSD schema for the type definition. The only way to change this schema is by changing the data contract in the code.
While exposing document services, you can change the schema that is generated using data policies. Enabling or disabling fields in the data policies will add or remove fields in the schema, allowing you to manage which fields are exposed or not. It is also possible to mark fields as required.
Transforms allow you to transform inbound and outbound messages that are exchanged asynchronously. This transformation applies to the complete message, including the headers. For inbound exchanges, the transforms are applied before the message is stored in the gateway queue. For outbound exchanges, transforms are applied after the message has been fetched from the gateway queue. The following are the two types of transforms that are available:
- XSL: You can use Extensible Stylesheet Language Transformations (XSLT) to transform any XML-based document to an XML document that uses the AIF schema or vice versa.
- .NET assembly: When a document is not based on XML, for example, a text file with comma-separated values (CSV), you can use a .NET assembly to convert the file into an XML message that complies with the AIF schema. This assembly is a DLL that contains a class that implements the
ITransforminterface and contains the code that transforms the message.
Pipelines are a lot like transforms, but there are a few differences. They allow you to transform contents of the message instead of the full message and can be used for both synchronous and asynchronous exchanges. They are also run before or after the transforms, depending on the direction. The following table explains the difference between transforms and pipelines:
There are two types of pipelines available; these are as follows:
- XSL: This is similar to transforms that use XSL, except that the XSL is only applied to the body of the message.
- Value substitution: The value substitution pipeline component allows you to replace one value with another based on a simple lookup table. For example, when messages are sent to a vendor, you can replace your currency code with the currency code of your vendor; for example, EUR versus EURO. When the direction is inbound, you can substitute in the opposite manner. The value substitution is based on Extended Data Types (EDTs). A value substitution map must be created, which contains a mapping between the internal and external value for a specific EDT. These maps are set up in the following form: System administration | Setup | Services and Application Integration Framework | Value substitution maps.
You can easily create your own pipeline components by creating an X++ class that implements the AifPipelineComponentInterface interface.
Value mapping is similar to the value substitution pipelines, but it differs by allowing you to substitute values based on business rules. For example, you can replace your item ID with the item number that is used by a vendor.
Document filters can be used to filter the keys that are returned while calling the service operations getKeys and getChangedKeys based on the query you provide. These filters will only be applied when change tracking is activated. There's more about this when we create a document service.
On the troubleshooting FastTab, you can enable logging for messages. When activated, the following three options are available:
- Original document: When selected, only the original document before modification by pipeline components is stored
- All document versions: When selected, a version of the document is stored every time a document is modified by a pipeline component
- Message header only: When selected, only the headers of the documents are stored
To consult the log, navigate to System administration | Periodic | Services and Application Integration Framework | History.
There is also the option to provide more information about exceptions in AIF faults and the ability to send error messages for asynchronous requests.
On the security FastTab, you can limit integration ports to only process requests for specific companies instead of for all companies. Access can also be configured to allow access only for certain users and user groups. For added security, be sure to set these options as strict as possible.