.. poplar_arpricelist documentation master file, created by
   sphinx-quickstart on Thu Feb  6 18:32:20 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

AR Price Lists
==============

.. toctree::
   :hidden:
   :maxdepth: 2
   :caption: Contents:
   
   self
   proposal

.. contents:: Table of Contents

The AR Price List module enables Sage users to maintain custom
per Customer, per Item, pricing.  It does not require the IC or OE modules
for Sage's native price list functionality.

See it in action for the Sage sample data below. In this demo, a custom price
is created for Customer ``1200`` and Item ``BK-360``.  Instead of the default
price of $117.00, the price will be automatically set to $99.00 for all
invoices for customer 1200.

.. raw:: html

    <video width="640" controls>
      <source 
          src="https://s3.amazonaws.com/dev.expi/content/poplar_arpricelist/poplar_arpricelist_demo.mp4" 
          type="video/mp4">
      Your browser doesn't support the video tag.
    </video>

Installation
~~~~~~~~~~~~

Install the customization using the Customization Manager for Orchid
Extender.  Open the package manager and install the ``poplar_arpricelist``
package.

.. figure:: media/arpricelist_install_package.png
    :scale: 50%
    
    Installing the AR Price List package using the Python Package Manager.

Configuration
~~~~~~~~~~~~~

By default, the customization attaches to the Invoice Entry (``AR2100``) screen
when installed.  This will apply the custom pricing to all invoices entered 
through the Sage screen.

If invoices are input from other sources, such as import or EDI, a view script
is included that can be attached to the AR Invoice Details (``AR0033``) view. 
The view script will update the invoice line item pricing for invoices input
from other sources.

Take the following steps to connect the ``PPITMPRC.AR0033.py`` view script to
the ``AR0033`` view:

1. Open the Sage Desktop and navigate to Extender -> Setup -> View Events,
   Scripts, and WF.
2. Input View ID ``AR0033``.  The view name ``Invoice Details`` is displayed.
3. Select the Scripts tab.
4. Add a new entry.

   - Active: Yes
   - Run Order: <next available>
   - Name: ``PPITMPRC.AR0033.py``

5. Save the entry and close the window.

Restart the Sage Desktop.  The view script is now enabled.

.. figure:: media/arpricelist_view_script_config.png
    :scale: 50%
    
    The ``PPITMPRC.AR0033.py`` script has been attached to the AR0033
    view and is set Active.

Adding New Prices
~~~~~~~~~~~~~~~~~

New prices can be added manually or imported.

Manually Adding Prices
----------------------

Prices can be added manually using the Extender Custom Table Editor.
Take the following steps to add or manage a custom price:

1. Open the Sage Desktop and navigate to Extender -> Setup -> Custom Table
   Editor
2. Select the ``AR Price Lists`` table.
3. Input or select a Customer using the finder. If the customer number is valid
   the customer short name is displayed.
4. Input or select an Item using the finder. If the item number is valid
   the item description is displayed.
5. Input a custom price.
6. Save or add the record.

.. figure:: media/arpricelist_price_input.png
    :scale: 50%
    
    Setting a custom price of $99.00 for the Swivel Mount when sold to
    Ronald Black.

Importing Prices
----------------

The Extender Custom Table Editor can import custom price values from many
different file types.  This example will use a CSV file that can be read by
Excel as it is easy to render as text.  The same steps apply regardless of
format.

To create a price list import file, create a new file with the following 
three columns in order:

1. Customer ID (IDCUST) - String
2. AR Item ID (IDITEM) - String
3. Price (PRICE) - Decimal

A file that updates the price list to add a custom price of $100 for item
``BK-360`` when sold to customer ``1200``::

    "IDCUST","IDITEM","PRICE"
    "1200","BK-360",100.00

To import the file, use the Extender Custom Table screen:

1. Open the Sage Desktop and navigate to Extender -> Setup -> Custom Tables.
2. In the custom table screen, select the table named ``PPITMPRC.PPITMPRC``.
3. From the ``File`` menu, select ``Import Records``.
4. Set the import options:

   - Type: ``Single CSV File``
   - Title Record: ``True``
   - File: <select file to import>

5. Once the import dialog indicates that it is ready, import the
   prices.

.. figure:: media/arpricelist_import.png
    :scale: 50%
    
    The import handler has identified the columns in the input and
    is ready to import.

Exporting Prices
----------------

The Extender Custom Table Editor can export custom price values to many
different file types.  This example will use a CSV file that can be read by
Excel as it is easy to render as text.  The same steps apply regardless of
format.

Extender will export the price list with the following three columns:

1. Customer ID (IDCUST) - String
2. AR Item ID (IDITEM) - String
3. Price (PRICE) - Decimal

An export for custom pricing of $100 for item
``BK-360`` when sold to customer ``1200``::

    "IDCUST","IDITEM","PRICE"
    "1200","BK-360",100.00

To export the file, use the Extender Custom Table screen:

1. Open the Sage Desktop and navigate to Extender -> Setup -> Custom Tables.
2. In the custom table screen, select the table named ``PPITMPRC.PPITMPRC``.
3. From the ``File`` menu, select ``Export Records``.
4. Set the export options:

   - Type: ``Single CSV File``
   - File: <select file to export>
   - Criteria: Optionally filter the output for a specific customer or item

5. Once the export dialog indicates that it is ready, export the
   prices.

.. figure:: media/arpricelist_export_filter.png
    :scale: 50%
    
    A sample export filter that will generate a custom price list
    for Ronald Black.