Mapping Guideline for FORTRAS ENTL512 to Conizi Event Bulk format

v1.1 - 2019-MAY-16

Introduction

This documentation is a part of the Mapping Guideline series for conizi semantic model. The messages described here are used for communicating with conizi applications, such as Track and Trace and Order Management, and other partners connected to the conizi network.

The structure of status reports and the content of the fields and message parts will be described in this document.

The standard of the source message format is FORTRAS and the used version is Release 100. The message format is often just referred to as REL100.

Technical Background

The conizi platform processes JSON format objects and their exact format is specified by the JSON Schema standard, version draft-06. The schema documentation can be found in a public repository on the https://github.com/conizi/semantic-model URL.

The structures of the conizi manifest and status business objects are specified by the files under model/transport/truck/groupage/forwarding folder.

FORTRAS ENTL512 Message Structure

FORTRAS messages consist of records and each record type has a different set of fields. Each record and each field inside the records was given an id or a name. In this mapping documentation we will refer to the records and fields by their ids and names.

Please refer to Appendix 1. for the list of record ids and Appendix 2. for field names.

Conizi Event Bulk Message Overview

FORTRAS ENTL512 messages need to be mapped to Conizi Event Bulk JSON message format. This schema has a few fields on root level and it can contain multiple consignment-event, pickuporder-event and package-event sub items. All fields of ENTL512 messages need to be mapped against consignment-events sub item. Every N00 record could contain 4 different status codes (N00/statusCodes[X]), therefore one consignment-events item needs to be generated from all status codes of all N00 records.

The schema must be referenced from each level of the message. To better understand this concept, check for the $schema tags in the Appendix 3..

The following schema references must be added for different message sections, levels:

Message section / level	schema reference
Root level	https://raw.githubusercontent.com/conizi/semantic-model/master/transport/truck/groupage/forwarding/event-bulk
consignment-event	https://raw.githubusercontent.com/conizi/semantic-model/master/transport/truck/groupage/forwarding/consignment-event

Mapping

In the mapping description we use the path notation to refer to source and target fields. Source field path consists of the record type and the field of that record. Eg.: M00/waybillConsignorId

Event bulk Level

conizi event bulk field	FORTRAS ENTL512 field	Description
sender	header/senderEdiId	The sender of the current record. This usually equals to the ordering party unless the record is a copy that was generated by some other component. In this case the sender can be different from the ordering party
receiver	header/receiverEdiId	The intended recipient of the the current record. This usually equals to the contracted party unless the record is intentionally sent to another system.
network		The network under which rules the consignment should be processed. Identified by the Conizi platform
consignment-events	See Consignment Event Level	array - generated by every N00 record (based on consignement status codes)

Consignment Event level

Consigment events are generated from Q10 records containing consignment (non-pickuporder) related status codes.

Common fields

conizi consignment event field	FORTRAS ENTL512 field	Description
consignmentNoShippingPartner	N00/consignmentNumberSendingDepot	Consignment number of the shipping partner
consignmentNoReceivingPartner	N00/consignmentNumberReceivingDepot	Consignment number of the receiving partner
sender	header/senderEdiId	The sender of the current record. This usually equals to the ordering party unless the record is a copy that was generated by some other component. In this case the sender can be different from the ordering party
receiver	header/receiverEdiId	The intended recipient of the the current record. This usually equals to the contracted party unless the record is intentionally sent to another system.
network		The network under which rules the consignment should be processed identified by the Conizi platform
shippingPartner/partnerId	M00/waybillConsignorId	The partner which is sending the consignment to the receiving partner for further delivery.
receivingPartner/partnerId	M00/waybillConsigneeId	The partner which is receiving the goods declared on the manifest from the shipping partner for further delivery.
originalEventCode	N00/statusCode[x]	Original event code

Event type specific mapping

Event type specific JSON sub items need to be created based on the status code fields of N00 records (four status code field / one N00 record) .

As the main rule we defined that only one event type specific JSON sub item can be mapped based on one status code.

For instance if you have a N00 record with a status code which means: successful unloading, but partly missing and damaged, you will have to map this event to “unloading.exceptions.partlyMissingDamaged”, instead of generating two separated sub items, e.g.: unloading.exceptions.partlyMissing and unloading.exceptions.damaged.

Some event type specific JSON sub item (e.g.: deliveryAttemptFailed, deliveryStarted) have event type specific fields which need to be mapped based on meaning/description of the field.

E.g. deliveryStarted/tourNumber : “ Number of the planned / assigned local traffic tour for delivery” (see the Conizi Consignment Event JSON schema descriptions)

Common event type specific JSON fields	FORTRAS ENTL512 field	Notes
eventDateTime
message
remarks
exceptions		depends on the meaning of the status code e.g.: deliverySuccessful.exceptions.damaged

Appendix 1. FORTRAS REL100 ENTL512 Record References

We only include the information here that is necessary to find the fields in the originating message referenced by the mapping documentation. Describing the STAT message format in detail is outside of the scope of this documentation.

FORTRAS Header

FORTRAS header field	Length	From	Notes
header	4	1	fix ‘@@PH’
type	7	5	fix ‘ENTL512’
empty	1	12
rowLength	4	13	0512
empty	2	17	00
startAddress	2	19	35
empty	2	21	00
internalSign	1	23	1
empty	1	24	0
mailboxLength	2	25	‘7 ‘
mailboxSender	x	27	‘AAAAAAA’
mailboxReceiver			Startaddress-(Startadress+Mailbox-Length)

Examples:

@@PHENTL512 0512003500107 AAAAAAA BBBBBBB @@PHENTL512 05120044001018LONGSENDERHEADER LONGRECEIVERHEADER

Data records

Each data record begins with a 3 character id which declares its type. The record type ids are listed in the table with the short description of their contents.

Record type	Description
M00	Receiving depot record
M10	Status of loading units
M20	Status of lead seal numbers
N00	Status on consignment level
O00	UEZ addresses
O10	UEZ packages
O20	UEZ barcodes
Z00	Control record

Appendix 2. FORTRAS REL100 ENTL512 Field References

In the following chapters each field will be identified and labeled with a unique tag, so that they can be located unambiguously inside the ENTL512 format file. These tags later will be used in the mapping section as paths for the incoming data.

In the table we specify the length of the field and the place where their data begins according to the FORTRAS REL100 standard.

M00 - Receiving depot record

Field reference	Length	From	Notes
recordType	3	1	Constant M00.
dataType	3	4
releaseVersion	3	7	100.
waybillConsignorId	35	10
waybillConsigneeId	35	45
codeList	3	80
waybillNumber	35	83
waybillDate	8	118
arrivalDate	8	126
arrivalTime	4	134
timeLimitStatus	4	138
unloadingStartDate	8	142
unloadingStartTime	4	150
unloadingEndDate	8	154
unloadingEndTime	4	162
euroPalletsDebitSending	4	166	Mandatory if the waybill contained values.
boxPalletsDebitSending	4	170	Mandatory if the waybill contained values.
euroPalletsDebitReceiving	4	174	Mandatory if the waybill contained values.
boxPalletsDebitReceiving	4	178	Mandatory if the waybill contained values.
unloadingNotes	70	182
routingId1	35	252	If the ENTL is sent via a data center, for instance, each entered routing ID contains a copy of the ENTL
routingId2	35	287	If the ENTL is sent via a data center, for instance, each entered routing ID contains a copy of the ENTL

M10 - Status of loading units

Field reference	Length	From	Notes
recordType	3	1	Constant M10.
loadingUnitNo	35	4
conditionOfLoadingUnit	3	39
additionalText	30	42
conditionOfLoadingUnit	3	72
additionalText	30	75
conditionOfLoadingUnit	3	105
additionalText	30	108
conditionOfLoadingUnit	3	138
additionalText	30	141
conditionOfLoadingUnit	3	171
additionalText	30	174
conditionOfLoadingUnit	3	204
additionalText	30	207

M20 - Status of lead seal numbers

Field reference	Length	From	Notes
recordType	3	1	Constant M20.
seal1	35	4
sealCondition1	3	39
seal2	35	42	The fields for the second lead seal number are mandatory if a second lead seal is present.
sealCondition2	3	77
seal3	35	80	The fields for the third lead seal number are mandatory if a third lead seal is present.
sealCondition3	3	115
seal4	35	118	The fields for the fourth lead seal number are mandatory if a fourth lead seal is present.
sealCondition4	3	153

N00 - Status on consignment level

Field reference	Length	From	Notes
recordType	3	1
waybillNumberSendingDepot	35	4
sequentialWaybillItem	3	39
consignmentNumberSendingDepot	35	42
consignmentNumberReceivingDepot	35	77
statusCode1	3	112
discrepancyNumber1	4	115
packagingType1	3	119
notes1	35	122
statusCode2	3	157
discrepancyNumber2	4	160
packagingType2	3	164
notes2	35	167
statusCode3	3	202
discrepancyNumber3	4	205
packagingType3	3	209
notes3	35	212
statusCode4	3	247
discrepancyNumber4	4	250
packagingType4	3	254
notes4	35	257

O00 - UEZ addresses

Field reference	Length	From	Notes
recordType	3	1
preliminaryConsignmentNoOfReceivingDepot	35	4
qualifier	3	39
name1	35	42
name2	35	77
streetAndStreetNumber	35	112
countryCode	3	147
postcode	9	150
place	35	159
townArea	35	194
consignorId	35	229

O10 - UEZ packages

Field reference	Length	From	Notes
recordType	3	1
preliminaryConsignmentNoOfReceivingDepot	35	4
codeAndNo1	35	39
number1	4	74
packagingType1	3	78
errorMessageCode1	3	81
additionalText1	35	84
codeAndNo2	35	119
number2	4	154
packagingType2	3	158
errorMessageCode2	3	161
additionalText2	35	164

O20 - UEZ barcodes

Field reference	Length	From	Notes
recordType	3	1
preliminaryConsignmentNoOfReceivingDepot	35	4
barcode1	35	39
errorMessageCode1	3	74
additionalText1	35	77
barcode2	35	112
errorMessageCode2	3	147
additionalText2	35	150

Z00 - Control record

Field reference	Length	From	Notes
recordType	3	1	Z00
recordNumber	6	4	Number of all record types without Z00, PH and PT record.
dateOfCreation	8	10	(DDMMYYYY)
timeOfCreation	6	18	(HHMMss)

Appendix 3. Sample Conizi Format Event Bulk File

The below sample conizi format event bulk message was created based on a real life sample. Names were replaced with random / sample values.

This sample can be used to get a hint on how the resulting file should look like after the conversion from FORTRAS format.

 { "$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/event-bulk",
    "sender" : 
    { "ediId" : "AAAAAAA" },
    "receiver" : 
    { "ediId" : "BBBBBBB" },
    "consignment-events" : 
    [ 
      { "$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/consignment-event",
        "consignmentNoShippingPartner" : "00000001_AA",
        "consignmentNoReceivingPartner" : "00000002",
        "sender" : 
        { "ediId" : "AAAAAAA" },
        "receiver" : 
        { "ediId" : "BBBBBBB" },
        "network" : 
        { "networkId" : "XXX",
          "codelist" : "ZZ",
          "product" : "YY" },
        "shippingPartner" : 
        { "partnerId" : "1111" },
        "receivingPartner" : 
        { "partnerId" : "2222" },
        "unloading" : 
        { "eventDateTime" : "2018-05-23T06:06:00",
          "exceptions" : 
          { "missing" : 
            {  } } } } ] }