Mapping Guideline for FORTRAS STAT512 to Conizi Event Bulk format
v1.2 - 2019-MAY-17Introduction
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 STAT512 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 STAT512 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.
STAT512 Q10 records need to be mapped to a consignment-event or a pickuporder-event depending on the meaning of the related status code. Q10 records with pickuporder related status codes need to be mapped to pickuporder-events (e.g.: pickupStarted) and Q10 records with consignment related status codes need to be mapped to consignment-events (e.g.: deliveryStarted).
Every STAT512 Q20 record needs to be mapped to a package-event sub item. The appropriate measuringPointQualifier1 value identifies the correct measuring point related JSON sub item (e.g.: stocktakingGateway) and the scanCode1 value indicates the possible exception item (e.g.: exceptions.damaged). Optionally a Q30 record could contain some additional scanning data. like masterBarcode, lotNo, etc.
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 |
| pickuporder-event | https://raw.githubusercontent.com/conizi/semantic-model/master/transport/truck/groupage/forwarding/pickuporder-event |
| package-event | https://raw.githubusercontent.com/conizi/semantic-model/master/transport/truck/groupage/forwarding/package-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.: Q10/consignmentNumberDeliveringParty
Event bulk Level
| conizi event bulk field | FORTRAS STAT512 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 consignement event related Q10 records (based on consignement status codes) |
| pickuporder-events | See Pickuporder Event Level | array - generated by pickuporder related Q10 records (based on pickuporder status codes) |
| package-events | See Package event level | array - generated by Q20 records |
Consignment Event level
Consigment events are generated from Q10 records containing consignment (non-pickuporder) related status codes.
Common fields
| conizi consignment event field | FORTRAS STAT512 field | Description |
|---|---|---|
| consignmentNoShippingPartner | Q10/consignmentNumberSendingDepot | Consignment number of the shipping partner |
| consignmentNoReceivingPartner | Q10/consignmentNumberReceivingDepot | Consignment number of the receiving partner |
| consignmentNoDeliveringPartner | Q10/consignmentNumberDeliveringParty | Consignment number of the delivering 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 | Q00/consignorId | The partner which is sending the consignment to the receiving partner for further delivery. |
| receivingPartner/partnerId | Q00/consigneeId | The partner which is receiving the goods declared on the manifest from the shipping partner for further delivery. |
| reportingPartner/partnerId | Q00/causingPartyId | The partner which is reporting the event. |
| originalEventCode | Q10/statusCode | Original event code |
| referenceNumber | Q10/referenceNumber | Reference number |
| waitDowntimeMinutes | Q10/waitDowntimeMinutes | Wait/Downtime in minutes |
Event type specific mapping
Event type specific JSON sub items need to be created based on the status code field of the Q10 record.
As the main rule we defined that only one event type specific JSON sub item can be mapped based on one Q10 record, so actually based on one status code.
For instance if you have a Q10 record with a status code which means: successful delivery, but incomplete and damaged, you will have to map this event to “deliverySuccessful.exceptions.incompleteAndDamaged”, instead of generating two separated sub items, e.g.: deliverySuccessful.exceptions.damaged and deliverySuccessful.exceptions.incomplete.
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 STAT512 field | |
|---|---|---|
| eventDateTime | Q10/timeOfEvent + Q10/dateOfEvent | Date and time when the event occured YYYY-MM-DD hh:mm:ss |
| remarks | Q10/additionalText | Additional remarks |
| exceptions | depends on the meaning of the status code e.g.: deliverySuccessful.exceptions.damaged |
Pickuporder Event level
Pickuporder events are generated from Q10 records containing pickuporder related status codes.
Common fields
| conizi consignment event field | FORTRAS STAT512 field | Description |
|---|---|---|
| pickupOrderNo | Q10/pickupOrderNumber | Unique identification for the pickup order within the transport management system of the contract partner |
| pickupOrderDate | Q10/timeOfEvent + Q10/dateOfEvent | The date on which the pickup order was forwarded to the contracted partner. YYYY-MM-DD hh:mm:ss |
| 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 pickup order should be processed identified by the Conizi platform |
|
| orderingPartner/partnerId | Q00_status/consignorId | Person or company that ordered the transport of the pickup order. |
| contractedPartner/partnerId | Q00_status/consigneeId | The partner which is contracted for processing the pickup order. |
| reportingPartner/partnerId | Q00_status/causingPartyId | The partner which is reporting the event. |
| originalEventCode | Q10/statusCode | Original event code |
Event type specific mapping
Event type specific JSON sub items need to be created based on the status code field of the Q10 record.
As the main rule we defined that only one event type specific JSON sub item can be mapped based on one Q10 record, so actually based on one status code.
| common event type specific JSON fields | FORTRAS STAT512 field | Description |
|---|---|---|
| eventDateTime | Q10/timeOfEvent + Q10/dateOfEvent | Date and time when the event occured YYYY-MM-DD hh:mm:ss |
| remarks | Q10/additionalText | Additional remarks |
| exceptions | depends on the meaning of the status code e.g.: pickupAttemptFailed.exceptions.wrongAddress |
Package Event level
Package events are generated from Q20 records.
Common fields
| conizi package event field | FORTRAS STAT512 field | Description |
|---|---|---|
| sender | header/senderEdiId | The sender of the current record. This usually equals to the receiving party. |
| receiver | header/receiverEdiId | The intended recipient of the the current record. This usually equals to the shipping party. |
| network | The network under which rules the consignment and its packages should be processed identified by the Conizi platform |
|
| shippingPartner/partnerId | Q00_status/consignorId | The partner which is sending the consignment to the receiving partner for further delivery. |
| receivingPartner/partnerId | Q00_status/consigneeId | The partner which is receiving the goods declared on the manifest from the shipping partner for further delivery. |
| reportingPartner/partnerId | Q00_status/causingPartyId | The partner which is reporting the event. |
| packageNo | Q20/barcode1 | Unique identification for the package. This is often an SSCC / NVE barcode number. |
Measuring point specific mapping
Measuring point specific JSON sub items need to be created based on the measuring point qualifier field of the Q20 record (Q20/measuringPointQualifier1). The following table contains the measuring point specific JSON sub items from the JSON schema.
As the main rule only one measuring point specific JSON sub item can be mapped based on one Q20 record, so actually based on one measuring point qualifier.
| measuring point specific JSON sub item name | description |
|---|---|
| pickupSender | Events occured while pickup the package. |
| unloadingShippingPartner | Events occured while unloading the package by the shipping partner. |
| loadingShippingPartner | Events occured while loading the package by the shipping partner. |
| entrySecurityAreaShippingPartner | Events occured while the package enters the security area of the shipping partner. |
| exitSecurityAreaShippingPartner | Events occured while the package leaves the security area of the shipping partner. |
| stocktakingShippingPartner | Events occured while stocktaking the package by the shipping partner. |
| unloadingGateway | Events occured while unloading the package by the gateway. |
| loadingGateway | Events occured while loading the package by the gateway. |
| entrySecurityAreaGateway | Events occured while the package enters the security area of the gateway. |
| exitSecurityAreaGateway | Events occured while the package leaves the security area of the gateway. |
| stocktakingGateway | Events occured while stocktaking the package by the gateway. |
| unloadingHUB | Events occured while unloading the package by the HUB. |
| loadingHUB | Events occured while loading the package by the HUB. |
| entrySecurityAreaHUB | Events occured while the package enters the security area of the HUB. |
| exitSecurityAreaHUB | Events occured while the package leaves the security area of the HUB. |
| stocktakingHUB | Events occured while stocktaking the package by the HUB. |
| unloadingReceivingPartner | Events occured while unloading the package by the receiving partner. |
| loadingReceivingPartner | Events occured while loading the package by the receiving partner. |
| entrySecurityAreaReceivingPartner | Events occured while the package enters the security area of the receiving partner. |
| exitSecurityAreaReceivingPartner | Events occured while the package leaves the security area of the receiving partner. |
| StocktakingReceivingPartner | Events occured while stocktaking the package by the receiving partner. |
| deliveryReceiver | Events occured while delivery the package. |
| unloadingAfterDeliveryAttempt | Events occured while unloading the package by the receiving partner after an unsuccessfull delivery attemp. |
| unloadingExternalDeliverer | Events occured while unloading the package by an external deliverer. |
Most of the measuring point specific JSON sub items have the same field set under the main item (e.g.: deliveryReceiver).
For the full list of fields please check the latest JSON schema in the following link: package-event.json.
| commond fields of measuring point specific JSON sub items | FORTRAS STAT512 field | Description |
|---|---|---|
| eventDateTime | Q10/timeOfEvent + Q10/dateOfEvent | Date and time when the event occured YYYY-MM-DD hh:mm:ss |
| packageType | Type of the package that is beeing reported it could be identify based on the scan code sometimes. (Optional) |
|
| masterBarcode | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’MST’] |
| lotNo | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’CHG’] |
| bestBeforeDate | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’MHD’] |
| transportUnitNo | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’TUN’] |
| scanUser | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’SCU’] |
| gateNo | Q20/Q30/referenceData | |
| terminalNo | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’TID’] |
| bulkiness/Length | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’MEA’] (L/W/H) |
| bulkiness/Width | Q20/Q30/referenceData | e.g.: Q30[referenceQualifier=’MEA’] (L/W/H) |
| bulkiness/Height | Q20/Q30/referenceDataa | e.g.: Q30[referenceQualifier=’MEA’] (L/W/H) |
| bulkinessCategory | Q20/Q30/referenceData | Bulkiness category |
| exceptions | depends on the scan code e.g.: loadingGateway.exceptions.damaged Optional |
|
| remarks | Additional remarks |
Appendix 1. FORTRAS REL100 STAT512 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 ‘STAT512’ |
| 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:
@@PHSTAT512 0512003500107 AAAAAAA BBBBBBB
@@PHSTAT512 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 |
|---|---|
| Q00 | Header record status |
| Q10 | Status on consignment level |
| Q11 | Additional text acc. to Q10 |
| Q20 | Status on barcode level |
| Q30 | Additional scanning data |
| Z00 | Control record |
Appendix 2. FORTRAS REL100 STAT512 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 STAT512 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.
Q00 - Header record status
| Field reference | Length | From | Notes |
|---|---|---|---|
| recordType | 3 | 1 | |
| releaseVersion | 3 | 4 | |
| codeList | 3 | 7 | |
| consignorId | 35 | 10 | |
| consigneeId | 35 | 45 | |
| causingPartyId | 35 | 80 | |
| routingId1 | 35 | 115 | |
| routingId2 | 35 | 150 |
Q10 - Status on consignment level
| Field reference | Length | From | Notes |
|---|---|---|---|
| recordType | 3 | 1 | |
| consignmentNumberSendingDepot | 35 | 4 | Mandatory if it is not a status for a pick-up order. |
| consignmentNumberReceivingDepot | 35 | 39 | Mandatory if it is not a status for a pick-up order. |
| pickupOrderNumber | 35 | 74 | Only mandatory if it is a status for a pick-up order. |
| statusCode | 3 | 109 | code list |
| dateOfEvent | 8 | 112 | DDMMYYYY |
| timeOfEvent | 4 | 120 | hhmm |
| consignmentNumberDeliveringParty | 35 | 124 | |
| waitDowntimeMinutes | 4 | 159 | |
| nameOfAcknowledgingParty | 35 | 163 | |
| additionalText | 70 | 198 | |
| referenceNumber | 12 | 268 |
Q11 - Additional text acc. to Q10
| Field reference | Length | From | Notes |
|---|---|---|---|
| recordType | 3 | 1 | |
| additionalText1 | 70 | 4 | |
| additionalText2 | 70 | 74 | |
| additionalText3 | 70 | 144 |
Q20 - Status on barcode level
|Field reference|Length|From|Notes| |—————|—–|—-|—–| |recordType|3|1|| |consignmentNumberSendingDepot|35|4|| |measuringPointQualifier1|3|39|code list| |barcode1|35|42|| |scanDate1|8|77|| |scanTime1|6|85|| |scanCode1|3|91|code list| |additionalText1|35|94||
Q30 - Additional scanning data
| Field reference | Length | From | Notes |
|---|---|---|---|
| recordType | 3 | 1 | |
| referenceQualifier1 | 3 | 4 | code list |
| referenceData1 | 35 | 7 | |
| referenceQualifier2 | 3 | 42 | code list |
| referenceData2 | 35 | 45 | |
| referenceQualifier3 | 3 | 80 | code list |
| referenceData3 | 35 | 83 | |
| referenceQualifier4 | 3 | 118 | code list |
| referenceData4 | 35 | 121 | |
| referenceQualifier5 | 3 | 156 | code list |
| referenceData5 | 35 | 159 |
Z00 - Control record
|Field reference|Length|From|Notes| |—————|——|—-|—–| |recordType|3|1|| |recordNumber|6|4|| |dateOfCreation|8|10|| |timeOfCreation|6|18||
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"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"consignment-events": [
{
"$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/consignment-event",
"consignmentNoShippingPartner": "42443886",
"consignmentNoReceivingPartner": "7058749",
"consignmentNoDeliveringPartner": "",
"sender": {
"ediId": "aaaaaaa"
},
"receiver": {
"ediId": "bbbbbbb"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"shippingPartner": {
"partnerId": "910058"
},
"receivingPartner": {
"partnerId": "910123"
},
"reportingPartner": {
"partnerId": "910123"
},
"deliveryStarted": {
"eventDateTime": "2019-02-11 07:28:00"
},
"originalEventCode": "117",
"referenceNumber": "190211073127"
},
{
"$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/consignment-event",
"consignmentNoShippingPartner": "42443784",
"consignmentNoReceivingPartner": "7058942",
"consignmentNoDeliveringPartner": "",
"sender": {
"ediId": "aaaaaaa"
},
"receiver": {
"ediId": "bbbbbbb"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"shippingPartner": {
"partnerId": "910058"
},
"receivingPartner": {
"partnerId": "910123"
},
"reportingPartner": {
"partnerId": "910123"
},
"deliveryStarted": {
"eventDateTime": "2019-02-11 07:24:00"
},
"originalEventCode": "117",
"referenceNumber": "190211073127"
},
{
"$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/consignment-event",
"consignmentNoShippingPartner": "42444271",
"consignmentNoReceivingPartner": "7059327",
"consignmentNoDeliveringPartner": "",
"sender": {
"ediId": "aaaaaaa"
},
"receiver": {
"ediId": "bbbbbbb"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"shippingPartner": {
"partnerId": "910058"
},
"receivingPartner": {
"partnerId": "910123"
},
"reportingPartner": {
"partnerId": "910123"
},
"deliveryStarted": {
"eventDateTime": "2019-02-11 07:27:00"
},
"originalEventCode": "117",
"referenceNumber": "190211073127"
}
],
"package-events": [
{
"$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/package-event",
"consignmentNoShippingPartner": "42443886",
"sender": {
"ediId": "aaaaaaa"
},
"receiver": {
"ediId": "bbbbbbb"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"shippingPartner": {
"partnerId": "910058"
},
"receivingPartner": {
"partnerId": "910123"
},
"reportingPartner": {
"partnerId": "910123"
},
"packageNo": "00340023980008816149",
"loadingReceivingPartner": {
"eventDateTime": "2019-02-11 07:27:00",
"packageType": "FP",
"scanUser": "xxxxx"
}
},
{
"$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/package-event",
"consignmentNoShippingPartner": "42443784",
"sender": {
"ediId": "aaaaaaa"
},
"receiver": {
"ediId": "bbbbbbb"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"shippingPartner": {
"partnerId": "910058"
},
"receivingPartner": {
"partnerId": "910123"
},
"reportingPartner": {
"partnerId": "910123"
},
"packageNo": "00340310042405562012",
"loadingReceivingPartner": {
"eventDateTime": "2019-02-11 07:27:00",
"packageType": "HP",
"scanUser": "yyyyyyyy"
}
},
{
"$schema" : "https:\/\/raw.githubusercontent.com\/conizi\/semantic-model\/master\/transport\/truck\/groupage\/forwarding\/package-event",
"consignmentNoShippingPartner": "42444271",
"sender": {
"ediId": "aaaaaaa"
},
"receiver": {
"ediId": "bbbbbbb"
},
"network": {
"networkId": "ZZZ",
"codelist": "XXX",
"product": "YYY"
},
"shippingPartner": {
"partnerId": "910058"
},
"receivingPartner": {
"partnerId": "910123"
},
"reportingPartner": {
"partnerId": "910123"
},
"packageNo": "00340258090003354639",
"loadingReceivingPartner": {
"eventDateTime": "2019-02-11 07:27:00",
"packageType": "FP",
"scanUser": "zzzzzz"
}
}
]
}