Administrator guide
For the person who installs, configures, and supports the product.
Requirements
| Component | Requirement |
|---|---|
| Fishbowl | 2026.10 or later |
| Plugin | ILC CloudPages plugin |
| Custom fields | One for the area per box and one for the boxes per pallet, on Part or on Product. The Settings dialog can create them. |
| Unit of measure | Each product sold by area uses a unit of measure in the unit the page is set to: square meters or square feet. |
| Access right | Create Sales Order, for a user who adds lines |
The page reads with SQL and writes through the Fishbowl API. It needs no other server component.
Installation
Installation is the same for every ILC catalog page. For the full steps, see https://ilcreports.com/how-to#install.
- Buy the page on ilcreports.com.
- Install the CloudPages plugin in Fishbowl.
- Configure CloudPages with the manifest URL from the purchase.
- Confirm that the purchased pages appear in the installation.
- Grant page access to the users who need it.
Verify. Open a saved sales order. Click Sell by Area in its toolbar. Click ? to run the guided tour. The tour changes nothing in Fishbowl.
To configure the page, see Settings.
Updates
Updates are the same for every ILC catalog page.
A customer gets the latest stable version of a page by default. To stay on a previous version, or to return to one, choose the version in the ilcreports.com portal.
Fishbowl keeps its own data through an update. The plugin data in Fishbowl holds the access rights, the module placement, and the page settings. This data also survives a page removal.
For what changed in each version, see the release notes.
Security
The page reads two access rights.
| Right | What it changes |
|---|---|
| Create Sales Order | A user without it meets a disabled Add product and a disabled Review and update. The page then only shows the order's lines. |
| Administration | A user without it cannot open the Settings dialog. The page shows "Settings are open to an administrator only." |
This check hides a control. It does not enforce access. The page asks the Fishbowl client whether the user holds the right, and the client answers from credentials it already has. Treat the result as visibility.
Two facts follow from how the client answers.
- A user named admin passes every right check. Do not test this page's gating with the admin account.
- If the Fishbowl subscription lapses, every right that is not a view right returns false. The admin account loses access too.
Who to grant access to. A user who can open the page can read the lines of the open sales order, every active product with its list price and its available stock, and the custom field names on Part and Product. A query through the bridge is not right-checked. Grant page access to the people who take orders for products sold by area: counter staff and inside sales.
Considerations
The page adds lines to a sales order. It never changes or deletes a line that is already on the order.
Every added line takes the sales order's own tax code and class, not the product's defaults. Its price is the one Fishbowl quotes for this customer at the line quantity, written on the line explicitly.
Create a custom field in the Settings dialog creates a Text custom field on Part or Product through the Fishbowl import. It creates nothing else, and it changes no existing field.
Data handling
Every query and API call the page makes:
| Operation | Against | Right checked |
|---|---|---|
| Query | so, customer, taxrate, qbclass: the order number, customer, tax code, and class | None |
| Query | soitem, product, part, uom: the order's standard lines, with the two custom fields | None |
| Query | product, part, qtyinventorytotals, uomconversion: the active products and their available stock, when Add a product opens | Create Sales Order |
| Query | customfield: the field lists in Settings | Administration |
API ProductPriceRq | The customer's price at the area typed | Create Sales Order |
API AddSOItemRq | One call for each staged line | Create Sales Order |
Import ImportCustomFields | One field, from Create a custom field | Administration |
| Plugin data read | SellByAreaPage, for the settings | None |
| Plugin data write | SellByAreaPage, from the Settings dialog | Administration |
The page sends one AddSOItemRq for each line. One line failing does not stop the others. Fishbowl reports a refusal inside its answer, not as an error: the page reads the status code, marks the line failed, and shows Fishbowl's message.
The custom field import reports success whether or not it created the field. The page reads the field list back, and reports a failure when the field is not there.
What leaves the Fishbowl client. The failed lines, when a user clicks Save the failures. That is a CSV file of the number, description, boxes, quantity, and reason for each failed line. The user chooses where to save it. Nothing else leaves the client, and the page sends nothing to ILC.
Settings
An administrator sets these in the Settings dialog, the gear. They apply to every user of the page. The page works before anybody changes a setting.
| Setting | Default | What changes |
|---|---|---|
| Row height | Medium | The height of the grid rows: Compact, Small, Medium, or Large. |
| Unit of area | Square metres (m²) | The unit the page shows and writes. Square feet (ft²) is the other choice. |
| Area per box | Part field m2 Per Box | The custom field that holds the area one box covers. |
| Boxes per pallet | Part field Boxes Per Pallet | The custom field that holds the boxes in one pallet. |
If Area per box is still on its default, a change of unit moves it with the unit: ft² reads Part field sqft Per Box, and m² reads m2 Per Box. A field an administrator chose stays as chosen.
A field that was chosen and later deleted or made inactive stays in the list, marked "missing". The page then counts every box as one unit of area.
The theme control in the page header switches light and dark for the user who clicks it. The page otherwise follows the theme of the Fishbowl client.
A badge in the page header reads Demo when the page reaches no Fishbowl. Connected to Fishbowl, the page shows no badge, because that is the normal state.
These values are fixed and no one can change them:
| Limit | Value |
|---|---|
| Rounding | Up, to a whole box. |
| Line quantity | Boxes times the area per box, to two decimal places, in the product's unit of measure. |
| Line note | Total Cartons = and the box count. |
| Blank box size | A blank or missing area per box counts as 1. A blank boxes per pallet counts as 1. |
| Lines shown | Standard sales lines only. Other line types are not listed. |
| Products listed | Active products whose part is an inventory part. |
| Available | On hand less allocated and not available, across every location, in the product's unit of measure. |
| Unit conversion | None. The page writes the number in the unit it is set to. |
| Window | 1100 by 700 pixels |
Change where the page appears in the CloudPages plugin page Edit dialog:
| Placement | Default |
|---|---|
| Path | Apps:ILC Products |
| Modules | Sales Order |
| Toolbar button | Sell by Area |
Troubleshooting
The page says to open a sales order first
- Symptom: The page shows "Open a sales order first." and no grid.
- Cause: The page opened with no saved sales order behind it. A new order that is not saved yet has no number.
- Fix: Save the order. Then click Sell by Area in the sales order toolbar.
Add product and Review and update are disabled
- Symptom: Both controls are grayed out. Their message names the Create Sales Order access right.
- Cause: The user does not hold Create Sales Order.
- Fix: Grant the right to a user group the user belongs to.
Every product shows one unit of area per box
- Symptom: The per box column reads 1 for products that have a box size.
- Cause: The Settings dialog points at a different field, or at a field that is marked "missing". Or the field on the product is blank.
- Fix: Open the gear and check Area per box. Then fill in the field on the part or product.
The line quantity is more than the user typed
- Symptom: 45 was typed, and the line says 46.08.
- Cause: The page rounds up to whole boxes, and writes the area those boxes cover.
- Fix: None. This behavior is expected.
The line quantity is in the wrong unit
- Symptom: A line holds a number of square feet against a product sold in square meters, or the reverse.
- Cause: The page is set to one unit, and the product's unit of measure is the other. The page does not convert.
- Fix: Set Unit of area to the unit the products are sold in. Correct the line on the sales order.
A product is missing from Add a product
- Symptom: A product does not appear in the list.
- Cause: The product is inactive, or its part is not an inventory part.
- Fix: None for a product that is not an inventory part. Activate an inactive product in Fishbowl.
The price differs from the product's price
- Symptom: The calculator price is lower or higher than the list price.
- Cause: A pricing rule for this customer applies. The page asks Fishbowl for this customer's price at the area typed, so a quantity break moves the price as the area grows.
- Fix: None. This behavior is expected.
Available does not match the order's location
- Symptom: Available in Add a product is more than one warehouse holds.
- Cause: The page adds stock across every location.
- Fix: None. This behavior is expected.
A line failed to write
- Symptom: The Result window marks a line red.
- Cause: Fishbowl refused the line. The Reason column holds Fishbowl's message.
- Fix: Act on the message. Click Save the failures to keep a copy, then stage the line again.
Create a custom field reports a failure
- Symptom: "Fishbowl reported success but the field is not there."
- Cause: The import ran, and the field did not appear in the field list.
- Fix: Create the field in Fishbowl's Custom Fields module. Then choose it in the Settings dialog.
Before a support request
When a line fails, click Save the failures in the Result window. The file names each failed line and Fishbowl's reason.
Collect:
- The Fishbowl version and the page version.
- The sales order number.
- The failures file, when a line failed.
- The Settings dialog, as a screenshot: the unit and the two fields.
- The browser console output.
- A screenshot of the page.