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
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.

Quality Families have a display name. They are shared across the organization.

Notes

• There is no enforced limit to the number of families an organization can create.
• Renaming or deleting a family does not affect existing qualities — it simply removes the label from the dropdown.

---

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 default MQC, recycling MQC, and price precision 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 — the template: what is being measured, in what unit type, with what value format
2. Quality Attribute — 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 Prefill loading/delivery attributes 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

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 default conditioning field pre-populates 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, 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

Functional Tags

The group tag 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.

Quality-Specific MQC by Container Type

This 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.

Fields

This mapping is used when creating containers to automatically fill in the correct MQC — reducing manual data entry and ensuring consistency.

---

Units of Measure

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

Quantity Units

Quantity units define the display name, shorthand (e.g., MT, Ctn), and decimal precision rules for commercial quantities and prices.

VolumeEnum — Available Unit Codes

Measurement Units for Quality Attributes

For quality attribute specifications, Jules uses a more granular measurement unit catalog supporting physical measurement systems (length, weight, volume, density, temperature, etc.) and both metric and imperial unit systems.

Unit Availability by Context

The system controls which unit codes are available in which contexts (purchase quantities, sale quantities, logistic costs) through administrator configuration.

---

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

Renaming or deleting a quality family or group does not cascade to existing qualities. Migration tools are needed to reorganize the hierarchy after the fact.

2. Soft deletion preserves history

Qualities and Other Products support soft deletion. 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 — applies to buy and sell operations
• Recycling MQC — applies when the operation is classified as recycling

Additionally, the container-type MQC 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 default conditioning drives loading mode

A quality's default conditioning carries a loading type (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 default stock picking rule (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 external ERP ID field for synchronization. This 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 records are global reference data shared across the platform. Quality, Quality Family, Quality Group, Other Product, and all other catalog entities are per-organization — each tenant maintains its own product catalog independently.

---

Glossary