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.
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:
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
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.
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.
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.
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.
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
9. Create and configure endpoint
Create a new endpoint: APInvoiceJour with Local endpoint CEU. Select Active to activate the endpoint.
Add endpoint user or user group. In our example SourceEnpointUser in Inbound XML will be blank. (For more information, see Security Authorization)
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.
Click 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.
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
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.
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:
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:
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:
You can see that new journal has been successfully created with multiple lines and different account types: