Create the port input object

The input object is the form people fill in for each cost calculation. It has a main object (the port template) linked to several sub-objects (pilots, tugs, port-specific inputs). You build it all under Object definitions.

Before you start

You need the Custom data admin permission (custom_data.custom_data_admin). Without it, Object definitions will not appear in the Admin hub.

Step 1 — Create the port object

1. Go to Sidebar → Admin → Cost Calculations → Object definitions (route /cost-definitions).

2. Click New — the Object definition modal opens.

3. Fill in:

   Field	What to enter
   Name	Human-readable port name, e.g. Den Helder
   System code	pcc<Port> with no spaces, e.g. pccDenHelder. Alphanumeric and underscores only.
   Application area	Cost calculation
   Available	Toggle on

4. Click Save.

System code is permanent

The System code is the port's identity throughout the entire setup. Every tariff group you create later must reference this exact code. It is locked after you save and cannot be changed.

The new object appears in the list. Click it to open the Object definition details page.

Step 2 — Add the input sections

Sections are Linked object fields on the main port object. Each section becomes a tab (or the top card) on the calculation form.

The ship section (the root group)

Add the first linked field for the ship:

1. On the details page, click Add in the Field definitions card.
2. Set Field type to Linked object.
3. Set Object to link to the nautical ship mapping.
4. Leave Group completely blank.
5. Set Visibility to the first option in the dropdown (Public).
6. Click Save.

Two rules that prevent a crash

1. The ship field's Group must be blank. Leaving Group empty makes this field the _root group, which the calculator requires. If no field has a blank Group, the calculator throws "Cannot convert undefined or null to object" and stops working.

2. Every field's Visibility must be Public. The Visibility dropdown's option labels are missing in the current app — the options appear unlabelled. Always select the first / topmost option, which is Public. If any field is set to the second or third option (Private or Hidden), the calculator drops it from the form. If all fields in a section end up non-Public, the crash above occurs.

Per-port sections (pilots, tugs, port-specific)

For each additional section (for example inbound pilots, outbound pilots, tugs, and a port-specific section):

1. Click Add again.
2. Set Field type to Linked object.
3. Set Object to link to the matching sub-object (create the sub-objects first — see Step 4).
4. Enter a Group name, e.g. Inbound, Outbound, Basis information. This becomes the tab header.
5. Set Visibility to the first option (Public).
6. Click Save.

Step 3 — Add the fields

Sub-object fields are the actual inputs (GT, draft, number of tugs, ship type, …). Add them on each sub-object's details page via Add.

Field types you'll use

Field type	Use for
Integer	Whole numbers: GT, LOA, draft (in dm), number of tugs
Decimal	Decimal numbers: calculated products such as m²×days
Boolean	Yes/no flags, e.g. "ISPS applicable"
List	A choice from a fixed set, e.g. ship type, call period, location
Single line text	Free-text inputs where needed
Linked object	Sections linking to another object (used on the main port object — see Step 2)

List fields and their keys

When you add a List field, you define the options in the List items table. Each row has a Label (what the user sees) and a Key (a code string):

• The Key is what tariff conditions reference later. Choose short, stable codes — for example tanker_lng, bulkcarrier, cruise, day, night.
• You cannot change a Key after tariff conditions reference it, so settle on the codes before you start adding tariffs.
• Check the Must match checkbox so users cannot type free-text values.

Visibility and required

Set Visibility to the first option (Public) on every field — both on the main port object's linked-section fields and on every leaf field in every sub-object. See the caution above for what happens if you don't.

Mark fields Required as appropriate so the user cannot leave critical inputs blank before clicking Calculate.

Step 4 — Create the pilots / tugs sub-objects

Sub-objects hold the leaf fields for specialised sections. Create them before you link them in Step 2.

1. Go to Object definitions and click New.
2. Fill in a name (e.g. Den Helder Pilots) and a System code (e.g. pccDenHelderPilots).
3. Set Application area to Cost definition (not "Cost calculation" — that is only for the main port object).
4. Click Save, then open the sub-object and add its leaf fields.

Typical pilot sub-object fields:

Field	Type	Notes
draft	Integer	Actual draught in dm
pilotQuantity	Integer	Number of pilots
areaFrom	List	Departure area; Keys used in area-gate conditions

A typical port-specific sub-object (e.g. pccDenHelderPort) might contain:

Field	Type	Example Keys / notes
havengeldCategory	List	zeeschip, cruise, fishing
location	List	nieuwe_diep, other
ispsApplicable	Boolean	Yes/no
callPeriod	List	day, evening, night

Checklist

Before you move on to tariffs, confirm:

• Main port object exists with Application area = Cost calculation and Available = on.
• System code matches the planned pattern (pccDenHelder) — it cannot be changed later.
• One linked-section field has a blank Group (the ship section — the _root group).
• All other linked-section fields have a Group name (a tab header).
• Every field on every object has Visibility = Public (first option).
• All List field Keys are finalised and stable.
• Sub-objects (pilots, tugs, port-specific) exist with Application area = Cost definition.