2. Demand data loading¶

This training presents the data structure used by Demand Planning and guides the load of each dataset in the Community Edition. The eight files follow the same process sequence, from 01 through 08.

Demand Planning overview¶

Demand Planning aims to generate a sales projection that combines two components:

• a statistical foundation for sales projections;
• collaboration among Planning, Sales, Marketing, and other teams in building the plan.

The demand plan is essential for make-to-stock operating models, particularly in long supply chains such as those that depend on imported products or components. Because this type of operation relies on a future sales projection to make inventory, production, distribution, and productive and logistics capacity decisions, the demand plan becomes the main input for the tactical and operational decisions that follow.

Data structure¶

In the Community Edition, the Demand Planning module has a straightforward data structure, consisting primarily of the master and transactional data shown below:

---
config:
  layout: elk
  elk:
    mergeEdges: false
    nodePlacementStrategy: NETWORK_SIMPLEX
---
flowchart LR
    %% Global wrapper keeps the three registration groups stacked and pointing to Sales on the right.
  subgraph registrations[" "]
    direction TB

    subgraph materialRegistration["Material Registration"]
      direction LR
      materialCharacteristics["Material<br/>Characteristics<br/><span style='font-size:10px;color:#64748b'>E.g.: Family, Category</span>"]
      materialCharacteristicValues["Characteristic<br/>Value by<br/>Material"]
      materials["Materials<br/><span style='font-size:10px;color:#64748b'>Finished Goods, Semi-Finished,<br>Raw Materials</span>"]

      materialCharacteristics --> materialCharacteristicValues --> materials
    end

    subgraph locationRegistration["Location Registration"]
      direction LR
      locationCharacteristics["Location<br/>Characteristics<br/><span style='font-size:10px;color:#64748b'>E.g.: Channel, Region</span>"]
      locationCharacteristicValues["Characteristic<br/>Value by<br/>Location"]
      locations["Locations<br/><span style='font-size:10px;color:#64748b'>Customers, Plants,<br>DCs, Suppliers</span>"]

      locationCharacteristics --> locationCharacteristicValues --> locations
    end

    subgraph unitRegistration["Units of Measure Registration"]
      direction LR
      globalConversions["Global<br/>Conversions<br/><span style='font-size:10px;color:#64748b'>E.g.: TON->KG</span>"]
      unitsOfMeasure["Units of<br/>Measure"]
      materialConversions["Material<br/>Conversions"]

      globalConversions --> unitsOfMeasure
      materialConversions --> unitsOfMeasure 
    end
  end

  sellout["Sales<br/>(Sell-Out)"]

  materials --> sellout
  locations --> sellout
  unitsOfMeasure --> sellout

%% Keep the outer registrations wrapper visually transparent.
style registrations fill:transparent,stroke:transparent,stroke-width:0px

Accessing Data Registration and Extraction¶

In the Community Edition, open the side menu → Data → Data Operations. The catalog is organized from left to right as Theme, Group, Section, and Topic. Selecting a topic opens its API endpoint and the Download, Import, and, when applicable, Delete operations below the catalog.

Load order¶

Numbering is global: it indicates the order in which files are presented and loaded in this tutorial.

01. Units of measure¶

Units of measure are references used by materials, sales, inventory, routings, and bills of material. This tutorial registers UN, KG, and TON.

Loading the units-of-measure dataset¶

X01_unit_of_measure.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Unit of Measure Id	Unique unit code and the key referenced by other datasets.	UN, KG, TON
Description	Name presented to the user.	Units, Kilograms, Metric tons

Import the three rows through Import.

02. Material characteristics¶

Planning characteristics classify materials and will be used in the next training to build forecast clusters. This dataset registers each characteristic's name and type; its values are later provided in the material file columns.

Loading the material-characteristics dataset¶

X02_material_characteristics.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Material Characteristic Id	Unique characteristic code.	MATERIAL_STAGE, PRODUCT_FAMILY, PRODUCT_FORMAT
Description	User-facing name and the column title in the material file.	Material Stage, Product Family, Product Format
Type	Type of accepted values.	CATEGORICAL on all three rows

• Material Stage identifies the material's process position: Raw Material, Roll, Semi-Finished, or Finished Good;
• Product Family groups materials by family: Pulp, White Paper, or Tissue Paper;
• Product Format describes the physical presentation: Pulp, Jumbo Roll, Skid, A4, Letter, or 12-Roll Pack.

03. Materials dataset¶

Materials represent raw materials, intermediates, and finished goods. The Material Stage, Product Family, and Product Format columns are included in the same file because those characteristics were registered in the previous step.

Loading the materials dataset¶

X03_materials.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Id	Unique material code.	16 raw-material, intermediate, and finished-good codes
Description	Full material description.	Description corresponding to each code
Active	Controls participation in planning executions. An inactive material's history can still be used by statistical models.	TRUE or 1
Lifecycle Stage	Commercial lifecycle stage.	Blank because it is not used in this tutorial
Introduction Date	Date from which the material is considered current.	Blank
Discontinuation Date	Date after which the material is no longer considered current.	Blank
Default Unit of Measure (SNP)	Base unit used by Supply Chain plans for production, purchasing, and transfers.	TON
Sales Unit of Measure (DP)	Optional Demand Planning reference unit.	Blank; the effective forecast unit is confirmed in the cluster-combination configuration
Default Transfer Unit of Measure (DRP)	Optional default transfer unit.	Blank and outside this training's scope
Operational Model	How the material is operationally supplied.	MTS (make-to-stock)
Material Stage	Material position in the production process.	Raw Material, Roll, Semi-Finished, Finished Good
Product Family	Commercial or production family used for grouping.	Pulp, White Paper, Tissue Paper
Product Format	Physical format or presentation.	Pulp, Jumbo Roll, Skid, A4, Letter, 12-Roll Pack

Import the 16 materials through Import.

04. Global unit conversions¶

Global conversions record equivalences that apply to every material. They are used when the relationship between two units does not depend on the SKU, unlike the material conversions presented in the next step.

In this scenario, Sales history is in KG, while the forecast is generated and analyzed in TON. The global conversion between kilograms and tonnes is therefore required for the Demand Planning execution.

Loading the global unit-conversion dataset¶

X04_unit_conversions.xlsx

PathImportExcel fileFields

Field	Meaning	Value used in the tutorial
Origin Unit of Measure Id	Unit in which the origin quantity is expressed.	TON
Target Unit of Measure Id	Equivalent target unit.	KG
Origin Quantity	Reference quantity in the origin unit.	1
Target Quantity	Equivalent quantity in the target unit.	1000

The row establishes 1 TON = 1,000 KG. The platform also performs the inverse conversion from KG to TON.

05. Material conversions¶

This dataset records equivalences that depend on the SKU. For the eight finished goods, one UN corresponds to 0.25 KG or 0.40 KG, depending on the material.

The current history is already in KG, and the scenario's productivities are in TON. The global KG ↔ TON conversion in file 04 is therefore sufficient for the current forecast. File 05 completes the UN → KG → TON network so that a future input or analysis expressed in units can also be converted.

Loading the material-conversion dataset¶

X05_material_unit_conversions.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Material Id	Material to which the specific equivalence applies.	Eight finished goods
Origin Unit of Measure Id	Origin-quantity unit.	UN
Target Unit of Measure Id	Equivalent target unit.	KG
Origin Quantity	Reference quantity in the origin unit.	1
Target Quantity	Weight of one unit of the material.	0.25 or 0.40

06. Location characteristics¶

These characteristics classify demand locations by region and channel. As with materials, this dataset registers the characteristics, while their values are provided later in the location file itself.

Loading the location-characteristics dataset¶

X06_customer_characteristics.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Location Characteristic Id	Unique characteristic code.	CUSTOMER_REGION, SALES_CHANNEL
Description	User-facing name and the column title in the location file.	Customer Region, Sales Channel
Type	Type of accepted values.	CATEGORICAL on both rows

• Customer Region identifies the served region: Central, Coastal, or East;
• Sales Channel identifies the sales channel: Direct or Indirect.

07. Locations dataset¶

Locations represent suppliers, plants, distribution centers, transshipment points, customers, or demand regions. Customer Region and Sales Channel values are loaded in the final columns of this same file; there is no separate load for those values.

Loading the locations dataset¶

X07_locations.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Location Id	Unique location code. It may be an ERP code, internal abbreviation, customer, or region/channel combination.	12 codes
Description	Full location description.	Description corresponding to each code
Active	Controls participation in planning executions. Its history can still be used by statistical models when inactive.	TRUE or 1
Location Type	Role of the location in the network.	Internal for plant/DC, Supplier for supplier, and End Client for customer or demand region
Country, State, City	Optional geographic reference.	Reference data not used by this tutorial's calculations
Customer Region	Region associated with End Client locations.	Central, Coastal, East
Sales Channel	Channel associated with End Client locations.	Direct, Indirect

Planning-book availability, default unit, and indirect safety-stock fields stay blank because they do not participate in this Demand Planning flow.

08. Sales¶

In OpsFactor, Sales history may represent sell-in or sell-out. The Community Edition provides sell-out, which records a past sale—typically associated with billing—from a location. This tutorial uses the term Sales because it is more direct for the person running the process.

Sales history is the input to Demand Planning statistical models. For monthly or weekly projections, load at least two years of history so that models such as Holt-Winters and ARIMA have at least two complete seasonal cycles.

The file contains 38 months, from January 2024 through February 2027, for eight finished goods and six customer locations. Every quantity is in KG; the global conversion in file 04 makes it possible to generate and analyze the forecast in TON.

Loading the Sales dataset¶

X08_sellout_history.xlsx

PathImportExcel fileFields

Field	Meaning	Values used in the tutorial
Document Id	Unique sales-record identifier.	One code per row
Reference Date	Sales reference date.	First day of each month
Origin Location Id	Customer or demand region that originated the history. It must exist in the location dataset.	Six End Client locations
Material Id	Sold product. It must exist in the material dataset.	Eight finished goods
Unit of Measure Id	Unit in which the quantity was recorded.	KG on every row
Quantity	Quantity sold for the specified date, location, and material.	Positive historical quantity

Import the 1,824 rows last, after materials, locations, and units of measure have been registered.

Return to the course map or continue to the 3. Demand Forecast Overview.