RubyGems - workarea - Versions diffs - 3.4.16 → 3.4.17 - Mend

workarea 3.4.16 → 3.4.17

Files changed (572) hide show

data/docs/source/articles/images-flow.html.md DELETED Viewed

@@ -1,10 +0,0 @@
----
-title: Images Flow
-excerpt: A diagram to illustrate how images (product images, content assets) flow into the system and how they are modified and presented to end users.
----
-# Images Flow
-The following diagram illustrates how images (product images, content assets) flow into the system and how they are modified and presented to end users.
-![Images Diagram](images/images.svg "View Larger")

data/docs/source/articles/index-storefront-search-documents.html.md DELETED Viewed

@@ -1,104 +0,0 @@
----
-title: Index Storefront Search Documents
-excerpt: This document provides procedures developers can use to manually index Storefront search documents.
----
-Index Storefront Search Documents
-================================================================================
-This document provides procedures developers can use to manually index Storefront search documents.
-These procedures are for _manually_ indexing search documents. However, most search indexing is _automatic_, as explained in [Search, Indexing](searching.html#indexing_7).
-See also [Storefront Search Features, Indexing](storefront-search-features.html#indexing_12) for an overview of Storefront search document creation and indexing.
-Index All Storefront Search Documents
---------------------------------------------------------------------------------
-Workarea's `search.rake` Rakefile provides a task for (re)indexing all Storefront search documents.
-Index all Storefront search documents from a shell session within the environment:
-```bash
-$ bin/rails workarea:search_index:storefront
-```
-Index all Storefront search documents within Ruby:
-```ruby
-Rake::Task['workarea:search_index:storefront'].invoke
-```
-The procedures above index documents _inline_ (i.e. in the foreground).
-Alternatively, set the environment variable `INLINE` to `false` before executing the task to perform the indexing with Sidekiq workers (i.e. in the background):
-```bash
-$ INLINE=false bin/rails workarea:search_index:all
-```
-Index Specific Storefront Search Documents
---------------------------------------------------------------------------------
-In some cases, you may need to index only specific Storefront search documents.
-The procedure for this varies for product and non-product search documents.
-### Non-Product Documents
-For non-product search documents (e.g. categories, pages, searches), initialize a Storefront search model and call `#save` to index the resulting search document.
-```ruby
-catalog_category = Workarea::Catalog::Category.first
-Search::Storefront::Category.new(catalog_category).save
-```
-See [Storefront Search Features, Search Models](storefront-search-features.html#search-models_13) for an explanation of Storefront search models.
-### Product Documents
-For product search documents, don't use a search model directly.
-Use any of the following API calls, which create the search model instances for you.
-(See [Workers](workers.html) for more details regarding the `perform` and `perform_async` methods.)
-* `Workarea::IndexProduct.perform(product)`
-* `Workarea::IndexProduct#perform(id)`
-* `Workarea::IndexProduct#perform_async(id)`
-* `Workarea::BulkIndexProducts.perform_by_models(products)`
-* `Workarea::BulkIndexProducts.perform(ids)`
-* `Workarea::BulkIndexProducts#perform(ids)`
-* `Workarea::BulkIndexProducts#perform_async(ids)`
-For example, index one product:
-```ruby
-catalog_product = Workarea::Catalog::Product.first
-Workarea::IndexProduct.perform(catalog_product)
-```
-Or, enqueue a background job to index 5 products in bulk (using only a single request to Elasticsearch):
-```ruby
-catalog_product_ids = Workarea::Catalog::Product.all.pluck('id').first(5)
-# => ["71C098FFD9", "9A7160EBF0", "2702316B04", "06C6FC0827", "0FA514641B"]
-Workarea::BulkIndexProducts.new.perform_async(catalog_product_ids)
-```
-Each of the API calls above provides two additional functions, which is why these calls are used instead of creating search models directly.
-First, calling any of the above methods sets `:last_indexed_at` on each of the affected models in MongoDB.
-Among other things, this timestamp is used by workers responsible for keeping indexes fresh.
-Second, for each product passed in, these methods create a collection of _product entries_ to represent the document within the Storefront search indexes.
-The product entries collection (an instance of `Search::ProductEntries` is a collection of search models, each of which produce a search document to be indexed.
-This allows more or fewer search documents to be indexed for each product.
-For example, with [Workarea Browse Option](https://github.com/workarea-commerce/workarea-browse-option) installed, a single MongoDB document may be represented by multiple search documents in each search index (e.g. one for each color of the product).
-In contrast, with [Workarea Package Products](https://github.com/workarea-commerce/workarea-package-products) installed, the child products of a package are not indexed at all (they produce an empty product entries collection).
-The product entries abstraction also allows a different search model to be used conditionally.
-For example, Workarea Browse Option extends product entries to use a different search model for those products that "browse by option".
-This search model uses only variants of the given option (e.g. blue) to construct the search model.
-Similarly, Workarea Package Products uses a different search model for "package" products.
-This search model includes details from the package's "child" products, which themselves are not indexed.

data/docs/source/articles/infrastructure.html.md DELETED Viewed

@@ -1,46 +0,0 @@
----
-title: Infrastructure
-excerpt: An overview of the required pieces of infrastructure for hosting Workarea.
----
-# Infrastructure
-This will be a brief overview of what you'll need to host a Workarea app on your own. Workarea is a hefty application which can be complex to run efficiently, so we recommend our [Workarea Commerce Cloud hosting](https://www.workarea.com/pages/commerce-cloud) for merchants who want to focus on their unique business problems.
-## Application
-### Web
-Workarea ships with a [default Puma configuration](https://github.com/workarea-commerce/workarea/blob/master/core/lib/workarea/configuration/puma.rb) out-of-the-box, which is the application server we recommend. Workarea is known to work with [Passenger](https://www.phusionpassenger.com), and will probably work with most any application server that supports Rails.
-### Sidekiq
-Workarea depends on [Sidekiq](https://sidekiq.org) for performing background work, so you'll need to have a Sidekiq daemon running along with the application server. Workarea will automatically configure Sidekiq based on its own configuration.
-## Databases
-### MongoDB
-Workarea uses on [MongoDB](https://www.mongodb.com), so you'll need a production-grade replica set. Currently, the latest version of Workarea supports MongoDB v4.0.x.
-### Elasticsearch
-Workarea uses [Elasticsearch](https://www.elastic.co/products/elasticsearch) for large portions of functionality. You'll want a production-grade cluster running version v5.6.x.
-### Redis
-Workarea uses [Redis](https://redis.io) for the Sidekiq queue, cache, Rack::Attack, and more. Note that while only one instance of Redis is _required_, we recommend running two. The first would be for persistent data like the Sidekiq queue or recommendations. The second is for ephemeral data like cache.
-## Miscellaneous
-### Assets
-Currently, Workarea depends on [Amazon's S3](https://aws.amazon.com/s3/) to back its asset storage. You'll need at least one bucket setup to run Workarea. An optional second (called the "integration" bucket in the code) can be configured for integrating with other systems, like flat-file exports, image imports, etc.
-### Geolocation
-Workarea provides a number of geography-based features. For these features to function, you have two options. The first (very slow) way is to configure the [Geocoder gem](https://github.com/alexreisner/geocoder) that Workarea uses to look up request location by IP address. The second, preferred way is to integrate an upstream proxy like [nginx](http://nginx.org) to lookup geography data based on IP address and add headers, which the Workarea application will read. See [the ngx_http_geoip_module](http://nginx.org/en/docs/http/ngx_http_geoip_module.html) for an example.
-### Compliance
-This is just dropping you a note that the Workarea application is written to be compliant with PCI-DSS requirements. Workarea Commerce Cloud hosting provides a complete top-to-bottom certified, tier 1, PCI-DSS environment. This is recommended for all merchants.

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

@@ -1,61 +0,0 @@
----
-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 DELETED Viewed

@@ -1,124 +0,0 @@
----
-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 DELETED Viewed

@@ -1,35 +0,0 @@
----
-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 DELETED Viewed

@@ -1,88 +0,0 @@
----
-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 DELETED Viewed

@@ -1,59 +0,0 @@
----
-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).