Error: Reference source not found

Integration Layer Procedures

Mapping Standards and Guidelines

Version 1.28
Exel Procedures
Mapping Standards and Guidelines

i. Document control
Identification Mapping Standards&Guidelines_v1.26.doc

Title Mapping Standards & Guidelines

Author Jeremy Parr-Morley

Distribution Exel SI Hub team

Related Material

i. Document amendments
Version Date Author Description

1.0 05/03/02 J.Parr-Morley Initial issue based on reviewed Mapping

Guidelines used for other projects.

1.1 4/4/02 O. Cruickshank Added new sections, amended existing ones.

1.2 19/07/02 J.Parr-Morley Changes following review.

1.3 08/10/02 O. Cruickshank Removed references to resource registry.

Updated Error code handling

Updated Event Agent section.

1.4 17/04/03 R. Arun Prasad Updated Mapping Standards

1.5 23/04/03 Vinoth. K Updated Mapping standards with procedures

from Nokia Integration; Changed the Title of
document to be more generic.

Added sections 12.4 and 12.6

1.6 29/04/03 Vinoth.K After JA’s review comments, included

guidelines 12.6.1 in section 12.6

1.7 18/8/03 O. Cruickshank Removed ‘known bugs’ section. Updated

backup settings section.

1.8 19/8/03 O. Cruickshank Added system settings section.

1.9 25/9/03 O. Cruickshank Added section 2, details for fixing EDIFACT

trees, the Syntax type and Merging trees.

1.10 1/10/03 O. Cruickshank Updated adapter setting sections

2
Exel Procedures
Mapping Standards and Guidelines

Version Date Author Description

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.13 20/10/03 O. Cruickshank Use of resource registry to hide passwords,

section 10.

1.14 11/11/03 O. Cruickshank Updated audit log settings, section 5.1

1.15 1/12/03 O. Cruickshank Updated object naming sections

1.16 02/12/03 Vinoth.K After JA’s review comments, updated section

14.13

1.17 04/03/04 O. Cruickshank Updated with details of Listener map

implementation and design.

1.18 22/03/04 O. Cruickshank Removed version card details

1.19 8/07/04 O. Cruickshank Use retry on input card.

1.20 28/07/04 O. Cruickshank Must use a valid sender email address.

1.21 27/09/04 Venkatachalam. Standards for creating Oracle sequence

M added.

1.22 28/09/04 Venkatachalam. Cut down procedure for TRADACOM type

M tree added.

1.23 30/09/04 Venkatachalam. Syntax object added for ANSIX12 type tree.
M

1.24 08/10/04 Dhiren Ghelani Review and misc updates

1.25 06/12/04 Olly Cruickshank Update backup settings.

1.26 06/12/04 Ramesh Grandhi Rules for X12 transformation maps

Section 18 - Adapter settings

1.27 23/03/05 Dhiren Ghelani Rosetta Net PIP standards added

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

i. Document sign off

Name Role Date Signature

4
Exel Procedures
Mapping Standards and Guidelines

Table of Contents
1. PURPOSE................................................................................................7

2. LISTENER MAP.......................................................................................8

2.1 Standards......................................................................................................................................8

3. STANDARD TYPE TREES......................................................................9

3.1 Standards......................................................................................................................................9

4. BESPOKE TYPE TREES.......................................................................11

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.2 Standards SQL SCRIPTS.........................................................................................................17

8.3 Guidelines...................................................................................................................................17

10. EVENT AGENT......................................................................................20

10.1 Guidelines...................................................................................................................................20

11. RESOURCE REGISTRY........................................................................21

11.1 Pathnames..................................................................................................................................21

11.2 Password masking.....................................................................................................................21

12. VERSION CONTROL CARD.................................................................22

5
Exel Procedures
Mapping Standards and Guidelines

13. DEPLOYMENT.......................................................................................23

14. EXCEPTION HANDLING.......................................................................24

14.1 System Errors............................................................................................................................24

14.2 Translation Errors....................................................................................................................24

14.3 Use of FAIL() statements..........................................................................................................24

15. NAMING CONVENTIONS......................................................................25

15.1 Executable Maps........................................................................................................................25

15.2 System Maps..............................................................................................................................25

15.3 Translate Maps..........................................................................................................................25

15.4 Type Trees..................................................................................................................................26

15.5 Database Stored Procedures....................................................................................................26

15.6 Java Class...................................................................................................................................26

15.7 UNIX scripts...............................................................................................................................27

15.8 Functional Map Names.............................................................................................................27

15.9 Card Names................................................................................................................................27

15.10 MDQ naming standard.........................................................................................................27

15.11 Directories & Structure........................................................................................................27

15.12 Event Agent............................................................................................................................28

15.13 Translate Maps......................................................................................................................28

15.14 Type Trees – Nokia Integration...........................................................................................29

15.15 Message Codes.......................................................................................................................30

16. INTEGRATION FLOW DESIGNER (MSD FILES)................................30

17. ADAPTER SETTINGS...........................................................................31

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
2. Listener Map
2.1 Standards
Standard
= RUN ( "001_Receive_01" ,
ECHOIN ( 1 , MessageIn ) +
ECHOIN ( 2 , TEXT (Resource)) +
" -AEM" )
=IF (ReturnCode Field:CallReceive !="0",
IF (ReturnCode Field:CallReceive = "30", FAIL (
"001." + SUBSTITUTE ( Message Field:CallReceive,
"FAIL function aborted map:","" )) ,
FAIL ( "001." + ReturnCode Field:CallReceive
+ " " + Message Field:CallReceive)))
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.
Procedures
Mapping Standards and Guidelines
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)
The receive map should be called with two inputs
and the audit log should be echoed back.
If the return code from running the Receive map is
non-zero, then the Listener should also fail.
The error code of the Receive map should be used
to fail the listen map, if the Fail function caused the
receive map to fail, the error message should be
used.
The input card should be set to rollback – the input
should not be deleted if the map fails.
perform very badly if listen maps are left on.
Retry settings must be turned on in case of
temporary glitch in OS or disk.
8
Exel Procedures
Mapping Standards and Guidelines

3. Standard Type Trees

3.1 Standards

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.

3.1.6 ANSI X12

3.1.7 General Elements

 Element delimiter is *
 Composite delimiter is ~
 Repetition Delimiter for type trees from versions 4020 should be ^
 Segment terminator is <CR><LF>

3.1.8 Additional Changes

To standardise the trees the following additional changes are required:
 Restriction lists should be removed from all items.
 "delimiter control ANSI edi" should be a category
3.1.9 ANSI X12 trees needs to be cut down to the appropriate message type. (Note: The
procedure for cutting down trees is detailed in the user guides.)

9
Exel Procedures
Mapping Standards and Guidelines

3.1.10 RosettaNet PIPs

For Rosetta the following process should be used:

1. Separate trees need to be maintained for inbound and outbound.

2. <CR><LF> needs to be added to each tag on the outbound tree.

10
 Exel Procedures
Mapping Standards and Guidelines

4. Bespoke Type Trees

4.1 Standards

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
restriction lists
All validation (with the exception of Data Types)
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’

Could be better achieved by partitioning the relevant input

type tree according to the value of asset
Hard Coding should be avoided. Wherever possible
parameterised table driven values should be used.
The use of PUT() and GET() should be avoided
Hard coding is bad coding practice and imposes
a high maintenance overhead.
Hard coding is where there is reference to or
comparison against a literal value that may
change over time and could be better handled
using maintainable table stored values.
Data should be input and output via cards only. If
for any reason you must use PUT then use it
with VALID and FAIL to enable roll back in the
event of a problem

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.

FAIL Statements for System Functions (DBLOOKUP, LASTERRORCODE and LASTERRORMSG

PUT, RUN etc) should have LASTERRORCODE have the exact Mercator error message which is
important for debugging purposes

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):

For a System level map (e.g. a Hubware or Listen map):

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.

The following settings should appear in the system definition file;

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")

8.2 Standards SQL SCRIPTS

For creating Sequences in Oracle:

CREATE SEQUENCE Mercator.SEQUENCE_NAME START WITH 1 MAXVALUE 9999999

MINVALUE 1 NOCACHE ORDER CYCLE;

Where

START WITH specifies the first sequence number to be generated.

MAXVALUE specifies the maximum value the sequence can generate.

MINVALUE specifies the sequence's minimum value.

NOCACHE specifies that values of the sequence are not preallocated.

ORDER guarantees that sequence numbers are generated in order of request.

CYCLE specifies that the sequence continues to generate values after reaching either its
maximum or minimum value.

8.3 Guidelines

Guideline
Tables that do not require update by the
translation processes be exported to files.
Update of the exported files should be on an as
required basis.
Reason
This minimizes the database connections and
increases the map speed.

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;

EITHER(DBLOOKUP (“<query>”, “-TE+ <mapname> -DBNAME <dbname> -MDQ

<mdq>”),
FAIL (<error message>)

9. INPUT AND OUTPUT CARD SETTINGS

Standard
All file paths on map cards should be referenced
using relative path names or Resource Registry
variables
Database settings should appear in both the
DatabaseQueryFile and the Command section.
For Database and other adapters (including file) the This is because sometimes for unspecified
AdapterRetry option should be set to:
ON
MaxAttempts = 3
Interval(Secs) = 1
Reason
Avoids need to edit/rebuild maps to move them
between directories or environments
Command settings override the DatabaseQueryFile
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.)
(possibly various) reasons a card cannot access
the adapter at the first attempt.

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
Output Card Target should be set as sink.
Makes debugging easier. Fixed filenames can also
cause problems in event server.
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

10. Event Agent

10.1 Guidelines
Only one map will be delivering data to SCI2 (using the HTTP adapter).

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

11. Resource Registry

11.1 Pathnames
The Resource Registry should be used to resolve paths that differ from one environment to
another.
One such variable; %datapath% is resolved to the following values.

datapath is stored as a global variable, generally global variables should be used sparingly
and variables should be stored against specific systems.

11.2 Password masking

Also the Resource Registry can be used to hide passwords. A resource file should be created
per business group.
 The resource name should be made up of the <username>@<servername>
 Server should be specified as ALL
 Encryption must be turned ON
For example:

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

12. Version Control Card

The version control card is no longer required and should be removed from any new
development.

22
Exel Procedures
Mapping Standards and Guidelines

13. Deployment
See separate deployment procedures

23
Exel Procedures
Mapping Standards and Guidelines

14. Exception Handling

14.1 System Errors
The message hub will invoke all translation maps through a RUN() request.
The message hub will handle all exceptions thrown by the called translation process.
An E-mail notification will be raised and where possible the exception will be stored in the
exceptions table.
See Software Architecture document for detailed Hub principals.

14.2 Translation Errors.

Missing external data.
The map should generate a FAIL() statement.
Invalid data
For input cards the Mercator runtime engine will generate a standard error code.
For data found to be invalid within the map a FAIL() statement should be
generated.
Note: Instead of calling the FAIL() function for Missing external data and Invalid data, the
failed data can be encapsulated in an XML Header with the exception and input data. Please
refer to the user guide for further information.
Output adapter failures
The Mercator runtime engine will generate a standard error code.
Input adapter failures.
The Mercator runtime engine will generate a standard error code.

14.3 Use of FAIL() statements.

The fail statement should take the form:
FAIL (“E0n.”+LASTERRORCODE()+ “ <error description>”)
Where n is an incrementing number through the map (i.e. always starts at one in each map),
LASTERRORCODE should only be used if applicable (for example in a DBLOOKUP) and
<error description> is a text description of the error.
The Mercator Error Codes document in LN should be updated with details of the error code.

24
Exel Procedures
Mapping Standards and Guidelines

15. Naming Conventions

15.1 Executable Maps
The names will be in all upper case to ensure consistency.
In order to make the naming conventions practical there are separate formats that should be
used for the system maps and the translate maps.

15.2 System Maps

The format for the system map names will be:
<identifier>_<function>
Where:
Function: Description of the function carried out by map
Version: 2 digit version number
For example a generic polling map may have the following name:
010_BatchRun.mms

15.3 Translate Maps

The format for the names will be:
<identifier>_<Message description>_<from>to<to>
Where <Message description> is made up of the following fields for EDI;
Msgtype: 6 digit/character msgtype as known by 3rd party service
MsgVersion: EDI message standard

Where <Message description> is made up of the following fields for XML;

Msgtype: XML element name for the message
Standard: XML

The other fields are as follows;

Identifier: 3 character identifier for the map.
From: n character identifier for the source of the message
To: n character identifier for the destination of the message
Version: 2 digit version number
For example, an EDIFACT despatch advice would have the following format:
037_DESADV99BtoMOT_SCI2.mms

25
Exel Procedures
Mapping Standards and Guidelines

15.4 Type Trees

The format for the names of type trees is:

<identifier>_<data description>_<data version>_<version>

Where:
Identifier: 4 character identifier for the map.
Data description: type of data the type tree describes
Data version Version of the data the type tree describes
Version: optional 2 digit version number
For example;
1000_ActualShipment_3.3.1.mtt
or
1000_ActualShipment_3.3.1_01.mtt
for amended type trees.

15.4.1 Database Tables

When the type tree is describing a database table then the description should be the name of
the table that is being modeled
For example;
Static_01.mtt

15.4.2 Database Queries

For a query specific Type Tree the query name should begin with ‘Q_’.
Q_SentData.mtt

15.5 Database Stored Procedures

Database stored procedure must start with SP_

SP_RESENDERRORTRANS

15.6 Java Class

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

15.7 UNIX scripts

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.

15.8 Functional Map Names

Functional maps should all be prefixed with ‘F_’; map names should aim to be descriptive
using up to three groups of 3 Character abbreviations e.g. a functional map which put a
message on a queue could be called
F_PutMsg

15.9 Card Names

Card names should be descriptive both of data and function. They can be more flexible in
their names than executable maps. The name should describe the input/output of the data.
If the card is connecting to a database the card name should include the name of the table
name and the relevant level (i.e. table, row of field).
For example:
StaticTable – this input card will receive the static table.
DESADVD99B – this output card will output the EDIFACT despatch Advice message

15.10 MDQ naming standard

There will be one bespoke mdq file for the hub. This will be called hub.mdq.
All bespoke queries in this mdq will have the following format:
<Query_name>
For example;
GetStaticRecords

15.11 Directories & Structure

The following directory structure is suggested:
mercator (In production – name of directory where Mercator is installed, In
development and source safe: Working , QA, ReleaseNo.)
+maps (In production holds executables, in sourcesafe holds all source.)
+database (Only required if database is local)
+debug (Any log files / debug files)
+repository
+Sub Directories for Hub System files.
+Sub directories for each message type. Eg.
+EDIFACT
+X12
+XML

27
Exel Procedures
Mapping Standards and Guidelines

+Bespoke format directories.

+resource
+tables (Holds file copies of tables, owned by the system, used for
reference not update.)

15.12 Event Agent

The Event Agent should use URLs in the following format;
http://localhost:<port number>/hubware?*

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

 Generally the naming of maps abides the above-mentioned standard. However,

when the outbound translate map produces multiple outputs of various formats
(including EDI) for various trading partners, the names of the Trading partners are
appended to the map name in the end separated by underscore (“_”) to denote
multiple output instead of the EDIFACT message versions.
For example, an outbound Unison GRMK flow message translated to EDIFACT
DESADV and IFTSTA for SCI2 and NMP trading partners would have the
following format:
123_UnisonGRMKtoSCI2_NMP.mms
 In case of the split maps, the word “Split” is included in the map name.
For the same example, the map name would have the following format:
124_UnisonGRMKSplit.mms
4) Version number present in Map names does not match the VSS version. When the map
is first Deployed in LIVE system, the map name has no version in it. For each
subsequent change, a version number is added to the map name
For example, when the map 123_UnisonGRMKtoSCI2_NMP.mms is changed to
incorporate MCR, its renamed as 123_UnisonGRMKtoSCI2_NMPv01.mms and added
to the system. Still, the older ones are maintained in the system. “Branching” feature in
VSS is used to achieve this specification. Same map source file is branched to different
folder, renamed with version number suffixed to the original name and then copied back
to the maps folder from where it was branched. This would result in multiple files in
VSS with version numbers in the map names, but all “linked” together, so that change
in map is reflected in all these files. Different VSS versions of these maps could be
deployed accordingly.

15.14 Type Trees – Nokia Integration

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

15.15 Message Codes

There are several allowed naming conventions. Ensure that enough information is provided whilst
coining the message code.
Here are a few guidelines to follow…
1. All characters need to be in uppercase
2. No special characaters are allowed apart from ‘_’ understcore.
3. Begin the msgcode with a character.
4. The maximum allowed size is 26. Try to keep well below 26.

Some of the existing naming conventions are listed below.

1. For CRH-E use

CRHE_<Warhouse Code>_<OwnerCode>_<MsgName>
This should be used for CRH-E implementations

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>

16. INTEGRATION FLOW DESIGNER (MSD FILES)

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. Adapter Settings

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