Stock-taking
Stock-taking is the process of physical verification of the actual quantities and conditions of goods held in a storage location.
Domain model
The enfore platform has support for stock-taking in enforePOS1 and enforePOS2 with a substantially different set of features. Therefore, there are two different domain models, one for enforePOS1 stock-taking and one for enforePOS2 stock-taking.
enforePOS1
An enforePOS1 stock-taking is represented by a StockTaking
structure with a minimal set of configuration options. In enforePOS1, stock-taking is always performed by entering counting data on a resource-by-resource basis. There is no support for concurrent counting using multiple participants nor for counting areas.
The general life-cycle of an enforePOS1 stock-taking is rather simple:
enforePOS2
TBD
Data export
This section describes how data for a stock-taking can be exported via the enfore API and the format of the exported data.
Triggering data export
A data export for a stock-taking can be triggered by a POST /org/{org-id}/stock-taking-exports
with a StockTakingReference
identifying the stock-taking whose data to export as payload. Note that triggering an export is only possible for stock-takings that have reached a terminal state (CANCELED
, COMPLETED
, or COMPLETED_RECONCILIATION
).
The state machine for a data export is simple:
The status of a StockTakingDataExport
can be determined by polling. Once the status reaches COMPLETED
, a download URL for the export data can be acquired via GET /org/{org-id}/stock-taking-exports/{export-id}/download
.
The "happy-path" sequence of exporting data for a stock-taking is:
Export data format
The result of a data export for a stock-taking is a ZIP file containing a JSON file with meta-data about the stock-taking as well as a number of CSV files containing the counting and context data of the stock-taking.
The general structure of the ZIP file is:
CSV format rules
General
All CSV files of the stock-taking export format adhere to the CSV format as defined by RFC4180 and use a header row. The header row will contain the names of the columns as defined in the DBML definition for the export.
Numbers
All numbers are exported using the format pattern ###0.###
. Values for columns defined as type integer
do not contain a decimal separator or fractional digits.
Timestamps
All timestamps are exported as ISO 8601 timestamps with complete date plus hours, minutes, and seconds (but no fractional seconds) and using UTC timezone. That is, the format should match YYYY-MM-DDThh:mm:ssZ
, e.g., 2000-05-24T13:15:30Z
.
File contents
meta.json
The file meta.json
contains the JSON structure StockTaking
that can be acquired via the regular GET
call in the API when querying a stock-taking.
For enforePOS1 stock-takings, this is the same as the response from GET /org/{org-id}/stock-takings-enfore-pos-1/{stock-taking-id}
.
counting_areas.csv
The file counting_areas.csv
contains a list of all counting areas of the stock-taking.
For enforePOS1 stock-takings and area-less enforePOS2 stock-takings, this fill will be empty.
The DBML definition for the file is:
Table counting_areas {
id varchar [primary key, note: 'Technical ID of the counting area']
name varchar [not null, note: 'Name of the counting area']
type area_type [not null, note: 'Type of the counting area']
Note: 'List of the counting areas of the stock-taking'
}
Enum area_type {
STORAGE_AREA
TEMPORARY_AREA
}
participants.csv
The file participants.csv
contains a list of all participants of the stock-taking.
For enforePOS1 stock-takings, there is no device information and usually only a single participant exists.
For enforePOS2 stock-takings, there will be device information for all participants that have actually counted something. Participants that do not have counted may or may not have device information.
The DBML definition for the file is:
Table participants {
id varchar [primary key, note: 'ID of the participant']
staff_member_id varchar [not null, note: 'ID of the IndividualContact of the participant']
staff_member_name varchar [not null, note: 'Name of the participant']
device_id varchar [note: 'ID of the Device object used by the participant']
device_name varchar [note: 'Name of the Device object used by the participant']
Note: 'List of the participants of the stock-taking'
}
The value of the staff_member_id
field is the identifier of the staff member that is participant of the stock-takings. The identifier can be used to fetch the staff member via the "Staff & Access Rights"-API endpoint /org/{org-id}/staff-members/{staff-member-id}
. The identifier can also be used to fetch the IndividualContact
of the staff member via the Contacts-API endpoint /org/{org-id}/individual/{contact-id}
.
The value of the device_id
field is the identifier of the device used by the participant of the stock-taking. The identifier can be used to fetch the device via the "Organization Structure"-API endpoints /org/{org-id}/devices/{device-id}
or /org/{org-id}/enforepos-devices/{enforepos-device-id}
.
resources.csv
The file resources.csv
contains a list of all counted resource/condition pairs and aggregated count results for each.
The DBML definition for the file is:
Table resources {
id varchar
condition varchar
name varchar
article_id varchar
tracking_unit unit_of_measure [not null]
counted_units integer
first_counted_on timestamp
first_counted_by varchar
last_counted_on timestamp
last_counted_by varchar
indexes {
(id, condition) [pk]
}
Note: 'Information about the resources counted as part of the stock-taking'
}
Ref: resources.first_counted_by > participants.id
Ref: resources.last_counted_by > participants.id
Enum unit_of_measure {
ENERGY_JOULES
ENERGY_GIGAJOULES
ENERGY_MEGAJOULES
ENERGY_KILOJOULES
ENERGY_CENTIJOULES
ENERGY_MILLIJOULES
ENERGY_MICROJOULES
ENERGY_CALORIES
ENERGY_KILOCALORIES
ENERGY_WATTHOURS
ENERGY_GIGAWATTHOURS
ENERGY_MEGAWATTHOURS
ENERGY_KILOWATTHOURS
ENERGY_CENTIWATTHOURS
ENERGY_MILLIWATTHOURS
ENERGY_MICROWATTHOURS
LENGTH_KILOMETERS
LENGTH_METERS
LENGTH_DECIMETERS
LENGTH_CENTIMETERS
LENGTH_MILLIMETERS
LENGTH_POINTS
LENGTH_INCHES
LENGTH_FEET
LENGTH_YARDS
MASS_TONS
MASS_KILOGRAMS
MASS_GRAMS
MASS_MILLIGRAMS
MASS_POUNDS
QUANTITY_PIECES
TIME_SECONDS
TIME_MINUTES
TIME_HOURS
TIME_DAYS
TIME_WEEKS
DIGITALINFORMATION_BYTES
DIGITALINFORMATION_KILOBYTES
DIGITALINFORMATION_KIBIBYTES
DIGITALINFORMATION_MEGABYTES
DIGITALINFORMATION_MEBIBYTES
DIGITALINFORMATION_GIGABYTES
DIGITALINFORMATION_GIBIBYTES
DIGITALINFORMATION_TERABYTES
DIGITALINFORMATION_TEBIBYTES
DIGITALINFORMATION_PETABYTES
DIGITALINFORMATION_PEBIBYTES
TIME_MONTHS
TIME_YEARS
VOLUME_CUBIC_MILLIMETERS
VOLUME_CUBIC_CENTIMETERS
VOLUME_CUBIC_DECIMETERS
VOLUME_CUBIC_METERS
VOLUME_MILLILITERS
VOLUME_CENTILITERS
VOLUME_DECILITERS
VOLUME_LITERS
VOLUME_HECTOLITERS
VOLUME_FLUID_OUNCES
VOLUME_PINTS
VOLUME_QUARTS
VOLUME_GALLONS
VOLUME_BARRELS
}
Note that the file uses a composite primary key consisting of the resource
and condition
columns. That means, that there may be multiple records for the same resource, when the resource exists in multiple conditions.
The value of the id
field is the identifier of the resource that has been counted as part of the stock-taking. If the resource is a product, the identifier can be used to fetch the product via the ERP-API endpoint /org/{org-id}/products/{product-id}
.
The value of the condition
field identifiers the condition of the counted resource. For enforePOS1 stock-takings, the value of the column is the name of the condition (one of NEW
, REFURBISHED
, USED_LIKE_NEW
, USED_VERY_GOOD
, USED_GOOD
, USED_ACCEPTABLE
, DAMAGED
).
area_counts.csv
The file area_counts.csv
contains a list of all area counts performed as part of the stock-taking.
This file will be empty for enforePOS1 stock-taking and area-less enforePOS2 stock-takings.
The DBML definition for the file is:
Table area_counts {
id varchar [primary key]
area varchar
participant varchar
Note: 'List of the are counts of the stock-taking'
}
Ref: area_counts.area > counting_areas.id
Ref: area_counts.participant > participants.id
counting_data.csv
The file counting_data.csv
contains the low-level stock count data provided by the participants of the stock-taking.
For enforePOS1 stock-takings, low-level data is not stored, so the file essentially contains the same count data as resources.csv
.
For enforePOS2 stock-takings, low-level data is stored and made available via this file in the export.
The DBML definition for the file is:
Table counting_data {
id varchar [primary key]
resource varchar [not null]
condition varchar
lot varchar
counted_units integer [not null]
counted_on timestamp [not null]
counted_by varchar [not null]
area_count varchar
Note: 'List of counting data of the stock-taking'
}
Ref: counting_data.resource > resources.id
Ref: counting_data.counted_by > participants.id
Ref: counting_data.area_count > area_counts.id
The value of the resource
field is the identifier of the resource that has been counted as part of the stock-taking. If the resource is a product, the identifier can be used to fetch the product via the ERP-API endpoint /org/{org-id}/products/{product-id}
.
The value of the condition
field identifiers the condition of the counted resource. For enforePOS1 stock-takings, the value of the column is the name of the condition (one of NEW
, REFURBISHED
, USED_LIKE_NEW
, USED_VERY_GOOD
, USED_GOOD
, USED_ACCEPTABLE
, DAMAGED
).
The value of the lot
field is the identifier of the lot that the counted units belong to. The identifier can be used to fetch the lot via the ERP-API endpoint /org/{org-id}/lots/{lot-id}
.
counted_unique_items.csv
The file counted_unique_items.csv
contains the list of all unique item units that have been counted as part of the stock-takings.
As enforePOS1 stock-takings do not support counting unique item units, this file will be empty in exports of enforePOS1 stock-takings.
The DBML definition for the file is:
Table counted_unique_items {
id varchar [primary key]
resource varchar [not null]
lot varchar
condition varchar
counted_via varchar [not null]
Note: 'List of unique items counted as part of the stock-taking'
}
Ref: counted_unique_items.resource > resources.id
Ref: counted_unique_items.counted_via > counting_data.id