--- title: "Set up document - XML" slug: "set-up-document-xml" description: "Learn to create and manage XML documents for data exchange without coding, ensuring efficient data import/export with best practices and transformations." tags: ["Task topic"] updated: 2026-03-20T07:44:31Z published: 2026-03-20T17:44:19Z canonical: "docs.staedean.com/set-up-document-xml" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.staedean.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://www.w3schools.com/xml/default.asp). ### Steps 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 name: 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] > **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. 1. Expand the **Properties** section. 2. Define the file encoding to be used when reading or writing the related XML files. The default file encoding is Unicode (UTF-8). In the **Encoding** field, enter or select a value. 3. By default, if the encoding is 'Unicode (UTF-8)', on write, the encoding type is written to the file header. You can select **Yes** to not write the encoding type to the file header. Select **Yes** in the **Without BOM** field. 4. You can process an external document in these ways: - **Direct**: You can use this to import or export (big sets of) simple data. For simple data, the document lines only have a root record. When a message is run, the data is directly mapped. More technically: It only loads the data in the memory of the record table (usually the **BisBufferTable**). As a result, the import or export of data is faster. - **Query**: You can use this to import or export complex data. For complex data, the document lines have several records and parent-child relations. When a message is run, the records are stored in the record table (usually the **BisBufferTable**) before the data is mapped. When the message run is finished, the records are deleted from the record table. In the **Process type** field, select an option. 5. 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] > **Note** > > Using this option, you can only add one namespace to an XML file. 9. Sub-task: Set custom handler. 1. Expand the **Custom** section. 2. For an **XML** document, several standard handler classes are available. 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. 10. Sub-task: Set read options. 1. Define the filename settings based on which files are searched for when importing data from files. Expand the **Read** section. 2. Define the filename filter to define which files must be imported for the document. You can use these variables: You can also use other common search symbols. **Example:** %1*.%2. As a result, files are only imported if the name starts with the current company ID and has the extension '**XML**'. In the **Read filename** field, type a value. - **%1**: filters files based on the current active company ID. - **%2**: filters file based on the file extension. The applicable file extension is defined by the current document type. In this case, it is '**XML**'. 3. You can block files with the same filename from being imported several times. Each processed file is stored in the file history. If **Read only once** is **Yes**, on import, the filenames are compared with the file history. If a file is found that is processed earlier, it is not processed but moved to the **Error folder**. Select **Yes** in the **Read only once** field. 4. 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] > **Note** > > If you use input validation, make sure the **Process type** is set to '**Query**'. 11. Sub-task: Use read transformations. 1. 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] > **Note** > > When a message is run to import an XML file to which XSLTs must be applied: > > - The original XML file is copied from the working folder to the archive folder with the '_org' addition to its name. > - The XSLTs are applied to the XML file in the working folder. > - The transformed XML file is processed by the message. > - When 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. > - The transformed XML file is deleted from the working folder. 2. Click **XSLT**. 3. Click **New**. 4. In the **XSLT ID** field, type a value. 5. In the **Description** field, enter the purpose of the XSLT. 6. In the **XSLT** field, enter the XSLT code. > [!NOTE] > **Note** > > You can write the XSLT code here or write it in another editor and copy it here. 7. The Connectivity Studio **XML reader** expects root tags for each record. You can receive an XML file with one record, but without root tags around the record. Before the XML file is read by the message, you must add these root tags. You can add the predefined '**Add root tag**' XSLT to the document to add the required root tags. If you apply this XSLT, make sure the root tag name to be used is defined in the **Root name** field on the document header. Click **Import XSLT**. 8. Click **Add root tag**. > [!NOTE] > **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. 9. The Connectivity Studio **XML reader** does not support namespaces. If you receive XML files with namespaces, these namespaces must be removed before the file can be read by the message. You can add a predefined XSLT to the document to remove namespaces. Click **Import XSLT**. 10. Click **Remove namespaces**. 11. Close the page. 12. Sub-task: Set write options. 1. Define the filename settings based on which filenames are created when exporting data to files. Expand the **Write** section. 2. 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] > **Note** > > You cannot use the table name itself as variable in the filename. 3. 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] > **Note** > > You can only select a field from the defined table. 4. 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] > **Note** > > You can only select a field from the defined table. 5. To make the filename unique, you can add a unique number to the filename, provided by a number sequence. The related variable is '**%4**'. In the **Number sequence** field, enter or select a value. 6. Define the filename for the files that are created based on the document. You can use fixed values and variables. The available variables are: In the **Write filename** field, type a value. - **%1**: The name of the current document. - **%2**: The current date. - **%3**: The current time. - **%4**: The unique number as provided by the defined number sequence. - **%5**: The value of the defined **First field** - **%6**: The value of the defined **Second field** - **%7**: The ID of the current company. - **%8**: The ID of the current user. - **%9**: The file extension as defined by the applicable document type. For example: 'xml' or ‘json’. - **%10**: The UTC internet date/time (RFC3339 with underscores). Example: 2021-01-05T14_38_51Z 13. Sub-task: Use write transformations. 1. 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] > **Note** > > When a message is run to export an XML file to which XSLTs must be applied: > > - The message is run, and the XML file is created in the working folder. > - The XSLTs are applied to the created XML file. > - The transformed XML file stays in the working folder. > - A copy of the transformed XML file is saved to the Archive folder. 2. Click **XSLT**. 3. Click **New**. 4. In the **XSLT ID** field, type a value. 5. In the **Description** field, enter the purpose of the XSLT. 6. In the **XSLT** field, enter the XSLT code. > [!NOTE] > **Note** > > You can write the XSLT code here or write it in another editor and copy it here. 7. The Connectivity Studio **XML writer** always adds root tags to each record. If only one record is written to an XML file, sometimes, the receiver of the file doesn't expect root tags. After the XML file is created by the message, you can have the root tags removed. You can add the predefined '**Remove root tag**' XSLT to the document to remove the root tags. 8. Click **Import XSLT**. 9. Click **Remove root tag**. > [!NOTE] > **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. 10. Close the page. 14. Sub-task: Set record layout options. 1. Expand the **Record layout** section. 2. If you use an XSLT to add root tags to an XML file, define the root tag name. In the **Root name** field, type a value. 3. You can enter a URL or file reference to an XSD that is used to validate the XML that you read or write. Usually, this is only used when you test a message. When live, this usually is not applied because it influences the performance. In the **XSD URL** field, type a value. 15. Close the page. ## Related - [Customize document handler class](/customize-document-handler-class.md) - [Create separate files](/create-separate-files.md)