Companies, Sites & Contacts in Jules

Product documentation — The relationship model between trading counterparties, physical locations, and people. Every operation, contract, invoice, and shipment in Jules is anchored to this foundation.

---

Table of Contents

1. Overview

2. The Core Triangle: Company, Site, Contact

3. Company

4. Site

5. Contact

6. Company ↔ Site Relationship

7. Company ↔ Contact Relationship

8. Site ↔ Contact Relationship

9. Site Qualities & Licenses

10. Site Blacklists & Whitelists

11. Service Providers: Shipping Lines, Forwarders, Customs Agencies

12. Internal Users & Companies

13. Geography: Locations, Ports & Logistics Points

14. Site PDF & Contract Prefill Defaults

15. Key Business Rules

16. Glossary

---

Overview

Before a single trade can happen in Jules, three master data objects must exist: a Company (the legal trading counterparty), a Site (the physical location where goods are produced, stored, or delivered), and a Contact (the person who manages the relationship). These three objects form the backbone of every operation, contract, invoice, and logistics flow in the platform.

Every other module in Jules — operations, contracts, bookings, invoices, bills, goals, and margins — references one or more of these master data entities. Getting this foundation right is critical: it drives document generation, logistics prefill, credit management, and counterparty access controls.

---

The Core Triangle: Company, Site, Contact

Jules separates three concerns that are often conflated in simpler systems:

These three entities are independent but linked through explicit relationship tables. A single company can have multiple sites (e.g., a recycler with yards in three cities), multiple contacts, and a site can itself have its own set of contacts distinct from the parent company's.

---

Company

A Company is the top-level legal entity in Jules. It represents any organization your business trades with — a supplier, a customer, a service provider parent entity, or an internal business unit.

Company Types (SiteTypeEnum)

Despite the enum name referencing "Site", the type field is shared between Company and Site objects in Jules:

Company Fields

Credit & Coverage Fields

Jules tracks credit exposure directly on the company record:

Document Defaults

Companies carry default document settings used when generating POs, SOs, and other commercial documents:

Default User Assignments

---

Site

A Site is a physical location — a yard, warehouse, processing facility, or delivery point. While a company is the legal counterparty, the site is the operational counterparty: it's where trucks pull up, containers are loaded, and stock is kept.

Sites are the primary reference on operations: when you create a purchase or sale, you pick the site, not the company. The company is derived from the site's company link.

Site Types

Site Status

Sites have a lifecycle status that indicates the commercial relationship stage:

Core Site Fields

Warehouse-Specific Fields

Sites of type WAREHOUSE carry additional stock management configuration:

Site Activity Fields

---

Contact

A Contact is an individual person — the human being you communicate with at a company or site. Contacts in Jules are not user accounts: they represent external counterparty personnel, not internal Jules platform users.

Contact Fields

Contact Roles

Contact Receivables

The receivables field controls which documents are automatically sent to a contact:

Contact Linking (linkedTos)

A contact is linked to one or more entities through the linkedTos field. This replaces the old single-link model and allows a contact to be simultaneously linked to a company, a site, a shipping line, a forwarder, and so on:

---

Company ↔ Site Relationship

The SiteToCompany join captures which company owns or operates a given site. This relationship is fundamental: it determines which company appears on documents when you trade with a site.

Key rules:

• A site belongs to exactly one company at a time (the companyId on a site)

• The company can have many sites

• Sites can exist without a company link (independent sites, e.g., ports or customs depots)

On operations: when a trader selects a site, Jules automatically resolves the parent company to populate the counterparty on the PO/SO, invoice, and contract.

---

Company ↔ Contact Relationship

The CompanyToContact join links contacts to trading companies. Multiple contacts can be assigned to one company (e.g., the business manager, the logistics coordinator, and the accountant at the same supplier).

When assigning contacts to a company, you pass contactIds on the create or update mutation. Jules also tracks:

• businessManager — a single designated business manager contact surfaced directly on the company record

• defaultUserId / defaultAdminId / defaultAccountRepId — internal Jules user defaults (not contacts) for the company

---

Site ↔ Contact Relationship

The SiteToContact join links contacts to specific sites. A contact linked to a site will appear on documents generated for that site (POs, SOs, shipment notifications) and will receive documents according to their receivables configuration.

This is distinct from the company-level contacts: a large supplier may have corporate contacts at the company level (e.g., a CFO for invoice discussions), and site-level contacts (e.g., the yard manager who handles daily logistics at a specific location).

The**contact**** field on Site**: each site has a single designated primary contact surfaced as contact (singular), used as the default signatory or addressee on generated documents. The contacts (plural) field returns all associated contacts.

---

Site Qualities & Licenses

Site Qualities (SiteToQuality)

A site's accepted material types and trade parameters are configured through SiteToQuality records. This is a crucial configuration: it tells Jules which qualities can be traded at a given site, and under what commercial conditions.

Each SiteToQuality record represents a directional relationship (BUY or SELL) between a site and a quality:

Why this matters: when creating an operation for a given site, Jules can suggest the correct qualities, pre-populate prices and MQCs, and flag when a requested quality is not configured for that site.

Site Licenses (SiteToLicense)

Many recyclable materials require regulatory permits to be traded or transported. Jules tracks these directly on the site through SiteToLicense records.

Key use case: before booking a shipment involving hazardous or regulated materials (e.g., Basel Convention-regulated waste), Jules operators verify that the destination site has a valid license for the relevant quality, with sufficient remaining quota. License expiration alerts prevent non-compliant trades.

---

Site Blacklists & Whitelists

Blacklisted Sites (SiteToBlacklistedSite)

A site can designate other sites as incompatible — meaning goods from a blacklisted site cannot be sold to, or purchased through, the blacklisting site. This is used to enforce trade compliance (e.g., a customer who refuses material from certain origins) or commercial agreements (e.g., exclusivity clauses).

The blacklist is maintained as a list of blacklistedSites on the site record and managed through the SiteToBlacklistedSite join. Jules warns traders when an allocation would pair a site with one of its blacklisted counterparts.

Whitelisted Sites (SiteToWhitelistedSite)

Conversely, a site can maintain a whitelist of approved counterpart sites — only material from whitelisted origins will be accepted. This is common with mills that have strict origin requirements (e.g., "only certified EU-origin scrap").

Blacklisted Shipping Lines (SiteToBlacklistedShippingLine)

Beyond site-to-site restrictions, a site can also blacklist specific shipping lines (carriers). This appears on the site as blacklistedShippingLines. Traders will be warned or blocked from booking a blacklisted carrier for shipments involving that site.

Typical use case: a customer specifies "no shipments on [Carrier X]" due to past service failures or contractual commitments with other carriers.

---

Service Providers: Shipping Lines, Forwarders, Customs Agencies

Beyond trading counterparties (companies and sites), Jules tracks several types of service providers — organizations that provide logistics, customs, and financial services. These implement the same LegalEntity interface as Company, meaning they share the same address, legal, and financial field structure.

Shipping Line (ShippingLine)

A carrier that operates vessels and provides maritime transport. Shipping lines in Jules are:

• Selected during freight booking to route containers

• Blacklisted at the site level when a customer refuses a specific carrier

• Linked to contacts (via ShippingLineToContact) for logistics communication

Key fields: value (carrier name), uid (SCAC or carrier code), logisticsEmail, accountingEmail, full LegalEntity address and legal fields.

Logistic Forwarder (LogisticForwarder)

A freight forwarder who manages booking, documentation, and customs on behalf of the trader. In Jules:

• Forwarders are assigned to freight bookings

• They have dedicated contacts (via LogisticForwarderToContact)

• They carry the same legal entity fields as companies (address, tax codes, bank accounts)

Customs Agency (CustomsAgency)

A customs broker who handles import/export declarations. In Jules:

• Customs agencies are linked to operations and sites

• They carry contacts (via CustomsAgencyToContact) for document exchange

• They implement the full LegalEntity interface with address, legal, and finance fields

Agent (AgentToContact)

Agents are intermediaries — brokers or commercial agents — who facilitate trades between buyers and sellers. They:

• Earn commissions on operations (fixed per unit or percentage)

• Have dedicated contacts linked via AgentToContact

• Can be the source of AGENT type links on a contact's linkedTos

Provider Contacts Summary

---

Internal Users & Companies

UserToCompany

The UserToCompany join links your internal Jules users (traders, admins, account managers) to trading companies. This is different from contacts: users are internal platform accounts, while contacts are external counterparty people.

This assignment controls:

• Which users are responsible for a given company's account

• Default user assignments on operations (defaultUserId, defaultAdminId, defaultAccountRepId on the company)

• The society field allows scoping user-company assignments to a specific internal business unit

---

Geography: Locations, Ports & Logistics Points

Jules maintains a rich geographic reference system that underpins site configuration, operation routing, and document generation.

Location (Location)

A Location is a structured geographic reference associated with a site. It stores country, city, region, and zip code in a normalized, searchable format — distinct from the free-text address fields on a site.

Address (Address)

The Address entity supports geocoded address lookup and autocomplete via an external geocoding service. It returns lat/lng coordinates and structured address components (street, city, country, zip code, state). Sites use this to set their GPS coordinates and formatted addresses.

Country (Country)

The country reference table. Each country carries:

Port of Loading (PortOfLoading)

A port from which goods are exported. Sites list their preferred portsOfLoading. Each port has:

• value: port name (e.g., "Hamburg", "Antwerp")

• country: the country where the port is located

• isEU: EU port flag

• trackingCode: used for vessel tracking integrations

Port of Destination (PortOfDestination)

A port where goods arrive. Sites list their acceptable portsOfDestination. Additional fields beyond the loading port:

• currency: local currency at the destination

• inspectionAdminCost: default inspection administrative cost at this port

• trackingCode: tracking integration code

Site to Port Relationships

Sites link to their routing preferences through two join entities:

These defaults pre-populate on operation qualities, reducing manual entry.

Quay (Quay)

A quay is a specific berth or terminal within a port — a more granular reference than the port itself. Used on bookings and containers to specify the exact loading or unloading point. Quays carry a full address (city, country, zip code).

Place of Receipt (PlaceOfReceipt)

The inland point where goods are handed over to the carrier before the main maritime leg. Typically a container depot, dry port, or rail terminal. Sites carry a defaultPlaceOfReceipt.

Place of Delivery (PlaceOfDelivery)

The inland point where goods are delivered to the buyer after the main maritime leg. Sites carry a defaultPlaceOfDelivery.

Recycling Yard (RecyclingYard)

A named reference for recycling or processing facilities used as intermediate handling points. Sites can designate a defaultRecyclingYard — a facility where material is processed before or after primary transport.

Pre-Carriage Area (PreCarriageArea)

A geographic zone designation for the local transport leg before the main maritime freight. Sites carry a preCarriageArea reference and a preCarriageAreaComment. This feeds into pre-carriage rate lookup when building a full logistics cost model.

Geography Hierarchy

---

Site PDF & Contract Prefill Defaults

SiteToPdfParameters / PoSoParams

Each site carries a set of document generation defaults that pre-populate PO and SO fields when a document is created. These are retrieved via getPoSoParams(siteId, qualityId):

SiteToContractPrefill

When creating a new contract, Jules can pre-fill consignee and notify party details based on the site. The SiteToContractPrefill entity stores:

This accelerates contract creation for repeat counterparties, ensuring document defaults are consistent and reducing data entry errors.

---

Key Business Rules

1. Site is the operational counterparty, Company is the legal counterparty

In Jules, operations are always created against a site, not directly against a company. The company is resolved from the site's SiteToCompany relationship. This matters because:

• A multi-site supplier will appear on invoices as the parent company, even when the specific site differs

• Blocking a company (isBlocked = true) does not automatically block its sites — and vice versa

• Credit exposure is tracked at the company level, aggregating across all sites

2. Contacts are linked to multiple entity types simultaneously

A contact can be linked to a company, a site, a shipping line, and a forwarder all at once through the linkedTos field. This reflects real-world relationships where a logistics coordinator works for a parent company but also handles specific site operations and carrier bookings. When Jules surfaces "suggested contacts" for an operation, it considers all relevant linkedTos associations.

3. Site quality configuration drives operation defaults

Before a site can be used in a trade for a specific material, a SiteToQuality record must exist for the site + quality + direction (BUY or SELL). This configuration record carries:

• Pricing defaults (margin, currency, unit)

• Physical constraints (MQC, capacity)

• Commercial intelligence (rating, score)

If this configuration is missing, traders will not see the quality as an option when creating operations for that site.

4. License quota is consumed by confirmed operations

SiteToLicense records track quota consumption against the license's frequency period (weekly, monthly, quarterly, annual). When an operation involving a licensed material is confirmed at a site, Jules deducts from the available quota. Operators are warned when a trade would exceed the available license quota.

5. Blacklists operate at the allocation level

Site blacklists and shipping line blacklists are enforced when allocating purchase and sale operations. Jules checks whether the buy-side site and sell-side site are incompatible before allowing the allocation. The blacklist does not prevent the operation from being created — it prevents the two sides from being matched.

6. Whitelists restrict acceptable origins at restricted sites

When a site has isRestrictedQualities = true, only qualities explicitly configured in SiteToQuality are accepted. Combined with the whitelist (whitelistedSites), this gives customers with strict origin requirements full control over what material enters their facility.

7. ERP synchronization is contact- and company-aware

Jules supports bulk import and synchronization of companies, sites, and contacts from an external ERP (*Erp mutations). The erpId field on company and site is the ERP's foreign key. User-to-company assignments can also be synchronized via createManyUsersToCompaniesErp and deleteManyUsersToCompaniesErp.

8. The uid field on legal entities is the unique internal identifier for document stamping

The uid field on Company, ShippingLine, LogisticForwarder, and CustomsAgency is the short identifier stamped on generated documents and shared externally. It differs from the database id (UUID) in that it is human-readable and stable across environments.

---

Glossary