Microsoft Dynamics AX 2012
®
Using the Excel Add-in to
update and import data
Concept Paper
This document describes the concepts relating to the Excel addin when used for updating or importing data in Dynamics AX
Date: June 2011
CCAX2012IC0010
Table of Contents
Overview..................................................................................................... 3
Key Concepts in the Excel Add-in ................................................................ 4
Connection........................................................................................................................ 4
Data Sources and the Field Chooser ..................................................................................... 4
Filters............................................................................................................................... 5
Security ............................................................................................................................ 5
Publish Options.................................................................................................................. 6
Matrix Fields ..................................................................................................................... 7
Lookups and Caching ......................................................................................................... 8
Surrogate Keys and Identity................................................................................................ 9
Date Effective tables ......................................................................................................... 11
Inheritance ...................................................................................................................... 12
Dimensions ...................................................................................................................... 12
Error Handling .................................................................................................................. 14
Serialization ..................................................................................................................... 15
Limitations and common pitfalls ............................................................... 15
Getting Started – A step by step guide ...................................................... 16
Supported AIF Services ............................................................................. 17
Example Errors using services ............................................................................................ 17
List of supported services .................................................................................................. 18
Supported tables .............................................................................................................. 18
Tips for events .......................................................................................... 18
Do .....................................................................................................................................19
Don’t ..................................................................................................................................19
2
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
-
Overview
The Microsoft Dynamics Add-ins for Microsoft Office enable queries and AIF Document
services to be integrated into documents built with Microsoft Word or Microsoft Excel.
This quick-start guide shows the steps required for using the add-ins, which enable the
following scenarios:
Scenario
Ad-hoc data access in
Microsoft Excel
Update business data
in Microsoft Excel
Incorporate business
data into documents
using templates
Import reference and
master data
Description and examples
Use the “export to excel” button from any grid in the
AX client or EP to begin authoring an ad-hoc report in
excel. The report will start with the same filters and
columns associated with the list page, and can be
extended and refreshed as the underlying data is
changed. Examples include:

Analyzing sales opportunities for a team

Analyzing current list of cases assigned to people

Viewing Vendors or Customers and their currently
outstanding transactions
A template author builds a template associated
columns and cells in a Microsoft Excel worksheet with
fields in a web service that has been configured to
work with the Office add-ins. End users use this
template to read business data, update the data and
send the updates back to Microsoft Dynamics AX.
Examples include:

Editing or creating budget amounts

Publishing journal entries
A template is designed to include business data from a
query that has been designed and configured to work
with the Office add-ins. The template designer drags
and drops the fields into the Word or Excel document.
The template is placed in a SharePoint library which
has been associated with a Document Type in the
Microsoft Dynamics AX document handling system. End
users can generate documents based on this template
from within forms in Microsoft Dynamics AX: Examples
include:

Sending a form letter to a customer

Sending a project quotation to a prospect
Templates can be built based on Tables or Services in
Microsoft Dynamics AX, and data can be read, created,
or updated from within Microsoft Excel. Note that when
importing/reading from Tables, only Administrators
3
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
may use the table-based import functionality due to
security restrictions. Examples include:

Importing reference data for proof of concept

Importing customers or vendors into the system during
implementation.
Key Concepts in the Excel Add-in
Connection
The office add-ins connect directly to the AOS using WCF-based web services. By default,
the default connection information specified in the local client configuration is used to
identify the AOS and port used to connect, and the default legal entity is obtained from the
user preferences in Dynamics AX. When a workbook is constructed via document generation
or via export to excel from EP pages or client grids, the connection information is
automatically overridden to include the server and port of the originating AOS.
Data Sources and the Field Chooser
Data sources refer to the top level nodes shown in the field chooser, each of which
corresponds to a Table, Service, or query. Data sources can be added to a workbook by
using the “Add Data” tab. They can be removed by right clicking on the root of the data
source and choosing delete. Adding tables to a workbook requires administrative
permissions.
The field chooser determines the mode of operation of the Excel add-in. When open, fields
may be added or removed from the workbook. When closed, no changes to the structure of
the tables can be made. Closing the field chooser removes all data from the workbook.
Fields can be added to the workbook in two manners: Value Bindings and Column bindings.
Value bindings may only be used for read-only data sources. Buttons on the action strip
dictate which binding style is used. Using either double click or drag/drop of any field will
add a column binding to the location in focus. Dragging a data table will add either required
fields (for read/write) or all fields (for read-only sources) to that location.
The names of fields shown are based on the localized label associated with the field. If none
exists, the localized label of the underlying data type is used. If none exists, the name from
4
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
the AOT is used. The AOT name is visible in a tool-tip when hovering over the fields or by
choosing “properties” from the context menu on any field.
Calculated fields can also be included as read-only fields in the worksheet
The column headers on the worksheet may be modified to suit the purpose of the
spreadsheet if the default label is not descriptive of the content
Once a field is added to the worksheet, focusing on that field when the field chooser is open
will highlight the field in the field chooser
Fields may be bound multiple times on the same worksheet, and synchronization of any
edits to the underlying data is maintained by the addin when the data sources are editable.
Filters
When a query is added to a workbook, either via the “Add Data” tab, or by virtue of export
to excel, all ranges and filters are included. The user may further filter the workbook by
adding additional filter clauses. However, the original filter from the exported or chosen
query cannot be viewed or edited. Criteria in the filter tab have the same meaning as they
do in the “Advanced filter” control in the AX Client. For instance, shorthand notation like
“>10”, or “10..20” may be used. If the same filter field is specified multiple times, the
conditions are “OR-ed” together.
Security
All interactions between the excel client and the AOS are performed on behalf of the
windows principal running the addin. This means that row-level filtering imposed by the XDS
security system will applied to any results read into the workbook. Only administrators can
create, update, or delete information using tables because the underlying service that is
used (AifGenericDocumentService) gives permissions to all tables in the system. For enduser update scenarios, AIF Document services must be used. The permissions applied on
the Create, Update, and Delete methods are respected when those methods are called to
update data using web services.
5
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
Publish Options
The publish options dialog, accessible from the Publish option on the ribbon, controls
aspects of how the workbook is published and how changes are tracked in the workbook.
Track Changes
The Excel add-in has two modes of operations driven by the “Track Changes” option found
in Publish->Publish Options. The default mode of operation is when the “Track Changes”
setting is enabled. In this mode, data can be read, modified, updated, and deleted, and as
those changes are made, the add-in is tracking them so that at publish time, only the
updated, deleted, or created records are sent to AX.
Track Changes = Yes (Default)
Some data validation occurs in realtime
Updates, Deletes, and Creates are
tracked
Key fields must be unique and may
not be updated once established
Updates made by users running excel
without the add-in are not recognized
Track Changes = No
No data validation occurs until publish
time
Data can only be created, not updated,
or deleted or refreshed
Key fields may be updated and changed
any time
Updates can be made by users without
the add-in installed.
Publishing Order
When multiple services and tables are included and there are interdependencies among
them, the publishing order dialog in publish options must be used to properly order the
tables and services so that dependent data are sent first. For example, if a single template
6
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
includes customer groups and customers, the customer group table must be published
before customers.
Publish to Folder
Generally, when a publish operation is performed, the changes (created records, updated
records, or deleted records) are sent synchronously to the AOS for processing. Each change
will call the proper method on the document service, and if there are failures, the resulting
error messages are retrieved and placed on the error status sheet. An alternative method of
publishing is to export the changes to a folder on disc, and then use the file directory of an
AIF inbound port to import the information. This process consists of:
1. Building an inbound port in System Administration-> Setup-> Services and Application
Integration Framework-> Inbound ports
2. Configure the adapters to use a File system adapter and map it to a file system directory
3. Build the template to write output to the same directory, or alternatively, publish the results to
one directory and later copy them to the inbound port directory
4. Initiate processing of the inbound port (TODO: Example)
5. Check on progress by opening the worksheet and using the “Retrieve Status” button
a.
As messages are processed, errors will be placed on the AX Status sheet
b.
As messages are processed, the status of each data source will change from
“Published” to “Processed”
Matrix Fields
A matrix field is a calculated field that can be used to display and edit aggregated
information in a matrix format. This is very similar to the way that a pivot table displays
information. Matrix fields are used in conjunction with normal fields to produce editable
matrix of values. A matrix field is created by right-clicking on a data source node and
choosing “Create Matrix Field”. This presents a dialog which requires 3 elements:

Name: The name of the new matrix field, which will be displayed in the field chooser

Measure: A numeric field in the data source (or child data sources) to aggregate

Condition: An expression that indicates which values qualify for aggregation into the matrix
field
Once created and bound to a sheet, the values in the matrix field and the underlying
contributing rows to the field are kept in sync by the add-in. As changes are made to the
individual rows, the totals are adjusted accordingly in the matrix. Likewise, when changes
are made to the total, the change is proportionally distributed across the rows that
contribute to the total.
The screenshot below provides an example of how to use matrix fields in conjunction with
the budget transaction service. This same approach can be applied to any scenario where
numeric data needs to be laid out in columnar fashion or when you wish users to be able to
edit aggregate information and reflect those changes at a lower level of detail.
7
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
Matrix fields are intended to allow editing of existing data rather than creating new
information, and are subject to the following restrictions:

No new rows: New rows cannot be list that contains matrix fields, but as new rows are
added to the other associated lists in the workbook, those new rows will be added to the
matrix view.

Only Edit Totals: The only editable columns in the matrix are those which

Key fields not required: Whereas other lists used to edit or create data must always include
key fields, this is not the case with lists containing matrix fields.

New detail rows: A new detail row may be created in the case that a cell in the matrix has
no contributing rows in the underlying data. For instance, in the above example, if there were
no “Amendment” values for Commissions, the initial value for cell D5 would be 0. Changing
this value to 100 would create a new budget transaction header in the backing data and set
the fields that are implied by the filter and row value (in this case, Comment=Commissions
and Type=Amendment. Remaining required fields, if they exist, along with any identity fields
need to be filled out prior to publishing.
Lookups and Caching
Lookups enable users of the Excel template to choose from a list of valid values when
creating or updating information from Excel. A lookup is performed by pressing the “Field
Lookup” button on the ribbon interface while the focus is on a field that is a foreign key
within the service or table as shown below.
8
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
By default, the lookup dialog performs a query against the AOS to retrieve the valid values
of the related data source. The query will return additional fields to assist in making a valid
selection by adding the AutoLookup field group, the AutoID field group, and the Title 1 and
Title 2 fields. Only the first 1000 records are returned to the lookup dialog. In the case that
there are more valid values, a warning is presented to the user, and the filter dialog must
be used to narrow the scope of the lookup. For instance, when looking up an item, an item
group or item name filter will need to be added if more than 1000 items exist.
When selected, all fields from the related data source will be populated on the worksheet.
For instance, if there is a multi-segment key or if there are AutoLookup fields bound to the
worksheet, any of those fields will initiate the lookup, and any chosen value will populate all
fields that are on the worksheet.
In addition to querying the AOS for valid lookup values, lookups can be performed against a
cached data set within the workbook. To enable this, choose properties from the right-click
menu on the field for which you wish to configure the lookup and select caching. When
configured like this, the next data refresh will query the system for the valid values and
store them on a hidden sheet in the workbook. Once cached, the field lookup control will
read the valid values and associated lookup fields from the hidden sheet without requiring a
connection to a server.
The cache lookup property is implicitly turned on for any related tables within the workbook.
For example, if custTable and custGroup tables are both added to the same workbook, all
lookups of custgroup from custTable’s reference to custGroup will be done using the values
present within the workbook and will never require querying the AOS.
Cached data sources can also be configured to provide in-cell dropdowns which further
ensure that proper data are entered into the worksheet as shown below.
Surrogate Keys and Identity
Every table or service that can be used by the Excel Add-in must have a unique index that
does not include rec-id. All components of that index will be shown in the field chooser with
the key icon, and will be included in any excel table that includes information from that data
source. The unique index that is used will be one of the following, evaluated in this order
9
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
o
Replacement Key
o
Alternate Key
o
Primary Index
o
Unique index without rec-id
If none of these conditions is met, then the table or service cannot be used for update in the
excel addin.
Additionally, all fields in the table or service that are rec-id-based references to other tables
must refer only to tables which have a unique index designated as the “replacement ID” for
the table. The reason is that the service interfaces that are used by the Excel Add-in require
the replacement ID rather than requiring the rec-id to be looked up on the client side.
The screenshot below illustrates the importance of this. The top grid shows the HCMGoal
table data as it appears when edited in excel, and in the lower grid, the same data is shown
in the AX table browser. In the table browser, the Worker field is represented by a rec-id
value that references the HCMWorker Table. Because the rec-id is not a meaningful or
visible value within the AX application, it is replaced with the visible and more meaningfule
fields that represent the rec-id. Specifically, in the field chooser, it is expanded to include all
of the AutoLookup and AutoID fields of the referenced table (Woerker.Initials,
Worker.Name, Worker.Party ID, Worker.Party Type, and Worker.Personnel number). These
fields are drawn from all of the tables that contribute to the identity of the HCMWorker table
including the dirPartyTable and dirPerson tables. When update, create, or delete documents
are sent to the service, the actual Party ID is used rather than the rec-id.
Editing Identity fields
Once a row of data in Excel has all of the identity fields filled out, these fields cannot be
changed. For example, consider the following simple table. In the above example, the Goal,
Goal Heading, and Party ID constitute the identity fields. Once these three fields are filled
10
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
out in a row, or once they are read from existing records, the values cannot be changed.
Rather, the record must be deleted from the worksheet and rebuilt with new correct key
values. Also, the add-in prevents duplicate identity combinations from being entered into
the worksheet if a duplicate row is typed in. However, if a copy/paste operation results in
duplication of identity fields, these rows will behave as if they are the same row.
At publish time, if there are rows that do not have valid values for all key components, the
following error is issued, and will prevent the publish from occurring or result in the rows
that have incomplete keys to be removed from the worksheet.
Sequence Numbers
Some tables and services have identity fields which are filled out on the server using the
number sequence facility. However, the identity fields are still required to be entered as a
part of the data entry in excel in order to be recognized by the add-in as complete records
that are ready to be sent to the server. In these cases, a temporary identity can be used for
newly created records which will be replaced by the real value once the record is received
and processed on the server.
Keys in Parent/Child data sources
When a data source contains multiple related data tables, there must be valid identity fields
as per the rules outlined above on each data table within the data source except for leaf
nodes. For example, in a header/line service such as budget transaction service, it is
possible that the lines contribute no visible identity but can still be used in the excel add-in.
Date Effective tables
Date effective tables in Dynamics AX 2012 handle the common scenario of data changing
over time where prior revisions are retained. Dynamics AX automatically handles the
creation of new records and the maintainance of prior versions. The Excel add-in is limited
in how date effective tables are handled:

Current revision only: Only the current revision of any date effective table is retrieved and
displayed. It is not possible to read prior versions in the add-in

Create revision only: When records are edited, a new date effective record is created in the
system. There is no support for editing existing records.

No delete support: Records cannot be deleted when the table is date effective.

Key editing: Because the valid to/valid from portions of a date effective table are frequently a
part of the key, they cannot be edited, which is a general restriction on key fields.
This is best seen as an example. The screenshot below shows the DirPersonName table,
which keeps track of a person’s name as it changes through time. On the left, you see the
view in excel, which shows only a single record for Sanjay Patel – namely the current name.
In this example, the middle name was changed from Test1 to Test2. You can see both
records are retained in the right hand view in the SQL database. Even though the action in
Excel was an “update” action, the system will treat it as a “create” action, retaining the prior
version.
11
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
A few notes about dates are important when dealing with date effective tables:

A “NULL” date, meaning that there is no beginning to the timeslice where a value is valid is
represented in Dynamics AX as 1/1/1900. Due to peculiaritieis in the way in which this date is
handled in Excel, the date will be changed to 1/2/1900 when read. There is additional
information on Excel’s handling of 1/1/1900 in KB 245104 at
http://support.microsoft.com/kb/245104.

A record that never expires in a date effective table is set to 12/31/2154.
Inheritance
Dynamics AX 2012 introduces a concept of inheritance in the data model and this concept is
exposesd in the Excel Addin. Below is a screenshot of the DirPartyTable table as it is shown
in the field chooser. A Party has many subtypes, each of which is shown in the field
chooser: People, Internal/External organizations, Legal Entites, etc. The Party Type field is a
special enumeration that indicates the actual type of that row. Rows in the spreadsheet can
represent different types as shown below.
Dimensions
Financial dimensions are modeled in Dynamics AX as references to various dimension tables
using different EDTs such as “LedgerDimension” or “DimensionDefault”. Each of these
references results in a series or orderd dimension attributes which makes up the value for
12
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
that particular field. Examples of how these different EDTs are represented within the field
chooser are shown below.
The containing node, for example “LedgerDimension” above represents the entire
concatenated account number. The individual segments, or attributes, are listed beneath
each dimension. In this way, either the complete account number (for example: 60001-123)
or the individual segments (600001, 123) can be associated with a single column in a
spreadsheet. Examples of this are shown below as seen in the general ledger service.
Following are some key concepts around using dimensions in the Excel add-in:

The segmented field is read-only. If you enter data directly into it it will be lost and overridden
by the individual dimension attribute fields.
13
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA

The dimension attribute descriptions cannot be included on the worksheet. The only way the
account name or name of the dimension can be seen is within the field lookup control.

Account rules and advanced account rules are not adhered to in the data entry experience. For
example, in the AX client or Enterprise portal, the valid set of dimension attributes will be
driven by the values of the individual segments. This is not the case in excel. If additional
segments are required outside of those within the account structure, they will need to be
typed in the worksheet directly.
Error Handling
When a publish action is performed, the add-in will call the proper methods on the relevant
AIF document services to send update, create, and delete actions to the AOS. Each change
that was made since the data was refreshed will result in a call to a service. If any errors
are returned from calling these methods, they are listed on a worksheet within the
workbook called “Dynamics AX Status”.
The records that failed to be sent will remain in the workbook in the erroneous state. The
user may then make adjustments to the failed records and publish again until all records are
successfully sent.
Error propogation from the service must be enabled in the inbound port where the service is
activated for this functionality to work. To do this, verify the setting in System
Administration->Setup->Services and Application Integration Framework->Inbound Ports
shown below:
14
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
Serialization
All queries, service references, data bindings, matrix fields, filters, port references,
connection information, and the current snapshot of which records have been updated,
created and deleted are stored within the workbook upon workbook save. As such, future
changes to the data model or dimensional structure of AX will not be reflected in document
templates which have been previously built.
Limitations and common pitfalls
This section lists some limitations and helpful tips when using the Excel Add-in.
1. Update is for Services and Tables: The “refreshable export” or query-based capabilities of
the office add-ins are for reading and refreshing data only, not for updating data. So, for
example, if you wish to export a list page to excel, make some changes to that data and send
the updates back to AX, you will need to use a service and add a specific action to the form to
enable this sort of scenario. The “export to excel” functionality cannot be used for this
scenario.
2. Queries and Services must be activated: Queries and services will only be displayed in the
“Add Data” dialog if they have been added to the list of valid data sources in Organization
Administration->Setup->Document Management->Add Data Sources. Any services that are
named in this dialog must also be activated in AIF at
3. Table access is for Admin only: The Excel Add-in has an option to read and write directly to
AX tables. Due to security concerns, this capability is only available to those in the
Administrator role. To enable updating of data for end users, an AIF document service must be
used – either one that is included in the product, or one that has been added as a
customization. Services enable role-based security to be enforced.
4. Services must comply with restrictions: Only AIF Document services are supported in the
Excel Add-in. Services that are built based on data contracts are not supported in this release.
Additionally, there are several restrictions as to how the service must be constructed in order
to use the service. These restrictions will be described in an accompanying document along
with the list of which services that are included with the product will work without
modification.
5. Not all tables are supported: Table-based import/export is available only for tables which
do not externally expose rec-id relationships. This means that tables must have a visible
Primary Index, or specify a visible Replacement Key in order to be supported. In addition, all
referenced tables must also meet these restrictions.
6. Refreshable Queries require configuration: To enable the refreshable Export to Excel
feature, you must explicitly enable it in the Dynamics AX Client by going to File->Options and
setting the “Workbook supports refresh” option to “When Possible”.
15
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
7. Working with Data: When the “Field Chooser” is open, you may add and remove fields to
the workbooks. Once closed, you can read, update and publish changes. You must explicitly
switch between these two modes by opening and closing the Field Chooser pane.
Getting Started – A step by step guide
The following steps guide you from a newly installed deployment through basic usage of the
Office Add-ins.
1. Setup: When running setup, select the “Office Addins” component from the list of
components. After running setup, open up Microsoft Word or Microsoft Excel and verify that
there is a “Dynamics AX” tab added to the ribbon interface.
a. Go-Live Note: You may need to verify the correct version of VSTO is used and
possibly modify the registry as per connect issue 669371.
b. Register Services: During the initial setup of Dynamics AX, perform the “Set up
Application Integration Framework” step of the installation checklist. If you have
completed this checklist without perfomringn this step, you can return to it at System
Administration->Setup->Checklists->Initialization Checklist.
Go-Live Note: In the go-live build, this functionality is located in the Inbound
Ports form (System Administration->Setup->Services and Application
Integration Framework->Inbound ports). Once there, use the “Register
services” and “Register adapters” buttons.
2. Deploy Services: Services which have Create or Update methods can be used to modify data
in excel. In order to use the services, you must first add them to an AIF Services port and
activate the port using the following steps:
a. Create Port: Create a new port using the “New” button on the action strip, give the
port a name and description
b. Add the service: In the Service contract customizations fast tab, press “service
operation constraints” and add the desired services
c. Configure options: On the “Trobule shooting” fast tab, set the Logging mode to “Log
All” and check the “propagate errors” checkbox
d. Activate Port: Press “Activate” on the action strip to activate the port
3. Expose Services and Queries: Open Organization administration->Setup->Dcument
management->Document data sources. For any queries or services that you wish to expose to
the Office add-ins, select the proper query and/or service, and check the activate box.
4. Select data source in Excel: Open excel, and press the “Add Data” button on the Dynamics
AX tab of the ribbon. You should see the queries and services that were exposed in step 3
above. Select the data you wish to incorporate into the spreadsheet, for example, “Budget
Register entries”.
5. Add field references: position the cursor in the cell where you wish to place data and
double-click on fields in the field chooser to add fields to the worksheet. Note that all required
fields and key fields must be added if you are working with a service and wish to create new
records.
6. Add filters: Appropriately filter the data selection you wish to view using the “Filter” button
on the ribbon.
7. Close Field Chooser: Close the field chooser using the “Field Chooser” icon on the ribbon.
8. Refresh data: Press the “Refresh All” button in the ribbon. The data from the service or query
is read and filtered according to the filter and placed in the sheet.
9. Make Changes: Make and adjustments, additions, or creations to the dataset.
16
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
10. Publish Data: Press the “Publish data” button, which will send all changes in the data set
back to Dynamics AX using the chosen service.
Supported AIF Services
There are two types of WCF-based services in Dynamics AX 2012: Document Services
(those based on Axd framework) and Data-contract-based. The Excel add-in only works with
Document Services. Document Services are based on a query which defines their structure.
Only certain query structures are supported. Following are the restrictions on queries that
form the basis of document services. Services which violate these rules may be added to
the document data sources form by the administrator, but will result in the following errors
when accessed in the add-in. For this reason it is important that developers and
administrators test services for use with the add-in prior to adding them to this form.

Replacement Keys: The root level of the document service must have unique indexes other
than Rec-ID. This may be in the form of a non-recid Primary Index or a Replacement Key.

Related Replacement Keys: Each field within the service which is a rec-id-based foreign key
must relate to a table that has a replacement key specified.

Relationship Direction: When parent-child relationships exist in the underlying query
associated with the service, only relationships originating on the child element, and pointing to
the parent may be used. For example, in the custCustomerService, the custTable parent data
sources holds a foreign key to the dirParty child data source. This pattern is not supported in
the Excel Add-in.

Query and Service consistency: Document services are based on an underlying query
which defines the data contract used in the service at the time that the service is generated.
The Excel Add-in uses this query definition to perform read operations when refreshing data
into the workbook. Because of this, any overrides to the read method, or extension of the
schema beyond what is in the underlying query will not be reflected in the service.

View Support: Views may be used within document services to provide an easier to use data
model for end users. However, the PrepareForXXXExtended methods must be implemented to
properly handle information sent to the service within the views. Views may only be used as
the “leaf” level node in the underlying query. For instance if there is a query “Parent, child,
grandchild”, then only the grandchild node can be a view.
The above restrictions impact many services that are included with Dynamics AX. For some
of the more common services (particularly global address book services) we will be
providing resource kits to address importing these structures into Dynamics AX. The
following table picks out a few of the common errors on commonly requested services and
discusss the reasoning behind these errors. A more comprehensive guide to successfully
developing services for use with the office addins will be provided at a later date.
Example Errors using services
Service
Error
BillOfMaterials Invalid
Keys
Error Text
Cannot load
[AxdBillsOfMaterials]. The data
source [BOMVersion] does not
have a valid replacement key
or a primary index other than
rec-id.
Analysis
The root of the
underlying query has
no visible means of
identifying it as
“recid” is the only
unique index.
17
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
CustService
Invalid
Relation
within the
service
The relation between data
source CustTable and data
source DirParty contains an
unsupported RecId relationship
ExchangeRate
Invalid
relation
outside the
service
The relation between data
source CurrencyPair and data
source RateType contains an
unsupported RecId relationship
VendTable
Invalid
Relation
within the
service
The service
[VendTableService] has
surrogate foreign key
expansion errors:
The table [VendTable]
surrogate foreign key field
[Party] does not have a
reference data source.
The “Parent” data
source custTable
references child data
source dirParty. Child
data sources must
reference the parent
for use with excel
addin.
The field
“CurrencyPair” is a
rec-id-based relation
to an extneral table
“Rate Type”, and rate
type has no
replacement key
specified.
The “Parent” data
source vendTable
references child data
source dirParty. Child
data sources must
reference the parent
for use with excel
addin.
List of supported services
Only the following services as shipped in Microsoft Dynamics AX 2012 are supported without
modification in the Excel Add-in. Additional services meeting the above requiements can be
constructed in order to extend the scenarios where excel can be used to update, create, and
delete business data in Dynamics AX.
BudgetTransaction, EMSMeterReading, EMSSubstanceFlow, GenerlJournal,
ProductionPickingList, ProjectHourJournalS, SysImportBusSector, VendGroup,
VendRequestSignup
Supported tables
Not all tables presented in the “Add tables” dialog may be used with the Excel add-in, rather
only those which meet the following requirements:

Visible Identity: There must be a unique index on the table which does not contain recID as
a component. This may be either the “Replacement Key”, or the “Primary Index”

Valid References: All relations in the relations collection for the table that refer to other
tables via rec-id must be related to tables that have a “Replacement Key” specified.
Tips for events
The following list summarizes DOs and DON'Ts to consider when working with the excel add-in.
18
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
Do

Only add tested services and queries to the document data sources form

Ensure that all services have proper identity, error handling, field selection and security before
exposing them to end users

Run imcremental compilations and refresh caches while working iteratively designing services for
use with the office add-ins
Don’t

Use the Excel Add-in for extremely high volume or large documents in interactive mode
19
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA
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
www.microsoft.com/dynamics
This document is provided “as-is.” Information and views expressed in this document, including URL and other
Internet Web site references, may change without notice. You bear the risk of using it.
Some examples depicted herein are provided for illustration only and are fictitious. No real association or
connection is intended or should be inferred.
This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You
may copy and use this document for your internal, reference purposes. You may modify this document for your
internal, reference purposes.
 Microsoft Corporation. All rights reserved.
Microsoft, Microsoft Dynamics, and the Microsoft Dynamics logo are trademarks of the Microsoft group of
companies.
All other trademarks are property of their respective owners.
20
USING THE EXCEL ADD-IN TO UPDATE AND IMPORT DATA