1. To-Increase Dynamics 365 for Finance & Operations
  2. EDI studio
  3. Activities

Set up document - EDI
Application task

Use an EDI document to read data from or write data to a file if you use an EDI standard for your EDI. For example: EDIFACT or ANSI X12. The data in the file is structured in line with these standards.
Note: If you do not use an EDI standard, you can use other EDI document types for EDI. For example: JSON, XML, or Text.


Standard 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 EDI document, for example, select an 'EDI' 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 'EDI'.
8. Sub-task: Set properties.
  8.1 Expand the Properties section.
  8.2 Define the file encoding to be used when reading or writing the related text files.
The default file encoding is Unicode (UTF-8).
  In the Encoding field, enter or select a value.
  8.3 By default, if the encoding is 'Unicode (UTF-8)', on write, the encoding type is written to the file header.
Select Yes to not write the encoding type to the file header.
  Select Yes in the Without BOM field.
  8.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.
  8.5 It can be, that you receive text files with varying encoding. You can receive these files, based on one document. To do so, use dynamic encoding. As a consequence, on read, the defined file encoding is not used. The used encoding is searched for in the text file and the applicable encoding is used to read the text file.
  Select Yes in the Use dynamic encoding field.
  8.6 You can use an EDI type to indicate which EDI standard is used for the EDI document. For example, EDIFACT or ANSI X12. This is used for informational purposes only.
  In the EDI type field, enter or select a value.
 

Note: If you want to use qualifiers, in the document record fields, make sure to select an EDI type with the desired qualifiers defined.
9. Sub-task: Set custom handler.
  9.1 Expand the Custom section.
  9.2 For an EDI document, two standard handler classes are available:
- BisDocumentEdi: This handler class reads data from or writes data to a text file using an EDI standard, for example, EDIFACT or ANSI X12.
- BisDocumentEDIFACTCounter: This handler class reads data from or writes data to a text file using EDIFACT. With this handler class, you can apply numbering and control counts to your EDI messages. The numbering and counts are only applied on write.
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:
BisDocumentEDIFACTCounter handler:
With the 'BisDocumentEDIFACTCounter' handler class you add these values to a message:
- Header number. Uses the MESSAGEREFERENCENUMBER element of the UNH segment to store the sequential number of the header in the message.
- Segment count. Uses the NUMBEROFSEGMENTIN and MESSAGEREFERENCENUMBER elements of the UNT segment to store the number of segments within the applicable header. For each header, the segment count starts again.
- Header count. Uses the INTERCHANGECONTROLCOUNT of the UNZ segment to store the number of headers (UNH segments) in the message.
To apply this, in the document, add the mentioned elements as fields to the applicable records. Example: Add the MESSAGEREFERENCENUMBER field to the UNH record.
Version 3 handler:
Select the 'BisDocumentEdiV3' or 'BisDocumentEDIFACTCounterV3' 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
10. Sub-task: Set read options.
  10.1 Define the filename settings based on which files are searched for when importing data from files.
  Expand the Read section.
  10.2 Define the filename filter to define which files must be imported for the document.
You can use these variables:
- %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 'TXT'.
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 'TXT'.
  In the Read filename field, type a value.
  10.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.
  10.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: If you use input validation, make sure the Process type is set to 'Query'.
11. Sub-task: Set write options.
  11.1 Define the filename settings based on which filenames are created when exporting data to files.
  Expand the Write section.
  11.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: You cannot use the table name itself as variable in the filename.
  11.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: You can only select a field from the defined table.
  11.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: You can only select a field from the defined table.
  11.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.
  11.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:
- %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. In this case, it is 'txt'.
- %10: The UTC internet date/time (RFC3339 with underscores). Example: 2021-01-05T14_38_51Z
  In the Write filename field, type a value.
12. Sub-task: Set record layout options.
  12.1 Expand the Record layout section.
  12.2 Define the separator to indicate the end of a segment. You can use any character or symbol to terminate segments. The most common segment terminators are apostrophe ('), new line (\n), return (\r), and space (\s) or a combination. The default segment terminator is '\r\n.
The segment terminator is added after the field with the End segment check box selected.
  In the Segment terminator field, type a value.
  12.3 Define the delimiter to separate the data elements in the segment. The common and default Data element separator is a plus (+). Example: BGM+380+342459+9'\r\n. This segment consists of separate simple data elements.
  In the Data element separator field, type a value.
  12.4 For EDIFACT, you can group data elements together within a segment. this is called a composite data element. Define the delimiter to separate the data elements to be grouped together. The common and default composite data element separator is a colon (:). Example: UNH+000127+INVOIC:D:97B:UN'/r/n. This segment consists of two simple data elements (UNH and 000127) and a composite data element (INVOIC:D:97B:UN) where four simple data elements are grouped together by the colons.
  In the Sub-element separator field, type a value.
  12.5 A value in an EDI file can contain a character that is used as delimiter for Segment terminator, Data element separator, Composite data element separator, or Release character. The release character is used to prevent this character in the value from being handled as delimiter. Therefore, on:
- Write, the release character is placed in front of the character in the value.
- Read, the value is taken from the file and the release character is removed before the value is imported.
Example: The value is a time 15:34:22. In the EDI document the release character is applied and the time is shown as 15?:34?:22.
  In the Release character field, type a value.
13. Close the page.

See also

Provide feedback