Update Action Rules in AIF

Update Action Rules in AIF

Microsoft Dynamics AX 2009

This topic describes the rules for updating data in Application Integration Framework (AIF). AIF services support updating data so companies can implement data synchronization with systems external to Microsoft Dynamics AX. Update functionality is exposed through the update service operation. Each document service that is included with Microsoft Dynamics AX that supports data updates has an update service operation. AIF supports two types of updates:

Full update - All the data submitted to AIF is considered to be the full document and all fields in the database tables will be updated with the fields from the submitted document. If there are fields in the table that are not in the submitted data, those table fields will be cleared according to the rules for the data type of the field.

The result of a full update is the same as if you deleted the record and then added it from the submitted data with the following exceptions:
- Primary key fields are not changed.
- Fields that are allowed by the schema but not included in the submitted data are cleared.
- Fields that are not allowed by the schema and therefore cannot be sent as part of the update message are defaulted if they have defaulting logic but are not affected otherwise.
For more information about full updates, see Walkthrough: Updating Data with AIF (Full Update).

Partial update - Only the fields contained in the submitted message will be updated in the database tables. If there are fields in the table that are not in the submitted data, those field values will retain their original values (except for fields that are defaulted based on other fields that have been updated).

Microsoft Dynamics AX 2009 SP1 introduces different functionality for the partial update. If a message contains a field and the value for that field is NULL, then AIF will not update the table field with a NULL but will, instead, leave the field value in the table as it is. If you are using SP1 and send a NULL value for a field, the result is the same as if the field was not in the message. There are now three possible scenarios for the partial update:

Message field	The field in the table….
The field is not in the message.	remains untouched.
The field is in the message and a NULL value is specified (for example, <Field>xsi:nil</Field>).	remains untouched.
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.	is changed to reflect the specified value.

Even though the message schema specifies that a field is nullable, in a partial update, the null value is interpreted to mean that the field should be left untouched. In the version prior to SP1, this scenario would cause AIF to update the table field with a NULL.

Whether you are issuing a full or partial update, you must first read the data from the Microsoft Dynamics AX database. This is necessary because AIF uses concurrency control to determine whether the records being updated have already been changed by another user. For more information about concurrency control in AIF, see Concurrency When Updating Data. After reading the data, you must submit an XML message that sends the data to be updated into AIF.

For both full and partial updates, the header of the update message must specify the update action as shown in the following code. For more information about message schemas, see AIF Messages.

<?xml version="1.0" encoding="utf-8" ?>
<Envelope xmlns="http://schemas.microsoft.com/dynamics/2008/01/documents/Message">
    <Header>
<Action>http://schemas.microsoft.com/dynamics/2008/01/services/CustomerService/update</Action>
    </Header>
    <Body>
...
    </Body>
</Envelope>

Setting Fields to NULL

If you do not have SP1 installed, you use the update action attribute, and you want to specify that a field should be NULL, you must include the field element in the message and use the nil attribute as shown in this code example:

<CreditMax xsi:nil="true"/>

If you have SP1 installed and you want to specify that a field should be NULL, the field must be in the message and you must send in the X++ NULL value for the field based on its data type. For more information about X++, XML, and .NET data type conversions, see AIF Services and Primitive Data Type Conversions for XML and .NET Framework.

Action Attributes

In addition to specifying the update action in the header, data submitted for updating data can also use the action attributes. These attributes are specified at the table level in the message, and they specify how the individual records should be handled by the update as shown in the following table.

Action attribute	Description
`create`	Creates the record in the database. The new record is created with the field values from the record in the message. Any table fields not in the message will be defaulted according to the field data type and the table defaulting logic. You cannot put the `create` attribute on the root table because only child records can be created.
`update`	Updates the record in the database. The `update` action attribute specifies that only the fields that are contained in the message will be updated; other database field values remain. The `update` action attribute can be at the root-level table or at a child-level table. If the `update` action attribute is specified for a top-level record, then all the child records must have an action attribute of one of these values: `create`, `delete`, or `update`.
`replace`	Replaces the record with the values in the message. If a field is in the database table but is not in the message, the field will not be defaulted. The replace action attribute must be at the root-level table because only parent records can be replaced. If the top-level table has the `replace` attribute, no other records can have an attribute. If the parent record has the `replace` attribute and the child records contain any of the update action attributes, an error is generated. Using the `replace` action attribute indicates a full update and is the same as specifying the `update` action in the header and no action attributes in any of the records.
`delete`	Deletes the record in the database. Only records in child tables can be deleted.

Full Update

A full update is one in which all the data fields are in the submitted message. If an element is in the table (the schema) but the corresponding data element is not in the submitted XML, then the table field is cleared according to the rules for the data type of the field. A full update is specified in one of two ways:

The presence of the update action in the message header and no other update attributes in any of the records.
The presence of the update action in the message header and the top record in the submitted data contains the replace action attribute.

Child Data

When performing a full update, there are certain rules that AIF follows with regard to child data; for example, if you are updating a customer and the customer addresses (the child records of the customer record).

For example, if a customer who has one address exists in the database and the message that is submitted for update contains:

The customer data
One address that matches the existing address in the database
One address that does not match an existing address in the database

AIF will:

Update the customer
Update the first address
Create the second address in the database

In the previous scenario, the field values for the record that is created will come from the fields in the submitted message; any table fields that are not in the submitted message will be cleared according to the rules for the field's data type.

If a customer who has three addresses exists in the database and the message that is submitted for update contains:

The customer data
Two addresses that match existing addresses in the database

AIF will:

Update the customer
Update the two matching addresses
Delete the third address from the database

Full Update XML

The following is an example of an XML message that could be sent into AIF to update a customer and the customer address.

<?xml version="1.0" encoding="utf-8" ?> 
<Envelope xmlns="http://schemas.microsoft.com/dynamics/2008/
    01/documents/Message">
    <Header>
        <Action>http://schemas.microsoft.com/dynamics/2008/
            01/services/CustomerService/update</Action>
    </Header>
    <Body>
        <MessageParts xmlns = "http://schemas.microsoft.com/dynamics/2008/
            01/documents/Message">
            <EntityKeyList xmlns = "http://schemas.microsoft.com/dynamics/
                2006/02/documents/EntityKeyList">
              <EntityKey xmlns = "http://schemas.microsoft.com/dynamics/2006/
                  02/documents/EntityKey">
                 <KeyData>
                    <KeyField>
                        <Field>AccountNum</Field>
                        <Value>4507</Value>
                    </KeyField>
                </KeyData>
            </EntityKey>
            </EntityKeyList>
            <Customer xmlns="http://schemas.microsoft.com/dynamics/2008/
                01/documents/Customer">
                <DocPurpose>Original</DocPurpose>
                <SenderId>DAT</SenderId>
                <CustTable class="entity">
                  <_DocumentHash>bfcfbcd4fcc592c0c9fe693c5f811dbd
                      </_DocumentHash>
                  <AccountNum>4507</AccountNum>
                  <AccountStatement>Always</AccountStatement>
                  <Address>7212 9th Street Fargo, ND 58102 US</Address>
                  <Blocked>No</Blocked>
                  <CashDisc>5D2%</CashDisc>
                  <City>Fargo</City>
                  <CountryRegionId>US</CountryRegionId>
                  <County>Cass</County>
                  <Currency>USD</Currency>
                  <CustGroup>40</CustGroup>
                  <ForecastDMPInclude>No</ForecastDMPInclude>
                  <GiroType>None</GiroType>
                  <GiroTypeCollectionletter>None
                      </GiroTypeCollectionletter>
                  <GiroTypeFreeTextInvoice>None
                      </GiroTypeFreeTextInvoice>
                  <GiroTypeInterestNote>None
                      </GiroTypeInterestNote>
                  <GiroTypeProjInvoice>None</GiroTypeProjInvoice>
                  <InclTax>No</InclTax>
                  <InterCompanyAllowIndirectCreation>No
                      </InterCompanyAllowIndirectCreation>
                  <InterCompanyAutoCreateOrders>No
                      </InterCompanyAutoCreateOrders>
                  <InterCompanyDirectDelivery>No
                      </InterCompanyDirectDelivery>
                  <InvoiceAddress>InvoiceAccount</InvoiceAddress>
                  <LanguageId>En-us</LanguageId>
                  <MandatoryCreditLimit>No</MandatoryCreditLimit>
                  <Name>Northwind Traders</Name>
                  <NameAlias>NW Traders</NameAlias>
                  <OneTimeCustomer>No</OneTimeCustomer>
                  <PartyId>1318</PartyId>
                  <PartyType>Organization</PartyType>
                  <PaymTermId>D30</PaymTermId>
                  <RecId>5637144604</RecId>
                  <RecVersion>1</RecVersion>
                  <RFIDCaseTagging>No</RFIDCaseTagging>
                  <RFIDItemTagging>No</RFIDItemTagging>
                  <RFIDPalletTagging>No</RFIDPalletTagging>
                  <ShipCarrierBlindShipment>No
                      </ShipCarrierBlindShipment>
                  <ShipCarrierFuelSurcharge>No
                      </ShipCarrierFuelSurcharge>
                  <State>ND</State>
                  <Street>7212 9th Street</Street>
                  <WebSalesOrderDisplay>WebEntered
                      </WebSalesOrderDisplay>
                  <ZipCode>58102</ZipCode>
                  <AddressRelationship class="entity">
                    <IsPrimary>Yes</IsPrimary>
                    <PartyId>1318</PartyId>
                    <RecId>5637144837</RecId>
                    <RecVersion>1</RecVersion>
                    <Shared>Yes</Shared>
                    <AddressRelationshipMap class="entity">
                      <AddressRecId>5637145087</AddressRecId>
                      <PartyAddressRelationshipRecId>5637144837
                          </PartyAddressRelationshipRecId>
                      <RecId>5637145068</RecId>
                      <RecVersion>1</RecVersion>
                      <RefCompanyId>dat</RefCompanyId>
                      <CustAddress class="entity">
                        <Address>7212 9th Street Fargo, ND 58102 US</Address>
                        <AddrRecId>5637145128</AddrRecId>
                        <AddrTableId>2303</AddrTableId>
                        <City>Fargo</City>
                        <CountryRegionId>US</CountryRegionId>
                        <County>Cass</County>
                        <RecId>5637145087</RecId>
                        <RecVersion>1</RecVersion>
                        <ShipCarrierBlindShipment>No
                            </ShipCarrierBlindShipment>
                        <ShipCarrierResidential>No
                            </ShipCarrierResidential>
                        <State>ND</State>
                        <Street>7212 9th Street</Street>
                        <TimeZone xsi:nil="true" xmlns:xsi="http://
                            www.w3.org/2001/XMLSchema-instance"/>
                        <type>Invoice</type>
                        <ZipCode>58102</ZipCode>
                      </CustAddress>
                    </AddressRelationshipMap>
                  </AddressRelationship>
                  <AddressRelationship class="entity">
                    <IsPrimary>No</IsPrimary>
                    <PartyId>1318</PartyId>
                    <RecId>5637144839</RecId>
                    <RecVersion>1</RecVersion>
                    <Shared>No</Shared>
                    <AddressRelationshipMap class="entity">
                      <AddressRecId>5637145089</AddressRecId>
                      <PartyAddressRelationshipRecId>5637144839
                          </PartyAddressRelationshipRecId>
                      <RecId>5637145070</RecId>
                      <RecVersion>1</RecVersion>
                      <RefCompanyId>dat</RefCompanyId>
                      <CustAddress class="entity">
                        <Address>111 5th Street Baltimore, 
                            MD 21210 US</Address>
                        <AddrRecId>5637144604</AddrRecId>
                        <AddrTableId>77</AddrTableId>
                        <City>Baltimore</City>
                        <CountryRegionId>US</CountryRegionId>
                        <County>Baltimore</County>
                        <DlvMode>U11A</DlvMode>
                        <DlvTerm>TERMNA3RD</DlvTerm>
                        <Name>Jane Smith</Name>
                        <RecId>5637145089</RecId>
                        <RecVersion>1</RecVersion>
                        <ShipCarrierAccount>234-456
                            </ShipCarrierAccount>
                        <ShipCarrierAccountCode>UPS
                            </ShipCarrierAccountCode>
                        <ShipCarrierBlindShipment>No
                            </ShipCarrierBlindShipment>
                        <ShipCarrierID>U11A</ShipCarrierID>
                        <ShipCarrierResidential>No</ShipCarrierResidential>
                        <State>MD</State>
                        <Street>111 5th Street</Street>
                        <TimeZone xsi:nil="true" xmlns:xsi="http://
                            www.w3.org/2001/XMLSchema-instance"/>
                        <type>ShipCarrierThirdPartyShipping</type>
                        <ZipCode>21210</ZipCode>
                      </CustAddress>
                    </AddressRelationshipMap>
                  </AddressRelationship>
                </CustTable>
            </Customer>
        </MessageParts>
    </Body>
</Envelope>

Partial Update

In a partial update, in addition to required fields that must always be present, only the data that is to be updated is contained in the inbound message. All the other field values that are not contained in the inbound update request message remain unchanged in the database table unless there is some defaulting logic. For example, there may be a FullName field that is defaulted from the FirstName and LastName fields. If the FirstName field is in the submitted data and has changed and the FullName field is not in the submitted data, then the FullName field in the table will be updated by the defaulting logic to reflect the change to the FirstName field.

The inbound message for a partial update must contain the entity key of the record to be updated in addition to the data to be updated. In the following XML, the record entity key is contained in the EntityKeyList tags.

The signature for the update service operation is: void update(EntityKey[], <DocumentObject>), where the <DocumentObject> contains one or more tables (for example, SalesTables or CustTables). The number of tables in the <DocumentObject> parameter and the length of the EntityKey array must match and the EntityKey[n] must reference the corresponding table in the <documentType> parameter.

A partial update has the update action in the header and for each record in the message contains one of the action attributes (see previous table).

For example, if you pass in a message to update the customer, you can use attributes to specify that the following updates should occur as shown in the following XML message:

The customer record should be updated
A customer address should be updated
A new customer address should be created
A customer address should be deleted

<?xml version="1.0" encoding="utf-8" ?> 
<Envelope xmlns="http://schemas.microsoft.com/dynamics/2008/
    01/documents/Message">
    <Header>
        <Action>http://www.microsoft.com/dynamics/services/2008/
            01/CustomerService/update</Action>
    </Header>
    <Body>
        <MessageParts xmlns = "http://schemas.microsoft.com/dynamics/2008/01/documents/Message">
 
        <EntityKeyList xmlns="http://schemas.microsoft.com/dynamics/
            2006/02/documents/EntityKeyList">
            <EntityKey xmlns="http://schemas.microsoft.com/dynamics/
                2006/02/documents/EntityKey">
                <KeyData>
                    <KeyField>
                        <Field>AccountNum</Field>
                        <Value>4507</Value>
                    </KeyField>
                </KeyData>
            </EntityKey>
  </EntityKeyList>
 
            <Customer xmlns="http://schemas.microsoft.com/dynamics/
                2008/01/documents/Customer">
                <DocPurpose>Original</DocPurpose>
                <SenderId>DAT</SenderId>
                <CustTable class="entity" action="update">
                    <AccountNum>4507</AccountNum>
                    <CreditMax xsi:nill="true"/>
                    <CustGroup>40</CustGroup>
                    <PartyType>Organization</PartyType>
                    <RecId>5637144604</RecId>
                    <RecVersion>779953820</RecVersion>
                        <CustAddress class="entity" action="update">
                            <AddrRecId>5637144604</AddrRecId>
                            <AddrTableId>77</AddrTableId>
                            <DlvMode>AIR</DlvMode> 
                            <RecId>5637145089</RecId>
                            <RecVersion>1</RecVersion>
                        </CustAddress>
                        <CustAddress class="entity" action="create">
                            <Address>2100 5th Street Baltimore, MD 
                                21210 US</Address>
                            <AddrTableId>77</AddrTableId>
                            <City>Baltimore</City>
                            <CountryRegionId>US</CountryRegionId>
                            <County>Baltimore</County> 
                            <DlvMode>U11A</DlvMode>
                            <DlvTerm>TERMNA3RD</DlvTerm>
                            <Name>Molly Clark</Name>
                            <ShipCarrierAccount>234-45678
                                </ShipCarrierAccount>
                            <ShipCarrierAccountCode>UPS
                                </ShipCarrierAccountCode>
                            <ShipCarrierBlindShipment>No
                                </ShipCarrierBlindShipment>
                            <ShipCarrierID>U11A</ShipCarrierID>
                            <ShipCarrierResidential>No
                                </ShipCarrierResidential>
                            <State>MD</State>
                            <Street>2100 5th Street</Street>
                            <TimeZone>GMTMINUS0800PACIFICTIME
                                </TimeZone>
                            <type>AltDlv</type>
                            <ZipCode>21210</ZipCode>
                    </CustAddress>
                    <CustAddress class="entity" action="delete">
                        <RecId>5637145099</RecId>
                        <RecVersion>1</RecVersion>
                    </CustAddress>
                </CustTable>
            </Customer>
        </MessageParts>
    </Body>
</Envelope>

The following action attributes specify the associated updates:

<CustTable class="entity" action="update"> - specifies that the customer should be updated.
<CustAddress class="entity" action="update"> - specifies that the address should be updated.
<CustAddress class="entity" action="create"> - specifies that the address should be created.
<CustAddress class="entity" action="delete"> - specifies that the address should be deleted.

Valid Update Attribute Combinations

If a message contains the update action in the header, the following three scenarios are the only valid combinations of update attributes:

No attributes - Specifies a full update. This is the same as using the replace attribute at the top level.
The replace attribute at the top-level table - Specifies that all records will be replaced. If any child records specify any other attributes, an error will be generated.
The update attribute at the top-level table - Specifies that the record will be updated. All the child records must have either a create, update, or delete attribute.

Setting Fields to NULL

If you do not have SP1 installed, you have used the update action attribute, and you want to specify that a field should be NULL, you must include the field element in the message and use the nil attribute as shown in this code example:

<CreditMax xsi:nil="true"/>