close
1 EPC XFR Admin Guide - Shopping List Transfer Interface Description
2 Intended Audience
3 Introduction
4 Dependencies
5 General Description
6 Platforms
7 DataExchangeService Mode
8 XFR File Mode
8.1 Option 1 - Default
8.2 Option 2 - EWANAPI.EXE
8.3 Option 3 - epc_xfr_cfg.xml
9 Transfer File
9.1 Transfer File Format
9.1.1 Header Line
9.1.2 Parts Records
9.2  File Modification Timing
10 Appendix A

1 EPC XFR Admin Guide - Shopping List Transfer Interface Description

Daimler

2 Intended Audience

This document is intended for designers and implementers of programs such as Dealership Management Systems (DMS) that would need to obtain shopping list information from the EPC.



3 Introduction

This document describes the functionality of the Daimler Electronic Parts Catalog (EPC) that allows the current shopping list to be written to a file as changes are made to the list in the EPC. This file can then be accessed by a DMS system to transfer Part Numbers from the Shopping List.

4 Dependencies

The following describes features that depend on functionality, which is provided by the EWANAPI. Please install the EWANAPI on each client. Instructions you will find in the EWA Operation Manual. Note that 2 different versions of the the Operations Manual are available ( Central & Local).

5 General Description

The fundamental purpose of EPC is to locate part numbers.  These part numbers are typically then transferred to another program.  The automated transfer of the part numbers not only improves the speed of operation for the user, but also greatly reduces the risk associated with manually entering the number.

Another capability that EPC provides with regard to part numbers is the ability to save complete lists of frequently used part numbers for retrieval at a later date.  EPC also provides capabilities such as: clear, save, recall, copy, and delete for managing these saved lists (commonly referred to as "Shopping Lists").

The ability for the EPC to provide access to its shopping list in a simple, yet flexible format is required. The interface from EPC should be maintained as it currently exists which implies the shopping list is continually updated as parts are added or removed.  The minimum required information is the part number, part name, and part quantity.   The implementation should work in both a standalone and networked configuration and for multiple hardware platforms as required.

6 Platforms

This enhancement is included in version 1.7.4.0 (and higher) of the EPC application and is implemented for both locally hosted (intranet or LAN) or centrally hosted systems (Internet).

From version 1.12.2.0 onwards,  a further optional method is implemented which allows the Administrator to design a configuration with backwards compatibility to EPC Flexible Publishing regarding file name and location ( . i.e. for VP-Inland in Germany)

From version 1.27.0 onwards,  a further optional method is implemented which makes usage of a new DataExchangeService.


7 DataExchangeService Mode

This new Service gets enabled when a process-ID in form of a GUID will be handover to EPC by an EWANAPI call in parameter -processid From this point of time on will XFR File Mode DISABLED (described with the different Options) and ONLY the new DataExchangeService will be used for the whole session. The DataExchangeService is storing the the active shoppinglist content in the Core DB in an XML format. This new format allows to handle multibyte languages.

Here is an example of the content in the DB record:

<?xml version="1.0" encoding="UTF-8"?>
<shoppinglist>
 <user>TOM</user>
 <list_name>LIST1</list_name>
 <process_id>f47ac10b-58cc-4372-a567-0e02b2c3d479</process_id>
 <language>en</language>
 <parts>
  <part>
   <number>A1234567890</number>
   <name>BRAKE CALIPER</name>
   <quantity>001</quantity>
   <model_chassis>WDB123123</model_chassis>
   <gratuity_code></gratuity_code>
   <text></text>
  </part>
  <part>
   <number>N123456789012</number>
   <name>SCREW</name>
   <quantity>-</quantity>
   <model_chassis>WDB12312301123123</model_chassis>
   <gratuity_code>GC</gratuity_code>
   <text></text>
  </part>
  <part>
   <number>N98754321098</number>
   <name>HOSE</name>
   <quantity>3.5</quantity>
   <model_chassis></model_chassis>
   <gratuity_code></gratuity_code>
   <text>Optional with A1234567890</text>
  </part>
 </parts>
</shoppinglist>

8 XFR File Mode

Extra care was taken for EPC to ensure the shopping list location was flexible enough to be set whether an online central application or a locally installed application.  Flexibility is also important for those who are running in a Citrix environment, and they may login to any machine and get their normal user desktop.  The only caveat is that the location must be available within the session in which EPC is running.

There are 3 ways to define how and where the transfer (.xfr) file should be stored:

8.1 Option 1 - Default

As default the filename is always <username>.xfr and can not be changed.

The default location is based upon several criteria.  Since most DMS systems have access to a machine’s local drive, since Citrix allows a user to maintain their own documents directory in an Active Directory environment, and since the Microsoft standard is that applications should place documents in the user’s documents directory, then the default filename for each user is (since EPC 1.14.9)

“%USERPROFILE%\XFER\%EWA_XFR_USER%.xfr”.

Note:
Environment variables are allowed with no restriction (Only Option 1).
The default string uses following variables:

    - %USERPROFILE%  -> System environment variable which represent the Windows user Home Directory

    - %EWA_XFR_USER%  -> Special EPC variable (not found in System environment) which represent the EWA User Name

Example: Windows User "Jim" and EWA User "Derek" than the transfer file is found in:

                c:\Documents and Settings\Jim\XFER\Derek.xfr

If there is a need that the filename should also be the Windows User Name, than could the variable %EWA_XFR_USER%  replace by the System environment variable %USERNAME%. This would change the path in the example to:

                 c:\Documents and Settings\Jim\XFER\Jim.xfr

This default location can be changed in the user profile via the Utilities configuration. 

8.2 Option 2 - EWANAPI.EXE


Notes:
Using EWANAPI will disable the functionality described in Option 1 and Option 3.
The information shown here is only an example. For a full description of how to use EWANAPI see the separate documentation for EWANAPI

The default location can be overridden via commandline if you are using ewanapi.exe. This is only valid for the current session.

Example:

EWANAPI.exe -application EPC-Net -c -V WDB2201701A009213 -S d:\xfr\shoppinglist.xfr -userid dummyuser -userpwd dummypassword

The parameter –S sets the location and filename to d:\xfr\shoppinglist.xfr

 

8.3 Option 3 - epc_xfr_cfg.xml

Notes:
Using the epc_xfr_cfg.xml file will disable the functionality described in Option 1.

From EPC version 1.12.2.0 onwards, a new config file can be created, which does not exist as default.

The file must be stored under (case sensitive):

[EWA_HOME]\config\epc_xfr_cfg.xml

 

Example of "epc_xfr_cfg.xml":

Notes:
Comments inside the file are not allowed !

 

<xml>

  <SECTION name="DEFAULT">


    <PARAMETER name="LocationMode">Client</PARAMETER>

    <PARAMETER name="Path">\\DMSSERVER\XFR\</PARAMETER>

    <PARAMETER name="FilenameMode">Client</PARAMETER>

    <PARAMETER name="SupplementaryTextinXFR">OFF</PARAMETER>

  </SECTION>

  <SECTION name="ABC">

    <PARAMETER name="LocationMode">Client</PARAMETER>

    <PARAMETER name="Path">%DMSFILEPATH%\issfile\</PARAMETER>

    <PARAMETER name="FilenameMode">User</PARAMETER>

    <PARAMETER name="SupplementaryTextinXFR">ON</PARAMETER>

  </SECTION>

  <SECTION name="WORKSHOP123">

    <PARAMETER name="LocationMode">Server</PARAMETER>

    <PARAMETER name="Path">c:\xfr\</PARAMETER>

    <PARAMETER name="FilenameMode">User</PARAMETER>

    <PARAMETER name="SupplementaryTextinXFR">CLIENT</PARAMETER>

  </SECTION>

</xml>

 

ParameterExample ValueDescription
SECTIONDEFAULTAllsettings in epc_xfr_cfg.xml are based on WORKSHOPID in which the user is a member. For each WORKSHOPID an individual setting can  be defined. If the WORKSHOPID is not found in this file, than the DEFAULT section will be used.
LocationModeServer
Client
This parameter interacts with the next parameter Path. It defines from which view will the Path be used:

LocationMode=Server:
Path must be reachable from the Server. If i.e. Path=c:\xfr this folder must exist on the Server. The Client needs no direct connection to this Path.

LocationMode=Client:
Path must be reachable from the Client. If i.e. Path=c:\xfr this folder must exist on the Client.
 

Pathc:\xfr\
%XFRPATH%
\\dmsserver\xfr\
Defines, the path to the xfr file (without the filename itself). Absolute path, environment variables and UNC path are allowed as acceptable formats.

Note:
Environment variables will only work with LocationMode = Client  !

Note:
UNC path will only work with LocationMode=Client because the server is running with SYSTEM account and is not allowed to use UNC.
 

FilenameModeUser
Client
FilenameMode=User uses the User name as file name for the transfer file, i.e. "JIM.xfr"
FilenameMode=Client uses the Client hostname as file name for the transfer file, i.e "workstation1.xfr".

Note:
In a Terminal Server environment will with FilenameMode=Client have following behaviour:
LocationMode=Client  >  Filename = Terminal Server Client Name (recommended)
LocationMode=Server >  Filename = Terminal Server Name (should not be used !)
 


SupplementaryTextinXFRON
OFF
CLIENT
This setting allows to set the feature on a workshop base. It will overwrite the setting in the epc_cfg.xml.
Supplementary Text of a part will be shown in xfr file (= ON )
Supplementary Text of a part will be not shown in xfr file (= OFF )
Setting could be defined on Client side

 


9 Transfer File

9.1 Transfer File Format

The transfer file is not encoded to be backwards compatible to FlexPub xfr file.

The transfer file (xfr) is structured :

Each field has a variable length and is terminated with a vertical bar character (‘|’, ASCII 124).

Notes:
Two consecutive delimiters, “||” indicates an empty field. Example: SERVER01.XFR|USER1||

9.1.1 Header Line

Field NameExample ValueDescription
XFR_FILE_NAMEJIM.xfrname of transfer file (without the directory name)
 
USER_NAMEJIMname of current user
 
SHOPPINGLIST_NAMELIST1name of the last used Shopping list (could be empty)
 

Examples:

SERVER01.XFR|USER1||

BHCLNT02.XFR|USER2|LIST1|

 

 

9.1.2 Parts Records

The remainder of the file will be organized as lines of information with each line representing a part record on the shopping list. Each field is variable length. Each line will contain the following fields in the order shown:

Field NameExample ValueDescription
Part_NUMBERA1234567890Part Number without any special formatting including KB code.
 
PART_DESCRIPTIONBRAKE CALIPERPart description
 
QUANTITY001The contents of the part quantity field reflect exactly what is shown as the quantity in the EPC. This may be an integer (possibly with leading zeroes), a decimal quantity, a dash  ('-'), or other quantity designations contained in the data from Mercedes-Benz.
 
MODEL_CHASSISWDB123123The model number or chassis number (with World Manufacturer Code) that was current when the part was added to the list, if any. The World Manufacturer Code  is included if the user has entered an entire chassis number or only a six-digit model number.
 
GRATUITY_CODEGCGratuity (Shop) Code
 
SUPPLEMENTARY_TEXTOptional withSupplementary Text, if enabled in settings
 

All information will be represented as ASCII printable characters. There will not be any binary data (such as integer values). Each component of each entry will be stripped of trailing spaces and followed by a separator character, which at this time has been chosen to be the vertical bar character ('|' or ASCII 124).  A delimiter will not precede the first entry and a delimiter will follow the last entry. Lines which have missing components (such as a missing gratuity code) will contain two consecutive delimiters, "||".

Some Examples:

SERVER01.XFR|USER1|LIST2|
A1234567890|BRAKE CALIPER|001|WDB123123||
N123456789012|SCREW|  -|WDB12312310123123|GC|
A9876543210|USER ADDED PART|002||WP|
N987654321098|HOSE|3.5||Optional with A1234567890|
 

The first sample line above is an example of the transfer file header line containing the file name, user name, and most recently saved or loaded shopping list.

The sample code given in Appendix A opens each shopping list transfer file and processes the input. 

The format of the part numbers will be determined by the KB code.   The part number formats are described in Appendix A.   For example, the part number field for the last example part shown above contains two embedded spaces.

 

9.2  File Modification Timing

The shopping list transfer file for a given workstation is written any time the current shopping list in the EPC changes.  This includes the following:

Notes:
There is no way for a DMS program to request that the EPC write the current shopping list. 
If another program deletes or otherwise invalidates the transfer file, the EPC will not rewrite the file until one of the events listed above occurs.
No file-locking mechanism is used while the transfer file is being written, so care must be taken to ensure valid data.



10 Appendix A

 

The table below shows the valid part number formats for each KB that can be included in the EPC products.  The “Chars” column shows the range of the number of characters allowed after the KB code.  The “ES1” and “ES2” columns show whether parts with the given KB code can include the two types of ES codes.  Empty cells shown in this table correspond to embedded spaces in the formatted part number in the transfer file.  Trailing spaces will be deleted in the transfer file.

 

KBCharsES1ES2Source DataTransfer File Format
 0123456789012345678
A10

 

24A1234567890A1112223344        
A1112223344AB      
A1112223344CDEF    
A1112223344ABCDEF  
B800B61234567B61234567          
C800C12345678C12345678          
H1224H123456789012H123456789012      
H123456789012AB    
H123456789012  CDEF
H123456789012ABCDEF
K7-1000K1234567890K1234567890        
N1220N123456789012N123456789012      
N123456789012AB    
Q1-1800Q123456789012345678Q123456789012345678
Q B6900QB61234567QB61234567         
W1020W1234567890W1112223344        
W1112223344AB      
X9-1224X123456789012X123456789012      
X123456789012AB    
X123456789012  CDEF
X123456789012ABCDEF

                Where AB represents an ES1 Code and CDEF represents an ES2 code.