Microsoft Dynamics AX 2012
®
The Advanced ledger entry
service in Microsoft Dynamics
AX 2012 for Public sector
White Paper
This white paper provides an overview of operations that are
exposed in the Advanced ledger entry service in Microsoft
Dynamics AX 2012 for Public sector. It also outlines some
common development scenarios and provides step-by-step
instructions to integrate an external .Net application with
advanced ledger entries.
April 2013
http://microsoft.com/dynamics/ax
Send suggestions and comments about this document to
adocs@microsoft.com. Please include the title with your
feedback.
Table of Contents
Introduction ................................................................................................ 3
Purpose ............................................................................................................................... 3
Terminology ......................................................................................................................... 3
Audience.............................................................................................................................. 3
Assumptions ..................................................................................................................... 3
Prerequisites ..................................................................................................................... 4
Advanced ledger entry service .................................................................... 4
Operations ........................................................................................................................... 4
Setting up the Advanced ledger entry service ............................................. 5
Install Visual Studio Tools ...................................................................................................... 5
Deploy the service ................................................................................................................ 6
Deploy and configure the service directly .............................................................................. 6
Deploy and configure the service from the AOT ..................................................................... 6
Create a .NET project to consume the service ........................................................................... 7
Using the Advanced ledger entry service .................................................... 9
Skeleton of the C# class ........................................................................................................ 9
Consuming Advanced ledger entry service operations ................................................................ 9
Create ................................................................................................................................10
Read ..................................................................................................................................12
Update ...............................................................................................................................12
Find ...................................................................................................................................13
Delete ................................................................................................................................13
2
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Introduction
In the Public sector General Ledger module of Microsoft Dynamics AX 2012, advanced ledger entries
help create, adjust, and reverse ledger entries. For example, you can use advanced ledger entries to
reclassify expenditures if invoices for those expenses were mistakenly posted to the wrong account or
project.
The Advanced ledger entry service is similar to the General journal service and can be used to
integrate external business processes with the general ledger. Use the Advanced ledger entry service
when you need to do the following:

Affect the project ledger

Have advanced posting rules that are supported through posting definitions, such as rules to
generate additional entries to balance by fund
Purpose
This document discusses the Advanced ledger entry service together with its operations and
considerations for its implementation. The topics that are covered include the following:

Prerequisites for integration with the service

Service overview

Basic service integration scenarios
Terminology
Term
Definition
Application Integration
Framework (AIF)
AIF provides an extensible framework that supports multiple asynchronous
transports, and synchronous transport that uses web services, to reliably
exchange documents in XML format with trading partners or other systems.
[MSDN]
Audience
This document is intended for developers who are implementing a solution that is integrated with the
Advanced ledger entry service. General readers can get an overview of the service from the first few
sections.
Assumptions
This document assumes that the developer has an understanding of web services in general and web
services in Microsoft Dynamics AX in particular. The following table provides links to information about
services and AIF Document Services in Microsoft Dynamics AX 2012.
Document
Description
Services [White paper]
Provides an overview of the different types of services that are available in
Microsoft Dynamics AX 2012, and guidance to help developers and architects
to decide when to use a specific service type.
AIF Document Services [MSDN]
Provides an overview of AIF and how to create a document-based web
service.
This document assumes that the appropriate demo data set is installed. The code samples have been
tested on the City of Maple (COM) and Contoso data sets.
3
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Prerequisites
To benefit from this white paper, you should have experience in the following areas:

Writing and debugging code in Microsoft .NET Framework languages, such as C# and VB.Net (C#
is used for the examples in this white paper.)

Familiarity with Microsoft Visual Studio

Working experience with X++ and the Microsoft MorphX development environment
You must have Visual Studio 2010 (or a later version) installed to develop or debug the C# consumer
application that is described in this white paper.
Advanced ledger entry service
The Advanced ledger entry service is a document-based service that is used to create and manage
advanced ledger entries. The service can be found in the Application Object Tree (AOT) under
Services> AdvancedLedgerEntryService.
Operations
The Advanced ledger entry service supports the following operations:

create

delete

find

findKeys

read

update
4
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Setting up the Advanced ledger entry service
Install Visual Studio Tools
You must have Visual Studio Tools installed for Microsoft Dynamics AX before you can create a .NET
project to consume an AIF web service.
Follow these steps to install the Visual Studio Tools for Microsoft Dynamics AX.
1. Run Microsoft Dynamics AX 2012 Setup.
2. Under Install, click Microsoft Dynamics AX components.
3. Click Next to go to the Add or modify components page.
4. Under Developer tools, select the check box next to Visual Studio Tools.
5. Click Next to step through the remaining wizard pages.
6. Click Install to install the tools.
7. Click Finish to close the wizard.
8. Exit Setup.
5
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Deploy the service
You can deploy the service directly from the Microsoft Dynamics AX 2012 client, or you can deploy the
service from the AOT.
Deploy and configure the service directly
1. Open Microsoft Dynamics AX 2012.
2. Click System administration > Setup > Services and Application Integration Framework
> Inbound ports. Click New, and then enter a port name. Leave the form open.
3. Click System administration > Setup > Checklists > Initialization checklist, and then run
the setup for AIF. Wait until you see the green check mark.
4. Return to the Inbound ports form, click Service operations, and then select the create,
delete, find, findKeys, read, and update operations for the Advanced ledger entry service.
5. Close the Service operations form, and then click Activate.
Deploy and configure the service from the AOT
1. Open Microsoft Dynamics AX 2012, and switch to the Development Workspace.
2. In the AOT, right-click Service Groups, and then select New Service Group.
3. Name the group AdvancedLedgerEntryServiceGroup.
4. Right-click the newly created group, and then select New Service Node Reference.
5. Rename the service node reference AdvancedLedgerEntryService.
6. Right-click the newly created service node reference, and then select Properties.
7. Under the Service property of the service node reference, select AdvancedLedgerEntryService.
8. Right-click AdvancedLedgerEntryServiceGroup, and then select Deploy Service Group.
6
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
9. Make sure that the service is deployed successfully.
10. Go to System administration (module) > Setup > Services and Application Integration
Framework > Inbound ports.
11. Select AdvancedLedgerEntryServiceGroup, and make sure that it’s activated. If it is not, click
Activate to activate it. Copy the WSDL URI to use in the next procedure.
Create a .NET project to consume the service
Follow these steps to create a project to consume the service.
1. Open Visual Studio 2010.
2. Click File > New > Project.
3. Under Visual C# > Windows templates, select Console Application.
4. Name the project AdvancedLedgerEntryServiceTest, and then click OK.
7
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
5. In Solution Explorer, right-click the References node, and then select Add Service Reference.
6. In the Add Service Reference dialog box, in the Address field, paste the WSDL URI that you
copied in step 11 of the previous procedure, Deploy the service. Then click Go. You should be able
to see the service and its operations, as shown in the following screen shot.
7. Enter a name for the namespace, such as AdvancedLedgerEntryService, and then click OK.
The service reference has been successfully added to the console test application.
8
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Using the Advanced ledger entry service
Skeleton of the C# class
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
// import the service reference as a namespace
using AdvancedLedgerEntryServiceTest.AdvancedLedgerEntryService;
namespace AdvancedLedgerEntryServiceTest
{
class Program
{
static void Main(string[] args)
{
}
}
}
Consuming Advanced ledger entry service operations
The following data model represents an advanced ledger entry header and line in the Microsoft
Dynamics AX database.
The following code samples demonstrate how to use the service operations that are available in the
Advance ledger entry service.
9
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Note: The following code samples use the ledger dimensions and posting (journalizing) definitions
from a specific demo data set. To run this code, you may have to change the ledger dimensions and
posting (journalizing) definitions.
Create
The following sample C# code creates an advanced ledger entry with one line. Add this code in the
project that you created earlier, and then run the project through Visual Studio 2010.
// For this demo code,
// The calling context should be switched to partition 'ps' and company 'com'
CallContext callContext = new CallContext();
callContext.PartitionKey = "ps";
callContext.Company = "com";
callContext.LogonAsUser = "<A dynamics AX user to create the ALE>";
AdvancedLedgerEntryServiceClient serviceClient = new AdvancedLedgerEntryServiceClient();
AxdAdvancedLedgerEntry advancedLedgerEntry = new AxdAdvancedLedgerEntry();
EntityKey[] entityKeyList;
// Creating an advanced ledger entry with one line
advancedLedgerEntry.AdvLedgerEntryHeader = new AxdEntity_AdvLedgerEntryHeader[1];
advancedLedgerEntry.AdvLedgerEntryHeader[0] = new AxdEntity_AdvLedgerEntryHeader();
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine = new
AxdEntity_AdvLedgerEntryLine[1];
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0] = new
AxdEntity_AdvLedgerEntryLine();
// Creating ledger dimension for advanced ledger entry line
AxdType_MultiTypeAccount ledgerDimension = new AxdType_MultiTypeAccount();
ledgerDimension.DisplayValue = "101-11010";
ledgerDimension.Account = "11010";
ledgerDimension.Values = new AxdType_DimensionAttributeValue[1];
ledgerDimension.Values[0] = new AxdType_DimensionAttributeValue();
ledgerDimension.Values[0].Name = "Fund";
ledgerDimension.Values[0].Value = "101";
// Setting ALE header attributes
advancedLedgerEntry.AdvLedgerEntryHeader[0].AccountingDate = DateTime.Now;
advancedLedgerEntry.AdvLedgerEntryHeader[0].JournalizingDefinition = "GLALE";
advancedLedgerEntry.AdvLedgerEntryHeader[0].TransactionCurrency = "USD";
advancedLedgerEntry.AdvLedgerEntryHeader[0].TransactionText = "Correction";
// Setting ALE line attributes
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].AmountCurDebit = 100;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].AmountCurDebitSpecified = true;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].LedgerDimension =
ledgerDimension;
entityKeyList = serviceClient.create(callContext, advancedLedgerEntry);
10
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
After executing the preceding code, follow these steps to verify that the advanced ledger entry was
created.
1. Open Microsoft Dynamics AX 2012 in the ps partition with the com company.
2. Go to General ledger > Common > Advanced ledger entries. The newly created advanced
ledger entry appears as shown in the following screen shots.
11
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Read
The following sample C# code demonstrates the use of the read operation of the Advanced ledger
entry service.
// Reading the previously created ALE record
entityKeyList = new EntityKey[1];
entityKeyList[0] = new EntityKey();
entityKeyList[0].KeyData = new KeyField[1];
entityKeyList[0].KeyData[0] = new KeyField();
entityKeyList[0].KeyData[0].Field = "TransactionNumber";
entityKeyList[0].KeyData[0].Value = "DAT-000093";
advancedLedgerEntry = serviceClient.read(callContext, entityKeyList);
Update
The following sample C# code demonstrates the use of the update operation of the Advanced ledger
entry service. For the update operation, it is first necessary to read the record that needs to be
updated.
// Reading the ALE record
entityKeyList = new EntityKey[1];
entityKeyList[0] = new EntityKey();
entityKeyList[0].KeyData = new KeyField[1];
entityKeyList[0].KeyData[0] = new KeyField();
entityKeyList[0].KeyData[0].Field = "TransactionNumber";
entityKeyList[0].KeyData[0].Value = "DAT-000093";
advancedLedgerEntry = serviceClient.read(callContext, entityKeyList);
// Updating the transaction text of ALE header
advancedLedgerEntry.AdvLedgerEntryHeader[0].actionSpecified = true;
advancedLedgerEntry.AdvLedgerEntryHeader[0].action = AxdEnum_AxdEntityAction.update;
advancedLedgerEntry.AdvLedgerEntryHeader[0].TransactionText = "Updated transaction text";
// Updating the quantity and debit amount on ALE line
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].actionSpecified = true;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].action =
AxdEnum_AxdEntityAction.update;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].Quantity = 10;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].QuantitySpecified = true;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].AmountCurDebit = 200;
advancedLedgerEntry.AdvLedgerEntryHeader[0].AdvLedgerEntryLine[0].AmountCurDebitSpecified = true;
serviceClient.update(callContext, entityKeyList, advancedLedgerEntry);
12
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
After executing the preceding code, follow these steps to verify that the advanced ledger entry was
updated.
1. Open Microsoft Dynamics AX 2012 in the ps partition with the com company.
2. Go to General ledger > Common > Advanced ledger entries, and confirm that the transaction
text, quantity, and debit amount were updated correctly.
Find
The following sample C# code demonstrates the use of the find operation of the Advanced ledger
entry service.
QueryCriteria queryCriteria = new QueryCriteria();
queryCriteria.CriteriaElement = new CriteriaElement[1];
queryCriteria.CriteriaElement[0] = new CriteriaElement();
queryCriteria.CriteriaElement[0].DataSourceName = "AdvLedgerEntryHeader";
queryCriteria.CriteriaElement[0].FieldName = "TransactionText";
queryCriteria.CriteriaElement[0].Operator = Operator.Equal;
queryCriteria.CriteriaElement[0].Value1 = "Updated transaction text";
advancedLedgerEntry = serviceClient.find(callContext, queryCriteria);
Delete
The following sample C# code demonstrates the use of the delete operation of the Advanced ledger
entry service.
// Deleting the ALE record
entityKeyList = new EntityKey[1];
entityKeyList[0] = new EntityKey();
entityKeyList[0].KeyData = new KeyField[1];
entityKeyList[0].KeyData[0] = new KeyField();
entityKeyList[0].KeyData[0].Field = "TransactionNumber";
entityKeyList[0].KeyData[0].Value = "DAT-000093";
serviceClient.delete(callContext, entityKeyList);
13
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
After executing the preceding code, follow these steps to verify that the advanced ledger entry was
deleted.
1. Open Microsoft Dynamics AX 2012 in the ps partition with the com company.
2. Go to General ledger > Common > Advanced ledger entries, and confirm that the advanced
ledger entry was deleted.
14
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR
Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your
people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar
Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a
way that helps you drive business success.
U.S. and Canada Toll Free 1-888-477-7989
Worldwide +1-701-281-6500
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the
date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a
commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of
publication.
This white paper is for informational purposes only. Microsoft makes no warranties, express or implied, in this document.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of
this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means
(electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of
Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject
matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this
document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
© 2013 Microsoft Corporation. All rights reserved.
Examples of companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted
herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person,
place, or event is intended or should be inferred.
Microsoft, Microsoft Dynamics, MorphX, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation
in the United States and/or other countries.
15
THE ADVANCED LEDGER ENTRY SERVICE IN MICROSOFT DYNAMICS AX 2012 FOR PUBLIC SECTOR