Partial Update With AIF
Important
This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.
Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
Note
This topic has been updated to include information about features that were added or changed for Microsoft Dynamics AX 2012 R2.
This topic describes partial updates for data in Microsoft Dynamics AX using Application Integration Framework (AIF). The partial update options are illustrated by using messages for an asynchronous exchange. For more information about messages, see Messages and transforms in AIF and AIF Messages. For more information about asynchronous exchanges, see Walkthrough: Exchanging documents by using the file system adapter and Walkthrough: Exchanging documents by using the MSMQ adapter.
AIF supports a partial update scenario where only the fields that are contained in the submitted message are updated in the corresponding database tables. If there are fields in these tables that are not specified in the message, the fields retain their original values. However, fields that are not specified in the submitted message, but are based on fields that have been updated, are set to default values according to their default rules. For example, consider a field FullName that is based on a combination of FirstName and LastName. If FirstName or LastName are changed in a partial update where FullName is not specified, FullName is also changed.
The following table lists the three possible scenarios for a partial update:
Message Field Entry |
Resulting Table Field Entry |
|---|---|
The field is not in the message. |
The table field remains unmodified. |
The field is in the message and a NULL value is specified (for example, <Field>xsi:nil</Field>). |
The table field remains unmodified. |
The field is in the message and contains one of these values: a value (for example, <Field>123</Field>, an empty tag (for example, <Field></Field>), or an X++ NULL value. |
The table field is changed to contain the specified value. |
Specifying a Partial Update
In a partial update, the inbound message includes only the data to be updated plus any fields required by the document. All the other field values that are not contained in the inbound update request message remain unchanged in the database tables, unless there is some default logic.
The signature for the update service operation is:
void update(EntityKey[], <DocumentObject>)
The <DocumentObject> parameter contains one or more elements (for example, SalesTable or CustTable). The number of tables that are contained in the document object must equal the length of the entity key array. The index of each entity key that is passed through the EntityKey[] parameter must correspond to the position of its corresponding table in the document object.
Specifying Action Attributes
A partial update specifies the update action in the header of the message. The action for each record to be updated is specified by one of the action attributes.
The following table lists the specific actions that can be performed by using the sales order document service to update SalesTable and SalesLine.
Attribute |
Description of Update Action |
|---|---|
<SalesTable class="entity" action="update"> |
The sales order header should be updated. |
<SalesLine class="entity" action="update"> |
A sales order line should be updated. |
<SalesLine class="entity" action="create"> |
A new sales order line should be created. |
<SalesLine class="entity" action="delete"> |
A sales order line should be deleted. |
Example XML
The following example creates a message to update a sales order with three sales lines: one to be updated, one to be created, and one to be deleted.
<?xml version="1.0" encoding="utf-8" ?>
<Envelope xmlns="https://schemas.microsoft.com/dynamics/2011/
01/documents/Message">
<Header>
<Action>https://www.microsoft.com/dynamics/services/2008/
01/SalesOrderService/update</Action>
</Header>
<Body>
<MessageParts xmlns = "https://schemas.microsoft.com/dynamics/2008/01/documents/Message">
<EntityKeyList xmlns="https://schemas.microsoft.com/dynamics/
2006/02/documents/EntityKeyList">
<EntityKey xmlns="https://schemas.microsoft.com/dynamics/
2006/02/documents/EntityKey">
<KeyData>
<KeyField>
<Field>CustAccount</Field>
<Value>10002</Value>
</KeyField>
</KeyData>
</EntityKey>
</EntityKeyList>
<SalesOrder xmlns="https://schemas.microsoft.com/dynamics/
2008/01/documents/SalesOrder">
<SalesTable class="entity" action="update">
<CustAccount>10002</CustAccount>
<_DocumentHash>d2394857bffgg23924718kxk2908zj3s</_DocumentHash>
<SalesLine class="entity" action="update">
<ItemId>4710003</ ItemId >
… data omitted …
<SalesQty>77</ SalesQty >
<SalesUnit>Pcs</ SalesUnit >
</SalesLine>
<SalesLine class="entity" action="create">
<ItemId>4710005</ ItemId >
… data omitted …
</SalesLine>
<SalesLine class="entity" action="delete">
<ItemId>4710001</ ItemId >
… data omitted …
</SalesLine>
</SalesTable>
</SalesOrder>
</MessageParts>
</Body>
</Envelope>
Note
The document hash value in the <_DocumentHash> tag is used for concurrency. You must specify either the document hash or the RecID and RecVersion fields for each record. You can retrieve these values from a prior read operation. For more information, see Concurrency When Updating Data.
Clearing Surrogate Foreign Keys in a Table
Note
This feature is only available if Microsoft Dynamics AX 2012 R2 or a later version is installed.
Document service queries often contain tables that are linked with a surrogate foreign key. Default behavior for a partial update using a document service is to leave fields unchanged if they are not specified in the update. In other words, if you do not specify any new values for the fields in the LogisticsPostalAddress table when updating fields for a Sales Order, those values remain the same after the partial update. However, you can clear surrogate foreign key fields by using the ClearNilFieldsOnUpdate property and xsi:nil attribute.
To clear the surrogate foreign key fields when you perform a partial update, you set values for a property and an attribute. You set the property ClearNilFieldsOnUpdate to True. You use the xsi:nil attribute to indicate that the fields in the LogisticsPostalAddress table have no content. For more information about the xsi:nil attribute, see Xsi:nil Attribute Binding Support.
The following example shows XML that clears the surrogate foreign key values for a Sales Order that has a CustAccount of 10002.
<?xml version="1.0" encoding="utf-8" ?>
<Envelope xmlns="<a href='https://schemas.microsoft.com/dynamics/2011/'>https://schemas.microsoft.com/dynamics/2011/</a>
01/documents/Message">
<Header>
<Action><a href='https://www.microsoft.com/dynamics/services/2008/'>https://www.microsoft.com/dynamics/services/2008/</a>
01/SalesOrderService/update</Action>
</Header>
<Body>
<MessageParts xmlns = "<a href='https://schemas.microsoft.com/dynamics/2008/01/documents/Message'>https://schemas.microsoft.com/dynamics/2008/01/documents/Message</a>">
<EntityKeyList xmlns="<a href='https://schemas.microsoft.com/dynamics/'>https://schemas.microsoft.com/dynamics/</a>
2006/02/documents/EntityKeyList">
<EntityKey xmlns="<a href='https://schemas.microsoft.com/dynamics/'>https://schemas.microsoft.com/dynamics/</a>
2006/02/documents/EntityKey">
<KeyData>
<KeyField>
<Field>CustAccount</Field>
<Value>10002</Value>
</KeyField>
</KeyData>
</EntityKey>
</EntityKeyList>
<SalesOrder xmlns="<a href='https://schemas.microsoft.com/dynamics/'>https://schemas.microsoft.com/dynamics/</a>
2008/01/documents/SalesOrder">
<ClearNilFieldsOnUpdate>true</ClearNilFieldsOnUpdate>
<SalesTable class="entity" action="update">
<CustAccount>10002</CustAccount>
<_DocumentHash>d2394857bffgg23924718kxk2908zj3s</_DocumentHash>
<CustomerRef>NewCustomerAccount</CustomerRef>
<LogisticsPostalAddress xsi:nil=”true”/>
</SalesLine>
</SalesTable>
</SalesOrder>
</MessageParts>
</Body>
</Envelope>