Qualities, Commodities & Materials

Product documentation — How Jules organizes the materials your company trades: the three-level quality hierarchy, the product catalog, and every supporting reference table that drives operations, pricing, and compliance.

---

Table of Contents

1. Overview

2. The Quality Hierarchy: Family → Group → Quality

3. Quality Families

4. Quality Groups

5. Qualities (Material Grades)

6. Quality Attributes

7. Commodities & Market Indices

8. Conditionning

9. Packages (Equipment & Service Bundles)

10. Equipment

11. Services

12. Other Products & Other Product Groups

13. Logistic Materials & MQC Mapping

14. Units of Measure: QuantityUnit, Unit & BaseVolume

15. How Qualities Connect to Operations

16. Key Business Rules

17. Glossary

---

Overview

In Jules, every trade is about material — scrap metal, waste paper, plastics, electronic waste. Before a trader can create an operation, contract, or invoice, the platform needs to know exactly what is being bought or sold, at what specification, and in what unit.

The quality system is Jules' answer to that need. It is a structured, three-level classification that lets your organization define, name, and govern every material grade you trade — from broad categories ("Ferrous Metals") down to precise tradeable specifications ("HMS 1&2, max 5% non-ferrous, 80–120 kg/m³").

Beyond qualities, Jules maintains a broader product catalog that covers everything that can appear on an operation or invoice:

---

The Quality Hierarchy: Family → Group → Quality

Jules classifies recyclable materials in three nested levels. Each level adds precision.

This hierarchy is used to:

• Filter and browse the quality catalog efficiently (e.g., "show me all qualities in the HMS group")

• Set default MQC values at the group level, inherited by individual qualities

• Drive index pricing: commodities (see Commodities & Market Indices) operate at the macro level and map across families and groups

• Segment reporting: margin reports and goals can be sliced by family or group

---

Quality Families

A Quality Family is the top of the hierarchy. It is a free-text label that defines the broadest material category. Families have no configuration of their own — they exist purely as a grouping label.

Fields

Notes

• Families are shared across the entire organization.

• A quality's family field stores the string value of the family (not a foreign key to the QualityFamily entity). This means deleting a QualityFamily record does not cascade to qualities — it simply removes the label from the dropdown.

• There is no enforced limit to the number of families an organization can create.

---

Quality Groups

A Quality Group sits between the family and individual qualities. It refines the classification and carries important default values that pre-populate new qualities created within that group.

Fields

How defaults cascade

When a new quality is created and assigned to a group, the group's mqc, recyclingMqc, and pricePrecision values serve as intelligent defaults. Traders can override them at the quality level. This saves time when onboarding a new grade within a familiar product category.

---

Qualities (Material Grades)

A Quality is the core tradeable entity in Jules. It represents a specific material grade with its full commercial, logistical, and regulatory specification. Qualities are what appear on operation lines, contracts, and invoices.

Fields

Regulatory / Customs Codes

For cross-border trade and Basel Convention compliance, each quality can carry a set of official codes:

These fields are used when generating Annex 7 trans-frontier waste movement documents, which are required for certain cross-border recyclable material shipments under EU and Basel Convention regulations.

---

Quality Attributes

Quality Attributes are the technical specification fields that define exactly what a quality grade looks like — contamination limits, density ranges, size constraints, moisture content, and so on. They make a quality grade a precise specification sheet.

Architecture: Two-level system

Attributes work in two layers:

1. Attribute definition (Attribute) — the template: what is being measured, in what unit type, with what value format

2. Quality Attribute (QualityAttribute) — the instance: the specific threshold or value for a given quality

Attribute Definition Fields

Attribute Type Enum

Quality Attribute Instance Fields

How attributes flow through operations

When shouldPrefillLoadingDeliveryAttributes is enabled on a quality, its attribute values are automatically copied into container loading and delivery records. This means inspectors can see the expected specification directly in the field — and discrepancies trigger the configured penalties.

---

Commodities & Market Indices

A Commodity is a market-level reference for a material category, primarily used in index-based pricing. While Quality Groups and Families describe your internal product catalog, Commodities map to how the material is referenced on financial markets (e.g., LME Copper, TSI Heavy Melting Scrap).

Commodity Fields

CommodityMarket Fields

CommodityMarketIndexChoices

This entity exposes the available market index choices for index pricing configuration on operations. Each index choice specifies which PriceIndexPriceTypeEnum values (monthly average, spot, fixing, etc.) are valid for that index.

Commodities are a reference catalog, not a configuration that end-users create frequently. They are managed by administrators and drive the index pricing dropdowns when traders configure an operation's price as "INDEX" type.

---

Conditionning

Conditionning (note: the French-origin spelling is preserved in the codebase) describes how a material is physically presented or loaded. It answers the question: "Is this material loose bulk, or loaded in a particular way?"

Fields

LoadingTypeEnum

A quality's defaultConditionning field points to one of these values, pre-populating the conditioning field when the quality is selected on an operation or container.

---

Packages (Equipment & Service Bundles)

A Package is a named bundle that combines one or more Equipment types and Services for a specific quality. It represents a standard commercial offer template for how that material will be shipped and handled.

Package Fields

Packages are filtered by quality (filteredPackages(qualityId: ID)), meaning each quality can have multiple named packages tailored to different trade scenarios (e.g., a "local domestic" package vs. an "export FOB" package).

---

Equipment

Equipment defines the physical container or transport unit types available in Jules. It is used when specifying what container type will carry the goods in an operation or booking.

Fields

Equipment is referenced:

• On operation quality lines to specify the container type for a trade

• In Packages as bundled transport options for a quality

• On freight bookings to specify what containers are being booked

• In logistic cost calculations where rates vary by equipment type

---

Services

Services are logistics and handling service definitions — the non-material line items that can be attached to a quality's package. Examples: loading supervision, certificate of quality, fumigation, survey inspection.

Fields

Services appear in Packages alongside Equipment to define the full service offering for a quality grade.

---

Other Products & Other Product Groups

Other Products are the non-material catalog items that can appear on invoices and bills — costs, fees, adjustments, and services that are not recyclable material grades.

OtherProductGroup

An OtherProductGroup is the first-level classification for non-material products, equivalent to the Quality Family in the materials hierarchy. It is a simple label (e.g., "Logistics", "Finance Charges", "Inspection Fees").

OtherProduct Fields

OtherProductGroupTagEnum

The groupTag drives how Other Products are routed and displayed in the P&L and margin calculations — TRANSPORT costs are allocated differently from DEVIATION adjustments.

---

Logistic Materials & MQC Mapping

LogisticMaterial

A Logistic Material is a reference label for the physical packaging or logistic support material associated with freight (e.g., "Pallet", "Stretch Film", "Steel Band"). These appear in container and shipment records to track ancillary materials.

LogisticMaterialToMqc

The LogisticMaterialToMqc mapping is a pivotal configuration table: it defines the MQC (Minimum Quality Commitment) thresholds and tolerance rates that apply when a specific logistic material is combined with a specific quality.

This is the mechanism that allows MQC and tolerance settings to vary by transport mode or packaging method — the same quality may have different minimum weights depending on whether it is shipped in a standard container vs. an open-top vs. on a flatrack.

LogisticMaterialToMqc Fields

This mapping is queried at the time of container creation or operation setup via logisticMaterialToMqc(input: { logisticMaterial, qualityId }) to prefill the MQC automatically — reducing manual data entry and ensuring consistency.

---

Units of Measure: QuantityUnit, Unit & BaseVolume

Jules has three distinct but related systems for managing units of measure. Understanding the distinction is important when configuring new qualities or reading API responses.

QuantityUnit

QuantityUnit is the primary units-of-measure catalog for commercial quantities and prices. It ties together a display label with the underlying system code and precision rules.

VolumeEnum — Available Unit Codes

Unit

Unit is a more granular measurement reference catalog used for quality attributes and technical specifications. It supports physical measurement categories and unit systems, enabling quality attributes to specify precise measurement units.

BaseVolume

BaseVolume is a configuration table that maps system volume codes (VolumeEnum) to their role and market context. It determines which units are valid in which commercial context.

BaseVolumeTypeEnum

BaseVolume is an administrator-level configuration that controls which unit codes appear in which dropdowns. Most users will never interact with it directly — it silently shapes what choices are available when creating operations and bills.

---

How Qualities Connect to Operations

Qualities are the bridge between the material catalog and commercial activity. Every trade in Jules flows through them.

Where qualities are used across Jules

---

Key Business Rules

1. Hierarchy is advisory, not enforced by foreign keys

A quality's family and group fields store string values — not relational IDs pointing to QualityFamily or QualityGroup records. This means:

• Renaming a family or group does not cascade to the qualities that reference it

• Deleting a family or group does not break existing qualities

• Quality migration tools must be used if you reorganize the hierarchy after the fact

2. Soft deletion preserves history

Qualities and Other Products support soft deletion (isDeleted: true). Deleted items disappear from picker dropdowns but remain in the database to preserve historical operation and invoice records. This is critical for audit integrity — an operation created two years ago still correctly references its quality.

3. MQC has two variants and cascades via logistic material

Every quality defines two MQC values:

• Trading MQC (mqc) — applies to buy and sell operations

• Recycling MQC (recyclingMqc) — applies when the operation is classified as recycling

Additionally, the LogisticMaterialToMqc mapping can override these values for specific container types. The lookup order is: logistic material mapping first, quality default as fallback.

4. Threshold rates define tolerance windows

Each quality carries four tolerance rates defining acceptable weight deviation:

Containers outside these thresholds are flagged for commercial review.

5. Attribute penalties are quality-level defaults

When a quality attribute defines a penalty (e.g., "-5 USD/T for each 1% over the max contamination threshold"), that penalty is the default applied when the attribute is checked at container loading or delivery. Traders can override the penalty amount on a specific container record.

6. The defaultConditionning drives loading mode

A quality's defaultConditionning maps to a Conditionning record that carries a loadingType (MATERIAL or ITEM). This drives the container loading form: material mode shows weight entry fields, while item mode shows quantity counting fields.

7. StockPickingRule affects warehouse operations

For warehouse operations (where goods are received into a stockpile before being sold), the quality's defaultStockPickingRule (FIFO or LIFO) determines which inventory batch is consumed first when allocating stock to sale operations.

8. ERP ID synchronization

Qualities, Other Products, Equipment, and Services all carry an erpId field. This is the identifier in your organization's external ERP system. It is used when Jules synchronizes operation and invoice data to the ERP — ensuring that material master records are correctly matched across systems.

9. Regulatory codes are mandatory for Annex 7

For organizations trading recyclable waste across international borders, the quality fields hsCode, baselId, ecCode, nationalCode, rdCode, and officialName are required to generate valid Annex 7 trans-frontier shipment notification documents. Missing codes will cause document generation to fail or produce incomplete outputs.

10. Commodities are global; qualities are per-organization

Commodity and CommodityMarketIndexChoices records are global reference data shared across the platform. Quality, QualityFamily, QualityGroup, OtherProduct, and all other catalog entities are per-organization — each tenant maintains its own product catalog independently.

---

Glossary