sideshow.batch.neworder

New Order Batch Handler

class sideshow.batch.neworder.NewOrderBatchHandler(config)

The batch handler for new order batches.

This is responsible for business logic around the creation of new orders. A NewOrderBatch tracks all user input until they “submit” (execute) at which point an Order is created.

After the batch has executed the order handler takes over responsibility for the rest of the order lifecycle.

add_item(batch, product_info, order_qty, order_uom, discount_percent=None, user=None)

Add a new item/row to the batch, for given product and quantity.

See also update_item().

Parameters:

• batch – NewOrderBatch to update.

• product_info – Product ID string, or dict of PendingProduct data.

• order_qty – order_qty value for the new row.

• order_uom – order_uom value for the new row.

• discount_percent – Sets the discount_percent for the row, if allowed.

• user – User who is performing the action. This is used to set created_by on the pending product, if applicable. If not specified, the batch creator is assumed.

Returns:

NewOrderBatchRow instance.

allow_item_discounts()

Returns boolean indicating whether per-item discounts are allowed when creating an order.

allow_item_discounts_if_on_sale()

Returns boolean indicating whether per-item discounts are allowed even when the item is already on sale.

allow_unknown_products()

Returns boolean indicating whether pending products are allowed when creating an order.

This is true by default, so user can enter new/unknown product when creating an order. This can be disabled, to force user to choose existing local/external product.

autocomplete_customers_external(session, term, user=None)

Return autocomplete search results for external customer records.

There is no default logic here; subclass must implement.

Parameters:

• session – Current app db session.

• term – Search term string from user input.

• user – User who is doing the search, if known.

Returns:

List of search results; each should be a dict with value and label keys.

autocomplete_customers_local(session, term, user=None)

Return autocomplete search results for LocalCustomer records.

Parameters:

• session – Current app db session.

• term – Search term string from user input.

• user – User who is doing the search, if known.

Returns:

List of search results; each should be a dict with value and label keys.

autocomplete_products_external(session, term, user=None)

Return autocomplete search results for external product records.

There is no default logic here; subclass must implement.

Parameters:

• session – Current app db session.

• term – Search term string from user input.

• user – User who is doing the search, if known.

Returns:

List of search results; each should be a dict with value and label keys.

autocomplete_products_local(session, term, user=None)

Return autocomplete search results for LocalProduct records.

Parameters:

• session – Current app db session.

• term – Search term string from user input.

• user – User who is doing the search, if known.

Returns:

List of search results; each should be a dict with value and label keys.

do_delete(batch, user, **kwargs)

Delete a batch completely.

If the batch has pending customer or pending product records, they are also deleted - unless still referenced by some order(s).

execute(batch, user=None, progress=None, **kwargs)

Execute the batch; this should make a proper order.

By default, this will call:

• make_local_customer()

• process_pending_products()

• make_new_order()

And will return the new Order instance.

Note that callers should use do_execute() instead, which calls this method automatically.

get_default_item_discount()

Returns the default item discount percentage, e.g. 15.

Return type:

Decimal or None

get_default_store_id()

Returns the configured default value for store_id, or None.

get_default_uom_choices()

Returns a list of ordering UOM choices which should be presented to the user by default.

The built-in logic here will return everything from ORDER_UOM.

Returns:

List of dicts, each with key and value corresponding to the UOM code and label, respectively.

get_effective_rows(batch)

Only rows with STATUS_OK are “effective” - i.e. rows with other status codes will not be created as proper order items.

get_past_orders(batch)

Retrieve a (possibly empty) list of past orders for the batch customer.

This is called by get_past_products().

Parameters:

batch – NewOrderBatch instance.

Returns:

List of Order records.

get_past_products(batch, user=None)

Retrieve a (possibly empty) list of products which have been previously ordered by the batch customer.

Note that this does not return order items, nor does it return true product records, but rather it returns a list of dicts. Each will have product info but will not have order quantity etc.

This method calls get_past_orders() and then iterates through each order item therein. Any duplicated products encountered will be skipped, so the final list contains unique products.

Each dict in the result is obtained by calling one of:

• normalize_local_product()

• get_product_info_external()

Parameters:

• batch – NewOrderBatch instance.

• user – User who is performing the action, if known.

Returns:

List of product info dicts.

get_product_info_external(session, product_id, user=None)

Returns basic info for an external product as pertains to ordering.

When user has located a product via search, and must then choose order quantity and UOM based on case size, pricing etc., this method is called to retrieve the product info.

There is no default logic here; subclass must implement. See also get_product_info_local().

Parameters:

• session – Current app db session.

• product_id – Product ID string for which to retrieve info.

• user – User who is performing the action, if known.

Returns:

Dict of product info. Should raise error instead of returning None if product not found.

This method should only be called after a product has been identified via autocomplete/search lookup; therefore the product_id should be valid, and the caller can expect this method to always return a dict. If for some reason the product cannot be found here, an error should be raised.

The dict should contain as much product info as is available and needed; if some are missing it should not cause too much trouble in the app. Here is a basic example:

def get_product_info_external(self, session, product_id, user=None):
    ext_model = get_external_model()
    ext_session = make_external_session()

    ext_product = ext_session.get(ext_model.Product, product_id)
    if not ext_product:
        ext_session.close()
        raise ValueError(f"external product not found: {product_id}")

    info = {
        'product_id': product_id,
        'scancode': product.scancode,
        'brand_name': product.brand_name,
        'description': product.description,
        'size': product.size,
        'weighed': product.sold_by_weight,
        'special_order': False,
        'department_id': str(product.department_number),
        'department_name': product.department_name,
        'case_size': product.case_size,
        'unit_price_reg': product.unit_price_reg,
        'vendor_name': product.vendor_name,
        'vendor_item_code': product.vendor_item_code,
    }

    ext_session.close()
    return info

get_product_info_local(session, uuid, user=None)

Returns basic info for a local product as pertains to ordering.

When user has located a product via search, and must then choose order quantity and UOM based on case size, pricing etc., this method is called to retrieve the product info.

See get_product_info_external() for more explanation.

This method will locate the LocalProduct record, then (if found) it calls normalize_local_product() and returns the result.

Parameters:

• session – Current db session.

• uuid – UUID for the desired LocalProduct.

• user – User who is performing the action, if known.

Returns:

Dict of product info.

init_batch(batch, session=None, progress=None, **kwargs)

Initialize a new batch.

This sets the store_id, if the batch does not yet have one and a default is configured.

make_local_customer(batch)

If applicable, this converts the batch pending customer into a local customer.

This is called automatically from execute().

This logic will happen only if use_local_customers() returns true, and the batch has pending instead of local customer (so far).

It will create a new LocalCustomer record and populate it from the batch pending_customer. The latter is then deleted.

make_new_order(batch, rows, user=None, progress=None, **kwargs)

Create a new order from the batch data.

This is called automatically from execute().

Parameters:

• batch – NewOrderBatch instance.

• rows – List of effective rows for the batch, i.e. which rows should be converted to order items.

Returns:

Order instance.

model_class

alias of NewOrderBatch

normalize_local_product(product)

Returns a normalized dict of info for the given local product.

This is called by:

• get_product_info_local()

• get_past_products()

Parameters:

product – LocalProduct instance.

Returns:

Dict of product info.

The keys for this dict should essentially one-to-one for the product fields, with one exception:

• product_id will be set to the product UUID as string

process_pending_products(batch, rows)

Process any pending products which are present in the batch.

This is called automatically from execute().

If local products are used, this will convert the pending products to local products.

If external products are used, this will update the pending product records’ status to indicate they are ready to be resolved.

refresh_batch_from_external_customer(batch)

Update customer-related attributes on the batch, from its external customer record.

This is called automatically from set_customer().

There is no default logic here; subclass must implement.

refresh_batch_from_local_customer(batch)

Update customer-related attributes on the batch, from its local_customer record.

This is called automatically from set_customer().

refresh_batch_from_pending_customer(batch)

Update customer-related attributes on the batch, from its pending_customer record.

This is called automatically from set_customer().

refresh_row(row)

Refresh data for the row. This is called when adding a new row to the batch, or anytime the row is updated (e.g. when changing order quantity).

This calls one of the following to update product-related attributes:

• refresh_row_from_external_product()

• refresh_row_from_local_product()

• refresh_row_from_pending_product()

It then re-calculates the row’s total_price and updates the batch accordingly.

It also sets the row status_code.

refresh_row_from_external_product(row)

Update product-related attributes on the row, from its external product record indicated by product_id.

This is called automatically from refresh_row().

There is no default logic here; subclass must implement as needed.

refresh_row_from_local_product(row)

Update product-related attributes on the row, from its local_product record.

This is called automatically from refresh_row().

refresh_row_from_pending_product(row)

Update product-related attributes on the row, from its pending_product record.

This is called automatically from refresh_row().

remove_row(row)

Remove a row from its batch.

This also will update the batch total_price accordingly.

set_customer(batch, customer_info, user=None)

Set/update customer info for the batch.

This will first set one of the following:

• customer_id

• local_customer

• pending_customer

Note that a new PendingCustomer record is created if necessary.

And then it will update customer-related attributes via one of:

• refresh_batch_from_external_customer()

• refresh_batch_from_local_customer()

• refresh_batch_from_pending_customer()

Note that customer_info may be None, which will cause customer attributes to be set to None also.

Parameters:

• batch – NewOrderBatch to update.

• customer_info – Customer ID string, or dict of PendingCustomer data, or None to clear the customer info.

• user – User who is performing the action. This is used to set created_by on the pending customer, if applicable. If not specified, the batch creator is assumed.

set_initial_item_status(item, user, **kwargs)

Set the initial status and attach event(s) for the given item.

This is called from make_new_order() for each item after it is added to the order.

Default logic will set status to ORDER_ITEM_STATUS_READY and attach 2 events:

• ORDER_ITEM_EVENT_INITIATED

• ORDER_ITEM_EVENT_READY

Parameters:

• item – OrderItem being added to the new order.

• user – User who is performing the action.

update_item(row, product_info, order_qty, order_uom, discount_percent=None, user=None)

Update an item/row, per given product and quantity.

See also add_item().

Parameters:

• row – NewOrderBatchRow to update.

• product_info – Product ID string, or dict of PendingProduct data.

• order_qty – New order_qty value for the row.

• order_uom – New order_uom value for the row.

• discount_percent – Sets the discount_percent for the row, if allowed.

• user – User who is performing the action. This is used to set created_by on the pending product, if applicable. If not specified, the batch creator is assumed.

use_local_customers()

Returns boolean indicating whether local customer accounts should be used. This is true by default, but may be false for external customer lookups.

use_local_products()

Returns boolean indicating whether local product records should be used. This is true by default, but may be false for external product lookups.

why_not_execute(batch, **kwargs)

By default this checks to ensure the batch has a customer with phone number, and at least one item. It also may check to ensure the store is assigned, if applicable.