workarea 3.4.12

data/docs/source/articles/installing.html.md

@@ -0,0 +1,61 @@
+---
+title: Installing
+created_at: 2019/05/29
+excerpt: A guide on the Workarea install script.
+---
+
+# Installing
+
+Workarea is a large Rails engine that requires a few things out of a Rails app it's installed into. This guide will walk you through the details of running `bin/rails generate workarea:install` so you know what changes are being made and why.
+
+### `application.rb`
+
+First, this will require the Workarea gems in your `config/application.rb` file. This is done to ensure Workarea can control the environment your application is run in for the purposes of testing and rake tasks.
+
+### `routes.rb`
+
+The install generator will mount the three main engines that workarea is built on within your `config/routes.rb` file.
+
+```ruby
+Rails.application.routes.draw do
+  mount Workarea::Core::Engine => '/'
+  mount Workarea::Admin::Engine => '/admin', as: 'admin'
+  mount Workarea::Storefront::Engine => '/', as: 'storefront'
+end
+```
+
+### `workarea.rb`
+
+An initializer will be created at `config/initializers/workarea.rb`. This serves that the main location for modifying configuration for Workarea. The generator will add some default information based on the name of your application such as `site_name`, `host`, `email_from`, and `email_to`. These serve as critical pieces of information for Workarea to know in order to start the application. Be sure to address the `TODO`s in the file and add the correct production information before deploying to a live environment.
+
+### `development.rb`
+
+Workarea relies on [Sidekiq](https://github.com/mperham/sidekiq) for running background jobs. For development, the install generator will add the following line of code to your `config/environments/development.rb` to alleviate the need for sidekiq to be running while in development.
+
+```ruby
+require 'sidekiq/testing/inline'
+```
+
+This tells sidekiq to run workers in process while working locally.
+
+### `puma.rb`
+
+Workarea provides puma configuration out of the box, and the install generator will replace the default rails-generated `config/puma.rb` with the following:
+
+```ruby
+require 'workarea/configuration/puma'
+Workarea::Configuration::Puma.load(self)
+```
+This configuration class allows for customizing the puma configuration through environment variables, eliminating the need to add custom configuration files for each environment.
+
+### `test_helper.rb`
+
+Workarea provides robust [testing configuration](testing.html) for consistent and easy testing. The install generator will add `require workarea/test_help.rb` to your existing `test/test_helper.rb` file.
+
+### `favicon.ico`
+
+Workarea provides [favicon support](favicon-support.html) through content assets within the admin UI. As a result, the install generator removes the `public/favicon.ico` file generated with a new rails application so that it does not interfere with that functionality.
+
+### `seeds.rb`
+
+Workarea provides a large set of [seed data](seeds.html) to get your application started. The install generator adds the `db/seeds.rb` file so that you can run seeds like any other rails application.

data/docs/source/articles/integrate-a-payment-gateway.html.md

@@ -0,0 +1,124 @@
+---
+title: Integrate a Payment Gateway
+excerpt: Workarea uses the ActiveMerchant gem for integration with payment gateways. This gem consolidates gateway functionalities under a common interface.
+---
+
+# Integrate a Payment Gateway
+
+Workarea uses the ActiveMerchant gem for integration with payment gateways. This gem consolidates gateway functionalities under a common interface.
+
+**Note:** Different gateways offer different functionality under different names!
+
+Because of the variance in payment gateways, you will probably need to tailor your installation to the gateway. Fortunately, Workarea consolidates gateway knowledge into the `Workarea::Payment::StoreCreditCard` class. This class is responsible for representing a credit card on the gateway. On that class is a single method the system uses to save it on the gateway (get a token to use to reference the card from now on).
+
+**Note:** The Workarea platform out-of-the-box requires a gateway that supports tokenization! This is done for security. Please ensure your gateway supports this functionality.
+
+Here is the out of the box implementation of saving the card on the gateway, presented for reference. The `#save!` method is called when the system needs to persist a credit card to be referenced later.
+
+workarea-core/app/models/workarea/payment/store\_credit\_card.rb :
+
+```
+module Workarea
+  class Payment
+    class StoreCreditCard
+      include CreditCardOperation
+
+      def initialize(credit_card, options = {})
+        @credit_card = credit_card
+        @options = options
+      end
+
+      def perform!
+        return true if @credit_card.token.present?
+
+        response = handle_active_merchant_errors do
+          gateway.store(@credit_card.to_active_merchant)
+        end
+
+        @credit_card.token = response.params['billingid']
+      end
+
+      def save!
+        perform!
+        @credit_card.save
+      end
+    end
+  end
+end
+```
+
+Error handling for all communication to the gateway is consolidated within a single module, and then included for all operations to ensure consistent handling of possible errors. You see this in action with the call to `#handle_active_merchant_errors` above. The full implmentation is below for reference.
+
+workarea-core/app/models/workarea/payment/credit\_card\_operation.rb :
+
+```
+module Workarea
+  class Payment
+    module CreditCardOperation
+      def handle_active_merchant_errors
+        begin
+          yield
+        rescue ActiveMerchant::ResponseError => error
+          error.response
+        rescue ActiveMerchant::ActiveMerchantError,
+                ActiveMerchant::ConnectionError => error
+          ActiveMerchant::Billing::Response.new(false, nil)
+        end
+      end
+
+      def gateway
+        Workarea.config.gateways.credit_card
+      end
+    end
+  end
+end
+```
+
+After customizing these classes, you may need to customize how this token is used with the gateway. There are a number of places for this:
+
+- `Workarea::Payment::Authorize::CreditCard`
+- `Workarea::Payment::Capture::CreditCard`
+- `Workarea::Payment::Purchase::CreditCard`
+- `Workarea::Payment::Refund::CreditCard`
+
+Each of these responds to the `#complete!` method, which should implement performing the respective operation on the gateway. Out of the box implementation for purchase:
+
+workarea-core/app/models/workarea/purchase/credit\_card.rb :
+
+```
+module Workarea
+  class Payment
+    module Purchase
+      class CreditCard
+        include OperationImplementation
+        include CreditCardOperation
+
+        def complete!
+          # Some gateways will tokenize in the same request as the auth/capture.
+          # If that is the case for the gateway you are implementing, omit the
+          # following line, and save the token on the tender after doing the
+          # gateway authorization.
+          return unless StoreCreditCard.new(tender, options).save!
+
+          transaction.response = handle_active_merchant_errors do
+            gateway.purchase(
+              transaction.amount.cents,
+              tender.to_active_merchant
+            )
+          end
+        end
+
+        def cancel!
+          return unless transaction.success?
+
+          transaction.cancellation = handle_active_merchant_errors do
+            gateway.void(transaction.response.params['authorization'])
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+

data/docs/source/articles/integrate-a-web-analytics-provider.html.md

@@ -0,0 +1,35 @@
+---
+title: Integrate a Web Analytics Provider
+excerpt: Workarea analytics adapters are responsible for registering callbacks for events and in turn sending the correctly formatted data and events to the third party.
+---
+
+# Integrate a Web Analytics Provider
+
+[Workarea analytics](analytics-overview.html) adapters are responsible for registering callbacks for events and in turn sending the correctly formatted data and events to the third party.
+
+## Example Adapter
+
+The easiest way to understand how an adapter is implemented is to look at an example. The Workarea platform includes an official Google Analytics plugin, which acts as a Workarea analytics adapter for Google Analytics. Unpack the gem to view its source.
+
+```bash
+gem unpack workarea-google_analytics
+```
+
+## Adapter Template
+
+Below is a commented template for an analytics adapter.
+
+```javascript
+// pass a function that will be invoked by the analtyics framework
+WORKAREA.analytics.registerAdapter('myNewAdapter', function () {
+    // private methods may be included here
+    // return a hash of callbacks for analytics events
+    return {
+        'pageView': function () { /* pageView calls do not have a payload */ },
+        'categoryView': function (payload) { /* send payload */ },
+        'searchResultsView': function (payload) { /* send payload */ }
+        // ...
+    };
+});
+```
+

data/docs/source/articles/integrate-an-inventory-management-system.html.md

@@ -0,0 +1,88 @@
+---
+title: Integrate an Inventory Management System
+excerpt: Procedures for integrating Workarea with an external inventory system of record
+---
+
+Integrate an Inventory Management System
+======================================================================
+
+Workarea provides an inventory system that satisfies the needs of many retailers.
+However, some retailers prefer to manage their inventory in another system, usually an enterprise resource planner (ERP).
+
+In this case, you will need to integrate Workarea with the external system to keep their inventory data in sync, which is the subject of this document.
+To integrate inventory from an ERP, you must routinely update Workarea's inventory SKUs with data from the authoritative inventory system, specifically the fields `:available` and `:backordered`.
+Furthermore, you may need to report to the external system any changes that Workarea makes to these fields, which are recorded in inventory transactions.
+
+This document additionally provides general advice for integrating Workarea with another system (of any type).
+
+
+Update Inventory SKUs within Workarea
+----------------------------------------------------------------------
+
+Within Workarea, each item's inventory is represented by an inventory SKU, which is identified by the item's SKU.
+( See [Inventory: Inventory SKUs](inventory.html#inventory-skus_2). )
+Several administrable fields, primarily the integer fields `:available` and `:backordered`, represent the "raw" inventory data tracked by Workarea.
+( See [Inventory: Administrable Fields & Policies](inventory.html#administrable-fields-amp-policies_3). )
+
+You must design a strategy for keeping these fields in sync with the corresponding data from the external inventory system.
+__Maintaining accurate values for these fields is the core of this integration.__
+Refer to "General Tips for System Integration" below for further advice on this matter.
+
+
+Report Workarea's Inventory Transactions
+----------------------------------------------------------------------
+
+Workarea also makes its own changes to the inventory SKU values `:available` and `:backordered` when shoppers place and cancel orders.
+( See [Inventory: Purchasing, Capturing & Releasing Inventory](inventory.html#purchasing-capturing-amp-releasing-inventory_14). )
+You therefore may need to report these changes to the system you are integrating.
+( This may not be necessary if the external system manages these changes, perhaps during fulfillment rather than at the point of sale. )
+
+Whenever Workarea captures and frees inventory in this manner, it records details of the changes as an `Inventory::Transaction` specific to the order.
+Each inventory transaction is related to an order via its `:order_id` field.
+Whenever Workarea performs a capture, rollbak, or restock operation on inventory, its affects are recorded on the inventory transaction document, and its `:updated_at` timestamp is refreshed.
+Additionally, you can query whether a transaction's inventory has been captured by examining its boolean `:captured` field.
+
+Inventory transactions are indexed by `:updated_at` and `:captured`, facilitating queries for "captured transactions updated after _date_":
+
+```ruby
+# find inventory transactions updated after Midnight
+
+Workarea::Inventory::Transaction.where(
+  :updated_at.gt => Time.current.beginning_of_day,
+  captured: true
+)
+```
+
+You can use such a query to fetch the transactions that were updated since your last such query, enabling you to prepare ad-hoc reports to send to the partnering system.
+Each inventory transaction embeds a collection of `Inventory::TransactionItem` documents, one document per corresponding `Order::Item`.
+Each transaction item has the fields `:sku`, `:available`, and `:backordered`, where `:available` and `:backordered` indicate the number of units captured.
+You or the ERP can fetch and share this data routinely to keep the external system in sync with Workarea's inventory changes.
+
+
+General Tips for System Integration
+----------------------------------------------------------------------
+
+Until Workarea provides general-purpose documentation for system integration, a brief summary of the process is described here.
+
+
+### Determine Responsibilities
+
+An integration involves two systems and two teams, so you must determine who is responsible for what.
+Work with the partnering team to determine the following:
+
+* Who is pushing or pulling data?
+* According to what schedule or in response to what events?
+* Who is responsible for transforming the data to/from the opposing data format?
+* When updating, are you updating all the records, or only those that have changed since the last update?
+* And who is responsible for determining which records have changed since the last update?
+
+
+### Build the Integration
+
+Next, build the parts of the integration for which you are responsible.
+Tools for this within the Workarea system include:
+
+* [Admin API](https://plugins.workarea.com/plugins/api-admin)
+* [Callbacks workers](workers.html#callbacks-worker_7)
+* [Scheduled workers](workers.html#sidekiq-cron-job_5)
+* [Data file scheduling](https://plugins.workarea.com/plugins/data-file-scheduling)

data/docs/source/articles/integrating-with-other-software.html.md

@@ -0,0 +1,59 @@
+---
+title: Integrating with Other Software
+excerpt: Overview of a developer's options for integrating Workarea with third-party software.
+---
+
+# Integrating with Other Software
+
+Integrating with other systems is one of the toughest parts of a large-scale ecommerce site build. Whether it's an ESP, a crusty old mainframe system, or a homegrown CRM, Workarea has many options to help. Picking between these depends on the needs, capabilities, and people of the system you're integrating with, so below you'll find the major options outlined.
+
+## Plugins
+
+The easiest option for integration is a plugin already built by the Workarea team or the community. A typical install means adding the gem to the project's `Gemfile` and configuring some credentials. You'll want to check the README on the plugin for details.
+
+To see a list of available open-source integration plugins, check out the Workarea [Github repositories](https://github.com/workarea-commerce). For more info on how plugins work (including how to write your own), see the [plugins overview](plugins-overview.html).
+
+## API
+
+The admin API offers the minimum amount of work on the Workarea side for the integration. Through the API, you can get and/or update all the major resources in the Workarea system. This is a great option if you have the cooperation of developers on the other end - they can write calls to the API as needed.
+
+See the [API overview](api-overview.html) for more info, or jump into the deep end with [the API documentation](https://demo.workarea.com/api/docs).
+
+## Webhooks
+
+Webhooks are an option where Workarea will call out to a provided URL with a payload when a particular event (e.g. an order gets placed or a customer account is created) occurs. The payload will contain data related to the event. This is nearer to real-time than the other out-of-the-box options. Like API integration, choosing webhooks is good when you have the cooperation of developers on the other end. Someone will have to setup the desired events/URLs in the admin.
+
+See the [Webhooks plugin](https://github.com/workarea-commerce/workarea-webhooks) for more info.
+
+## Scheduled Data Files
+
+Scheduling data file transfers is a more old-fashioned, but still automated option for integration. Great for overnight batched integrations with older systems that will need to ingest CSV files and the like. An administrator can specify what they want to import or export, how often and when. It supports S3, SFTP, or local file system as data stores.
+
+See the [Data File Scheduling plugin](https://github.com/workarea-commerce/workarea-data-file-scheduling) for more info.
+
+## Admin Import/Export
+
+All the major index pages in the admin (people, orders, products, etc) are available to import and export in multiple formats from the admin interface. The links appear in the workflow bar in the bottom left of those screens. The downside to this option is that everything must be completely manual.
+
+![Import/Export Screenshot](images/import-export-screenshot.png)
+
+## Custom Code
+
+The most manual, developer-involved option for integration with third party software is to write the code manually. Obviously this the most expensive/time-consuming of the options. The advantage however, is the integration can be built completely bespoke to the merchant's needs.
+
+
+### Scheduled Workers
+
+Scheduled workers are good for working in batches, for example exporting orders every hour. Workarea includes a gem for scheduling Sidekiq jobs called [sidekiq-cron](https://github.com/ondrejbartas/sidekiq-cron). As a super admin, you'll be able to monitor the status of these jobs in the Sidekiq admin at `/admin/sidekiq/cron`.
+
+See the [Sidekiq Cron Job section](workers.html#sidekiq-cron-job_5) of the [workers article](workers.html).
+
+### Callbacks Workers
+
+Another good asynchronous option is callbacks workers. Workarea adds an extension to Sidekiq worker functionality to allow automatically enqueueing Sidekiq workers based on customizable callbacks in models. This is good for doing individual calls to external systems as the events in Workarea happen. For example, when an email signup is created, run a Sidekiq worker to add that email to an ESP.
+
+See the [Sidekiq Callbacks section](workers.html#sidekiq-callbacks_11) of the [workers article](workers.html).
+
+### Inline
+
+This is least preferred option of all for this task, due to its fragility. It puts the stability of Workarea at the mercy of the other system. The basic idea is adding in the calls to the external software inline with the Workarea code. Examples would be putting calls to fraud checks in checkout controllers, or "real-time" inventory calls from product detail pages. The pattern you'll use to do this is called "decoration", you can read more about it in [our decorators article](decoration.html).

data/docs/source/articles/inventory.html.md

@@ -0,0 +1,352 @@
+---
+title: Inventory
+excerpt: Workarea includes an inventory subsystem providing inventory management and automated merchandising, which developers can extend
+---
+
+Inventory
+======================================================================
+
+Workarea includes an inventory subsystem providing inventory management and automated merchandising based on inventory levels and policies.
+This system is fully functional as it is, but developers may need to extend or operate the system to accomplish the following:
+
+* Integrate Workarea with a retailer's inventory management system
+* Define and configure inventory policies
+* Explain to a retailer how the inventory system works, including inventory management and inventory's effects on the shopping experience (for example, you may need to explain how an item's inventory is preventing a product from matching a search)
+
+To develop these skills, you'll need to know the following:
+
+* How retailers manage inventory within Workarea
+* How Workarea protects retailers by not overselling, while also maintaining the quality of the shopping experience for shoppers
+* How Workarea captures and releases inventory when shoppers place and cancel orders, which maintains inventory integrity
+
+This document therefore describes the Workarea inventory system, from management to reporting.
+
+A retailer manages __inventory SKUs__, each of which has __administrable fields__, including a __policy__, from which Workarea derives various __inventory SKU states__.
+Workarea uses these states to prevent overselling and to communicate availability when presenting searches, categories, recommendations, products, and carts.
+Finally, when shoppers place and cancel orders, Workarea __purchases__, __captures__, and __releases__ inventory, managing the same inventory fields as retailers.
+Workarea records these __inventory transactions__ for each order and also provides reports and insights to help a retailer restock inventory effectively.
+
+
+Inventory Management
+----------------------------------------------------------------------
+
+A retailer can manage inventory within Workarea directly or within a separate inventory management system that is integrated with Workarea.
+( Regarding the latter, see [Integrate an Inventory Management System](integrate-an-inventory-management-system.html). )
+In either case, the retailer manages inventory via several administrable fields on inventory SKUs.
+
+
+### Inventory SKUs
+
+An _inventory SKU_ is a MongoDB-backed model representing the inventory for an item in the retailer's catalog.
+Each inventory SKU is identified by the item's SKU, a retailer-specific ID that relates the inventory SKU to other models representing the same item within Workarea.
+( See [Products](products.html) for a more thorough explanation of the models that represent merchandise, and their relationships. )
+
+Administrators, developers, and automated systems manage inventory by manipulating several administrable fields on each inventory SKU, including the inventory SKU's policy.
+
+
+### Administrable Fields & Policies
+
+The following table describes the _administrable fields_ of each inventory SKU:
+
+| Field | Description |
+| ----- | ----------- |
+| `:available` | The integer count of units that are available except when reserved; defaults to `0` |
+| `:backordered` | The integer count of units that are available when backorder is allowed, except when reserved, defaults to `0` |
+| `:reserve` | The integer count of units to reserve from the collective pool of `available` and `backordered`; defaults to `0` |
+| `:backordered_until` | The `Time` at which backordered units are expected to move to available |
+| `:policy` | A string identifying one of the policies enumerated in `Workarea.config.inventory_policies`; defaults to the first policy in that configurable collection |
+
+The most important of these fields are the integer values `:available`, `:backordered` and `reserve`, and the `:policy`, which Workarea uses collectively to derive various inventory states, as explained in the following sections.
+
+
+Presenting Products & Carts
+----------------------------------------------------------------------
+
+While the retailer is responsible for setting the inventory values in the above fields, Workarea is responsible for honoring those values throughout the shopping experience.
+Workarea must prevent overselling to protect the retailer, and must also maintain the user experience for shoppers.
+To accomplish both goals, Workarea performs automatic merchandising which prevents shoppers from adding unavailable items to their carts, or may hide items from shoppers altogether while inventory is unavailable.
+This requires determining the displayability and purchasability of each item, based on its inventory.
+Workarea derives these states from the administrable fields on the inventory SKU.
+
+
+### Inventory Policies & SKU States
+
+Introduced above, an _inventory policy_ is a class of object that declares the logic for converting the administrable values of an inventory SKU into _inventory SKU states_.
+An inventory policy also declares the logic for purchasing a SKU's inventory, which is covered below.
+
+Workarea includes several inventory policies, and plugins and applications can define and configure their own policies.
+( For a more in-depth look at policy class definitions and configuration, see [Define & Configure Inventory Policies](define-and-configure-inventory-policies.html). )
+The following example enumerates the available policies:
+
+```ruby
+puts Workarea.config.inventory_policies
+# Workarea::Inventory::Policies::Ignore
+# Workarea::Inventory::Policies::Standard
+# Workarea::Inventory::Policies::DisplayableWhenOutOfStock
+# Workarea::Inventory::Policies::AllowBackorder
+```
+
+For each inventory SKU, workarea uses the SKU's policy and other values of its administrable fields to derive the following inventory SKU states:
+
+| State | Description |
+| ----- | ----------- |
+| `available_to_sell` | The computed integer count of available units, derived from `:available`, `:backordered`, and `reserve` by the policy |
+| `purchasable?(quantity)` | Whether the item is purchasable, determined by comparing the given quantity to `available_to_sell`; quantity defaults to `1` |
+| `displayable?` | Whether the item is displayable, as determined by the policy |
+| `backordered?` | Whether the item is backordered, which can be true only when the policy is `'allow_backorder'` |
+
+The following sections explain each inventory policy and its effects on these inventory SKU states.
+
+
+#### Standard
+
+The standard policy allows purchase only from the `:available` units, minus those in `:reserve`.
+An item is displayable if it is purchasable.
+
+```ruby
+# create an inventory SKU
+sku = 'WIZRDRPG-5ED'
+inventory_sku = Workarea::Inventory::Sku.create(
+                  _id: sku,
+                  policy: 'standard',
+                  available: 0,
+                  backordered: 3,
+                  reserve: 1
+                )
+
+# review the administrable values
+inventory_sku.available
+# => 0
+inventory_sku.backordered
+# => 3
+inventory_sku.reserve
+# => 1
+
+# there are none available to sell, because this policy
+# does not allow purchase from :backordered
+inventory_sku.available_to_sell
+# => 0
+
+# The item is therefore not purchasable and not displayable
+inventory_sku.purchasable?
+# => false
+inventory_sku.displayable?
+# => false
+
+# And it is not considered backordered
+inventory_sku.backordered?
+# => false
+```
+
+
+#### Allow Backorder
+
+When backorder is allowed, units from `:backordered` are additionally available for purchase, minus those in `:reserve`.
+
+```ruby
+# change the inventory SKU's policy and re-initialize it
+# (to clear the memoized policy object)
+inventory_sku.update_attribute(:policy, 'allow_backorder')
+inventory_sku = Workarea::Inventory::Sku.find(sku)
+
+# the administrable values haven't changed
+inventory_sku.available
+# => 0
+inventory_sku.backordered
+# => 3
+inventory_sku.reserve
+# => 1
+
+# But the item is now considered backordered
+inventory_sku.backordered?
+# => true
+
+# And there are units to sell
+inventory_sku.available_to_sell
+# => 2
+
+# Up to 2 units are purchasable; the 3rd is reserved
+inventory_sku.purchasable?
+# => true
+inventory_sku.purchasable?(2)
+# => true
+inventory_sku.purchasable?(3)
+# => false
+
+# And the item is displayable
+inventory_sku.displayable?
+# => true
+```
+
+
+#### Displayable When Out of Stock
+
+An item that is displayable when out of stock behaves like a standard item, except it remains displayable when not purchasable.
+
+```ruby
+# Change the policy and re-init the inventory SKU
+inventory_sku.update_attribute(:policy, 'displayable_when_out_of_stock')
+inventory_sku = Workarea::Inventory::Sku.find(sku)
+
+# No changes to the administrable values
+inventory_sku.available
+# => 0
+inventory_sku.backordered
+# => 3
+inventory_sku.reserve
+# => 1
+
+# This policy does not allow backorder
+inventory_sku.backordered?
+# => false
+
+# So there are therefore none to sell, and
+# the item is not purchasable
+inventory_sku.available_to_sell
+# => 0
+inventory_sku.purchasable?
+# => false
+
+# However, it is displayable
+inventory_sku.displayable?
+# => true
+```
+
+
+#### Ignore
+
+Ignoring inventory can be useful for intangible items, such as gift cards, that have effectively infinite inventory.
+A retailer may also use this policy if they are not concerned with tracking inventory within Workarea.
+This is the default inventory policy.
+
+```ruby
+# Change the policy and re-init the inventory SKU
+inventory_sku.update_attribute(:policy, 'ignore')
+inventory_sku = Workarea::Inventory::Sku.find(sku)
+
+# Administrable values are the same
+inventory_sku.available
+# => 0
+inventory_sku.backordered
+# => 3
+inventory_sku.reserve
+# => 1
+
+# The item is not backordered
+inventory_sku.backordered?
+# => false
+
+# But there are effectively infinite units available
+# (This value will not change, even as orders with this item are placed)
+inventory_sku.available_to_sell
+# => 99999
+
+# The item is therefore always purchasable and displayable
+inventory_sku.purchasable?
+# => true
+inventory_sku.displayable?
+# => true
+```
+
+
+### Searches, Categories & Recommendations
+
+Workarea presents the items of the retailer's catalog as [products](products.html), which are (generally small) collections of items that share a name, description, and some details, while varying on other details (such as color, size, etc).
+When a product document is indexed into Elasticsearch, it contains inventory information from all the items that make up the product.
+
+[Storefront search features](storefront-search-features.html), such as searches, categories, and product recommendations, take inventory into account when deciding which products match and how they are sorted in results.
+The inventory-related display logic can be summarized as follows:
+
+* To match a search or category, a product must have at least one displayable SKU
+* To match a query for search-based recommendations, a product must have at least one purchasable SKU
+* When sorted by relevance (as opposed to a user-defined sort), search and category results sort products with at least one purchasable SKU above those without a purchasable SKU (unless the product is featured; featured products sort to the top)
+
+Search features essentially re-implement the concepts of displayable and purchasable using inventory fields within product search documents and with queries defined with the Elasticsearch query DSL.
+__These determinations can therefore be "stale" relative to the current inventory values in MongoDB__.
+
+A retailer can use inventory policies to determine how products should appear in the results for search-based features.
+It may be desirable for an item to be included in results even when it is not purchasable, but Workarea will de-prioritize the product within the results.
+
+The purpose of these presentation rules is to prevent shoppers from adding to their cart items that are not purchasable, which would create a poor user experience for the shopper.
+
+
+### Products & Carts
+
+While searching and browsing products, a shopper will often select a specific product to view in detail.
+The product detail page (PDP), like the search features, reflects the inventory of the items that make up the product.
+
+A PDP presents product options that the shopper selects to narrow the product to a specific item to be added to the shopper's cart.
+The product options are derived from the details of the product's displayable SKUs, hence, retailers can use inventory policies to determine which options should display.
+For example, an item with only backordered inventory is considered displayable when the SKU's policy is `AllowBackorder`, but not when the policy is `Standard`.
+
+Furthermore, after narrowing to a specific item, the shopper can add the item to the cart only if it is purchasable.
+To continue the previous example, an item with only backordered inventory can be added to the cart only if its policy is `AllowBackorder` or `Ignore`.
+
+As with the search features, these rules on the PDP are intended to keep non-purchasable items out of shoppers carts.
+However, after a shopper adds an item to their cart, it can become non-purchasable if other shoppers purchase the remaining inventory first (or inventory changes due to inventory management).
+Workarea therefore checks inventory on most cart and checkout requests to ensure the items in the cart are still purchasable.
+If items become non-purchasable, Workarea removes them from the cart and notifies the shopper.
+
+
+### Inventory Status Messages
+
+To more directly communicate an item's availability to shoppers, Workarea displays _inventory status messages_ on the PDP and in the cart.
+The messages are per-item, so on the PDP a shopper must first narrow the product to a specific item before being shown the inventory status.
+
+The inventory status shown is one of the following:
+
+* In Stock
+* _Number_ Left
+* Ships on _Date_
+* Backordered
+* Out of Stock
+
+These messages are for display only, and their logic is therefore encapsulated in a [view model](view-models.html): `Storefront::InventoryStatusViewModel`.
+Review the implementation of that view model in your Workarea version to see the logic for each status.
+
+
+Placing & Canceling Orders
+----------------------------------------------------------------------
+
+You've seen above how Workarea prevents the sale of non-purchasable merchandise.
+However, as shoppers place orders, Workarea must maintain accurate inventory levels.
+Workarea uses inventory transactions to purchase and release inventory as users place and cancel orders.
+Furthermore, Workarea exposes these inventory changes in the Admin through reports and insights.
+
+
+### Purchasing, Capturing & Releasing Inventory
+
+To maintain accurate inventory within its boundaries, Workarea must _purchase_ the inventory for an order, according to the inventory policy of each SKU.
+
+Regardless of policy, the value of `:purchased` on the inventory SKU is incremented by the quantity purchased.
+This value tracks the number of units purchased since the creation of the inventory SKU.
+Additionally, the current computed value from `#available_to_sell` is persisted to the field `:sellable`, which is used for presenting a low inventory report.
+
+Depending on policy, units are _captured_ from `:available` and `:backordered`, as described in the following table:
+
+| Policy | Capture Logic |
+| ------ | ------------- |
+| `'standard'` | Purchased quantity is decremented from `:available` |
+| `'displayable_when_out_of_stock'` | Same as `'standard'`, from which it inherits |
+| `'allow_backorder'` | Purchased quantity is decremented first from `:available` (until exhausted) and then from `:backordered` |
+| `'ignore'` | Nothing is captured |
+
+If a shopper later cancels the order, Workarea must _release_ the inventory, which is the reverse of a capture and relies on the record of the purchase stored in the inventory transaction.
+
+
+### Inventory Transactions
+
+When an order is placed, the details of the inventory captured are recorded in an _inventory transaction_, a separate document (an `Inventory::Transaction`) which embeds an inventory transaction item for each corresponding order item.
+Inventory transactions are used to manage the capturing of inventory and to provide a permanent record of what was captured.
+They are also used in the event of a cancellation to free the appropriate amount of inventory.
+
+( Inventory transactions are also covered in [Integrate an Inventory Management System](integrate-an-inventory-management-system.html). )
+
+
+### Reports & Insights
+
+Because Workarea is modifying inventory counts, it must provide a means for retailers to stay informed of current inventory levels.
+In addition to the inventory SKU administration screens, Workarea provides two reports directly relevant to those responsible for restocking inventory: "Low Inventory" and "Sales by Product".
+A retailer can view and export these reports in the Admin.
+Insights based on these reports also appear within several Admin dashboards.
+Relying on these insights, retailers can effectively manage inventory levels, completing the inventory cycle explained in this document.