Code Extension Type: CTL_UNIT_TRANSFER_ALLOWED (on page 1)
Purpose: For the Quay Crane (QC) to validate whether it is allowed to transfer the container. When this extension returns 'true', N4 updates the QC_ORDERS table in the ECS database with Transfer Allowed (TA) = Yes, and creates a CAS_UNIT_READY_TO_TRANSFER Event , which you can see in N4 apex logs.
This code extension is used for fully automated operations, and is called automatically by the QC workflows for loads and discharges. It can also be used for validating containers that arrive for load via non-automated equipment or that are planned for discharge to non-automated carry CHE.
The following property types are available in the map during a validation for unit transfer, encoded in the UnitCaptureAllowedValidationPropKey enum of the UnitTransferAllowedValidationPropertyMappings class:
WORK_ASSIGNMENT
UNIT_REF_ID
OCR_EVENT_TYPE
UNIT_FACILITY_VISIT
MEASURED_WEIGHT_KG
VISIT_ID
ACTUAL_SPREADER_ORIENTATION
The UnitTransferAllowedValidator code extension currently performs the following validations:
For Image Captured events, at present, no validation occurs at the time that the image is captured. Transfer Allowed is 'true' by default.
For Image Identified events, the N4 code extension validates for potential errors based on service business rules that you have created. For example, if you have a service business rule set up to prevent UNIT_DISCH events if the identified unit has a hold, the UnitTransferAllowedValidator code extension records a CHE_ERROR_UNIT_HAS_HOLDS event instead of a UNIT_DISCH event. Additionally, you can configure a General Notice that listens for the CHE_ERROR_UNIT_HAS_HOLDS event, and calls the CheECAlarmRecorder code extension, which publishes an EC Alarm about the hold in the XPS client interface. See Set up recording for QC exceptions for instructions.:
The container is in the discharge or load list:
This validates whether the container can be loaded to/discharged from the specific vessel. When the container is not in the load/discharge list, the default behavior updates the work instruction position to be 'Apron', so that the container is transferred to the ground. A container that is loaded or discharged is said to be in the load or discharge list if the unit's planned visit (inbound or outbound) is the same as the visit that it is actually loaded to or discharged from. The visit that a container is actually being loaded to or discharged from is provided to the code extension in the input parameters. Additionally, to prevent Remain-on-Board (ROB) containers from being discharged, if the unit is not a RESTOW or transship container, this code extension checks whether the Port of Discharge is the same as the Port associated with the current facility. If the POD is not the same, the transfer is not allowed unless the unit is an Export on a barge for load to a vessel.
Currently, this validation is performed against the CHE's point of work (POW). In a future release, N4 will perform this validation against the Carrier Visit ID.
The container's weight is allowed to be handled by various CHE:
This property evaluates whether the QC can drop the container to the designated CHE. You can configure whether the transfer allowed flag considers the maximum weight specified for the (multiple) CHE that would handle it by including the property, MEASURED_WEIGHT_KG, in the code extension's validation key (UnitCaptureAllowedValidationPropKey).
The container has a hold:
This checks for whether there is a service business rule to prevent unit load or discharge. If so N4 writes this information as a warning message to the apex log file. You can create an EC Alarm in XPS for this condition by enabling the CheECAlarmRecorder through a General Notice. See Set up recording for QC exceptions.
When there is a hold or permission that should prevent load, the default behavior of the code extension is to update container's Next Position to the APRON.
The reference implementation of this code extension does not prevent load or discharge for a hold. You can customize how to handle holds in the validateUnitHoldPermission() API in this code extension.
The container has damages:
If the unit has damages, N4 writes the result as a warning message to the apex log file.
The reference implementation of this code extension does not prevent load or discharge when the container is damaged. You can customize how to handle damages in the validateUnitDamages() API in this code extension.
The container's door direction matches the door direction in the work instruction:
If the container's work instruction (WI) has the door direction as either 'unknown' or 'any,' or if the door direction of the unit facility visit is either 'null' or 'unknown,' N4 skips the validation.
If there is a mismatch between the two, N4 modifies the container's plan to move the it to APRON. You can create an EC Alarm in XPS for door direction mismatches by enabling the CheECAlarmRecorder through a General Notice.
For loads, the work instruction's expected door direction is always 'FWD' or 'AFT', but it is possible for the CAS or the Crane Team UI to set the door direction value for an individual Unit Facility Visit (UFV) to a cardinal direction (N, S, E, W). If the door direction of a UFV is not already'FWD' or 'AFT', the UnitTransferAllowedValidator code extension translates it before comparing it with the load work instruction's door direction.
Twin, tandem, or multilift load containers are oriented correctly on the spreader:
Upon identification of a twin, tandem, or quad load, N4 verifies the containers' actual positions in the spreader or on the platform against the calculated spreader positions (based on factors such as the vessel position, berthing orientation (Starboardside or Portside) and the bollard layout). If the calculated spreader orientation differs from the actual orientation, the validation fails and writes a warning message to the apex log file.
The unit is a tank rail container:
For discharges only. N4 sets the transfer allowed to no if the identified container is a tank, and there is no tank rail information. An exception appears in the Crane Team UI Work List, which you can resolve by performing the inspection.
This validation is triggered during both image identification (by default) and image capture events (if configured), so if your site needs to perform tank rail validation during image capture, you can override the UnitTransferAllowedValidator code extension and un-comment the line in the following method:
isTank().
// return performTankValidationForImageCapture();
When triggered at Unit Capture, N4 uses an algorithm that relies on the assumption that all planned containers are discharged in sequence.
CAUTION: If there are any out-of-sequence discharges, the validation will be incorrect.
Algorithm for Identifying Tank Rail Containers During the Discharge Unit Capture Event:
1. Find all the unidentified containers and also the order in which containers came off the ship (based on the EC Events recorded), and
2. Get the order (i) for our unit reference (x).
3. Look up the work queue for the next 'n' containers that are yet to be identified sorted by the estimated move time.
4. In that list, if the i-th work instruction is for a tank and does not contain tank rail information, then N4 sets the Transfer Allowed attribute to ‘No’.
Validations ignored for Flexible Load Empty (FLMT)
Flexible Load Empties (FLMTs) are empty containers selected by AutoStow. For FLMTs, loadlist validations provided in this code extension are skipped when the following conditions are met:
The N4 setting INVXPS006 (AUTOSTOW_ALLOW_REROUTING_EMPTIES) is set to true.
The UFV has the ProjectedPoD set.
The unit's Freight Kind is Empty.