Whippy Ware

This document includes detailed information regarding the processes of setup and use for the “Akinon Whippy Ware” application.

Akinon Whippy Ware is a frontend application that enables the cumulative management of stock management through location-based definitions of stocks from a brand’s various warehouses and locations, thanks to the rule blocks defined within the application.

Two concepts are utilized within the application: “Stock Providers” and “Stock Locations”. Stock providers represent the warehouse(s) with which the brand is working. Stock locations represent the location of brand stocks. If the brand has stores, they can be included in these locations as well.

Here are the fundamental functions of the “Akinon Whippy Ware” application:

• Stock Provider Management

• Stock Location Management

• Stock List Rule Management

• Stock List Management

• Stock and Reserve Stock Number Display

The following sections of the document provides detailed information regarding the features of the Whippy Ware application.

1. Whippy Ware Setup​

To set up the Akinon Whippy Ware application, the brand needs to have reached an agreement with the Akinon team as part of the project. The application setup is executed by the internal teams at Akinon.

2. Stock List Definition Process at Omnitron​

In order to use the stocks consolidated via Whippy Ware on Omnitron and OMS applications, a stock list needs to be defined on Omnitron. A stock list is created on Whippy Ware based on the ID of the stock list created on Omnitron.

3. Whippy Ware Processes​

After completing the setup process explained above, certain actions need to be executed. Detailed information regarding these actions can be found in this chapter.

3.1. Stock Provider Definition​

Defining a stock provider is a crucial first step when using the Whippy Ware application. This process involves manually setting up all providers within the application to establish a foundation for stock management.

Stock providers act as grouping mechanisms for stock locations, enabling users to efficiently organize and manage their inventory. Locations can be grouped under relevant providers based on specific purposes, regions, or systems, ensuring clarity and streamlined operations. Once defined, stock providers facilitate the organization of stock locations, as detailed in Section 3.2, by allowing users to assign stock locations to specific providers. For example:

• Multiple stock locations associated with warehouses in the ABC region can be grouped under the "ABC Provider".

• Locations dedicated to fulfilling online orders can be grouped under the "E-Commerce Provider".

• Locations retrieving stock data from a specific ERP system, such as SAP, can be grouped under the "SAP Provider".

• If a general provider is preferred over a specific stock provider, the brand name can be used as the provider identifier.

The information of the stock provider defined via Whippy Ware needs to be identical to the defined information sent from the brand’s API. Otherwise, Whippy Ware will not be able to register the information received from the service into its own system.

Follow the steps below to create a Stock Provider:

1. Log into the Whippy Ware application.

2. Click Stock Providers.

   
3. This screen lists all previously created Stock Providers within the system.

   
4. Click the + Add New Provider button to add a new one.

   
5. On the next screen, fill in the information for the stock provider, which needs to be identical to the information received from ERP.

   

Stock Provider Field Descriptions:

Field Name	Status	Description	Example Value
Stock Provider	Mandatory	Stock provider name	Europe
Stock Provider Code	Mandatory	Stock provider ID defined on the ERP to be used by the service	114
Status	Mandatory	The active/passive status of the provider	Active

Completing these steps and accurately categorizing providers ensures smooth integration and stock data synchronization.

3.2. Stock Location Definition​

A stock provider, as defined in Section 3.1, can manage stock areas across multiple locations. These stock locations need to be defined on Whippy Ware in order to match them with a stock provider. The brand needs to determine a unique value for each stock location and to define these values both within its own system and on Whippy Ware.

Follow the steps below to create a Stock Location:

1. Click Stock Locations within the application.

   
2. This screen lists all previously created Stock Locations within the system.

   
3. Click the + Add New Location button to add a new one.

   
4. On the next screen, fill in the information for the stock location, which needs to be identical to the information received from ERP.

   

Stock Location Field Descriptions:

Field Name	Status	Description	Example Value
Stock Location	Mandatory	Stock location name	LocationA
Stock Location Code	Mandatory	Stock location ID defined on the ERP to be used by the service	133
Stock Provider	Mandatory	Select one of the stock providers defined in Section 3.1 within the system	Europe
Status	Mandatory	The active/passive status of the provider	Active

1. Click Save after entering the required information.

3.3. Stock List Rules Definition​

Whippy Ware enables stock calculation based on stock locations and providers. In order to do this, the user needs to define a calculation rule which will work in the background of the application. The brand provides stock providers, stock locations, and location-based/independent safety stocks to be used for the preparation of a stock list. The user defines the rule for calculating stocks in the background of the application using this information.

After creating Stock List Rules, follow the steps below to check their definition:

1. Click Stock List Rules within the application.

   
2. A new rule is defined based on shared information:

• Rule Name: A descriptive name for the rule.

• Rule: Rule config prepared by using the information provided by the brand regarding stock providers, stock locations, and whether they have virtual stock sales.

• Status: Indicates whether the rule is active or inactive.

• Rule Type: Specifies the type of rule being applied. It can be one of the following:

  • Prog: A configuration-based approach where users define rules using a set of predefined rule types.

  • Raw SQL: A direct SQL query approach for creating stock rules.

  • SQL: A JSON-formatted SQL query approach for creating stock rules.

    

Prog Rule Type​

The Prog rule type uses a configuration-based approach where users define the rules using a set of predefined conditions. The Prog rule type is flexible and allows users to build complex rules by combining multiple conditions. Here are the available rule types within the Prog rule:

• AndRule: Combines multiple conditions using logical AND.

• OrRule: Combines multiple conditions using logical OR.

• NotRule: Negates a condition.

• PeriodRule: Specifies a time-based condition.

• EqualRule: Checks for equality between source and target values.

• InRule: Checks if a value is within a specified set.

• GreaterThanRule: Checks if a value is greater than a specified target.

• GreaterThanOrEqualRule: Checks if a value is greater than or equal to a specified target.

• LowerThanRule: Checks if a value is lower than a specified target.

• LowerThanOrEqualRule: Checks if a value is lower than or equal to a specified target.

• SetValueRule: Sets a value to a specific target.

• SumRule: Calculates the sum of values.

• SubRule: Performs subtraction based on values.

An example for a Stock Rule written with the Prog rule type is shown below:

config = {
            "name": "and-rule",
            "children": [
                {
                    "name": "lower-than-or-equal-rule",
                    "source": 'stock',
                    "target": 20
                },
                {
                    "name": "period-rule",
                    "date": now().isoformat()
                },
                {
                    "name": "equal-rule",
                    "source": 'stock',
                    "target": 10
                }
            ]
        }

Raw SQL Rule Type​

The Raw SQL rule type allows users to define stock rules by writing direct SQL queries. Below is the expected JSON structure, including optional fields, which are explained further in this section:

{
  "sql": "",
  "alias_name": "active_stock",
  "params": {
    "sku_filter_key": "AND sku = ",
    "date_filter_key": "AND modified_date > "
    // Additional parameters can be added here
  }
}

• alias_name (optional): This value is user-defined and does not impact any built-in Akinon functionality.

• params (mandatory): Must be an object containing the following required keys:

  • sku_filter_key → Must follow the format "AND s.sku = "

  • date_filter_key → Must follow the format "AND s.modified_date > "

These keys enable API clients to use query parameters for SKU and date filtering.

• sql: The field for the SQL query string. Below is a list of accessible columns from the stocks table, along with restricted SQL keywords that should not be used to maintain security and performance.

Accessible Columns:

sku                 // VARCHAR(150)
stock               // POSITIVE INTEGER
reserved_stock      // POSITIVE INTEGER
stock_type          // VARCHAR(15) ('scheduled' or 'standard')
unit_type           // VARCHAR(15) ('qty' or 'kg')
period              // TSTZRANGE
provider_id         // INTEGER
location_id         // INTEGER
parent_id           // INTEGER
is_active           // BOOLEAN
modified_date       // TIMESTAMP

Forbidden SQL Keywords:

forbidden_words = [
    'insert', 'drop', 'update', 'delete',
    'alter', 'create', ';', 'truncate'
]

Performance Note

Avoid unnecessary JOIN operations and large IN lists for better query efficiency.

Example Configuration:

The following example demonstrates a Raw SQL rule with explanations:

{
  "rule_type": "raw_sql",
  "sql": """
SELECT 
    s.sku,
    SUM(
        CASE 
            WHEN s.stock_type = {stock_type} 
            AND s.period @> CURRENT_TIMESTAMP 
            THEN s.stock 
            ELSE 0 
        END
    ) AS {alias_name}
FROM 
    stocks_stock s // Mandatory table reference
WHERE 
    s.is_active = TRUE
    {sku_filter}
    {modified_date_filter}
GROUP BY 
    s.sku // SKU-based grouping is required
  """,
  "alias_name": "scheduled_stock",
  "params": {
    "sku_filter_key": "AND s.sku = ", // 's' alias preferred in FROM clause
    "date_filter_key": "AND s.modified_date > ",
    "stock_type": "'scheduled'" // Optional parameter
  }
}

This configuration calculates the total stock for active SKUs where the stock type matches {stock_type} and the period includes the current timestamp. The results are grouped by SKU to ensure proper aggregation.

SQL Rule Type​

The SQL rule type enables users to define stock rules using a structured JSON format that organizes SQL logic. This method is similar to Raw SQL but provides a structured approach for better management and maintainability.

Below is the general structure of the expected JSON, including optional fields. Further explanations are provided in this section.

{
  "group_by": ["sku"],
  "method": "sum",
  "default_value": 0,
  "buffer": {
    "method": "sum",
    "conditions": [...]
  },
  "conditions": [...]
}

Key Fields & Functionality

• group_by (mandatory): Defines the fields used for grouping results, by "sku".

• method (mandatory): Specifies the aggregation method for calculating stock. The most commonly used method is "sum", but Whippy also supports:

  • "avg" (average)

  • "min" (minimum)

  • "max" (maximum)

• default_value (optional, common: 0): Defines the stock value when no data is available. If a stock value is not provided for a product, the rule will return this default value instead.

• buffer (optional): If included, it must contain both method and conditions.

  • This allows Whippy to calculate active stock quantity and reserved stock quantity separately, using different conditions and/or methods.

  • The final active stock value in the API response is calculated as: active_stock - buffer_stock

• conditions (mandatory): Defines one or more conditions for filtering data before stock quantity calculation.

  • Multiple conditions are connected using the OR operator.

  • The general structure for a condition is:

{
  "order": <integer>,
  "operator": "and",
  "negated": <boolean>,
  "sub_conditions": [...]
}

Condition Fields

• order (optional): The order number of the condition relative to others in the list (integer).

• operator (optional, default: "and"): Defines how conditions are combined inside sub_conditions. Can be "and" or "or".

• negated (optional, default: false): If true, the condition result is reversed.

• sub_conditions (mandatory): A list of objects that specify detailed filtering conditions.

Example Condition

{
  "location_id__in": [101, 20],
  "location__is_active": true
}

Field Operators

Field Operators	Example	Description
__exact	{"sku__exact": "ABC123"}	Exact match
__in	{"provider_id__in": [1,2,3]}	Search in list
__gt	{"stock__gt": 0}	Greater than
__gte	{"stock__gte": 10}	Greater than or equal
__lt	{"stock__lt": 100}	Less than
__lte	{"stock__lte": 50}	Less than or equal
__contains	{"period__contains": "__now"}	Contains
__startswith	{"sku__startswith": "A"}	Starts with
__endswith	{"sku__endswith": "Z"}	Ends with
__isnull	{"period__isnull": true}	Null check

Available Fields​

Basic Stock Fields:

Field	Type	Description	Example Usage
stock	integer	Stock quantity	{"stock__gt": 0}
reserved_stock	integer	Reserved stock quantity	{"reserved_stock": 5}
sku	string	Product SKU value	{"sku": "ABC123"}

Location Fields:

Field	Type	Description	Example Usage
location_id	integer	Location ID	{"location_id": 1}
location__is_active	boolean	Location active status	{"location__is_active": true}

Stock Type Fields:

Field	Type	Description	Example Usage
stock_type	string	Stock type	{"stock_type": "scheduled"}
period	daterange	Scheduled stock period	{"period__contains": "__now"}

Provider Fields:

Field	Type	Description	Example Usage
provider_id	integer	Provider ID	{"provider_id": 1}
provider__is_active	boolean	Provider active status	{"provider__is_active": true}

1. Once the Stock List Rule is defined, it is displayed on the related screen for users to interact with.

3.4. Stock List Definition​

The Stock List feature in Whippy Ware facilitates the mapping between the Stock List ID (defined in Omnitron) and the stock rule to be applied to that list. This mapping ensures that the rules created within Omnitron and the Order Management System (OMS) are appropriately linked to specific stock lists for efficient stock management.

Follow the steps below to create Stock Lists:

1. Click Stock Lists within the application.

   
2. This screen lists all previously created Stock Lists within the system.

   
3. Click the + Add New Stock List button to add a new one.

   
4. On the next screen, fill in the information for the stock list.

   

Stock List Field Descriptions:

Field Name	Status	Description	Example Value
Stock List Name	Mandatory	Stock list rule name	edirne
Stock List Code	Mandatory	Stock list’s unique code	22
Status	Mandatory	The active/passive status of the stock list	Active
Remote ID	Mandatory	Omnitron stock list ID	165
Stock List Rules	Mandatory	Select the stock list rule you wish to use.	Lorem

1. Click Save after entering the required information.

3.5. Stock Display​

The stocks based on the SKUs, locations, and stock providers fetched from the brand via integration are displayed here. The Stock screen displays how many stocks are kept in reserve for an SKU in the related location. Reserve stocks are used for orders that have not been sent to the ERP or switched to the Preparing status yet.

Follow the steps below to display Stock:

1. Click Stock within the application.

   
2. This screen lists all Stocks fetched via integration.

   
3. Click the + Add New Stock button to add a new one.

   
4. On the next screen, fill in the information for the stock. Based on the preference of the brand, the user can select Scheduled stock type which will be valid between certain time intervals or Standard which will run without any limitations on date or time.

   

Stock Field Descriptions:

Field Name	Status	Description	Example Value
SKU	Mandatory	Product code	112123132-001
Stock Type	Mandatory	This is used to define Scheduled or Standard stocks.	Standard
Stock Provider	Mandatory	The stock provider to be used	LIF
Location	Mandatory	The location to be used	Lorem
Status	Mandatory	The active/passive status of the stock	Active
Stock Number	Mandatory	The stock number to be defined virtually	102
Stock List Rules	Mandatory	Select the stock list rule to be used.	Lorem