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