coding guide - seeburgermappingmanagement.seeburger.de/seexml/wiki/media/wiki... · 2019-04-17 ·...
TRANSCRIPT
© SEEBURGER AG 2017 169© SEEBURGER AG 2018 169
Coding Guide
© SEEBURGER AG 2017 170© SEEBURGER AG 2018 170
1 Introduction
© SEEBURGER AG 2018 171
Coding GuideIntroduction
Goal of this coding guide is to unify the creation of mappings. Especially for SEEXML partner mappings it isnecessary to have such a guide. We want to provide this guideline to everyone who is creating mappings forSEEBURGER (also external partners).
The following rules are valid from now on for all new BIC-mappings (direct mappings and SEEXML-mappings) created with BIC version 5.5.2 and higher!
© SEEBURGER AG 2017 172© SEEBURGER AG 2018 172
2 Naming conventions
© SEEBURGER AG 2018 173
Coding GuideNaming conventions
Message structures
Following rules are valid for all message strucures where it is allowed to set the name yourself (non EDIFACT,non ODETTE, non ANSI X.12, non VDA (+ERG), non SEEXML).
• Use English as language
• Use the underscore to separate between special parameters (e.g. DELFOR_XYZ)
• If a message has the suffix “STD” you must not change this structure! (use a copy with new name instead)
© SEEBURGER AG 2018 174
Coding GuideNaming conventions
INHOUSE
If the name of the INHOUSE-message is not predefined by the customer, choose the following namingconvention:
Syntax BusinessCase_Customer
Example DELFOR_XYZ
© SEEBURGER AG 2018 175
Coding GuideNaming conventions
SAP
We use the name generated by SAP. The German or English variant must be marked by D or E. Furthermore itmust be marked if it is a SAP-XML-IDoc. In all cases where the structure was adapted to the customerrequirements (so called Z-Idoc), it must be marked in the name.
Syntax BusinessCase_(D or E)Release_(Customer)
Example INVOIC02_D46C or ZORDERS05_E45B_XYZ or X_DELFOR02_D640
© SEEBURGER AG 2018 176
Coding GuideNaming conventions
VDA
We use the predefined names of the VDA plus version. Additionally, we put „STD“ at the end to show thatthe structure is conform to the VDA-guideline and the structure is provided by SEEBURGER. If changes of theSTD-structure will take place the structure must be renamed (i.e. VDA4905_V04_VW)!
Syntax VDAName_Version_(ERG)_(Addition)_STD
Example VDA4905_V04_STD or VDA4913_ERG_STD
© SEEBURGER AG 2018 177
Coding GuideNaming conventions
CSV
We use the same naming convention as for the general INHOUSE-messages
Syntax Business case_Customer
Example ARTICLEDATA_XYZ
© SEEBURGER AG 2018 178
Coding GuideNaming conventions
SQL / DATABASE
We use the same naming convention as for the general INHOUSE-messages.
Syntax BusinessCase_Customer
Example ARTICLEDATA_XYZ
© SEEBURGER AG 2018 179
Coding GuideNaming conventions
XML
The naming convention for XML structures is dependant on the publisher.
Syntax BusinessCase/Name_Version_(Customer)
Example BMECAT_10
© SEEBURGER AG 2018 180
Coding GuideNaming conventions
EDIFACT/ODETTE
The name of EDIFACT structures is predefined by the UN. We only put “STD” at the end of the name to verifythat the structure is EDIFACT/ODETTE conform and that it is provided by SEEBURGER. If changes of the STD-structure will take place the structure must be renamed (i.e. DELFOR_UN_D96A_PSA)!
We use the same naming convention for ODETTE structures.
Syntax MessageType_Organisation_Version/Release_STD
Example INVOIC_UN_D93A_STD or DELINS_OD3_STD
© SEEBURGER AG 2018 181
Coding GuideNaming conventions
SEEXML
Following naming conventions are valid for SEEXML:
Independent (CPG and Automotive):
Syntax Name_Version
Example SEEDELFOR_V3_0, SEEDESADV_V3_0, SEEINVOIC_V3_0
© SEEBURGER AG 2018 182
Coding GuideNaming conventions
Automotive:
CPG/Retail:
Syntax SEE_MessageTypeVersion
Example SEE_ORDERS_V01
Syntax Name_Version
Example SEEDELFOR_V2_0, SEEDESADV_V2_0, SEEINVOIC_V2_0
© SEEBURGER AG 2018 183
Coding GuideNaming conventions
TRADACOM
Tradacom-structures are predifend by the Article Number Association (UK) Ltd (ANA).
Syntax BusinessCase_Version
Example INVOIC_123
© SEEBURGER AG 2018 184
Coding GuideNaming conventions
ANSI X.12
The name of ANSI structures contain the message type, version and „STD“. The STD is used to verify that thestructure is ANSI conform and that it is provided by SEEBURGER. If changes of the STD-structure will takeplace the structure must be renamed (i.e. 830_3030_FORD)!
Syntax MessageType_Version_STD
Example 830_002040_STD
© SEEBURGER AG 2018 185
Coding GuideNaming conventions
SWIFT
We used the predefined names of the SWIFT Standard Organisation.
Syntax SwiftName_(Bank)
Example MT940, MT940_Commerzbank
© SEEBURGER AG 2018 186
Coding GuideMappings
The following rules are valid for all mappings:
• Use the underscore to separate between special parameters
• There are no further separators
Partner mapping:
Syntax Partner_EDI-Message-Partner_Direction
Example SCANIA_DELFOR_D96A_IN (SEEXML-Partner-Mapping)
© SEEBURGER AG 2018 187
Coding GuideNaming conventions
Process mapping:
Syntax Branch_CustomerOrSupplier(C or
S)_SourceMessage_TO_DestinationMessage_Customer
Example AUTO_C_SEEDELFOR_V3_0_TO_DELFOR02_[Customer] (SEEXML-Prozess-
Mapping)
© SEEBURGER AG 2018 188
Coding GuideNaming conventions
Direct mapping:
If a message type can be used for several business cases, the business case must be put directly after thepartner.
I.e. OPEL_PUS_DELJIT_UN_D97A_STD_TO_DELFOR02_D640
Syntax Partner_SourceMessage_TO_TargetMessage
Example TOYOTA_830_4010_STD_TO_DELFOR02_D640 (BIC Direct Mapping)
© SEEBURGER AG 2017 189© SEEBURGER AG 2018 189
3 Coding
© SEEBURGER AG 2018 190
Coding GuideCoding
We refer to the notion concerning mappings in the Mapping Management Guide!
All mappings, comments, variable names and so on must be written in English. You have to use BIC featureswhen possible. Try to write one line instead of five lines.
© SEEBURGER AG 2018 191
Coding GuideRules for any kind of mapping
Header
Following information must be mentioned in the header of each mapping.
1. @Customer Either the name of the customer for which the mapping is created or the key
word Standard-Mapping
2. @Author Name of the creator of the mapping
3. @SourceMessage Source Message of the mapping
4. @ReleaseSource Release of the source message (e.g. 4.6C)
5. @DestinationMessage Destination Message of the mapping
6. @ReleaseDestination Release of the destination message
7. @Type „Direction“ of the mapping (e.g. IE for INHOUSE EDIFACT
© SEEBURGER AG 2018 192
Coding GuideRules for any kind of mapping
8. @Partner Partner for which the mapping is valid
9. @Mapfiles Used mapfiles in this mapping
10.@Created on Date in format CCYYMMDD
11.@BIC-Version BIC version where the mapping was created
12.@Description Description of the use of the mapping
13.@ParentCopy Name of the mapping copied from
14.@SpecialInformation If there are special things (like user functions, use of additional programs…) mention here
15.@Changes Every change of the mapping must be documented in a new line and should contain the following information
- Description of the change
- Date of the change
- Name of the person who changed the mapping
© SEEBURGER AG 2018 193
Coding GuideRules for any kind of mapping
Example:/*
SEEBURGER AG BIC Mapping
@Customer = STANDARD-MAPPING
@Author = Name of mapping creator
@SourceMessage = DELFOR
@ReleaseSource = UN_D96A_STD
@DestinationMessage = SEEDELFOR
@ReleaseDestination = 3_0
@Type = E2X
© SEEBURGER AG 2018 194
Coding GuideRules for any kind of mapping
@Partner = DAF
@Mapfiles = Mention here used mapfiles
@Created on = 20061127
@BIC-Version = 5.4.2 Q7
@Description = Description can (and should!) be
over several lines
@ParentCopy = Name of the Mapping copied from
@SpecialInformation = STANDARD-MAPPING Based on guideline…
@Changes = 2006-11-27: First version
= 2006-11-28: Shortcut of changing person: Added RFF+DQ
*/
© SEEBURGER AG 2018 195
Coding GuideVariables
The first part of a variable name indicates the scope of usage. We use g for global, d for dim, p forparameter (at procedures) and l for local. Please note that the BIC manual recommends to use globalinstead of dim.
Concerning the name of the variables the content of the field you want to save, is important. A furtherpossibility is to use the original field name as variable name (e.g. g_P16_EDATUB$). Please avoid variablenames like temp$, y% and so on as no one, except you, know what they mean. You are only allowed touse variable names like that, if it is a local variable which is only valid for a small coding part.
Please do not use any hyphens (“-“) in variable names and delete every variable you do not need.
For every separate word in the variable name must divide with a (“_”). The first capital of any word mustbe in uppercase anything else generally in lowercase. Specific Elements such as Qualifier or own namesmust be completely written in uppercase.
© SEEBURGER AG 2018 196
Coding GuideVariables
Examples.: Customer number g_Customer_Number$
Supplier number g_Supplier_Number$
Transmission number g_Transmission_Number$
P16_EDATUB g_EDATUB$
Furthermore we describe some special conditions for variable names. Other interpretations of variablenames are not allowed.
© SEEBURGER AG 2018 197
Coding GuideConstants and System values
All constants must have uppercase letters. The values of the variables do not change in the mapping.
Examples.: DEBUG$ - for all Debug-Analysis
DEBUG_TEXT$ - for all Debug-Textes
DEFAULT_EDIFACT_ENCODING – for Edifact Encoding
MAPPING$ - for the Name of the mapping
VERSION$ - for the Version of the mapping
© SEEBURGER AG 2018 198
Coding GuideCounter
All Counters begin with “Counter_” followed by the reference of the counter. It is global defined asnumeric.
Examples: UNB Counter Counter_UNB%
Item Counter Counter_Item%
© SEEBURGER AG 2018 199
Coding GuideLoops
A specific counter for algorithmic operations is a loop. All loops begin with “Loop_” followed by thenumber of the Loop. A Loop is global defined as numeric.
Examples: Frist Loop Loop_1%
Second Loop Loop_2%
Every level within a loop (if-, for-, selectcase-loop) must be indented by four blanks (= 1 TAB) to have abetter view.
Using several nested loops you should comment the start and end commands.
© SEEBURGER AG 2018 200
Coding GuideLoops
Note: Use selectcase instead of if. This is caused in performance reasons.
If the loop appears into a procedure you have to put a ‘l_’ prefix before the variable name.
E.g. l_Loop1%, l_Loop2%, … This is necessary to avoid errors with global variables if you call the procedureinto a loop which is initiated by a Loop_*% variable.
© SEEBURGER AG 2018 201
Coding GuideBoolean Variables
All Boolean variables have their own specific prefix, e.g. you can use Found_, Created_ or Exist_. TheVariable is global defined as alphanumeric and can have the states “true” or “false”.
Examples: NAD there Created_NAD$
CPS found Found_CPS%
In BIS6 (language 2) you can use the Boolean data type with prefix ‘?’.
Examples: NAD there Created_NAD?
CPS found Found_CPS?
© SEEBURGER AG 2018 202
Coding GuideSpecific Values for getdestinationfield()
If you use getdestinationfield() in your mapping, you must defined the variable with the prefix “Current_”followed by the name of the field value.
Examples: Item.Number:value Current_Item_Number$
QTY.Qualifier:value Current_QTY_Qualifier$
© SEEBURGER AG 2018 203
Coding GuideArrays
All arrays begins with “Table_” followed by the name of the array.
Especially for array variables it is important to delete them as for every array at the beginning of themapping the respective memory is reserved.
Examples: L24 Table_L24$[10]
Item Table_Item$[10]
© SEEBURGER AG 2018 204
Coding GuideCommands
All commands and functions are written in lower case. Is there more than one line using “to”, you have toput that into the same column.
If unused Mapping Code is in the Mapping you have to delete it.
You must write mapping code in clearly arranged design.
Example:copy "380" to UNB.UNH.BGM:C002.1001;
copy K01:BELNR to UNB.UNH.BGM:1004;
© SEEBURGER AG 2018 205
Coding GuideDrag & Drop
Use the Drag&Drop option of the Mapping Designer as you can avoid unnecessary typing errors.
It is possible to setup existcopy as default command for drag and drop.
© SEEBURGER AG 2018 206
Coding GuideComments
Comments are important for everyone who uses the mapping. No-one knows what the creator of themapping thought during programming a complex loop and the creator himself doesn’t know it any morea few days later.
The more detailed the comments are, the better it is.
Comments are only allowed in English.
Usually, comments are inserted one line before the mapping code you want to comment.
© SEEBURGER AG 2018 207
Coding GuideComments
Example of good comment:
© SEEBURGER AG 2018 208
Coding GuideComments
Example of bad comment:
© SEEBURGER AG 2018 209
Coding GuideComments
Please do not left unused code in comment. This causes huge code.
Example:
© SEEBURGER AG 2018 210
Coding GuideCode formatting
Code must be correctly formatted, because, if the code is not formatted correctly, is badly formatted,hard to read, or cannot be copied-and-pasted without unwanted junk. Code should be easy to read andcopied-and-pasted. There three important rules:
• Code examples should use good semantic mark-up
• Tabs in code should not be converted in to spaces.
• Code should have basic syntax highlighting.
© SEEBURGER AG 2018 211
Coding GuideCode formatting
Example of good formatted code:
© SEEBURGER AG 2018 212
Coding GuideCode formatting
Example of bad formatted code:
© SEEBURGER AG 2018 213
Coding GuideCode formatting
Example of bad formatted code:
© SEEBURGER AG 2018 214
Coding GuideCode Review
Code review is important, if the code of mapping is not clear or difficult to read. Code review make theoverall quality of mapping code better and readable. Example of code review necessary:
Before code review: After code review:
This “Partner ID’s” can be replaced with parameter send from Partner_Def mapping.
© SEEBURGER AG 2018 215
Coding GuideCode Review
Before code review:
© SEEBURGER AG 2018 216
Coding GuideCode Review
After code review:
© SEEBURGER AG 2017 217© SEEBURGER AG 2018 217
4 Rules for Individual Mappings and Standard Mappings
© SEEBURGER AG 2018 218
Coding GuideMapfiles
It is allowed to use mapfiles. Every used mapfile must be opened by openmapfile in the first mandatoryrecord pattern or new mapping record. Additionally, every mapfile must be documented in the mappingheader.
The columns in mapfiles must be separated by the comma. They have the file ending *.map or *.cde. Themapfile names must be written in upper case and should not contain any hyphens to avoid problems withnon-Windows-systems.
© SEEBURGER AG 2018 219
Coding GuideJava User Functions
It is allowed to use Java User Functions. Before using them please make sure that the needed functioncannot be realised using BIC commands. The usage of Java User Functions must be mentioned in theheader comment under Special Information. The used JAVA classes must be available in all common javaruntimes to avoid update errors. SEEBURGER will not support errors and issues which are caused by javaclasses.
© SEEBURGER AG 2018 220
Coding GuideArrays
In general the usage of arrays isallowed.
Using two-dimensional arrays it isdifficult to retrace which column haswhich value (the index strats with0). Due to that you should handletwo –dimensional variables asfollows.
According to the column head linesyou have to create variables. Theindex of a column is defined by thevalue you assign to the respectivevariable.
© SEEBURGER AG 2018 221
Coding GuideArrays
You can access the array by using the following command:
g_Order_Date$ = L24_Table$[0][BSTDK%];
In general you should avoid using two-dimensional arrays. Instead use the BIC sort commands (e.g.sortsegmentsbyfieldvalue()) available >= BIC 5.5.2
© SEEBURGER AG 2018 222
Coding GuideHash tables
If possible (BIC 6, language V2) you can use hash tables instead of variables.
E.g.: Table_REF${}{} to save reference values.
In this case the references are saved into an hash table which is addressed by the qualifiers name as first key and the field name as second key.
© SEEBURGER AG 2018 223
Coding GuideProcedures
Definition:
A procedure is a set of instructions that perform a specific task, similar to subroutines or functions.
Procedures are reusable.
Procedures can have one or more parameters.
Procedures can be invoked several times.
Appearance:
Local procedures can be used within one mapping only.
Global procedures can be used by all mappings belonging to one workspace.
© SEEBURGER AG 2018 224
Coding GuideProcedures
Special features of global procedures
If a global procedure is changed only the procedure has to be compiled/deployed. After thecompilation/deployment the changes will be valid for all mappings.
Procedures comply with a record program of a mapping. Same functions/commands can be used toaccess the current source segment/target structure.
Global procedures cannot use variables that are defined in the mappings!
Global procedures can have own variables, they can be used in other methods that belong to the globalprocedure. Local ones can be used in the current method of the procedure only.
Global procedures can be imported/exported from/to the file system.
Global procedures can be imported/exported from/to the repository to share them with otherdevelopers.
Global procedures need to be activated and deployed in BIC MD and BIS Front-end to use them in a BISsystem.
© SEEBURGER AG 2018 225
Coding Guide
Avantages:
Global procedures are independent objects inthe repository and may be used accordingly.
If a global procedure is changed, only this globalprocedure has to be compiled. The mapping willcontain those changes without the need to berecompiled.
Disadvantages:
Global procedures are independent objects inthe repository and may be used accordingly.
If data is read/written from source/to targetstructure the usability is limited. It can be usedfor mappings with the same input/outputstructure only.
Tip: Can be avoided by varying the address strings e.g. using getField/setField method and pass fields byparameter.
Global procedures
© SEEBURGER AG 2018 226
Coding GuideLocal procedures
The procedure editor can be used by open the “Mapping procedures” tab in the mapping.
New procedures can be created, existing ones can be edited in the “Mapping procedures” tab.
© SEEBURGER AG 2018 227
Coding GuideLocal procedures
Procedure will be called by write down the procedure name followed by brackets inside the mapping.
Example: WRITE_ADDRESSDATA()
© SEEBURGER AG 2018 228
Coding GuideHow to use global procedures
New global procedures can becreated, existing ones can be editedby using the “Global procedure”folder in the BIC MD projectexplorer.
Each global procedure can have itsown methods with several inputand/or output parameter.
To use a global procedure on a BISsystem it needs to be checked in,activated and deployed (equivalentto mappings).
© SEEBURGER AG 2018 229
Coding GuideSyntax of procedures
Global procedure call: [Global_Procedure_Name]_[Method_Name]([Parameter]…)
Local procedure call: [Local_Procedure_Name]([Parameter]…)
User functions are no longer supported. However, it is possible to use Java classes to Import a user function as a global procedure to BIC MD.
Local procedures can be converted to methods that can be used by global procedures.
This process also works in reverse:
Procedure execution (local and global ones) allows return values. The return value will be passed back to the mapping for further usage.
© SEEBURGER AG 2018 230
Coding GuideMapping Repository
Central storage for objects (mappings, messages and global procedures)
Version management for such objects
© SEEBURGER AG 2018 231
Coding GuideMapping Repository
Context Menu
• Located in the Repository menu under File, Project, Message or Mapping.
• Shows all possible action at the choosed context.
© SEEBURGER AG 2018 232
Coding GuideMapping Repository
Context Menu – Actions
• Import new or other mapping / procedure version from the repository
• Check-In (Read-Only) / Check-Out (Read/Write) of mappings
• Get latest version of a mapping or message from the repository
• Activate mappings
• Create repository connection
• Disconnect repository connection
• Delete repository connection
• Import Codelistpool
© SEEBURGER AG 2018 233
Coding GuideMapping Repository
TreeView
• Located in the Configuration tab under converter
settings in frontend.
• Shows all mappings and messages in a tree view
(comparable to the Mapping Designer).
• Shows details of all available versions.
• Delete / purge of mappings / projects
• Unlock mappings