# Voyage Reference Numbering

1\. Purpose

The Voyage Reference Number is a human-readable identifier that operators use to label, search, and communicate about voyages. Because different operating companies have established their own reference conventions, Dataloy VMS supports a set of configurable numbering variants. Each variant is selected per company (or deployment) and determines how the reference string is constructed from the available voyage data.

***

### 2. Building Blocks

All variants are assembled from a small set of source fields. Understanding these fields is prerequisite to interpreting any variant formula.

| Field             | Source & Notes                                                                                                                                      |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VesselCode`      | Short alphanumeric code identifying the vessel in VMS master data.                                                                                  |
| `CompanyCode`     | Code identifying the operating company. May be numeric or alphanumeric depending on the variant.                                                    |
| `VoyageNo`        | Integer sequence number assigned to the voyage. Some variants reset this counter at the start of each calendar year; others increment continuously. |
| `VoyageStartYear` | The calendar year in which the voyage begins. Variants use either two digits (`YY`) or four digits (`YYYY`) of this value.                          |
| `ReferenceNo`     | Manually entered free-text reference. Used as a primary value in pass-through variants and as a fallback in several others.                         |
| `CpDate`          | Charter Party date. Used in Variant 16 to determine which era-specific formula applies and to extract the two-digit year component.                 |
| `ContractNo`      | COA (Contract of Affreightment) contract number. Used only in Variant 16 post-2016 logic.                                                           |
| `IsTc`            | Boolean flag indicating whether the voyage operates under a time-charter arrangement. Used only in Variant 2 to determine the TC/VC suffix.         |

**Padding notation:** Throughout this document, `VoyageNo(3)` means the voyage number zero-padded to a minimum width of 3 characters (e.g. voyage 7 becomes `007`). The width is given in parentheses.

***

### 3. Variant Summary

| Variant | Name                                         |
| ------- | -------------------------------------------- |
| 2       | Type-Year-Number with TC/VC Suffix           |
| 4       | Vessel-Dot-Year-Number                       |
| 5       | Vessel-Number (No Year)                      |
| 6       | Year-Vessel-Number                           |
| 8       | Numeric Company-Vessel-Year-Number           |
| 9       | Manual Reference (Pass-through)              |
| 11      | Vessel-Year-Number (3-digit)                 |
| 12      | Vessel-Year-Number (2-digit)                 |
| 13      | Manual Reference with Vessel-Number Fallback |
| 14      | Company-Vessel-Year-Number                   |
| 15      | Vessel-Number (Adaptive Width)               |
| 16      | COA Contract-Based (Date-Era Dependent)      |
| 17      | Vessel-Full Year-Number                      |
| 21      | Vessel-Year-Number (2-digit, Trimmed)        |
| 22      | Vessel-Year-Number (Continuous, No Reset)    |

***

### 4. Variant Reference

#### Variant 2 — Type-Year-Number with TC/VC Suffix

**Format:** `V + VesselCode + YY + VoyageNo(3) + [TC|VC]`\
**Example:** `VVESSEL25001TC`

Prefixes the reference with the letter `V`, appends a two-digit year and a zero-padded three-digit voyage number, and closes with a contract-type suffix: `TC` for time-charter voyages or `VC` for voyage-charter voyages.

| Field         | Description                                          |
| ------------- | ---------------------------------------------------- |
| `V`           | Literal prefix                                       |
| `VesselCode`  | Vessel master-data code                              |
| `YY`          | Last 2 digits of voyage start year                   |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits               |
| `TC` / `VC`   | Contract type suffix (Time Charter / Voyage Charter) |

***

#### Variant 4 — Vessel-Dot-Year-Number

**Format:** `VesselCode + '.' + YY + VoyageNo(3)`\
**Example:** `VESSEL.25001`

Combines the vessel code and voyage number with a period separator. The year component always uses two digits. The voyage number is zero-padded to three digits.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `.`           | Literal separator                      |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 5 — Vessel-Number (No Year)

**Format:** `VesselCode + VoyageNo(3)`\
**Example:** `VESSEL001`

The simplest format: vessel code immediately followed by a zero-padded three-digit voyage number, with no year component. Voyage numbering does not necessarily reset annually.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 6 — Year-Vessel-Number

**Format:** `YY + VesselCode + VoyageNo(3)`\
**Example:** `25VESSEL001`

Year-first variant: the two-digit year precedes the vessel code, followed by a zero-padded three-digit voyage number. No separator characters are used.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `YY`          | Last 2 digits of voyage start year     |
| `VesselCode`  | Vessel master-data code                |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 8 — Numeric Company-Vessel-Year-Number

**Format:** `CompanyCode(3) + VesselCode(4) + YY + VoyageNo(2)`\
**Example:** `00100012501`

All components are treated as integers and zero-padded to fixed widths. Falls back to the stored reference number if any component cannot be parsed as a number.

| Field            | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `CompanyCode(3)` | Company code, parsed as integer, zero-padded to 3 digits |
| `VesselCode(4)`  | Vessel code, parsed as integer, zero-padded to 4 digits  |
| `YY`             | Last 2 digits of voyage start year                       |
| `VoyageNo(2)`    | Voyage number, zero-padded to 2 digits                   |

> ⚠ **Note:** Falls back to the manually entered reference number if vessel code or company code cannot be converted to an integer.

***

#### Variant 9 — Manual Reference (Pass-through)

**Format:** `ReferenceNo (verbatim)`\
**Example:** *(as entered)*

Returns the manually entered reference number exactly as stored, without any computed components. Used when the operator is responsible for maintaining reference uniqueness.

| Field         | Description                                           |
| ------------- | ----------------------------------------------------- |
| `ReferenceNo` | Manually entered reference number — returned verbatim |

***

#### Variant 11 — Vessel-Year-Number (3-digit)

**Format:** `VesselCode + YY + VoyageNo(3)`\
**Example:** `VESSEL25001`

Vessel code followed by a two-digit year and a zero-padded three-digit voyage number. Similar to Variant 22 but without the explicit continuous (non-resetting) voyage number sequence requirement.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 12 — Vessel-Year-Number (2-digit)

**Format:** `VesselCode + YY + VoyageNo(2)`\
**Example:** `VESSEL2501`

Identical in structure to Variant 11 but the voyage number is zero-padded to only two digits, suitable for operations where voyage counts per vessel per year are expected to remain below 100.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(2)` | Voyage number, zero-padded to 2 digits |

***

#### Variant 13 — Manual Reference with Vessel-Number Fallback

**Format:** `ReferenceNo → VesselCode + VoyageNo(3)`\
**Example:** `VESSEL001`

Prefers the manually entered reference number. Falls back to concatenating the vessel code with a zero-padded three-digit voyage number only when no manual reference exists.

| Field         | Description                                      |
| ------------- | ------------------------------------------------ |
| `ReferenceNo` | Manually entered reference (preferred, if set)   |
| `VesselCode`  | Fallback: vessel master-data code                |
| `VoyageNo(3)` | Fallback: voyage number, zero-padded to 3 digits |

> ⚠ **Note:** Fallback is used only when `ReferenceNo` is null.

***

#### Variant 14 — Company-Vessel-Year-Number

**Format:** `CompanyCode + VesselCode + YY + VoyageNo(2)`\
**Example:** `COMPVESSEL2501`

Extends Variant 12 by prepending the company code, making the reference globally unique across multiple operating companies sharing the same vessel codes.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `CompanyCode` | Company master-data code               |
| `VesselCode`  | Vessel master-data code                |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(2)` | Voyage number, zero-padded to 2 digits |

***

#### Variant 15 — Vessel-Number (Adaptive Width)

**Format:** `VesselCode + VoyageNo(3 or 4)`\
**Example:** `VESSEL0023` / `VESSEL1000`

Similar to Variant 5 but dynamically adjusts the voyage number padding width: 4-digit padding is used if the voyage number itself is 4 digits long, otherwise 3-digit padding is applied.

| Field            | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| `VesselCode`     | Vessel master-data code                                            |
| `VoyageNo(3\|4)` | Voyage number; padded to 4 digits if ≥ 1000, otherwise to 3 digits |

> ⚠ **Note:** For unallocated budget estimates (where voyage number is null), the stored reference number is returned instead.

***

#### Variant 16 — COA Contract-Based (Date-Era Dependent)

**Format:** *(Era-dependent — see below)*\
**Example:** `25000001` / `250000123456000001`

A complex variant with era-specific logic based on CP date. The CP date is sourced from TC-in data if available; otherwise from the first cargo with a non-null CP date.

| Era / Condition                     | Formula                                                    |
| ----------------------------------- | ---------------------------------------------------------- |
| Pre-2016                            | `VesselCode + VoyageNo(3)`                                 |
| Post-2016, no contract or reference | `YY + VoyageNo(5)`                                         |
| Post-2016, contract number only     | `YY + VoyageNo(5) + ContractNo + VoyageNo(5)`              |
| Post-2016, reference + contract     | `ReferenceNo[0..5] + '-' + ContractNo + '-' + VoyageNo(5)` |

> ⚠ **Note:** The year used in post-2016 references is the two-digit year of the **CP date**, not the voyage start year.

***

#### Variant 17 — Vessel-Full Year-Number

**Format:** `VesselCode + YYYY + VoyageNo(3)`\
**Example:** `VESSEL2025001`

Uses the full four-digit year rather than the two-digit abbreviation, providing unambiguous century identification.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `YYYY`        | Full 4-digit voyage start year         |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

> ⚠ **Note:** Returns the stored reference number if vessel code is null.

***

#### Variant 21 — Vessel-Year-Number (2-digit, Trimmed)

**Format:** `VesselCode + YY + VoyageNo(2)`\
**Example:** `VESSEL2501`

Vessel code with two-digit year and a two-digit voyage number. Trailing whitespace from the voyage number segment is trimmed. Structurally identical to Variant 12.

| Field         | Description                                     |
| ------------- | ----------------------------------------------- |
| `VesselCode`  | Vessel master-data code                         |
| `YY`          | Last 2 digits of voyage start year              |
| `VoyageNo(2)` | Voyage number, zero-padded to 2 digits, trimmed |

***

#### Variant 22 — Vessel-Year-Number (Continuous, No Reset)

**Format:** `VesselCode + YY + VoyageNo(3)`\
**Example:** `VESSEL25001`

Structurally identical to Variant 11, but voyage numbers are **not reset at year boundaries** — they continue incrementing across years. This is the key operational distinction and must be configured correctly in the voyage numbering sequence setup.

| Field         | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `VesselCode`  | Vessel master-data code                                                     |
| `YY`          | Last 2 digits of voyage start year                                          |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits — **continuous, not reset annually** |

> ⚠ **Note:** Voyage number sequence must be configured as continuous (no annual reset) for this variant to produce correct results.

***