E205 Troubleshooting e-Biz Integrator configuration and formatter

1. E205Troubleshooting e-Biz Integrator configuration and formatter • Christopher Nye • Sr. S/W Engineer – QA • E-Business Division • Christopher.Nye@sybase.com

2. Formatter Overview • Transforms messages based on static definitions • Fewer interfaces needed between connected systems; instead of a one-to-one interface between systems, allows for a hub and spoke architecture E-Biz Integrator 56 Interfaces 16 Interfaces

3. Formatter Overview • Steps to reformat message: • Parse • Break apart a message buffer into data fields • Map • Reorder data from input format structure to output format, based on field-to-field correlation • Data transformation • data type conversion and application of output operations.

4. Parsing When parsing a message, the formatter takes a linear message buffer, and splits it into individual fields that can be evaluated and manipulated individually: John|Doe|125 Main St.|…. Parse First Name Last Name Street Address City State Zip SSN Job Code

5. Parsing (cont) Parsing fields • Field termination: Where does the data end? • Delimiter, exact length, regular expression • Tagged Data: Using message data as field identifier • Optional Fields: Does the data have to be in the message?

6. Parsing (cont) Parsing formats • Format Termination: Allows for a delimiter on a group of fields. • Optional formats: Fields that occur or not as a group • Alternative compounds: A compound format with two or more options to parse; similar to a C++ switch statement • Repeating data: A format that can appear more than once in the message • Random components: Message sections that can occur in any order

7. Parsing (cont.) Alternative compounds Allows for a “pick one” situation. Requires some way to differentiate between formats (usually tags or literals). F1 F2 F3 or F4 F2 F3 or F1 F5 F6

8. Repeating input data Formats can be set to repeat to handle multiple instances of the same fields. This may require some way to indicate the end of the repetition. …

9. Random formats • Random flat: Allows fields to be parsed in any order. This requires some way to distinguish one field from another. • Random compound: Allows formats to be parsed in any order. Field order within the formats is maintained. Requires method of identifying each format. 1 2 3 3 1 2 or or 1 2 3 4 5 6 7 8 9 4 5 6 1 2 3 7 8 9

10. Mapping Re-order and/or combine the fields generated during the parse step into a new output structure. Original message buffer Parse Map

11. Mapping (cont) • Access Modes: Control how field data is mapped from input to output • Repeating output data • Alternative output compounds: Same “pick one” as input compounds, but can select choices based on field data • Map objects

12. Mapping (cont) Access Modes for non-repeating fields • Not Applicable: no data mapped. Used for literals and fields that get data from somewhere other than input message such as a user exit • Normal Access: field data simply copied to output field

13. Mapping (cont) Access Modes for repeating fields • Controlling Field: the “driver” for the repeating format • Access Sibling Instance: map the same repeat instance as the controlling field • Access Parent Instance: map data from a repeat “above” the controlling field • Access n-th Instance: map data from a specific repeat instance

14. Mapping (cont) Alternative output compounds • Alternative selection can be based on mapped data (mandatory output fields) • Output controls allow alternative selections based on field data (Boolean controls) • Input Field Exist • Input Field=

15. Mapping (cont) Map objects Map objects allow for the field-to-field linking to be defined separate from the output format itself. This allows for true many-to-many mapping without having a global field lexicon. InputFormat1 InputFormat2 InputFormat2 Map1 Map2 Map3 OutputFormat1 OutputFormat1 OutputFormat2

16. Data Transformation Output Operations • Operation order • Case, Convert, Default, Prefix/Suffix, Length / Justify, Math Expressions, Substitute, Substring, Trim

17. Data Transformation (cont) User exits • Used to perform custom transformations on data fields using C++ code above and beyond normal formatter functionality • Typical exit flow: • Get data from input using formatter APIs • Manipulate data as needed • Return data to output field

18. Test Tools • Apitest and msgtest • Pros: Available on all platforms, in-depth debug output • Cons: command line tools, requires input file containing a single message • Visual Tester • Pros: Can take input from file, transport, or screen input; can split input into multiple messages • Con: Only on NT (may cause inconsistencies between test and development environment)

19. Apitest and msgtest These command line tools execute the same formatter function calls used by the broker and adapters, using the same libraries. They should be the core testing tools when developing new formats.

20. Apitest and msgtest (cont) Debug flags allow for far more detailed information than what is provided by status messages. apitest [-d [ filename ] ] Lists the message data parsed into each field msgtest [-d [filename]] [-dcm] [-dco] The –d flag lists the same parse data as in apitest. The dcm flag displays mapping from input field to output field. The dco flag shows the results of each output operation

21. Debug output Parse Debug Format Name='IC_Top' Properties: Type=Compound, Order=Ordinal ... Component Format Name='IF_Flat2' Properties: Type=Flat, Order=, Optional=No, Repeating=No [1] Field='fld3', Data_Type=Ascii_String, Data='20020115', Data_Length=8', Byte Offset=12 [2] Field='fld4', Data_Type=Ascii_String, Data='004', Data_Length=3', Byte Offset=21

22. Debug output (cont) Map Debug Format Name='OC_Top' Properties: Type=Compound, Order=Ordinal ... Component Format Name='OF_Flat2' Properties: Type=Flat, Order=(N/A), Optional=No, Repeating=No [1] Output field='fldC', Access_Mode=Normal_Access Input field='fld3', Data_Type=Ascii_String, Data='20020115', Data_Length=3', Byte Offset=12 [2] Output field='fldD', Access_Mode=Normal_Access Input field='fld4', Data_Type=Ascii_String, Data='004', Data_Length=3', Byte Offset=16

23. Debug output (cont) Output Debug Format Name='OC_Top' Properties: Type=Compound, Order=Ordinal ... Component Format Name='OF_Flat2' Properties: Type=Flat, Order=(N/A) [1] Output field='fldC', Data_Type=Custom_DateTime, Data='15-jan-02', Data_Length=9', Byte Offset=12 NNFOutCtrlCodeSetConvert='', Data_Type=Custom Date/Time, Data='15-jan-02', Data_Length=9' NNFOutCtrlFix='comma_suf', Data_Type=Custom Date/Time, Data='15-jan-02,', Data_Length=10'

24. Common Error Messages Where Errors are reported • NNSYMessageLog.nml • Lists timestamp, application that encountered error, and full error code and text • Error codes are listed in the Formatter Programmer’s Reference • Screen output from applications (on standard error stream)

25. Common Error Messages (cont) Errors During parse • Trailing characters • Mandatory input field not found • Not all fields found • Literal not found for input field

26. Common Error Messages (cont) Errors During map • Mandatory output field contains no data • Boolean control evaluated to false

27. Common Error Messages (cont) Errors During output operations • Math expression parse failed • Conversion to output type failed • Operations not “firing”

28. Other Common Problems • Incorrect output • Infinite loop in repeating format • Alternative formats selecting wrong choice

29. Questions