Electronic Data Interchange (EDI)

In this article
Product Information
Release Notes

Document types - File templates

Users can access the form by navigating to EDI > Setup > Document types.
Select or filter the applicable Document in the List and select FastTab Templates.

Templates hold the settings required to translate the EDI document into or out of the document type’s staging tables. Trading partners will often supply information in different formats and use different fields to specify information. Having templates allows us to configure these differences in a simple reusable fashion.

Create new template:

  • Select Create, a new dialog box called Create a new template will be displayed
  • Specify the Template ID and Description
  • Select the Type of file for which the template is being created, options:
  • Select Create

Copy existing template:

  • Select Copy, a new dialog box called Copy template will be displayed
  • Specify the Template ID and Description
  • Select Copy

Setup

Next step is to update Setup for the created template. The standard setup that applies to all types will be described first, thereafter unique setup for each Type will be discussed.

Standard setup

Regional settings - Select the default regional settings used within the file.

Field Description
Code page Select the applicable code page.
Time zone preference Select the time zone offset used when processing the document type:
Auto (default) – The standard D365 time zone logic applies.
User – The user who is running the process’s time zone.
No Conversion – no time zone offset is applied.
Company – the legal entities time zone offset is applied.
Manual – use the proceeding ‘time zone’ parameter.
Time zone Enabled and used to set the timezone when Time zone preference is set to Manual.

Decimals settings - Select the default decimal settings used within the file.

Field Description
Decimals The decimal precision applied.
Separator The decimal separator applied.
Thousand separator Only applies to Text templates. The thousand separator applied.

Date setttings - Select the default date settings used within the file.

Field Description
Custom date format Enabled when Culture is set to Custom
Format Select the default date format to be used for all text templates
Day Select the default format used for day for all text templates
Month Select the default format used for month for all text templates
Year Select the default format used for year for all text templates
Separator Select the default date separator used for all text templates
Custom time format Enabled when Culture is set to Custom
Format Select the default time format to be used for all text templates
Separator Select the default time separator used for all text templates
Custom date and time format Enabled when Date and time format is set to Custom
Custom date and time format Enter custom date and time format
Formatted date and time example Displays example date and time for Custom date and time format (in UTC timezone)
Custom time format Enter custom time format
Formatted time example Displays example time for Custom time format (in UTC timezone)

Text files

Text files templates setup

Text file are a very common way to transfer data. They are often delimited files with header and line information. This template type gives the ability to map such files to and from the documents staging tables. Text file can handle multiple headers.
Select the Setup button to set the following for text templates:

Field Description
Flat or structured Flat – A single line per record. Each line of text in the file has all the header information on it as well as the line information.
Structured – Multiple lines per record. Each line in the file is either a header type or a line type
Delimited or fixed Delimited – Columns using a defined separator.
Fixed – Fixed width
First row is header Specify if the First row is header record. This row will then be ignored on the inbound file.
Row delimiter Select the Row delimiter used within the file, options:
{CR}{LF} – Carriage return/line feed for windows
{CR} – Carriage return for MAC.
{LF} – Line feed for UNIX
{;} – Semicolon
{:} – Colon
{,} – Comma
{t} – Tab
{|} Vertical bar
{~} - Tilde
Column delimiter Select the Column delimiter used within the file, same selection as Row delimiter
Text qualifier Specify the Text qualifier used to identify text within the file. This will then be removed from the string when writing data to staging.
Record identifier position Where the file is Structured, specify the Record identifier position

If required to update regional, decimals or date settings, see Standard setup.

Note: Flat or structured cannot be changed when mappings exist.

Text files template mappings

Each document type has its own fields that can be either mapped to for inbound files or mapped from for outbound files.
The mapping is made up of two sections:

  • File sections (structured only) and
  • Field mappings (structured and flat) Select Mappings button to specify the columns within the file that are to be mapped.

File sections

Flat

Select Edit to update mappings for a text file

Note: The Section type information will be defaulted and only a single Line entry is possible for flat text templates.

Structured

File sections are the different types of lines that can be found in a structured type file (as defined in the Template’s setup called Flat or structured). Field mappings belong to each file section.

A Structured file can have many different file sections, all with an associated section type.

  • Select New to create a new record
  • Specify the Name of the file section. Exampled include header, lines, summary.
  • Select the Section type. The options are:
    • Header – Header information often related to the Customer information.
    • Line – Related to Item information. This may or may not include quantities
    • Line Detail – A sub line data line whose data will be mapped to the same record as the Line’s section type data (i.e. Item Quantity information)
    • Footer – Summary/Total information

      Note: A single record is possible for Header, Footer and Line sections within a file Section. Multiple records are possible for Header and Line Details.
      Note: Each section type that is included in the file must be specified even if no mappings are required.

  • Enter the section type Description
  • Enter the Record Identifier - The identifier value used to identify the line type from the files data. The position of this identifier is specified on the template’s setup called Row identifier position.

Field mappings

Field mappings define how the data is positioned in the file on the section line. Fields can also be statically set to values and certain functions are available to transform the fields data if required.

Field Description **Applicable to
Value type Whether the field value is a static value or a mapped field value Inbound & Outbound
Static value If the field type is a static type, then this is the static value Inbound & Outbound
Staging field The mapped field Inbound & Outbound
Staging table The table the mapped field represents Inbound & Outbound
Field position The position in the file the mapping represents Inbound & Outbound
** Field length Number of characters for field Inbound & Outbound
** Alignment Select Left or Right alignment for the field Outbound
** Padding character Enter a padding character for the field Outbound
Function Apply an optional function to the data of this field Inbound & Outbound

Note: ** Available for Fixed type text templates.

There are two ways to add a field mapping:

Manual selection
  1. To create a new mapping, select Add from the mapping FastTab.
  2. Select if the Value type will be:
    • Field - mapped to or from staging field, or
    • Static - Static value used
  3. If the Value type is Static, complete the Static value
    Note: Static value can be either plain text or a method between brackets for outbound files. Example:
    (currentDate())
    (currentLanguageId())
    (currentSessionDate())
    (currentSessionDateTime())
  4. Specify the Staging field. Switch bewteen the header and lines table to find the required field.
  5. Enter the Field position within the file.

Note: To delete a line, select the record then select Remove.

Fields picker

Alternatively, a bulk field picker can be used to add multiple mappings at once.

  • Select Fields picker
  • A new form is displayed allowing Header and Line selection of multiple available records
Field Description
Selected Mark whether to add the field.
Also indicates if the field is already selected for the template.
Field label The label of the field
Field name The name of the field
  • Select Update to update the mapping

Buttons Select all and Clear all are also available to easily select or clear all fields for the mapping.

Note: To delete a line, select the record then select Remove. Lines can also be moved using the Move up or Move down buttons. If a field needs to be added more than once, use manual Add button on the Mappings FastTab.

Field functions

Field mappings can have functions applied to them to transform the data or perform calculations based on that data. The functions are only available for certain data types based on their functionality.

Field function Field data type Description
Average Number Average value across all staging records for the selected field
Earliest Date Earliest value across all staging records for the selected field
First Any type First selected value across all staging records for the selected field
Last Any type Last selected value across all staging records for the selected field
Latest Date Latest value across all staging records for the selected field
Max Number Max value across all staging records for the selected field
Min Number Min value across all staging records for the selected field
Remove carriage returns String Remove Carriage returns in the value of the selected field
Remove decimal Number Remove decimals in the value of the selected field. Example: Line numbers.
Remove space String Remove spaces in the value of the selected field
Sum Number Sum of values across all staging records for the selected field

Note: The list of available functions can also be located via EDI > Setup > Configurations > Template field functions

XML files

When a new XML file template is created, the currently available fields will be defaulted in the mapping.
By selecting Mappings, users can remove/add fields or move position of field/s.
They can also enter a static value, apply custom formats and set the field as an attribute.

The elements in the XML template, uses the D365 table field names but it can be overridden in the Name column in Mappings.

Users can also enter a static value or apply functions for inbound and outbound files.

  • Static value: Users can use a static value on an inbound file where the field is not within the file. Or send a static value on an outbound file.
  • Custom format: Where the field is within the inbound file but needs to be formatted, use formula like substring to replace. On outbound files, custom format can also be used to format differently to document template’s setup, or other examples as per Custom format section.

Style sheets can also be applied, which will override the mappings. XML Collection should be used for XML files with multiple headers.

XML files templates setup

If required, update the general settings by seleting the Setup button.

Field Description
Remove blank elements Select to remove elements from the outbound file that do not have data. This is required for XSD validation.
XLST output is XML Select if the XLST output is XML
Suppress BOM characters No – Include byte order mark (BOM) characters in generated outbound XML files.
Yes – Suppress byte order mark (BOM) characters in outbound files
Format outbound document Outbound files:
• No – XML outbound file is created without carriage returns
• Yes - XML outbound file is created with carriage returns
Inbound files: not affected by setting, file with/without carriage returns can be imported.

If required to update regional, decimals or date settings, see Standard setup.

XML template mappings

When creating XLST Transformation or XLST Collection templates:

  • Select Mappings, the following options are available: - XML – Ability to override the default mappings - XSD – (XML Schema Definition) describes the elements within the XML document - XSLT – Ability to apply an XSLT transformation (if required)

Note: If the document type has staging record/s, users can use the following to create an example XML populated with information. Select Mappings > XML. Select Set data button on the Example FastTab, select a staging table record and select Choose.

XML Transformation

XML file can be transformed by utilizing Mappings > XSLT Paste XLST code on XLST tab. Can use Run transformation to check for compile errors.
When opening the form, it will also display any compile errors. Validate XSD is used to validate transformed XML, not the XSLT. Click Save XSLT. If scripting is allowed, ensure EDI Shared parameter Enable XLST scripting is enabled.

JSON files

When a new JSON file template is created, the currently available fields will be defaulted in the mapping.
By selecting Mappings, users can remove/add fields or move position of field/s.
They can also enter a static value and apply custom formats.

The elements in the JSON template, uses the D365 table field names but it can be overridden in the Name column in Mappings.

Users can also enter a static value or apply functions for inbound and outbound files.

  • Static value: Users can use a static value on an inbound file where the field is not within the file. Or send a static value on an outbound file.
  • Custom format: Where the field is within the inbound file but needs to be formatted, use formula like substring to replace. On outbound files, custom format can also be used to format differently to document template’s setup, or other examples as per Custom format section.

JSON Collection should be used for JSON files with multiple headers.

Note: If the document type has staging record/s, users can use the following to create an example XML populated with information. Select Mappings > XML. Select Set data button on the Example FastTab, select a staging table record and select Choose.

JSON files templates setup

If required to update regional, decimals or date settings, see Standard setup. Date settings allow for ability to override default JSON ISO standard date format yyyy-MM-dd’T’HH:mm:ss.ff

Code transformation files

Code transformation file format is available and uses the Incoming/outgoing transformation as developed in EDI > Setup > Configurations > Template code transformations

Code transformation files templates setup

If required, update the general settings by seleting the Setup button.

Field Default
Transformation Select the applicable Transformation Name. Values are filtered to Direction of the document template (Outgoing vs. Incoming)

If required to update decimals or date settings, see Standard setup.

EDIFACT files

Prerequisites

License: IconEDIStandardFormats
Feature enabled: EDI - Standard formats

EDIFACT files templates setup

If required, update the general settings by seleting the Setup button.

The following Options under General, are defaulted for EDIFACT and are used to populate the mappings in UNA Service string.

Field Default
Component data element separator :
Data element separator +
Decimal mark ** .
Release character ?
Segment terminator ‘

If required to update regional, decimals or date settings, see Standard setup.

Note: The Decimal separator is linked to the Decimal mark.
Date formats can also be overridden for a specific field within Mappings by using Custom format. For example, the document’s date format is set to yyyyMMdd, but can use yyyyMMddHHmm for specific field CreatedDateTime.

EDIFACT files template mappings

Each document type has its own fields that can be either mapped to for incoming files or mapped from for outgoing files. When creating an EDIFACT template, it automatically creates the EDI message and populates UNA segment under Mappings. EDIFACT mappings uses a tree structure, and normally includes a:

  • Header section – Header provides information related to the message, recipient, sender, reference, name and address, etc.
  • Detail section - Related to line-item information. For example: line number, item numbers, quantities, and pricing. Since this section needs to repeat per staging line: Select the line staging table in field Staging table.
  • Summary section – Document’s total monetary amounts. Also includes Section control, Control total and Message trailer.

Select Mappings to access the template’s mappings.

EDIFACT hierarchy is (Section) > Segment > Composites > Elements

Sections
  • Select Add section and enter a Name. Sections can be added under existing sections to create a tree structure.
    When creating the Detail section (that will be repeated for each line), select the applicable Staging table next to the Section’s Name. This will ensure the section is repeated for each line record. This is not required for Header or Summary section.
    Example Sections are:
  • Header section
  • Detail section
  • Summary section

Note: To Delete a section, select the section then select Delete section.

Segment

The level under Section is called Segments.

  • Select the applicable Section and select New to add a Segment.
  • Enter a Static value OR select the applicable Staging field. Segments are usually Static values like UNH, BGM, etc.
    When selecting a Staging field, the Staging table options include the header, line staging tables.
    It also includes EDIFACT message, which includes options like:
    • Created date
    • Created time
    • Segment count, and
    • Service string fields
  • Name is defaulted from the Static value / Staging field but can be overridden.
  • Where applicable, enter a Custom format for the field.

Note: To Delete a Segment, select the record then select Delete.
Segments can be moved up or down within its Section by using the Up and Down buttons.

Example Segments for a EDIFACT D01B are:

  • 0010 UNH Message header:
    • Static value = UNH
    • Name = 0010 Message header
  • 0020 BGM Beginning of message
    • Static value = BGM
    • Name = 0020 Beginning of message
Composites

The level under Segments is called Composites.

  • Select the applicable Segment and select New to add a Composite.
  • Enter a Static value OR select the applicable Staging field.
    When selecting a Staging field, the Staging table options include the header, line staging tables.
    It also includes EDIFACT message, which includes options like:
    • Created date
    • Created time
    • Segment count, and
    • Service string fields
  • Name is defaulted from the Static value / Staging field but can be overridden.
  • Where applicable, enter a Custom format for the field.

Note: To Delete a composite, select the record then select Delete.
Composites can be moved up or down within its Segment by using the Up and Down buttons.

Example Composites for Segment UNH for an outbound Vendor purchase order:

  • 0062 Message reference number:
    • Staging field = Group control number
    • Name = 0062 Message reference number
  • 0065 Message type
    • Static value = ORDERS
    • Name = 0065 Message type
Elements

The level under Composites is called Elements.

  • Select the applicable Composite and select New to add an Element.
  • Enter a Static value OR select the applicable Staging field.
    When selecting a Staging field, the Staging table options include the header, line staging tables.
    It also includes EDIFACT message, which includes options like:
    • Created date
    • Created time
    • Segment count, and
    • Service string fields
  • Name is defaulted from the Static value / Staging field but can be overridden.
  • Where applicable, enter a Custom format for the field.

Note: To Delete an Element, select the record then select Delete.
Elements can be moved up or down within its Composite by using the Up and Down buttons.

Example Elements for Segment 0065 Message type:

  • 0052 Message version number
    • Static value = D
    • Name = 0052 Message version number
  • 0054 Message release number
    • Static value = 01B
    • Name = 0054 Message release number
  • 0051 Controlling agency, code
    • Static value = UN
    • Name = 0051 Controlling agency, code
  • 0057 Association assigned code
    • Static value = EAN010
    • Name = 0057 Association assigned code

Short example to display section, segment, composite, element relation:

Section Segment Composite Element
Header section UNH (Message header) Message reference number  


ORDERS (Message type) D (Message version number)



01B (Message release number)



UN (Controlling agency, code)



EAN010 (Association assigned code)

X12 files

Prerequisites

License: IconEDIStandardFormats
Feature enabled: EDI - Standard formats

X12 files templates setup

If required, update the general settings by seleting the Setup button.

The following Options under General, are defaulted for EDIFACT and are used to populate the mappings in UNA Service string.

Field Default
Delimiter ^
Decimal mark .
Segment terminator ~

If required to update regional, decimals or date settings, see Standard setup.

Note: The Decimal separator is linked to the Decimal mark.
Date formats can also be overridden for a specific field within Mappings by using Custom format. For example, the document’s date format is set to yyyyMMdd, but can use yyyyMMddHHmm for specific field CreatedDateTime.

X12 files template mappings

Each document type has its own fields that can be either mapped to for incoming files or mapped from for outgoing files. When creating an X12 template, it automatically creates the EDI message and populates ISA section under Mappings. X12 mappings uses a tree structure, and normally includes a:

  • Header section – Header provides information related to the message, recipient, sender, reference, name and address, etc.
  • Detail section - Related to line-item information. For example: line number, item numbers, quantities, and pricing. Since this section needs to repeat per staging line: Select the line staging table in field Staging table.
  • Summary section – Document’s total monetary amounts. Also includes Section control, Control total and Message trailer.

Select Mappings to access the template’s mappings.

Sections
  • Select Add section and enter a Name. Sections can be added under existing sections to create a tree structure.
    When creating the Detail section (that will be repeated for each line), select the applicable Staging table next to the Section’s Name. This will ensure the section is repeated for each line record. This is not required for Header or Summary section.
    Example Sections are:
  • Header section
  • Detail section
  • Summary section

Note: To Delete a section, select the section then select Delete section.

Segment

The level under Section is called Segments.

  • Select the applicable Section and select New to add a Segment.
  • Enter a Static value OR select the applicable Staging field. Segments are usually Static values like UNH, BGM, etc.
    When selecting a Staging field, the Staging table options include the header, line staging tables.
    It also includes EDI X12 message, which includes options like:
    • Created date
    • Created time
    • Decimal mark
    • Delimiter
    • Reserved
    • Segment terminator
    • Segment count
  • Name is defaulted from the Static value / Staging field but can be overridden.
  • Where applicable, enter a Custom format for the field.

Note: To Delete a Segment, select the record then select Delete.
Segments can be moved up or down within its Section by using the Up and Down buttons.

Composites

The level under Segments is called Composites.

  • Select the applicable Segment and select New to add a Composite.
  • Enter a Static value OR select the applicable Staging field.
    When selecting a Staging field, the Staging table options include the header, line staging tables.
    It also includes EDI X12 message, which includes options like:
    • Created date
    • Created time
    • Decimal mark
    • Delimiter
    • Reserved
    • Segment terminator
    • Segment count
  • Name is defaulted from the Static value / Staging field but can be overridden.
  • Where applicable, enter a Custom format for the field.

Note: To Delete a composite, select the record then select Delete.
Composites can be moved up or down within its Segment by using the Up and Down buttons.

Elements

The level under Composites is called Elements.

  • Select the applicable Composite and select New to add an Element.
  • Enter a Static value OR select the applicable Staging field.
    When selecting a Staging field, the Staging table options include the header, line staging tables.
    It also includes EDI X12 message, which includes options like:
    • Created date
    • Created time
    • Decimal mark
    • Delimiter
    • Reserved
    • Segment terminator
    • Segment count
  • Name is defaulted from the Static value / Staging field but can be overridden.
  • Where applicable, enter a Custom format for the field.
  • For incoming documents, use Static value dynamic position to flag elements with dynamic positining (elements can be found in different order on the line). Set flag to Yes on static qualifier.
  • For outgoing documents, use Static value do not send if blank to flag where if an element is blank, it shouldn’t send the blank value and it’s qualifier. Set flag to Yes on static qualifier.
  • For outgoing documents, use Skip segment if blank to flag where if staging value is blank, it shouldn’t send the segment. Example is ‘Total charges’ in SAC segment. Set flag to Yes on applicable staging line.

Note: To Delete an Element, select the record then select Delete.
Elements can be moved up or down within its Composite by using the Up and Down buttons.

Short example to display section, segment, composite, element relation:

Section Segment Composite
Header section GS (Message header)  


PO (Message type)


Application Sender Code


Application Receiver Code

Custom format

Field mappings can have C# formats applied by using the field Custom format, some examples include:

Example Custom format Description Example before Example result
35 Left 35 characters of string Long description item that is more than 35 characters Long description item that is more
3,5 Substring (3,5) 123456789 34567
prefix{0,7:3,5}postfix Align example with prefix and postfix 123456789 prefix 34567postfix
C4 Currency with 4 decimals 123.45676 $123.4567
N2 2 decimals 123.45676 123.45
N0 0 decimals (for example line number) 1.0000000 1
{0,-10} Pad staging field with spaces to total of 10 characters ^1234^ ^1234          ^
XX{0,-8} Pad static value ‘XX’ with 8 characters ^XX^ ^XX        ^
F No thousand separator 1,234 1234
,##0.00;-#,##0.00;”” Replace 0 with blank ^0^
^123.45^		 ^^
^123.45^

More examples:

Example

An example of the document’s format can be viewed under the Example FastTab in Mappings.
Segment will display the selected Segment’s example, whereas Message displays the complete message’s example.
Set data can be used to select an existing staging record to populate the Message example.
Where Set data is blank, the Example message staging fields will not be populated, but will display the mapped {Table.Field} value.

Data entities

See Data entities for importing document type templates