Troubleshoot services and AIF [AX 2012]
Updated: February 1, 2013
Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
This topic describes how to troubleshoot common issues with document exchanges through the Application Integration Framework (AIF).
When you install web services on Internet Information Services (IIS), a record for the new website is added to AifWebsites table. If you uninstall web services on IIS, this record is not deleted from the table. This record may cause a warning to be displayed if you reinstall web services on IIS. You can manually delete the record from the AifWebsites table or simply ignore the warning.
You might encounter this error message when you change the Application Object Server (AOS) account. For information about resolving this issue in several different configurations, see Change the account used by AOS.
You must set the appropriate permissions for any new virtual directory in IIS so that Microsoft Dynamics AX can access the file share. The group that is named Microsoft Dynamics AX Web Service Administrators must have full access to the new virtual directory and file share. If this group does not exist as a local group on the computer, you must create it. You must then add, as a user, the domain account for all AOS instances that require access.
Directories that are accessed by the file system adapter must grant appropriate access to the domain account under which the AOS runs. If the AOS runs under the NETWORK SERVICE account, you must grant permissions for that specific account. For example, granting full permissions to Everyone will not enable the file system adapter to access the files in the directory or network share accessed by the file system adapter if the AOS runs under the NETWORK SERVICE account.
We strongly recommend that you use a domain account or a managed service account in a production environment. Use the Network Service account only in development and testing environments. See Create service accounts.
Document filters are applied only to documents that have been configured for change tracking. Change tracking must be enabled for the database tables that the document service uses. For more information about how to enable change tracking, see Configuring and Managing Change Tracking.
To use this service operation, you must create at least one document filter. See Configure processing options.
You can receive this error message when the timeout value specified in the Windows Communication Foundation (WCF) configuration is exceeded. To correct this problem, do not leave WCF connections open once you are finished using them. For example, be sure to call the Close method on client instances before they go out of scope. For an example of how to create, use, and close a client object, see Walkthrough: Exchanging documents by using the NetTcp adapter.
If you continue to experience timeout errors, change the timeout settings in the WCF adapter configuration in the integration port configuration form.
If you delete a service from the Application Object Tree (AOT), and then you add the service back to the AOT, you must perform a full generation of the common intermediate language (CIL) for the Microsoft .NET Framework. Use the Generate Full CIL option on the Build menu in the development workspace. For more information, see X++ Compiled to .NET CIL.
The AIF Document Wizard adds operations to the Service node in the AOT only one time. For more information, see Creating New Document Services. If you update the service by using the Update document service form, you update the Service class but do not change any information under the Service node in the AOT. To make new service operations available, you must add them manually to the Service node. To open the Update document service form, open a development workspace, and then click Tools > Application Integration Framework > Update document service.
The RecVersion field is not retrieved for documents that contain views. If you set the CheckInvalidFieldAccess database configuration parameter when you test service operations on documents that contain views, the service operations stop, and generate a stack trace or other errors. Therefore, do not set CheckInvalidFieldAccess in a production environment. If document consumers require the RecVersion field to support business logic, you can define a new field in your document that is named myRecVersion. You can then map the myRecVersion field to the RecVersion field of one of the underlying tables in the view. For more information, see Tables Overview and View Overview.
If services that use different serializers, such as XmlSerializer and DataContractSerializer, are hosted on the same port, client proxies can be generated that have duplicate types. In Microsoft Dynamics AX, this situation can occur when service operations for document services and custom services are added to the same port. In this situation, duplicate types can be generated for some of the classes, such as CallContext.
To avoid this situation, always host service operations for custom services and document services on different ports. For more information, see Managing integration ports.
When you create tables that will be used in data exchanges, make sure that you use unique names for all fields and data sources. Otherwise, schema generation may fail. For example, if you create tables in a parent/child relationship, and a field in the parent table has the same name as a data source in the child table, schema generation fails, and you receive the following message in the Infolog:XSD schema contains errors. Multiple definition of element 'http://schemas.microsoft.com/dynamics/2008/01/documents/Query1Document:SubEntity2' causes the content model to become ambiguous. A content model must be formed such that during validation of an element information item sequence, the particle contained directly, indirectly or implicitly therein with which to attempt to validate each item in the sequence in turn can be uniquely determined without examining the content or attributes of that item, and without any information about the items in the remainder of the sequence.
HTTP is supported only in exchanges where Internet Information Services (IIS) is set up. If you use HTTP in an exchange that does not include IIS, AOS may stop, and you may receive an error message that resembles the following message:An error occurred while receiving the HTTP response to http://localhost-1:8101/DynamicsAx/Services/Endpoints/DocumentManagementService. This could be due to the service endpoint binding not using the HTTP protocol. This could also be due to an HTTP request context being aborted by the server (possibly due to the service shutting down). See server logs for more details.
For more information, see Install web services on IIS.
If you send an outbound message by using the MSMQ adapter, and the message cannot be delivered for any reason, it goes into the “dead letter queue.” No error log is displayed. To display messages for error conditions when you send messages from Microsoft Dynamics AX by using the Message Queuing transport, you must code the appropriate exception handling from WCF.
The AIF Document Service Wizard does not create an entry in the schema for table fields for which the Visible property is set to No, even if the Mandatory property for the fields is set to Yes. These fields, which should never be set by user input, are omitted from the schema. Table fields for which the Visible property is set to No are always set by code that runs in the service. This behavior resembles the behavior of the client. Code in the client sets table fields that are not visible in forms that enable user input.
If you try to access data for a company that does not exist on the AOS instance where the integration port for the service is located, you receive an error message. This situation can occur when you move from a development environment to a testing environment, or from testing to production, and different companies are used in each AOS configuration.
To create a service that works in a specific environment, you must create access to the client configuration for that environment in code, and load the company name to use. For more information, see Manage an AOS configuration.
This situation may occur when you use the Office Add-ins for Microsoft Dynamics AX together with Microsoft Dynamics AX services to import or export data. By default, the Office Add-ins use the local client configuration.
The following list shows valid syntax for this security attribute:
[SysEntryPointAttribute(true)] – Run the service operation by using the caller’s permissions.
[SysEntryPointAttribute(false)] – Run the service operation without any security restrictions.
If you deploy a port by using a service operation that does not specify SysEntryPointAttribute, you receive an error message that resembles the following message: “SysEntryPointAttribute must be specified on a method exposed as a service operation. Class: AifTestCustomerService, Method: createCustomer.”
You must specify SysEntryPointAttribute for any custom service that you write. The AIF Document Service Wizard adds this attribute to any new document service that you create.
If you create or update a field of type str by using a document service operation, and the incoming data string is longer than the field that is defined in the table, the data is truncated. In other words, the data is imported into the field, but any data past the limit for the string length is lost, and you do not receive an error message.
In outbound service operations for documents that are created from Microsoft Dynamics AX tables, AIF does not serialize fields that have null or 0 (zero) values. In other words, the fields do not appear in the outbound XML message. There are two ways to make sure that that a field is serialized:
In the code for the service operation, indicate that the field is required. The modified code affects both inbound and outbound transfers, but it does not affect the behavior of the field in forms.
In the table, set the Mandatory property for the field to Yes. Setting the property in the table affects all use of the field, both in forms and in document service operations.
To indicate that the field is required only for the service operation, you must override the AxdBase.initMandatoryFieldsMap method for the document service and declare the field as mandatory in the method. For more information and an example, see initMandatoryFieldsMap.
By setting the Mandatory property to Yes on the table field, you guarantee that the field is always included in the outbound transfer. This property also enforces the requirement that a non-default value be set for the field when the field is saved to the database. In other words, the field cannot be inserted into the database if the field does not have a valid value. For more information about how to set the Mandatory property on table fields, see Best Practices for Table Field Properties.