Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Version 1.28
Exel Procedures
Mapping Standards and Guidelines
i. Document control
Identification Mapping Standards&Guidelines_v1.26.doc
Related Material
i. Document amendments
Version Date Author Description
2
Exel Procedures
Mapping Standards and Guidelines
1.11 02/10/03 R. Arun Prasad Included change to EDIFACT EDI Type Tree
Build
1.12 10/10/03 K.P. Pravinkumar Included missing guidelines after CRHE Map
Review.
1.23 30/09/04 Venkatachalam. Syntax object added for ANSIX12 type tree.
M
1.28 13/09/20 Dhiren Ghelani Added adapter settings for MQ , FTP, FILE,
05 E-MAIL, Details of the MDQ needed for
Translate map.
3
Exel Procedures
Mapping Standards and Guidelines
4
Exel Procedures
Mapping Standards and Guidelines
Table of Contents
1. PURPOSE................................................................................................7
2. LISTENER MAP.......................................................................................8
2.1 Standards......................................................................................................................................8
3.1 Standards......................................................................................................................................9
4.1 Standards....................................................................................................................................11
4.2 Guidelines...................................................................................................................................11
5. MAP RULES...........................................................................................12
5.1 Guidelines...................................................................................................................................12
6. MAP SETTINGS.....................................................................................14
6.1 Standards....................................................................................................................................14
7. SYSTEM SETTINGS..............................................................................16
7.1 Standards....................................................................................................................................16
8. SQL.........................................................................................................17
8.1 Standards....................................................................................................................................17
8.3 Guidelines...................................................................................................................................17
10.1 Guidelines...................................................................................................................................20
11.1 Pathnames..................................................................................................................................21
5
Exel Procedures
Mapping Standards and Guidelines
13. DEPLOYMENT.......................................................................................23
17.1 FTP..............................................................................................................................................31
17.2 FILE............................................................................................................................................31
17.3 E-Mail.........................................................................................................................................31
17.4 MQ...............................................................................................................................................31
6
Exel Procedures
Mapping Standards and Guidelines
1. Purpose
This document contains the standards and guidelines that should be applied in developing
Mercator software as part of any project.
The first section contains standards; these should always be used. They should not be
ignored unless there is no alternative way to achieve the necessary outcome.
The second section contains guidelines; wherever possible the developer should stick to
guidelines. However, guidelines can be ignored if the developer has a justifiable reason for
doing so and the person carrying out code QA agrees with that reason. A developer who
intends to ignore a guideline should check with the team leader before writing the relevant
code.
7
Exel Procedures
Mapping Standards and Guidelines
2. Listener Map
2.1 Standards
Standard Reason
An audit log should be created on warning or error.
Logs should be created in the logs directory and
should be given a unique name.
Make sure that the settings are set in both the map
and the system (Integration Flow Designer)
= RUN ( "001_Receive_01" , The receive map should be called with two inputs
ECHOIN ( 1 , MessageIn ) + and the audit log should be echoed back.
ECHOIN ( 2 , TEXT (Resource)) +
" -AEM" )
=IF (ReturnCode Field:CallReceive !="0", If the return code from running the Receive map is
IF (ReturnCode Field:CallReceive = "30", FAIL ( non-zero, then the Listener should also fail.
"001." + SUBSTITUTE ( Message Field:CallReceive,
The error code of the Receive map should be used
"FAIL function aborted map:","" )) ,
to fail the listen map, if the Fail function caused the
FAIL ( "001." + ReturnCode Field:CallReceive
receive map to fail, the error message should be
+ " " + Message Field:CallReceive)))
used.
The input card should be set to rollback – the input
should not be deleted if the map fails.
Listen maps should only be present in europa_tst during The test server only has a single CPU and will
testing. After this they should be disabled. perform very badly if listen maps are left on.
8
Exel Procedures
Mapping Standards and Guidelines
3.1.1 EDIFACT
In early versions of the standard trees there were a number of issues, all EDIFACT trees
should be checked for the following:
3.1.2 General
Default segment terminator should be just quote
Segment release character should be present
Composite release character should be present
Numeric elements should use a variable decimal separator.
Restriction lists should be removed from all items.
3.1.3 Control
Quote + LF should be in restriction list of "Terminator Delimiter Control"
Terminator of UNB (and subtypes) should be default quote and find=yes.
Default terminator for other control segments should be quote.
Default terminator for Envelope should be quote.
UNB/UNG date should be 6 or 8 chars.
"Delimiter Control EDIFACT EDI" should be a category
Add Space <SP> in the restriction list to the object “Reserved Delimiter Control
EDIFACT EDI”
3.1.4 EDIFACT trees need to be cut down to the appropriate message type. (Note: The
procedure for cutting down trees is detailed in the user guides.)
3.1.5 Include both INBOUND and OUTBOUND groups whilst cutting down.
9
Exel Procedures
Mapping Standards and Guidelines
10
Exel Procedures
Mapping Standards and Guidelines
Standard Reason
To ensure a consistent structure and facilitate the
ability to share map rule code between interfaces.
This approach will also ensure a readable and
logical map rule reference to data elements.
Type Trees should not contain validation rules or All validation (with the exception of Data Types)
restriction lists should be carried out in Maps for consistency and
ease of maintenance. User maintainable tables can
then be used rather than restriction lists, which
require a change to a type tree and redeployment of
dependent maps if a change is made.
Where possible share type trees, where this is not Maximizes reuse and it becomes clearer where type
possible copy and rename the type tree. trees are used.
Use <NL> as the record terminator in Type Trees if Windows and Unix use different terminators. If
using files. <NL> is used Mercator will select the appropriate
terminator depending on platform
4.2 Guidelines
Guideline Reason
Avoid having more items in a Type Tree than is The map will spend less time identifying objects and
needed by the map execute faster.
Be wary of the tools that automatically build type They do not necessarily do a good job. For example;
trees for you. an XML type tree may be simpler and easier to edit if
created manually.
11
Exel Procedures
Mapping Standards and Guidelines
5. Map Rules
5.1 Guidelines
Guideline Reason
Care must be taken when using ellipses. They can hide meaning and also field names do
Some object names may be quite long. One option is to not necessarily stay unique throughout the life of
display the shortest possible object name. Rather than a map
having the entire name appear, portions of the name are
replaced with a period . (full stop) which is used as an
abbreviation of ellipses …
e.g.
Company Field:Record:Input becomes
Company Field:.:Input
Avoid Complexity in map rules. Attempt to spread More complexity = more defects, simple code is
complex functionality across several maps. easier to maintain
Use functional maps to analyze data and run maps to do
transactions
If you have nested multiple 'IFs' testing for a field value, More complexity = more defects, simple code is
then partition the type tree instead easier to maintain.
e.g.
IF asset = ‘X’
ELSE
IF asset = ‘Y’
ELSE
IF asset = ‘Z’
SEARCHUP should be used instead of LOOKUP where SEARCHUP is much more efficient than
possible. If necessary use SORTUP to order the lookup LOOKUP.
table.
RESTART and REJECT should generally not be used. Care must be taken with the error handling and
use of REJECT and CONTAINSERRORS.
12
Exel Procedures
Mapping Standards and Guidelines
Guideline Reason
To add comments to source code, surround the comment Comments add information on why a rule has
start the comment with a slash-star and end it with a star- been done a specific way. Generally though, the
slash and put it in the rule field, for example; rules should be self-documenting.
Static and Xref Input Cards should be deleted if they are More complexity = more defects, simple code is
not used anywhere in the map easier to maintain.
Call to functional map should not be with a IF (PRESENT Mercator automatically checks if an element is
condition present and calls the functional map only if the
element is present. So additional condition is
not required
Rules that use (IF (PRESENT (X), X, Y) should be It is simpler way of coding the same condition
replaced with EITHER (X,Y)
For rules IF (X, Y, NONE), the NONE is not required It is simpler way of coding the same condition
Duplicate rules should be removed For example, do not perform the same lookup
twice, the second rule should instead grab the
output from the first rule.
Use of counter files should be restricted. Use database Counter Files may get corrupt during I/O
sequence files instead. operations by the map.
Remove any unused functional maps from the Reduces compiled map size and keeps the map
source map file. tidy.
13
Exel Procedures
Mapping Standards and Guidelines
6. Map Settings
6.1 Standards
Standard Reason
Audit should be applied to Input but not Output from
Having Audit on output forces Mercator to validate
a map. Do this by setting input trace ‘on’ in the MSD
output against Type Tree.
event server settings. A type tree used as a target does not have to
analyze, providing you understand why it doesn't
analyze. However it absolutely must analyze if it’s
going to be audited.
Also reports the wrong card number when cards
made use of 'restarts'.
Trace must be set off in all translate maps. Trace will slow down a map significantly.
Workspace should be set to Memory Can increase map speed and avoids files being left
behind after an event server crash.
Retry setting Retry settings should be switched on at card level if
the card is using any adapters.
Validation setting should be set as Standard This will enable the standard validation of input
data against the type tree.
Audit Settings For Mercator 6.5: -AEUM should be used when
Audit log needs to be echoed back from a child map echoing back an audit log from a child map.
For Mercator 6.7 and later versions: –AEM should
be used.
The following settings should appear in the map and the system definition file;
14
Exel Procedures
Mapping Standards and Guidelines
For a RUN map, audit logging should be turned off (the settings are actually irrelevant as the router
map will override them):
15
Exel Procedures
Mapping Standards and Guidelines
7. System Settings
7.1 Standards
Standard Reason
Max Concurrent Map Instances should be set to one Restricts amount of CPU used.
Pending Thresholds should be set to 100/ 1000 Restrict the number of threads spawned.
Map Server Location should relative to the Mercator The absolute path may change from one
home directory. environment to another.
16
Exel Procedures
Mapping Standards and Guidelines
8. SQL
8.1 Standards
Standard Reason
Use ‘bind’ to reference variables within SQL The Oracle database can then cache the query and
statements it becomes quicker to perform when it is repeated.
The MDQ should be accessed at run time, not Maps do not have to be recompiled if the database
at build time. details change.
Do not use SELECT * ,replace ‘*’ with explicit Will cause errors if database structure changes and
column names. make bring back unnecessary fields, increasing
network traffic.
Trace Errors should be switched on in both Makes debugging easier.
cards and rules.
-TE+ <mapname>
The sender column in the smtp_alert_controller This way bounced emails can be detected.
should use a valid email address
Translate map should run under Translate.mdq This will ensure failures in translates are rolled back
properly.
For Example;
DBLOOKUP("SELECT Name FROM MyTable WHERE ID=:bind("+ Item1:Row +")
and CorrelationID=:bind(" + Item2:Row +")",
“-TE+ <mapname> -MDQ DB.mdq –DBNAME MyDB")
Where
CYCLE specifies that the sequence continues to generate values after reaching either its
maximum or minimum value.
8.3 Guidelines
Guideline Reason
Tables that do not require update by the This minimizes the database connections and
translation processes be exported to files. increases the map speed.
Update of the exported files should be on an as
required basis.
17
Exel Procedures
Mapping Standards and Guidelines
SQL queries to the DB2 database should be Applying a SQL query to a DB2 table is not efficient
avoided
DBLOOKUP should not be performed for every It is inefficient to do a DBLOOKUP for every row in
row in the data file, instead the lookup table input data
should be an input card or some other method
should be used to minimize the number of
lookups performed
Be aware that a query may return multiple rows The map or SQL may need to handle these.
of data following a lookup
VALID() and FAIL() should be used with This enables Mercator to trap and record errors.
DBLOOKUP;
For example;
VALID(DBLOOKUP (“<query>”, “-TE+ <mapname> -DBNAME <dbname> -MDQ <mdq>”),
FAIL (<error message>)
If it is crucial that the map returns data, use the EITHER function instead of VALID to fail
the map when no data is returned;
Standard Reason
All file paths on map cards should be referenced Avoids need to edit/rebuild maps to move them
using relative path names or Resource Registry between directories or environments
variables
Database settings should appear in both the Command settings override the DatabaseQueryFile
DatabaseQueryFile and the Command section. settings so that the database details can be picked
up at run time. However sometimes it is necessary
to compile in database settings at build time (for
update keys etc.)
For Database and other adapters (including file) the This is because sometimes for unspecified
AdapterRetry option should be set to: (possibly various) reasons a card cannot access
ON the adapter at the first attempt.
MaxAttempts = 3
Interval(Secs) = 1
In system maps, the Backup switch should be set to Maps are then easier to debug.
write the output card to a file in the case of an error.
Note that resource registry variables cannot be used
here.
Backup settings should be set to ‘create’ not This prevents too many errors from occurring.
‘append’
Backup file name should be unique Makes debugging easier. Fixed filenames can also
cause problems in event server.
Output Card Target should be set as sink. Router will actually pass the output from the
Translate map to the send it to the specified
destination.
18
Exel Procedures
Mapping Standards and Guidelines
Most standard trees have a Syntax Group. User In EDIFACT/TRADACOMS, the Syntax type is
this in the output card of the executable map. used to release colons when they appear outside of
sub-elements.
Settings example;
backup example:
19
Exel Procedures
Mapping Standards and Guidelines
The command line parameters for sending a receiving data with SCI2 should be stored in the
Resource Registry for easy amendment.
Future maps that use the Event Agent as input and output need to use the session command.
This command is not covered in Mercator documentation but is used in the Mercator
example files.
The session command enables the event agent to return the response to the internet browser
that initiated the connection.
20
Exel Procedures
Mapping Standards and Guidelines
datapath is stored as a global variable, generally global variables should be used sparingly
and variables should be stored against specific systems.
The standard hubware.mrc configuration file must be amended and redeployed to include
the new resource file. The resource should be added as a global variable.
Note that the Event Server must be restarted in order to pick up any changes to resource
files.
21
Exel Procedures
Mapping Standards and Guidelines
22
Exel Procedures
Mapping Standards and Guidelines
13. Deployment
See separate deployment procedures
23
Exel Procedures
Mapping Standards and Guidelines
24
Exel Procedures
Mapping Standards and Guidelines
25
Exel Procedures
Mapping Standards and Guidelines
SP_RESENDERRORTRANS
All Hubware Java classes must be part of the package com.exel.www.hubware and must be
placed in the JAR file hubware.jar.
26
Exel Procedures
Mapping Standards and Guidelines
All UNIX scripts must use reserve a map identifier number for the purposes of error
handling and referencing. The map identifier does not have to appear in the UNIX script
name but should be referenced in the header.
27
Exel Procedures
Mapping Standards and Guidelines
Where <port number> are dependent on the environment that Event Agent is running in.
hubware? should be followed by variables and values, for example:
http://localhost:8080/hubware?
msgtype=PlannedShipment&recvr=motorola&outtype=AShip/
15.13 Translate Maps
The following points are to be considered for naming the maps:
1) Map names should not exceed 29 characters. (Mercator restriction for compiled map
(*.mmc) naming is 32 characters. 3 characters reserved for future map versions)
2) Inbound message flow
The format for the names will be:
<Identifier>_<EDIFACT version>toUnison_<FLOW>_<FLOW>
Where
Identifier: 3 character identifier for the map.
EDIFACT Version: EDI message version
FLOW: The name of the flows present in Nokia Integration. If the map
produces multiple outputs for different flows, all the flow names
are appended in the end of the map name with underscore (“ _”)
as separator.
For example, an EDIFACT DEFLOR message translated to Unison preferred formats for the
flows PURC (Purchase Order) and ISLU (Products) would have the following format:
162_DELFOR97AtoUnison_PURC_ISLU.mms
3) Outbound message flow
The format for the names will be:
< Identifier >_Unison<FLOW>to_<EDIFACT version/Trading Partners>
Where
Identifier: 3 character identifier for the map.
FLOW: The name/notation of the flows present in Nokia Integration.
EDIFACT Version: Output EDI message version
Trading Partners: Names of the Trading partners, e.g. SCI2, NMP
E.g. 153_UnisonDESPtoDESADV998.mms
Note:
28
Exel Procedures
Mapping Standards and Guidelines
The Type Trees for the standard EDIFACT messages follow the same naming convention as
mentioned in section 14.5
The format for the names of type trees related to bespoke messages / Unison preferred
formar message is:
< identifier >_Unison_IN_<FLOW><version> for Inbound message flow and
< identifier >_Unsion_OUT_<FLOW><Version> for Outbound message flow.
Where:
FLOW: The name/notation of the flows present in Nokia Integration.
Version: Version of the Unison preferred formats. Presently, it is 414.
For example;
1001_Unison_IN_PURC414.mtt
1001_Unison_OUT_GRMK414.mtt
15.14.1 Guidelines:
When there is a change in Type Tree that doesn’t impact the map, the Map is not rebuilt and
re-deployed. On the other hand, when the Type Tree changes are to be incorporated in the
map, the map is re-built and deployed again. For instance, say new fields are added to a
particular Type Tree. If the map that refers to this Type Tree does not use the new fields, the
maps need not be re-built and re-deployed. If the new fields are to be used, the map is built
again and deployed.
29
Exel Procedures
Mapping Standards and Guidelines
2.
For Nokia use
<Customer>_<MsgName>_<WarehouseCode>
For Nokia messages incoming from EDIFACT Suppliers use
<Customer>_<EDIFACT MsgName>_<Suppler Sender Codes>
For Nokia messages outgoing to suppliers use
<Customer>_<MsgName>_<SAP Supplier Code>_<Warehouse Code>
3.
For GFM U21 EDI based messages use
GFM_<Customer/implementation>_<MsgType> for
For other GFM implementation use
GFM_<Customer/Implementation>_<TST/UAT/RTS/PRD>_<PCC>
3.
For SCI implementation use
SCI2_<Customer/Implementation>_<MsgType>
Standard Reason
All translate map should be added to the Integration To deploy the maps to the server with standard
Flow Designer with the map setting standard setting.
mentioned in section 5.1 of this document.
In the deploy script, the server map directories To deploy the map in the right location in the
should be specified using absolute path under server.
integration flow designer view tab.
30
Exel Procedures
Mapping Standards and Guidelines
17.1 FTP
FTP data connection’s should be of PASSIVE (PV/PASV) mode, default setting of Mercator.
Use PORT method, after ensuring that the target/source ftp server doesn’t support passive
connections.
TIMEOUT parameter should be present. By default, set it up to be 20 seconds.
Do not use IP addresses. Set up a hostname or use the DNS.
Set to binary transfer (type=I) by default.
17.2 FILE
Use adapter setting –B to ensure that a temporary file is written and changes are backed out of
the send map fails
17.3 E-Mail
TIMEOUT parameter should be present. By default, set it up to be 20 seconds.
17.4 MQ
For data sources, include the options –CVT and -CMSG.
For data sources, ensure to specify an –EQN, if the rollback on failure option is set. This will
ensure that messages are dropped to the error queue.
For data sources, -REFRESH option will be useful to reset the cursor back to the beginning of
the queue where multiple messages are put to the queue at the same time. Again ensure that –
EQN is specified where you have rollback on failure
For listeners, use the resource registry to specify all arguments.
31