1. To-Increase Dynamics 365 for Finance & Operations
  2. Connectivity studio
  3. Design
  4. Set up documents
  5. Set up external documents - File based

Set up XML document

Use an XML document to exchange data in XML format without the need to code.

With a document of type XML, you can read data from or write data to an XML file.


Application Consultant Application Consultant Start Start Set up document - XML Set up document - XML Use an XML document to exchange data in XML format without the need to code.With a document of type XML, you can read data from or write data to an XML file.For more information on XML, refer to XML Tutorial. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. Click New. 4. Define a meaningful name for the document. Example: If the document is used for a sales integration, you can use names like 'Sales - Order' or 'Sales - Invoice'. In the Document field, type a value. Note: Best practice: In the document name, do not use the: - Application: Use the Application field to define the applicable application. - Document type: Use the Document type field to define the applicable document type. 5. In the Project field, enter or select a value. 6. Define the applicable application for the document. For an XML document, for example, select a 'Windows folder' or 'Files' application. In the Application field, enter or select a value. Note: You can only select an application that is defined for the applicable project. You can define project applications on the Projects page. 7. In the Document types field, select 'XML'. 8. Sub-task: Set properties. 9. Expand the Properties section. 10. In the Encoding field, enter or select a value. 11. Select Yes in the Without BOM field. 12. In the Process type field, select an option. 13. Namespaces are by default not supported by the Connectivity studio XML writer. However, a receiver of an XML file can expect namespaces. In this case, on write, you can have a namespace added to the XML document. In the Namespace field, you can define the namespace to be added to the XML file. Note: Using this option, you can only add one namespace to an XML file. 14. Sub-task: Set custom handler. 15. Expand the Custom section. 16. For an XML document, the standard handler class is 'BisDocumentXml'. This handler class reads data from or writes data to XML files. You can use a customized handler class. To do so, extend a standard handler class. In the Handler field, enter or select the desired handler class. Note: Select the 'BisDocumentXmlV3' handler, if you, on a message, use the XML document in combination with a connector of one of these types: - Web service - Blob storage - Upload and download - SharePoint 17. Sub-task: Set read options. 18. Expand the Read section. 19. In the Read filename field, type a value. 20. Select Yes in the Read only once field. 21. On running an applicable message, you can have a dialog shown with the data to be imported. You can review the data before it is actually imported. This can, for example, be useful when importing work breakdown structures, because you cannot easily undo the import. The dialog is only shown if you manually run the message. So, the dialog is not shown if you run the message in batch. Select Yes in the Validate input field. Note: If you use input validation, make sure the Process type is set to 'Query'. 22. Sub-task: Use read transformations. 23. You can receive XML files which structure differs from the structure as expected by Connectivity studio. In this case a transformation is required to restructure the XML file. This is done by applying XSLTs. Select Yes in the Read transformation field. Note: When a message is run to import an XML file to which XSLTs must be applied: 1. The original XML file is copied from the working folder to the archive folder with the '_org' addition to its name. 2. The XSLTs are applied to the XML file in the working folder. 3. The transformed XML file is processed by the message. 4. If the message is finished, the '_org' addition is removed from the original file's name in the archive folder. Note: If during processing the file an error occurred, the original file is moved from the archive to the error folder. 5. The transformed XML file is deleted from the working folder. 24. Click XSLT. 25. Click New. 26. In the XSLT ID field, type a value. 27. In the Description field, enter the purpose of the XSLT. 28. In the XSLT field, enter the XSLT code. Note: You can write the XSLT code here or write it in another editor and copy it here. 29. Click Import XSLT. 30. Click Add root tag. Note: If you receive an XML file with several records of the same entity, these records already have root tags. So, adding root tags is not needed. 31. Click Import XSLT. 32. Click Remove namespaces. 33. Close the page. 34. Sub-task: Set write options. 35. Expand the Write section. 36. Using a variable, you can add the value of two table fields to the filename. If you want to do so, define the applicable table. On write, this document is the target document. However, the file name is defined based on the root record values of the source document. So, make sure you select a table and table fields from the root record of the applicable source document. In the Table name field, enter or select a value. Note: You cannot use the table name itself as variable in the filename. 37. Define the first table field which value you want to add to the file name. The related variable is '%5'. In the First field field, enter or select a value. Note: You can only select a field from the defined table. 38. Define the second table field which value you want to add to the file name. The related variable is '%6'. In the Second field field, enter or select a value. Note: You can only select a field from the defined table. 39. In the Number sequence field, enter or select a value. 40. In the Write filename field, type a value. 41. Sub-task: Use write transformations. 42. With Connectivity studio, you write XML files in a specific structure. However, it can be that a different structure is required. In this case a transformation is required to restructure the XML file. This is done by applying XSLTs. Select Yes in the Write transformation field. Note: When a message is run to export an XML file to which XSLTs must be applied: 1. The message is run, and the XML file is created in the working folder. 2. The XSLTs are applied to the created XML file. 3. The transformed XML file stays in the working folder. 4. A copy of the transformed XML file is saved to the Archive folder. 43. Click XSLT. 44. Click New. 45. In the XSLT ID field, type a value. 46. In the Description field, enter the purpose of the XSLT. 47. In the XSLT field, enter the XSLT code. Note: You can write the XSLT code here or write it in another editor and copy it here. 48. Click Import XSLT. 49. Click Remove root tag. Note: To keep valid XML, do not apply this XSLT to XML files with several records of the same entity. For example, if you have several sales orders in one XML file. 50. Close the page. 51. Sub-task: Set record layout options. 52. Expand the Record layout section. 53. In the Root name field, type a value. 54. In the XSD URL field, type a value. 55. Close the page. Initialize records  and fields? Initialize records  and fields? Initialize document records and fields Initialize document records and fields For documents of type XML or JSON, you can initialize the records based on an input file. To initialize records and fields for:An XML document, you can use an input file of type XML or XSD.A JSON document, use an input file of type JSON.On initializing records, also the fields that are defined in the input file, are initialized. If you initialize based on:An XML file, only the field names are known and added to the relevant document records.An XSD file, besides the field names, also the field properties can be defined and added to the relevant document records.A JSON file, only the field names are known and added to the relevant document records.When the initialization is finished, review and complete the properties of the initialized records and fields.Usually, during review, you do not add records or fields. However, you can remove the not needed record and fields. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document of type XML or JSON. 4. Click Edit. 5. In the Record section, click Initialize. 6. On the dialog, in the Connector field, enter or select the desired connector of type Azure file storage 7. Select the input file for the initialization. If the document type is: - XML, select a file of type XML or XSD. - JSON, select a file of type JSON. In the File name field, enter or select a value. Note: The default filter is defined by the Read filename field on the document header. 8. Click OK. 9. A dialog is shown with these options: - Yes: all existing records and fields in the document are deleted and new records and fields are added based on the selected XML or XSD file content. - No: New records and fields are added based on the selected XML or XSD file content. Existing records and fields are kept in the document. - Cancel: The initialization is stopped before adding records and fields to the document. Click Yes. Note: This dialog is only shown for XML documents. 10. Close the page. Add document records - XML Add document records - XML To each document, add the data records to be exchanged. For external file-based documents, set up the records in line with how the data is structured and named in the file.This topic explains how to add records to an XML document.If records are already initialized for the document, you can review and complete the setup for these records. To do so, instead of adding a record, select the desired record. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired XML document. 4. Click Edit. 5. In the Record section, click Add line. 6. In the Record field, type a value. 7. In the Record table field, keep the default value 'BisBufferTable'. 8. In the Parent record field, enter or select a value. 9. Select Yes in the Combine with parent record field. 10. In the Join mode field, select an option. 11. Select Yes in the History field. 12. Sub-task: Set record details. 13. In the External name field, type a value. 14. Select Yes in the Use container field. 15. In the Container field, enter the name of the container tag. 16. In the Maximum occurrences field, enter a number. 17. In the Minimum occurrences field, enter a number. 18. Close the page. Notes Generic external document record details fields:External reference: You can indicate which field of the record contains the unique ID of the record in the external database. In this way, you link the external ID to the D365 FO record ID. Note: Usually, you only use this for an ODBC connection with CRM or if you use web services.Revision field: You can indicate which of the records fields contains the revision of the record in the external database. In this way, you find and link the latest revision to the record ID. Note: You can only use this field in combination with the External reference field. Manage document record setup - Internal documents

Manage document record setup - Internal documents

You have several options to manage the document record setup for internal documents.

You can:
  • Change the sequence of the records.
  • View the D365 FO table relations.
  • View where a record is used.
  • Check or change the table relations.
  • Define the data querying order.
  • Define the range of data to be queried.
  • Validate the record setup.

 Select fields Select fields You can add a selection of table fields to a record. You can select fields from the D365 FO table that is defined in the Record table field.This is mainly applicable to internal documents. However, you can also use this to quickly set up fields for external file-based documents.When the field selection is added to the record, review and complete the properties of the added fields. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document. 4. Click Edit. 5. In the Records section, in the Record list, find and select the desired record. 6. Click Select fields. 7. Sub-task: Define filter. 8. In the Table name field, enter or select a value. 9. Select Yes in the Show system fields field. 10. Select No in the Show inherited fields field. 11. Usually, you add fields to an internal document record with the type as defined in the table setup. However, you can add all selected fields with the type set to String. Select Yes in the Create as string fields field. Note: This field is only available for internal documents. 12. Sub-task: Select fields. 13. Click Select the fields of a specific group to open the drop dialog. 14. In the Field group name field, enter or select a value. 15. Click OK. 16. Click Select all. 17. Click Deselect all fields. 18. Click Select mandatory. 19. Select the Selected check box for the desired fields. 20. Click OK. Copy fields Copy fields You can copy fields from a record of another document. You can use this, for example, to save setup time if you use a specific record in several documents.You can only copy fields:From a record with the Record table defined.To a record with no fields.As a result, the full field setup is copied from the selected record to the current record. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired document. 4. Click Edit. 5. In the Record section, in the Record list, find and select the desired record. 6. Click Copy fields. 7. In the Record field, select the desired record from another document. Note: You can only select a record with the same Record table defined as the current record. 8. Click OK. 9. Close the page. Add document record fields - XML Add document record fields - XML To each document record, add the data fields which values must be exchanged. For external file-based documents, set up the fields in line with naming in the file.For XML documents, fields are always of type string, to enable type conversions.This topic explains how to add record fields to an XML document.If fields are already initialized for the document, selected for the record, or copied to the record, you can review and complete the setup for these fields. To do so, skip step 6. Procedure 1. Click Connectivity studio Integration Design. 2. Click the Documents tab. 3. In the list, find and select the desired XML document. 4. Click Edit. 5. In the Records section, in the Record list, find and select the desired record. 6. On the Fields tab, click New. 7. As a field name, enter a free-definable name. Usually, this is the name used in the external file. In the Field name field, type a value. Note: The value of this field cannot have spaces. 8. As a record table, enter a free-definable name. Usually, this is the name used in the external file. The value, as entered in the Field name field, is the default value. You can change this value. In the Record table field field, type a value. Note: The value of this field cannot have spaces. 9. Select the Key field check box. 10. In the Mandatory field, select an option. 11. In the Length field, enter a number. 12. In the Attribute Type field, select an option. 13. In the Attribute of field, enter or select a value. 14. In the Attribute name field, type a value. 15. In the Expression field, type a value. 16. Select the Search in children check box. 17. Select the Skip empty check box. 18. Sub-task: Set external references for record. 19. In the Line details section, set the external references for the record. You can indicate which of the records fields contains the unique ID of the record in the external database. In this way, you link the external ID to the record ID. In the External reference field, enter or select a value. Note: Usually, you only use this for an ODBC connection with CRM or if you use web services. 20. You can indicate which of the records fields contains the revision of the record in the external database. In this way, you find and link the latest revision to the record ID. In the Revision field field, enter or select a value. Note: You can only use this field in combination with the External reference field. 21. Close the page. Manage document record field setup

Manage document record field setup - Internal documents

You have several options to manage the document record field setup for internal documents.
You can:

  • Change the sequence of the fields.
  • View where a field is used.
  • Clean up unused fields.
  • Create a related record.

 Validate connectivity setup

Validate connectivity setup

If you open a form or save (changes to) the setup of a key element in Connectivity studio, the setup is validated automatically. If errors are found in the setup, an error icon   is shown. You can click the icon to show the related error messages.

You can also manually start an automated test to check for errors in the setup. As a result, the found errors are shown. Also, the error icons are shown where applicable.
When errors are found, you can try to fix these errors automatically.
You can check and auto-fix errors for these key elements in Connectivity studio:
 

Key element

Check

Projects

When automatically checked, only the project setup is checked, and not the related setup like messages and connectors. When started manually, the full project setup is checked.

Documents

The document setup is checked, including the document records setup.

Document records

Only the document records setup is checked.

Messages

The message setup is checked, including the data synchronization setup and message mapping.

Message - Data synchronization setup

Only the data synchronization setup is checked.

Message mapping

Only the message mapping is checked.

Message business events

A check is done if a business event is created for the message business event. Also, a check is done if the target fields and source fields match with the related document setup.

Connectors

Only the connector setup is checked.

Web services

The web service setup is checked, including the data synchronization setup.

Web service - Data synchronization setup

Only the data synchronization setup is checked.
 
In this flow, in the activity steps, as an example, the validation is done for documents.

 End End Yes No

Activities

Name Responsible Description

Set up document - XML

Application Consultant

 		Use an XML document to exchange data in XML format without the need to code.
With a document of type XML, you can read data from or write data to an XML file.
For more information on XML, refer to XML Tutorial.

Initialize document records and fields

Application Consultant
For documents of type XML or JSON, you can initialize the records based on an input file. 
To initialize records and fields for:
  • An XML document, you can use an input file of type XML or XSD.
  • A JSON document, use an input file of type JSON.
On initializing records, also the fields that are defined in the input file, are initialized. If you initialize based on:
  • An XML file, only the field names are known and added to the relevant document records.
  • An XSD file, besides the field names, also the field properties can be defined and added to the relevant document records.
  • A JSON file, only the field names are known and added to the relevant document records.
When the initialization is finished, review and complete the properties of the initialized records and fields.
Usually, during review, you do not add records or fields. However, you can remove the not needed record and fields.

Add document records - XML

Application Consultant

To each document, add the data records to be exchanged. For external file-based documents, set up the records in line with how the data is structured and named in the file.

This topic explains how to add records to an XML document.

If records are already initialized for the document, you can review and complete the setup for these records. To do so, instead of adding a record, select the desired record.

Manage document record setup - Internal documents

Application Consultant

 		You have several options to manage the document record setup for internal documents.
You can:
  • Change the sequence of the records.
  • View the D365 FO table relations.
  • View where a record is used.
  • Check or change the table relations.
  • Define the data querying order.
  • Define the range of data to be queried.
  • Validate the record setup.

Select fields

Application Consultant

You can add a selection of table fields to a record. You can select fields from the D365 FO table that is defined in the Record table field.

This is mainly applicable to internal documents. However, you can also use this to quickly set up fields for external file-based documents.

When the field selection is added to the record, review and complete the properties of the added fields.

Copy fields

Application Consultant

 		You can copy fields from a record of another document. You can use this, for example, to save setup time if you use a specific record in several documents.
You can only copy fields:
  • From a record with the Record table defined.
  • To a record with no fields.
As a result, the full field setup is copied from the selected record to the current record.

Add document record fields - XML

Application Consultant

To each document record, add the data fields which values must be exchanged. For external file-based documents, set up the fields in line with naming in the file.

For XML documents, fields are always of type string, to enable type conversions.

This topic explains how to add record fields to an XML document.

If fields are already initialized for the document, selected for the record, or copied to the record, you can review and complete the setup for these fields. To do so, skip step 6.

Manage document record field setup

Application Consultant

 		You have several options to manage the document record field setup for internal documents.
You can:
  • Change the sequence of the fields.
  • View where a field is used.
  • Clean up unused fields.
  • Create a related record.

Validate connectivity setup

Application Consultant

If you open a form or save (changes to) the setup of a key element in Connectivity studio, the setup is validated automatically. If errors are found in the setup, an error icon   is shown. You can click the icon to show the related error messages.

You can also manually start an automated test to check for errors in the setup. As a result, the found errors are shown. Also, the error icons are shown where applicable.
When errors are found, you can try to fix these errors automatically.
You can check and auto-fix errors for these key elements in Connectivity studio:
 

Key element

Check

Projects

When automatically checked, only the project setup is checked, and not the related setup like messages and connectors. When started manually, the full project setup is checked.

Documents

The document setup is checked, including the document records setup.

Document records

Only the document records setup is checked.

Messages

The message setup is checked, including the data synchronization setup and message mapping.

Message - Data synchronization setup

Only the data synchronization setup is checked.

Message mapping

Only the message mapping is checked.

Message business events

A check is done if a business event is created for the message business event. Also, a check is done if the target fields and source fields match with the related document setup.

Connectors

Only the connector setup is checked.

Web services

The web service setup is checked, including the data synchronization setup.

Web service - Data synchronization setup

Only the data synchronization setup is checked.
 
In this flow, in the activity steps, as an example, the validation is done for documents.

Provide feedback