Walkthrough: Transforming a document

Article
11/29/2021

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

This walkthrough describes how to use a transform in an inbound port to reformat an incoming sales order request to work with the Microsoft Dynamics AX sales order service.

For this scenario, the incoming request is an XML-based document. In a previous walkthrough, the inbound document was already formatted to comply with the Microsoft Dynamics AX sales order schema. In this walkthrough, you create a different inbound document that uses a custom schema. You will then provide an Extensible Stylesheet Language Tranformation (XSLT) to map the elements from the inbound document to the elements that are required by the sales order schema. Finally, you will submit the incoming document to Application Integration Framework (AIF) and view the results.

Prerequisites

Completion of the Walkthrough: Exchanging documents by using the file system adapter topic.

Creating the sales order request

For this scenario, the incoming sales order request document, the internal sales order, uses the following Extensible Stylesheet Definition (XSD) schema. You do not need to save a copy of this schema. It is presented here for your information.

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns="http://InternalSalesOrder" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="SalesOrder">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Header">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="CustAccountNum" type="xs:string" />
              <xs:element name="DateReq" type="xs:date" />
              <xs:element name="OrderDate" type="xs:date" />
              <xs:element name="PONum" type="xs:string" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Items">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Item">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="ID" type="xs:string" />
                    <xs:element name="Qty" type="xs:nonNegativeInteger" />
                    <xs:element name="Unit" type="xs:string" />
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

The following XML code creates an example of a document that complies with the XSD for the internal sales order. Save a copy of this file and name it InternalSO.xml.

<?xml version="1.0" encoding="utf-8" ?>
<?xml-stylesheet type="text/xsl" href="InternalSO.xslt"?>
<ns0:SalesOrder xmlns:ns0="http://InternalSalesOrder">
  <Header>
    <CustAccountNum>100002</CustAccountNum> 
    <DateReq>2011-05-30</DateReq>
    <DeliveryDate>2011-05-31</DeliveryDate> 
    <OrderDate>2011-05-01</OrderDate> 
    <PONum>P0</PONum> 
    <MessageId>{5FC77A8F-67D2-4BF1-A671-FF5A81EF0DDC}</MessageId>
  </Header>
  <Items>
     <Item>
       <ID>10003</ID> 
       <Qty>10</Qty> 
       <Unit>Pcs</Unit> 
     </Item>
  </Items>
</ns0:SalesOrder>

You must modify the internal sales order document:

Provide values that work in your test environment. For example, provide valid values for <CustAccountNum> and <ID>.
Provide a unique GUID value for <MessageId>.

Note

This scenario assumes that the internal sales order request contains a message ID that is formatted as a GUID. If your actual internal document does not contain a message ID, you may want to generate your own GUID. The value cannot be generated by XSLT, so you must provide some other facility to preprocess your source document to create the message ID. If you do not provide a message ID, one will be created for you by AIF and it will be included in the response message. However, because this interaction is asynchronous, you will not be able to use the AIF value to match response messages to request messages.

Creating the transform

For this scenario, use the following XSLT code. Copy the code to Notepad and name the file InternalSO.xslt when you save it.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:InternalSO="http://InternalSalesOrder">
  <xsl:template match="InternalSO:SalesOrder">
    <Envelope xmlns="https://schemas.microsoft.com/dynamics/2011/01/documents/Message">
      <Header>
        <MessageId>
          <xsl:value-of select="Header/MessageId"/>
        </MessageId>
        <Action>https://schemas.microsoft.com/dynamics/2008/01/services/SalesOrderService/create</Action>
      </Header>
      <Body>
        <MessageParts>
          <SalesOrder xmlns="https://schemas.microsoft.com/dynamics/2008/01/documents/SalesOrder">
            <SalesTable class="entity">
              <CustAccount>
                <xsl:value-of select="Header/CustAccountNum"/>
              </CustAccount>
              <DeliveryDate>
                <xsl:value-of select="Header/DeliveryDate" />
              </DeliveryDate>
              <PurchOrderFormNum>
                <xsl:value-of select="Header/PONum" />
              </PurchOrderFormNum>
              <ReceiptDateRequested>
                <xsl:value-of select="Header/DateReq" />
              </ReceiptDateRequested>
              <SalesLine class="entity">
                <ItemId>
                  <xsl:value-of select="Items/Item/ID" />
                </ItemId>
                <SalesQty>
                  <xsl:value-of select="Items/Item/Qty" />
                </SalesQty>
                <SalesUnit>
                  <xsl:value-of select="Items/Item/Unit" />
                </SalesUnit>
              </SalesLine>
            </SalesTable>
          </SalesOrder>
        </MessageParts>
      </Body>
    </Envelope>
  </xsl:template>
</xsl:stylesheet>

The previous XSLT above this paragraph uses a template to create the AIF message envelope and then maps the elements that are contained in the internal sales order document to the elements that are required by the Microsoft Dynamics AX sales order schema. (Recall that, in the previous walkthrough, the sales order schema that was used by the inbound port was specified in the Document data policies form.) The XSLT adds the <Action> element to specify the create action for the sales order.

Add the transform

To use the transform, you first must add the transform file to the list of available transforms by using the Manage transforms form.

Click System administration > Setup > Services and Application Integration Framework > Inbound ports.
Deactivate the integration port named SalesOrderCreate, if it is still active. (You created this integration port in the previous walkthrough.)
Click Inbound transforms. Then, on the Action Pane, click Manage transforms.
Click New.
In the Name field, type the name, InternalSO. Optionally, enter a description.
In the Type list, select XSL.
Click Load.
In the Open dialog box, change the file specification to XSLT files. Browse to the file that you named InternalSO.xslt. Click Open to load the file.

You can view the XML code in the Content text box.
Close the form to save the new transform.

Configure the integration port

Add the inbound transform to the integration port.

In the Inbound transforms form, click New.
In the Transform name list, select InternalSO.
Activate the port.
Close the forms.

Send the request and view the response

Because this scenario uses the integration port that you created in Walkthrough: Exchanging documents by using the file system adapter, you will use the same directories for inbound and outbound communication.

Save a copy of the file that you named InternalSO.xml to the folder named AIFIn.
Wait for the batch job to retrieve the file from the folder.
Watch the folder named AIFOut. After several minutes, AIF will save a response file to this folder.
Open the response file to view the XML code.