Administrator guide

For the person who installs, configures, and supports the product.

Requirements

ComponentRequirement
Fishbowl2024.x or later. The page reads the sales order import, which every supported release has.
PluginILC CloudPages plugin

Installation

Installation is the same for every ILC catalog page. For the full steps, see TBD (public documentation URL).

  1. Buy the page on ilcreports.com.
  2. Install the CloudPages plugin in Fishbowl.
  3. Configure CloudPages with the manifest URL from the purchase.
  4. Confirm that the purchased pages appear in the installation.
  5. Grant page access to the users who need it.

Verify. Open the page and choose How importing works from the ? menu. The tour opens a sample file, shows an order that cannot be imported and the order detail, and stops at the Import button. It writes nothing to Fishbowl.

A second tour, Building a mapping, walks the wizard from an open file to the Save step without saving anything. It is the quickest way to see what a mapping involves.

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 Fishbowl access rights:

RightWhat changes
ViewSalesOrderWithout it, the Preview control is disabled and says which right it needs.
AdministrationWithout it, the gear control reports that only an administrator changes settings.

The page needs one more right that it does not check. Fishbowl checks it:

RightWhy
CreateSalesOrderThe import refuses the write without it.

Who to grant access to. A user who can open the page reads every customer, every product, and every sales order. The page queries those tables directly through the plugin bridge. Grant page access to order entry and customer service staff. Do not grant it to a user who must not see customer pricing.

Considerations

The page writes sales orders under the identity of the logged in Fishbowl user. In the audit trail, an imported order looks the same as a typed one. The page can record the source file as a memo on the order, which is the one mark that tells them apart.

The page reads and writes one plugin data entry. It holds the mappings and the settings, and no order data.

Data handling

Every query and API call the page makes:

OperationAgainstRight checked
Querycustomer, address, stateconst, countryconst, to match the customer and its addressesNone
Querycarrier, taxrate, priority, sysuser, paymentterms, shipterms, carrierservice, joined to the customer for its own defaultsNone
Queryproduct, customerparts, uom, to match each line to a productNone
Queryso, for the duplicate check and to find the number of the order just writtenNone
Querysoitem, joined to pick and pickitem, to find the pick for an orderNone
Queryship, to find the shipment for an orderNone
Querysostatus, priority, soitemtype, carrier, carrierservice, taxrate, locationgroup, paymentterms, shipterms, fobpoint, qbclass, uom, sysuser, once at startup, to fill the lists the page offersNone
Querycustomfield, customfieldtype, tablereference, to find the custom fields on a sales order and its linesNone
Querysysproperties, for the date format and the home countryNone
API ImportSalesOrderThe sales orderNone. Fishbowl checks CreateSalesOrder.
API ImportPaymentDataThe paymentNone
API ImportMemoDataThe memoNone
API ImportPickingData, ImportPackingData, ImportShippingDataThe fulfillmentNone

No query is right checked. A query through the plugin bridge carries no right, so the control is the page access the administrator grants.

The page reads. It writes nothing by query: every write goes through one of the imports above.

Every SQL value is bound by name. The page joins no user input into a statement.

What leaves the Fishbowl client. One thing, and only when an administrator allows it. An X12 or EDIFACT file is sent to ILC's conversion service at https://edi-json.ilcreports.com to be turned into JSON. The setting Allow EDI files governs it, and it is off by default. Every other format is read inside the browser and is sent nowhere.

The service keeps nothing. Each file is parsed and discarded, and the only thing it retains is a count of requests per address, for the limit below.

The conversion service limits how many EDI files an hour it will take, and it counts them per network address rather than per person. Everyone at one office shares one allowance.

Files an hour
Without a token10
With a bearer token100

Settings → EDI key holds the key, and appears once Allow EDI files is on. Leave it empty and EDI still works on the free allowance; fill it in and every EDI file after that is sent with it. Nothing else about the page changes, because the key is all the page knows about the tiers — what issues a key, and how a customer gets one, sits behind the service rather than in the page.

An install can also ship with a key already in place, as ediToken on EOI_CONFIG beside ediEndpoint. The setting wins over it where both are set.

The key is stored the way every other setting is: in Fishbowl's plugin data, which is readable by anyone who can read plugin data for this page. It is written to the settings and never into a mapping, so exporting mappings does not carry it. Opening the page in a plain browser instead of the Fishbowl client keeps it in that browser's own storage in the clear — the settings say so there, and a real key does not belong in a browser.

A key that the service has not been configured to accept changes nothing: the service fails closed and leaves the caller on the free allowance. So a key that appears to do nothing is not proof the key is wrong.

The page shows what is left of the allowance once it falls below a quarter, and says when it lifts if it runs out. A file over 25 MB is refused before it is sent. Only EDI files count against the limit — no other format reaches the service at all.

The order file itself never leaves the client except in that one case. The page exports nothing else.

A user may write two files, both to the computer running Fishbowl and to nowhere else:

FileHolds
The mapping documentHow one mapping reads a file, as markdown. No order data.
The mapping exportThe mappings somebody has made, as JSON. No order data.

Settings

The settings, opened with the gear control

An administrator opens the settings with the gear control. The page stores them in plugin data, and they apply to every user.

SettingDefaultWhat changes
Show the sample filesOffAdds bundled example files and their mappings to the page. Use it to evaluate or to train.
Allow EDI filesOffPermits X12 and EDIFACT. Reading one sends it to ILC's conversion service. Every other format is read in the browser.
Only an administrator changes mappingsOnHides New mapping, Edit mapping and Delete from everybody else. Turn it off where the same person builds mappings and runs them. An administrator is never hidden from them.
Treat this Fishbowl asWhatever the home country saysChanges which tax fields the page checks. It changes nothing in Fishbowl. Use it to build a mapping for another region.

Who does which job

The page separates two jobs, and the guides follow the same line:

JobWhoWhere it is written down
Build a mapping for a customer fileAn administratorThis guide, under Building a mapping
Import today's orders with a mapping that existsAnybody with page accessThe user guide

By default an operator never sees the mapping controls. Give them the user guide, and keep this one.

Moving mappings between installations

The settings hold Export…, Import…, and a list to delete one from. Export writes every mapping somebody has made to a JSON file. Built-in mappings are not included, because they come with the page.

Import reads that file back. Each mapping gets a new identifier. A mapping whose name is already in use gets a new name. Importing the same file twice therefore makes two mappings, and overwrites none. Import obeys the mapping lock.

Every mapping records the shape it was written in. The page brings an older one forward when it reads it, both from storage and from an imported file, and reports what it changed. A mapping written by a newer version of the page is refused rather than guessed at.

Two values are fixed and are not configurable:

ValueFixed atWhy
Orders per import callOneFishbowl refuses an order whole. One call per order isolates a failure to that order.
Customer PO length25 charactersThe so.customerPO column holds 25. The page warns before it truncates.

Change where the page appears in the CloudPages plugin page Edit dialog:

PlacementDefault
PathReports:ILC Products
ModulesNone. Add the modules where order entry staff work.
Toolbar buttonNone

Building a mapping

A mapping tells the page how one customer lays their file out. Build it once per customer, against a real file from that customer.

You need the file open. The wizard reads it as you work: you click a cell or a field and the page fills the mapping in. Open the file first, then press New mapping.

The seven steps

StepWhat it settles
StructureWhere the orders are. For a spreadsheet: the header row, the first line row, and where the lines stop. For JSON or XML: the path an order sits at.
OrderWhat fills each sales order field.
LinesWhat fills each line.
BeforeWhether to check that the order is already in Fishbowl, and on which field.
AfterWhat happens once the order exists: a payment, memos, picking.
PreviewThe orders the mapping makes, drawn the way Fishbowl will hold them.
SaveThe name, the description, and the document.

Where a value comes from

Each field takes one of these. The page offers only the kinds that suit the file you opened.

KindReads
Fixed valueThe same value on every order.
From customerThe customer record in Fishbowl.
ColumnA named column, once per line.
CellOne cell of a spreadsheet, by reference.
FieldA named field in JSON or XML, by path.
EDI fieldA segment and element in an EDI document.
Qualified idAn EDI value picked by its qualifier, not by its position.
PartyAn EDI party picked by its code, not by its position.
One of a listOne entry of a repeating list.
DateAnother binding, read as a date and written the way this Fishbowl wants it.
TranslateAnother binding, with its value looked up in a table you supply.
CalculateAnother binding, multiplied or divided by a factor.
RuleThe first rule that matches decides the value.

A binding can wrap another. A date around a column is the ordinary case: read that column, and write it as a date.

One order or many

How many orders a file holds depends on the mapping, not on the file type.

Where a line's price comes from

Unit Price on the Lines step takes Ask Fishbowl as one of its kinds, alongside a column or a fixed value. Choosing it prices each line at what that customer pays for that product at that quantity, from the pricing rules.

Where the price does come from the file, a checkbox under the row offers to check it against Fishbowl anyway, and a line then reports when the two differ.

Leaving the price out of a mapping does not apply the pricing rules. An order imported with ProductPrice empty arrives at the product's base price. Measured on 2026-08-23: a product listing at 2.89, with a 25 percent break between quantity 200 and 500, imported at 2.89 for a quantity of 300 where the rule price is 2.1675. Asking Fishbowl is the only way a rule price reaches an imported line.

A mapping created before this choice existed keeps doing what it already did. A mapping that reads a price from the file continues to use the file, and one that does not now asks Fishbowl.

Rules worth knowing before you start

The mapping document

The Save step writes what the mapping does as markdown: every field, where it comes from, and an example value from the file in front of you. Copy it or save it to a file.

It is written to be enough for somebody to build the same mapping in code. Send it with a support request about a mapping.

Troubleshooting

The page is not in the list of available pages

Every order says the customer does not exist

An EDI file will not open

Every date is refused

The order imported but the payment did not

An order has no tax after an import

A mapping file will not import

New mapping and Edit mapping are disabled

Delete is disabled on a mapping that exists

A hundred orders take twenty seconds to import

Before a support request

The page has no debug control. To reproduce a problem:

  1. Open the settings and turn on Show the sample files.
  2. Load the sample closest to the customer file.
  3. If the sample works and the customer file does not, the mapping or the file is the cause, not the page.

Collect: