AIF upgrade process

  • Article
  • 14 minutes to read

Application Integration Framework (AIF) is the framework in Microsoft Dynamics AX that is used to exchange data with external systems. Code upgrade and data upgrade of AIF is part of upgrading to Dynamics AX 2009.

Before you upgrade

The message format has changed in Microsoft Dynamics AX 2009. Therefore, all AIF messages must be completely processed before you run the upgrade. Make sure that all messages have been processed from the following locations:

  • All inbound message locations such as file system directories, Message Queuing queues, or any location where AIF retrieves inbound messages.

  • The queue manager. All messages in the queue manager are unprocessed and must be deleted. To navigate to the queue manager, click Basic > Periodic > Application Integration Framework > Queue manager.

Code upgrade

The AIF code upgrade step upgrades existing Axd<Document> classes and methods. The upgrade process does not change any of the existing Axd<Document> classes but rather it creates corresponding services and artifacts. There are three types of classes that the code upgrade will process as shown in the following table.

Category

Description

Axd <Document> classes that ship with Microsoft Dynamics AX

Service classes and artifacts are generated for all Axd<Document> classes that ship with Microsoft Dynamics AX. If you have no custom classes or did not implement any custom actions, you do not need to take any further action. For more information about the standard services, see the Standard Axd<Document> classes section below.

Custom Axd<Document> classes

Service classes and artifacts are generated for all custom Axd<Document> classes. The results of the upgrade process differ depending on how these classes were coded. For more information about custom services, see the Custom Axd<Document> classes section below.

Custom classes that implement the AifServicable interface

The upgrade process generates a warning message but will not generate any service artifacts for these classes.

Standard Axd<Document> classes

Service classes and data objects are generated for each existing Axd<Document> class as shown in the following table (for the AxdSalesOrder class). The classes are found in the AOT by navigating to AOT > Classes. The AOT service node for each service is found by navigating to AOT > Services.

Generated artifact

Description

Example

Document class

The root data object.

SalesSalesOrder

Data objects

A data object class is created for each data source in the query. These objects are children of the document class.

SalesSalesOrder_SalesTable, SalesSalesOrder_DocuRefHeader, SalesSalesOrder_DocuRefLine, SalesSalesOrder_InventDim, SalesSalesOrder_MarkupTransHeader, SalesSalesOrder_MarkupTransLine, SalesSalesOrder_SalesLine

Service class

A service class is generated for each Axd<Document> class. For each action supported by the Axd<Document> class, an operation is created on the service class.

SalesSalesOrderService

AOT service node

An entry in the AOT Services node where you can view and modify the properties of the service and its operations.

SalesSalesOrderService

Action mapping for standard methods

Microsoft Dynamics AX 2009 supports a new set of actions, and the document services have operations that correspond to these actions. In some cases, the new actions have been designed to contain the functionality for two actions in the previous version.

Standard actions for the Axd<Document> classes that ship with Microsoft Dynamics AX will be upgraded as part of the code upgrade; no additional work is necessary. The following table lists the new actions and how actions from the previous version are mapped.

Previous version action

Mapped to service operation

createList

create

create

deleteList

delete

findList

find

findEntityKeyList

findKeys

readList

read

read

updateList

update

update

In Microsoft Dynamics AX 4.0, not all Axd<Document> classes that were included with the product supported all actions. If you customized a standard Axd<Document> class and enabled support of a standard action, the code upgrade adds a method to the service class with a name according to the following naming convention: action name + document class name.

For example, the AxdASN document class does not support the create action. If you added support for the create action to AxdASN, the code upgrade process adds a method called createASN to the new service class. You can find the action ID in the getActionList method of the Axd<Document> class. The following line of code in this method creates the full action name:

aifActionInfo.parmActionId(strfmt('%1%2',

methodstr(AxdBase, findEntityKeyList), this.getName()));

Action mapping for custom methods

If you have implemented custom actions on a standard Axd<Document> class, the code upgrade adds a method to the service class with a name according to the following naming convention: action name + document class name. For example, if you added a method called test to the AxdASN document class, the code upgrade process adds a method called testAxdASN to the new service class.

Custom Axd<Document> classes

Custom Axd<Document> classes are also upgraded during the AIF upgrade process. The services and artifacts that are generated are the same as those for the standard Axd<Document> classes as shown in the following table. However, the upgrade process will handle methods (actions) on custom document classes differently depending on how they were coded.

Generated artifact

Description

Example

Document class

The root data object.

Test

Data objects

A data object class is created for each data source in the query. These objects are children of the document class.

Test_Table1

Service class

A service class is generated for each Axd<Document> class. For each action supported by the Axd<Document> class, an operation is created on the service class.

TestService

AOT service node

An entry in the AOT Services node where you can view and modify the properties of the service and its operations.

TestService

Action mapping

Standard actions on a custom Axd<Document> class are mapped to the new actions supported in Microsoft Dynamics AX 2009 as shown in the following table. The new actions are implemented as methods in the service class.

Previous version action

Mapped to action

createList

create

deleteList

delete

findList

find

findEntityKeyList

findKeys

readList

read

updateList

update

If the actions create, read, update, or delete are supported by a custom Axd<Document> class, these actions are added to the new service class with the following naming convention: action name + document class name. For example, if you have a custom document class named AxdTest with an action called create, the upgrade process adds a operation called createAxdTest to the new service class.

If you have implemented a custom action on a custom Axd<Document> class, the upgrade process adds a method to the new service class with the following naming convention: action name + document class name. For example, if you have an Axd<Document> class named AxdTest and a custom method called createTest, the upgrade process adds an operation called createTestAxdTest to the new service class.

Artifact naming conventions

The following table lists the naming conventions used when the upgrade process generates services and artifacts. These naming conventions are applied to artifacts generated for the standard Axd<Document> classes as well as custom document classes, except for the prefix; no prefix is applied to services generated from custom document classes.

Artifact type

Name description

Name generation rules

Example

Document object

Name of the X++ class for the root data object.

<Prefix> + <Document Name> + "Service"

SalesSalesOrder

Data objects

Name of the X++ class for the child data objects of the document class.

<Root data object name> + "_" + <Query data source Name>

SalesSalesOrder_SalesTable,

SalesSalesOrder_DocuRefHeader, SalesSalesOrder_DocuRefLine, SalesSalesOrder_InventDim, SalesSalesOrder_MarkupTransHeader, SalesSalesOrder_MarkupTransLine, SalesSalesOrder_SalesLine

Service class

Name of the AIF service class.

<Prefix> + <Document Name> + "Service"

SalesSalesOrderService

AOT service node

Name of the AOT node for the service.

<Prefix> + <Document Name> + "Service"

SalesSalesOrderService

Service external name

Name of the service published to WCF.

<Document Name> + "Service"

SalesOrderService

Note

When custom document classes are upgraded, or when creating your own document classes, you do not need to use a prefix.


Data upgrade

The data upgrade process upgrades AIF data in the Microsoft Dynamics AX database. The tables listed in this section are new or upgraded in Microsoft Dynamics AX 2009. Any tables or fields that have a name prefaced with "DEL_" are tables used during the data upgrade and are for internal use only.

Note

The AIF code upgrade process must be run before the data upgrade process. This means that the Upgrade Aif Code step in the upgrade checklist must have been run previously. To verify that the code upgrade step has been run, check the AOT > Services node and you will see a list of AIF services. This signifies that the code upgrade process has already been run.


AifGlobalSettings

The field ResponseCacheLifetime has been added to the table and is set to 24 (hours).

AifService

This is a new table with the following fields:

  • ClassId

  • Name

  • Description

  • Enabled

  • ErrorState

  • ErrorMessage

  • Namespace

  • ExternalName

The upgrade process adds a service to this table for each Axd<Document> class. For each unique document ClassId in the AifAction table the upgrade process will:

  1. Locate the service node under AOT > Services.

  2. Add a record to the AifService table and populate it with data from the AOT.

  3. If the upgrade process encounters any errors while processing service actions in the AifAction table, these errors are concatenated and saved in the ErrorMessage field for each service.

  4. Sets the Enabled field to true if the service has an action enabled in the AifAction table.

Note

Only Axd<Document> classes that have registered actions (the action exists in the AifAction table) will be upgraded.


AifAction

The following fields have been removed:

  • ActionType

  • WebSvcOutOfSync

  • ActionEnabled

  • WebMethodEnabled

  • InfoLogData

  • ErrorState

The following fields have been added:

  • EnforceIdempotency

  • ServiceName

The data in the following fields has changed:

  • ActionId

In Microsoft Dynamics AX 2009, the actions create, read, update, and delete are not supported and can no longer be used. However, the functionality in these actions has been replaced by the new create, read, update, and delete service operations which can take parameters that contain multiple entity key values or multiple documents.

For each action where the Axd<Document> class has a matching service class in the AifService table, the upgrade process does the following:

  1. Verifies that the action can be upgraded. For documents that ship with Microsoft Dynamics AX, the methods create, read, update, and delete are not upgraded because these methods work with a single document or entity key. If the document class action cannot be upgraded, it is skipped and the upgrade process moves to the next action for the document class.

  2. If the action can be upgraded, the upgrade process gets the new method name as shown in the following table.

    Previous version action

    Mapped to method

    createList

    create

    deleteList

    delete

    findList

    find

    findEntityKeyList

    find

    readList

    read

    updateList

    update

  3. The record in the AifAction table is updated as follows.

    Field

    Value

    ActionId

    serviceClassName.Method

    Name

    serviceExternalName.serviceNodeOperationName

    ServiceName

    Service name in the AOT

    ClassId

    Service ClassId

    ExternalAction

    Service node operation name

    MethodName

    Service class method name

    EnableIdempotence

    Set depending on the value in the service reference node

After the data upgrade process completes, you may see actions in the AifAction table that are disabled (the field ActionEnabled is set to false). This can occur because:

  1. The record is for a create, read, update, or delete action in the previous version. These actions will be disabled in the table. You do not need to take any further action.

  2. If an unexpected error occurs during the upgrade process and an action cannot be upgraded, it will be disabled in the AifAction table.

AifDocumentSchemaTable

The DocumentClassId is updated to the ClassId of the data object.

AifDocumentFieldTable

The DocumentClassId is updated to the ClassId of the data object.

AifEndpoint

The PreventLoopbackSend and PropagateErrors fields are set to false.

AifResponse

The following fields have been added:

  • CreatedDateTime

All records are deleted during the data upgrade because the old message format is not forward compatible.

AifEndpointActionValueMap

The ActionId is updated to the new ActionId for actions that are successfully upgraded.

AifDataPolicy

The ActionId is updated to the new ActionId for actions that are successfully upgraded.

AifPipeline

The following fields have been added:

  • Direction

  • EndpointId

A pipeline can be inbound or outbound depending on the direction of the document flow which is determined by the action type of the endpoint action policy. For any records in AifEndpointActionPolicy that have a corresponding record in AifPipeline, the AifPipeline.Direction field is updated as follows:

  • Inbound if the action type is ReceiveDocument, ReceiveDocumentList, ProcessEntity, or ProcessEntityList.

  • Outbound if the action type is any other value.

The data upgrade process also updates the AifPipeline.ActionId field with the new ActionId and updates the AifPipeline.EndpointId with the EndpointId from the AifEndpointActionPolicy table.

AifEndpointActionPolicy

The following fields have been added:

  • InboundPipelineId

  • OutboundPipelineId

  • IsDefault

  • AutoErrorResponse

The follow columns have been removed:

  • XsltFilePath

  • SchemaRecId

  • PipelineId

  • DataPolicySynchronized

The ActionId field is updated with the new ActionId, and the InboundPipelineId and OutboundPipelineId fields are updated if there are any pipelines associated with the endpoint action policy.

AifEndpointActionParameterSchema

This is a new table with the following fields:

  • EndpointId

  • ActionId

  • ParameterClassId

  • SchemaRecId

  • DataPolicySynchronized

The data upgrade process creates a record in this table for each record in the AifEndpointActionPolicy table. The fields EndpointId, ActionId, SchemaRecId, and DataPolicySynchronized are all updated from the AifEndpointActionPolicy table. The ParameterClassId is set to the ID of the serializable data object.

AifDataPolicyXPath

The following fields have been added:

  • DocumentClassId

The ActionId is updated to the new ActionId for actions that have been upgraded. The DocumentClassId is set to the SerializableClassId.

AifXmlTransformConfig

The following fields have been added:

  • ParameterName

The data upgrade process sets the ParameterName field to the parameter name of the service operation.

AifValueSubstitutionComponentConfig

This is a new table with the following fields:

  • PipelineComponentRecId

  • ParameterName

The data upgrade process adds a record in this table for each record in the AifValueSubstitutionConfig table. The ParameterName field is set to the parameter name of the service operation. The PipelineComponentRecId field is set to the PipelineComponentRecId field value in the AifValueSubsititutionConfig table.

Data that is not upgraded

Data that is configured to use an ActionId that has not been upgraded will be moved according to the following table.

Table name

Moved to table name

AifAction

DEL_AifAction

AifDataPolicy

DEL_AifDataPolicy

AifDataPolicyXpath

DEL_AifDataPolicyXpath

AifEndpointActionPolicy

DEL_AifEndpointActionPolicy

AifEndpointActionValueMap

DEL_AifEndpointActionValueMap

AifPipeline

DEL_AifPipeline

AifPipelineComponent

DEL_AifPipelineComponent

AifSchemaStore

DEL_AifSchemaStore

AifValueSubstitutionConfig

DEL_AifValueSubstitutionConfig

AifWebsites

DEL_AifWebsites

The AifWebsites table is not upgraded and any Websites created in a previous version will be contained in the DEL_AifWebsites table. In Microsoft Dynamics AX 2009, the administrator must add the Websites manually. For more information, see "Configure Web sites for document exchange" in the Server and Database Administration Help.

Schema changes

In Microsoft Dynamics AX 2009, the message and document schemas have changed. After upgrading, you will need to refresh the AIF services by following these steps:

  1. Click Basic > Setup > Application Integration Framework > Services.

  2. Click Refresh.

There are various schemas that define the format and content of messages in AIF as shown in the following table.

Schema

Description

Message schemas

Define the format and content of the message metadata. This includes elements such as the envelope, the header, query criteria, entity key lists, and so on. The message schemas are included with Microsoft Dynamics AX. For more information, see "Message XSDs" and "Schemas" in the Microsoft Dynamics AX Developer Help.

Document schema

Defines the format and content of the business data in a message. This schema contains all the fields that can participate in a data exchange. Any message that comes into AIF must validate against the document schema.

Endpoint schema

Further restricts the document schema fields that can participate in a data exchange for a particular endpoint. The endpoint schema is defined by the data policy that you set for each endpoint action.

Due to these schema changes, any external systems that create inbound AIF messages must be modified to correctly format messages according to the new schemas. Any external systems that rely on data in outbound AIF messages must be modified to handle any changes in the outbound data.

Message schemas

Any message schema elements in inbound messages must validate against the new message schemas located in <Microsoft Dynamics AX Installation Directory>Application\Share\Include. For more information see, "AIF Messages" and "Message XSDs" in the Microsoft Dynamics AX Developer Help.

Document schemas

The document schemas have changed and any inbound messages that contain business data must be modified to validate against the new schemas. Also, outbound messages containing business data will be formatted to validate against the new schemas. For more information, see "Schemas" and "Document Schema Overview" in the Microsoft Dynamics AX Developer Help.

As a result of the schema changes, you may need to update the XSLTs that are used in pipeline transformations. After you have updated the XSLTs, you can reimport them by clicking Basic > Setup > Application Integration Framework > XSLT repository. You may also need to update your value lookups which you can do by clicking Basic > Setup > Application Integration Framework > Value lookup.

Endpoint schemas

The endpoint schemas are also known as endpoint action data policies. After upgrading, any document schema changes will not be reflected in existing endpoint data policies. New elements in the document schema will be turned off in the data policy, unless they are also required elements. The AIF administrator must modify existing endpoint action policies and add any new elements to the data policy if necessary. For more information, see "Configure endpoint action data policies" in the Server and Database Administration Help.

After you upgrade

Refresh the AIF document services

In order to call the AIF document services, you must refresh them.

  1. Click Basic > Setup > Application Integration Framework > Services.

  2. Click Refresh to load the services. There may be a delay while the services load.

For more information, see "Configure services" in the Server and Database Administration Help.

User permissions

Be sure that all source endpoint users are granted view permissions to AIF tables.