Etasoft Mini Translator version 1.x

Transcription

1 Etasoft Mini Translator version 1.x Copyright Etasoft Inc. Main website Product website Purpose...2 Requirements...2 Package Details...2 Results...3 Licensing...3 Main Program...5 What Are Invalid EDI Files?...8 Looping and Processing Details...9 Maps and Map Editor...9 Batch Command Line Execution...12 Performance...14 Developer SDK...14 Technical Support...14 Etasoft Inc. Page 1 12/1/2009

2 Purpose Mini Translator is a set of tools designed to produce human readable formats out of EDI data files. It is mini translator, EDI standards database and report generator rolled into one. Typical translators are designed to produce or consume EDI files in order to make other computer systems talk to each other. Mini Translator is designed to take an EDI file and produce one of easier to read formats like CSV, Text or XML. It uses slim down version of database with EDI standards to find names and meaning of most of EDI constants. Requirements Minimum Requirements Software Windows 2000/XP/Vista/Server 2003/7 Hardware Pentium 1GHz, RAM 256Mbt Recommended Software Hardware Windows XP Pro Pentium 1.5GHz, RAM 512Mbt Package Details Package comes as setup program for Windows based personal computers. Software product does not install any separate runtimes or systems and does not require them to be preinstalled. Example: software does not use.net or Java runtimes and does not need them preinstalled. It does not create any Registry entries. We recommend to always use setup program to install product on new computer. However technically you could simply copy it from one computer to the other (so called xcopy install scenario). Once installed product creates following important files: 1. edirepgui.exe main program. 2. edireprun.exe command line batch type report runner. 3. edireports.pdf Users Manual documentation. Etasoft Inc. Page 2 12/1/2009

3 Results After successful execution Mini Translator produces files in number of formats. Some formats like CSV can be open in popular spreadsheet programs such as Microsoft Excel. You might need to move and resize spreadsheet columns to see all the data properly. Keep in mind that spreadsheet programs have certain limitations on how many columns and rows they can display or how big of spreadsheets they can handle. Some have hard set limits of no more than 256 columns and no more than rows. If your EDI file contains hundred thousand segments you might not be able to open it in a typical spreadsheet program. It is limitation of spreadsheet program and not of Mini Translator. Output of EDI 837 displayed as CSV crosstab spreadsheet. Sensitive customer information is removed from this screenshot. Licensing Default package installation comes as time limited trial evaluation license. After fixed number of days starting from the day of the first use, trial evaluation license will expire and most of software features will become disabled. If you like the product and purchase it, you will receive permanent license key. This new key must be entered in License dialog: Etasoft Inc. Page 3 12/1/2009

4 License key should be entered via License button on Mini Translator main screen. If you let trial version to expire this will eventually stop software from processing data. Once you decide to purchase the product, you will receive new permanent license key that you can enter in the License screen. This new key will unlock the product without a need to reinstall it. Etasoft Inc. Page 4 12/1/2009

5 Main Program Main program allows both run and creation of reports. Set your EDI file, desired output file and report formats at the top of the screen. You can also drag and drop files from other programs like Windows Explorer or My Computer screens. Once file is dropped, Mini Translator will fill Output file name based on report format of your choice. Input EDI file and output directory for output file must exist. Use top of the screen to enter your input, output files and choose report format. Etasoft Inc. Page 5 12/1/2009

6 Runtime options allow you to setup report execution modes: 1. Run report once input file is dropped on - this option if checked will execute report once file is dropped on the program main screen. You can use Windows Explorer or My Computer to drag and drop files on Mini Translator. 2. Open report after execution this option if checked will try to open report in external program associated with specific format. Example: if you have Microsoft Excel installed then CSV file most probably will open in it. If you want other program to open reports change default association between program and file name extension in Windows. Example: you can change that XML files would open in your favorite XML editor instead of default program or notepad. Please refer to Windows help or documentation on how to change file associations. 3. Auto-start. Also watch input file and run report if file changes this option if checked will monitor input file for changes and execute report once file change is detected. It also executes report on startup. This option is used mostly for semiautomated processing. You can setup Mini Translator to wait for file to be copied into the directory by other program, so it would kick-start report processing as soon as input file comes in. It is not recommended to use this option for files that are on mapped network drives, files on mapped NFS or mainframe remote computers. Remote connections are not reliable, even rather short network disruption may stop file change detector process inside Mini Translator. For remote files use command line batch runner edireprun.exe program and execute it at certain time intervals during the day using some scheduled execution program. 4. Run basic EDI validation this option if checked executes basic EDI validation. Basic EDI validation performs ISA, GS, ST, SE, GE, IEA EDI envelop checking. Etasoft Inc. Page 6 12/1/2009

7 Mappings are created or reused every time Mini Translator runs. Mappings allow you to customize report by selecting fields you want to see in the report and by settings the rules how those fields should be filled up. Use Edit and Delete buttons to customize or remove existing maps. Etasoft Inc. Page 7 12/1/2009

8 You can always press Close or Stop button even during processing. EDI Hot Spot prints some of the processing information. It also lists any validation or processing errors. What Are Invalid EDI Files? Once you open EDI file in some text editor like Notepad, it looks cryptic. However all valid EDI X12 files have same properties: 1. They all start with three letters: ISA 2. After 103 characters there is word GS. Sometimes GS is on the second line. If GS is on the second line then there might be only 102 characters between ISA and GS. Mini Translator reads and breaks down EDI files using these two points above. Most common scenarios why Mini Translator might not be able to process the file: 1. That is not an EDI X12 file. Period. It is flat file, XML or scanned print image form or something else but EDI file. 2. If you copy and paste EDI file from Internet Browser window in most cases resulting EDI file will not be valid anymore. This is due to how spaces are displayed in the Browsers. Instead of 103 characters between ISA and GS you might end up having much less. Etasoft Inc. Page 8 12/1/2009

9 3. Usually EDI files are sent over secure connections using encryption/decryption communications. Sometimes not just communications but EDI files are encrypted themselves. Encryption leaves ISA/GS part valid but all segments in the file unreadable. Unless EDI file is decrypted Mini Translator will not be able to read it correctly. 4. Some EDI files come from mainframe computer systems. Occasionally they are formatted into columns of 80 characters long. Extra carriage return and line feed characters break segments into multiple lines making EDI file invalid. Those files can not be processed. 5. Rarely EDI software communication packages combine multiple EDI messages of various types into one file. There are two variations of this combination: a) Example: 810 invoices and 997 acknowledgements with the same separators in one file. This is valid EDI file however output of Mini Translator might not look right. Because Mini Translator will try to flatten EDI loops and encounter few loops repeating independent of each other (as per example above: 810 invoices will repeat separately from 997 loops). It is like trying to combine two spreadsheets that have no common fields; at the end combined spreadsheet will have mix of lines that do not tie up. b) Example: 810 invoices and 997 acknowledgements with the different separators in one file. This is not possible to process. Mini Translator detects separators at the start of the EDI file. If separators change somewhere in the middle of the file Mini Translator will continue processing the file using old separators found at the file start. Scenario when various EDI messages are mixed in one file with different separators is very rare but we mention it here to complete possible list of files that can not be processed. Looping and Processing Details Mini Translator uses compact database with EDI information to look up number of codes and values you see in a typical EDI file. This allows creation of the output that contains human readable text instead of 2-3 letter codes. Mini Translator also tries to create flat structure out of looping EDI hierarchies. As a result EDI header fields repeat they values for every new line of the output file. New line in the output is created when nested EDI loop repeats. You can alter output using mappings screen. Creating flat structure out of looping EDI messages with many nested hierarchical levels is not a trivial task. Flat structure is created by repeating header and trailer field values while creating new values of detail fields on each new output line. Mini Translator performs looping structure analysis as first processing step. Result of this analysis is how many output lines or columns are created in the report output file. If you want to reduce number of lines created, exclude some fields from the output using buildin Map Editor screen then use modified map for processing. Maps and Map Editor Software comes with build-in map editor and map generator. If option Create new or use existing based on input is selected then map generator will take over and create mappings for you. Mappings are reused by matching existing map properties to incoming input file properties. Once match is found, existing map is used. If there is no map matching incoming file then new map is created based on input file. This complex setup in most cases should relieve you from any need to modify mappings. However if you need to change what fields should be included in the output and how they should be filled with values, then select the map from the drop down list and use Edit button. Once you edit the list of fields, choose OK in the dialog screen. Your mappings will be saved. After that you can choose the map in the Use Map: drop down to force Mini Translator use specific map, or you can allow Mini Translator to auto-select map based on input file. The way how auto-select works is simple: 1. Once Mini Translator reads input EDI file, it detects EDI file identity. In most cases identity is just Transaction Identifier + Interchange Sender Id. 2. Mini Translator reads all maps from the database and matches identity of the incoming EDI file against existing maps. 3. If non of existing maps have the same identity, new map is created. 4. If any of the maps match based on identity, then that map is used for processing. Auto-select is turned off when option Create new or use existing based on input is not selected. Etasoft Inc. Page 9 12/1/2009

10 Select items you want to have produced in the report. Set line up field to produce desired number of lines in the output. Repeat Previous and Use Next options control what value should be placed in the field for each new row if current value is empty. They are especially important for header and trailer fields, and fields that are optional. Sometimes you might want to have some fields to be always present for each line of output, sometimes you might want to have some fields to be produced in the output only when they have a value in that line. Repeat Previous and Use Next options allow this type of control. 1. If you check Repeat Previous translation will use current value or if there is no current value for the output row it will reuse value from previous row. 2. If you check Use Next translation will use value from the next output row. 3. If both Repeat Previous and Use Next are checked then translation will try to fill the value first from current row, then from previous row and finally if all are empty then use next rows. 4. If both Repeat Previous and Use Next are unchecked then translation will use only current row value. In most setups Repeat Previous is set on header fields and Use Next is set on trailer fields. If you want output field to always have a value check both Repeat Previous and Use Next. If you want output to have only value when it is in the file and belongs to current line uncheck both Repeat Previous and Use Next. Mini Translator tries to line up output automatically based on how many times each field repeats and based on general structure of the message. This might produce undesired output since automatic line up is based on best-guess scenario and may not reflect your specific business needs. In most cases when automatic line up will not match your needs it will produce too many lines in the output side. You can always turn-off automatic line up and guide Mini Translator by manually selecting field using Map Editor screen. Etasoft Inc. Page 10 12/1/2009

11 Best candidates for line up field usually are unique data identifiers such as: invoice number, invoice line number, purchase order number, purchase order line number, subscriber or insured Id, patient Id, claim Id, claim line number, claim date, patient diagnostic procedure code. In this example EDI X Healthcare Claim is lined up based on claim detail lines. Based on what output field is chosen for line up field Mini Translator will create as many output lines as many values of line up field there are in the input file. Example 1: if you setup line up field to be invoice number, you will get as many output lines as many invoice numbers there are in the input file. Example 2: if you setup line up field to be claim detail line number, you will get as many lines as many claim detail lines there are in the input file. Etasoft Inc. Page 11 12/1/2009

12 When report runs new input file it calculates and provides hints what fields are better suited to line up all other fields. This hint is displayed next to field name as *** suggestion. Suggestion is just that. Best way to find proper setting is by experimentation. Experiment with Line up field setting until you get desired output. Batch Command Line Execution You can run Mini Translator as part of other batch based job. Batch execution is used in automated or semi-automated data processing systems where execution takes place at certain times during the day or when certain events occur (example: input file is copied to receive directory). Batch execution is common for long running processing jobs, overnight running jobs. Etasoft Inc. Page 12 12/1/2009

13 Use edireprun.exe command line batch processing utility to run reports in batch mode. edireprun.exe utility takes following case sensitive parameters: 1. license=? License key to run Mini Translator (mandatory parameter). Use your license key from License screen of Mini Translator main program. 2. input=? Input file name (mandatory parameter). 3. output=? Output file name (mandatory parameter). 4. csv2 Output format is CSV file without header fields. 5. csv3 Output format is CSV file crosstab. 6. xml Output format is XML file. 7. txt Output format is Field=Value text file. 8. validate Perform basic EDI validation. No validation if this parameter omitted. Parameters to output XML file and validate EDI input. You can also setup report execution program as shortcut icon on your desktop. That way you can have few icons and each will run and process different input file. Simply open some text editor like notepad.exe and enter all the command line text into it. Then save file with.bat extension. In the Windows Explorer right click on that file with.bat extension, press Copy menu and right click on the desktop and press Paste Shortcut. Now you will have a shortcut desktop icon that you can double click to execute the report. Etasoft Inc. Page 13 12/1/2009

14 Save report execution command as batch file with.bat extension. Enter your license key from License screen of Mini Translator main program. Here is desktop shortcut icon to run specific report after.bat file was created and shortcut for it pasted on the desktop. Performance Mini Translator reads and parses EDI files in computer memory. That puts certain limits on how big input EDI files it can process. Also since output report files are more verbose than input EDI files total output size could be 7-10 times greater than input size. Example: if your input EDI file is 4 Mbt your CSV output file might be around 30 Mbt. If your EDI file is greater than 40 Mbt we recommend breaking it in smaller chunks before you try to process it using Mini Translator otherwise resulting file might be over 300 Mbt and will be hard to view in any file editor. Developer SDK You can execute Mini Translator as part of your.net application or ASP.NET web page. It comes with API for software integration installed into DeveloperSDK directory. Developer SDK simply allows you to call Mini Translator processing engine via your code. All you need to do is distribute all the DLLs and all files with *.db extension as part of your program. Main runtime DLL is edirepruntime.dll. Reference it in your.net project. Use class edireportexecute to run the reports. Look at complete sample called edirepdotnet under DeveloperSDK directory. Technical Support Please contact technical support if you have any questions or concerns. Contact information is listed on the product and company websites. Etasoft Inc. Page 14 12/1/2009