Microsoft Dynamics AX 2009 AIF Integration for AP Invoice Journals

Standard AX allows to create purchase invoice and invoice register (LedgerPurchaseInvoiceService) via Application Integration Framework (AIF). However, if you need to create Non-Purchase invoices (AP > Journals > Invoices > Invoice Journal), then you will need to create your own custom AIF service. In this article we will explain in details how to do that.

Table of Contents:

Part I – Setup Application Integration Framework

      1. Create and configure directories

      2. Configure File System transport adapter

      3. Add channels

      4. Create the document query

      5. Create a Service Using the AIF Document Service Wizard

      6. Adding Code to Document Service class

      7. Publish the service

      8. Add local endpoint

      9. Create and configure endpoint

      10. Configure action policies and data policies

      11. Configure endpoint action data policies

Part II – Configuration, Testing, Results

      12. AX setup

      13. Sample XML

      14. Batch processes for AIF Service

      15. Testing

      16. Tips and enhancements

Part I – Setup Application Integration Framework

 1. Create and configure directories

 If you have not already done so, you must create an inbound and an outbound directory.

  • In the inbound directory you will save XML files that should be received and processed by AIF.

  • The outbound directory is where the XML files produced by AIF will be saved. These files normally will be consumed by some third party applications.

Later in this article we will explain that there will be some batch processes (see part II, number 14) running, which are responsible for processing inbound and outbound messages.

Now, using Windows Explorer, please create an inbound and an outbound directories, and set appropriate permissions for the new directories.

creating inbound and outbound directories

2. Configure File System transport adapter

To use the File System as the transport, you must first configure the File System adapter.

Create transport adapter: AifFileSystemAdapter: Basic > Setup > Application Integration Framework > Transport adapters.

Select AifFileSystemAdapter from the Adapter class field. There may be a slight delay while AX scans for adapters:

configure files sytem transport adapter

3. Add channels

The channels associate the file system adapter with the file system directories that you just created. You must create two channels: one for the outbound directory, and one for the inbound directory.

Create inbound and outbound channels: Basic > Setup > Application Integration Framework > Channels

add channels

4. Create the document query

The document query is a standard Microsoft Dynamics AX query that is associated with an Axd<Document> class. Document queries are located in the AOT under the ​Queries node. The query name matches that of the document class with which it is associated. For example, if you create a document query named APInvoiceJournal then the document class that is generated will be AxdAPInvoiceJournal.

Create new query: APInvoiceJournal with two joined tables: LedgerJournalTable and LedgerJournalTrans.

create the document query

5. Create a Service Using the AIF Document Service Wizard

Create AIF document service using our new query: APInvoiceJournal and click next.

Microsoft dynamics > Tools > Development tools > Application Integration Framework > Create document service.

For more information, see Running the AIF document service wizard.

6. Adding Code to Document Service class

You can now review all objects created in AOT under your new project AxdAPInvoiceJournal.

Go to Projects\Private\AxdAPInvoiceJournal and open it.

adding code to document service class

You can make modifications for your service to meet your specific requirements.  For example, you can modify AxdAPInvoiceJournal.prepareForSave() to initialize, verify and process journal header and lines.

Hint: Standard AX allows to create ledger journals of type Daily only. You will receive the following error: Journal name APInv does not support journal type Daily. In that case, you can modify AxdAPInvoiceJournal.prepareForSave() to properly initialize LedgerJournalTable and LedgerJournalTrans. For example you can adjust your code similarly like it was done for AxdPurchaseInvoice.prepareForSave()

If you want to consume the service from an external application using a Web service then you must assign the Security Key to the service and make sure that the user calling the service belongs to a user group that has correct access level to that security key. For more information, see How to: Create and Apply Security Keys.

To avoid permission errors please add security key to APInvoiceJournalService. In our example we will use a standard one: LedgerPurchaseInvoiceService.

project ax invoice journal

7. Publish the service

The service only needs to be published once. If you have already published the service, you can skip this step. In this section, you will publish the service.

Go to Basic > Setup > Application Integration Framework > Services and press Refresh:

Mark the Enabled checkbox next to the service you want to publish.

AIF services

Note: If the service is going to be exposed as a Web service, you must click Generate.

8. Add local endpoint

A local endpoint is the origination for sent messages and the destination for received messages

Create local endpoint: Basic > Setup > Application integration framework > Local endpoints

For example,

Company: CEU

Local endpoint: CEU

add local endpoint

9. Create and configure endpoint

Create a new endpoint: APInvoiceJour with Local endpoint CEU. Select Active to activate the endpoint.

create and configure endpoint

Add endpoint user or user group. In our example SourceEnpointUser in Inbound XML will be blank. (For more information, see Security Authorization)

create and configure endpoint 2

10. Configure action policies and data policies

Click Configure to perform document-specific configuration, including value mapping, for the document exchange. Value mapping is translation of field data values based on business rules, for example, translating internal item numbers to vendor-specific item numbers or industry standard numbers depending on the trading partner. For more information, see Configure endpoint action data policies.

configure action policies and data policies

Click data policies

parameter data policies

11. Configure endpoint action data policies

There are two types of qualifiers for data fields on the Data Policies form: required and enabled. These have different meanings and effects depending on the direction of the transfer.

If a data field is allowed to be included in an inbound exchange, it is said to be enabled. For inbound documents, only fields that are enabled are allowed to be submitted by the endpoint. If a document is received that includes fields that are not enabled, the document is rejected and an exception is logged.

There are two terms that are used when discussing whether a field is required in a document: mandatory fields and required elements.

configure endpoint action data policies

Note: The fields contained in the inbound XML must be enabled in the endpoint data policy. If you have fields enabled in the data policy and they are marked as required, then those fields must be in the inbound XML or an error is generated. If you have fields enabled in the data policy and they are not marked as required, then those fields can be omitted from the inbound XML.

For more information about creating and configuring endpoints see Create an endpoint and Configure an endpoint

Part II – Configuration, Testing, Results

12. AX setup

For the new service to work some setup is required in AX. More specifically, we can create a new journal name to be used only with our service, or we can use an existing journal name. Let’s create a new one – APInvAIF, go to General Ledger > Setup > Journals > Journals names

journal names ax setup

For more information, see How to setup journal names

13. Sample XML

The following code is an example of what an XML message could look like when you submit data in order to create an invoice journal (APInvoiceJournal.xml)

<?xml version=”1.0″ encoding=”UTF-8″?>

<Envelope xmlns=”https://schemas.microsoft.com/dynamics/2008/01/documents/Message”>

<Header>

<MessageId></MessageId>

<SourceEndpointUser> </SourceEndpointUser>

<SourceEndpoint>APInvoiceJour</SourceEndpoint>

<DestinationEndpoint>ceu</DestinationEndpoint>

<Action>https://schemas.microsoft.com/dynamics/2008/01/services/APInvoiceJournalService/create</Action>

</Header>

<Body>

<MessageParts xmlns=”https://schemas.microsoft.com/dynamics/2008/01/documents/Message”>

<APInvoiceJournal xmlns=”https://schemas.microsoft.com/dynamics/2008/01/documents/APInvoiceJournal”>

<LedgerJournalTable class=”entity”>

<JournalName>APInvAIF</JournalName>

<LedgerJournalTrans class=”entity”>

<AccountNum>100010</AccountNum>

<AmountCurDebit>11.00</AmountCurDebit>

<DocumentDate>2014-12-13</DocumentDate>

<Invoice>12345</Invoice>

</LedgerJournalTrans>

</LedgerJournalTable>

</APInvoiceJournal>

</MessageParts>

</Body>

</Envelope>

14. Batch processes for AIF Service

For AIF to begin sending and receiving documents for adapter-based exchanges, the services that move documents through the queues must be running as batch jobs within Microsoft Dynamics AX. For more information, see “Start and stop the asynchronous AIF”

Also we can simply create a job to call AIF service manually:

static void AIFReceiveAndProcess(Args _args)

{

AifGatewayReceiveService gtwyRec = new AifGatewayReceiveService();

AifInboundProcessingService inSvc = new AifInboundProcessingService();

;

//Running Gateway Receive Service…

gtwyRec.run();

 

//Running Inbound Processing Service…

inSvc.run();

 

info(“End”);

}

15. Testing

Finally, to get our service working all we need is to drop an XML (APInvoiceJournal.xml) into our inbound folder (D:\Inbound) and run AIFRecevieAndProcess job.

testing inbound

testing aif receive and process

 

After you submit the message to create Invoice Journal, you can check the status of the exchange in the Queue manager form (Basic > Periodic > Application Integration Framework > Queue manger). After AIF has processed the message, you can view it in the Document history form or troubleshoot any errors in the Exceptions form (Basic > Periodic > Application Integration Framework > Exceptions).

Make sure that new journal has been created, Account payable > Journals > Invoices > Invoice journal:

invoice journal

Next time we will create AIF invoice journal with account type Vendor/Customer and compare it with AX 2012.

16. Tips and enhancements

Issues

Standard AX allows to create Ledger journal lines only of type: Ledger (Previous example). If you try to submit Invoice Journal Line of type Customer/Vendor/etc:

tips and enhancements

In that case you will receive the following error: “The account type must be ledger.”

To read more about limitations, see AIF general journal services require the journal type to be Daily and the account type to be Ledger.

All what you need is to fix the following validation in LedgerJournalTransType.validateAccountType(). You need to add an initialization of ledger journal:

tips and enhancements AIF

You can see that new journal has been successfully created with multiple lines and different account types:

tips and enhancements journal voucher

Have other Microsoft Dynamics AX inquiries or needs? Visit our Help Desk for AX page to see how our experts can help!

You can also contact Ellipse Solutions, LLC by email at info@ellipsesolutions.com or by calling (937) 312-1547.

  Microsoft Dynamics AX Project WIP Analysis