Custom Fields Screen

Summary

The Custom Fields screen is a settings screen where an administrator adds their own attributes from the ERP that StockIQ has no built-in field for. 

Custom fields can be added for the following data extracts: Item, Item-Site, Item-Site-Supplier, Supplier, Sales Order Line, and Supply Order Line.

Two kinds of custom fields are supported:

• Stored: values come from the nightly ERP import (impt.<Entity>CustomFieldValue), a spreadsheet upload, or a user typing them into a detail panel. A value a user enters or uploads is never overwritten or removed by a later import.
• Calculated: if Calculated From has a value, the field is calculated, and it's worked out each time it's displayed (e.g. {Cost} - {Discount}, {DueDate} - 7). Formulas support + - * / and parentheses. A formula can only use number and date values from the same kind of record. A Check Expression button validates the formula using the same rules as Save. If the formula uses a protected cost or price, a warning tells the admin that anyone who can see the field will see its calculated value.

Custom Fields Grid

This grid shows existing custom field configurations. Click a row to open it in the Custom Field Definition
 pane on the right.

• Field Code- The field's unique identifier. It becomes the column name in grids, exports, and the API as
   CF_<code>; for example, Brand becomes CF_Brand. It must also match the CustomFieldCode your ERP feed or upload file sends values under. Use only letters, numbers, and underscores, and start with a letter.
• Name- The caption users see on column headers and detail panels. You can rename it at any time without
   affecting saved grid layouts or integrations.
• Applies To- The kind of record the field belongs to: Item, Item-Site, Item-Site-Supplier, Supplier, Sales
   Order, or Supply Order Line. This decides which grids and panels show the field, which key columns identify a record in an upload or import, and which operands a calculated field can use.
• Data Type- How values are stored, sorted, and formatted: Text, Integer, Decimal, Date, Date/Time, or Yes/No. A calculated field can only be Integer, Decimal, Date, or Date/Time, and the type must match what its formula produces.
• Active- Inactive fields stop appearing in grids and exports, but their recorded values are kept. Turning a
   field back on makes them reappear.
• Calculated From- The formula, if the field is calculated. If this column is blank, the field is stored. It's
   the quickest way to see which fields are calculated.
• Order- Display Order, which sets where these fields appear relative to each other in grids and panels. Lower numbers come first.

Custom Field Definition

In addition to reiterating some details from the left grid, the definition pane allows you to further expand
 upon how you'd like calculated fields to work.

Under the editor there's a clickable Available Operands list for the selected record type. It lists everything
 a formula for this kind of record can use, and it updates when you change Applies To. It has three columns:

• Operand – the friendly name, followed by the {Code} you'd type into the formula. Clicking an operand adds it to the end of the Calculated From box, so you don't have to type codes yourself.
• Type – whether the operand is a number or a date.
• Source – Custom field (another numeric or date custom field on the same kind of record) or Built-in (a standard StockIQ property such as a cost, quantity, or date). Cost and price operands show a ⚠ and the permission that normally protects them, such as View Costs or View Prices. That's a reminder that a formula using them shows the result to anyone who can see the field.

 Only operands from the same kind of record are listed. For example, an Item field can't use an Item-Site
 value, because one item has many item-sites and there's no single value to use. Text and Yes/No fields never
 appear, since a formula can't do math with them. Supplier records have no built-in operands because the
 supplier record has no numeric or date properties, but a calculated Supplier field can still use other numeric
 or date Supplier custom fields. If nothing is available, the list explains why.

 The pane also shows an Update Info box with who created the selected field and who last changed it.

Toolbar

• Undo- Discards unsaved edits and reloads the screen from the last saved state. It asks you to confirm first.
• Save- Saves the selected field. Any formula is checked first, and the save is refused with a warning message
   if:
  • the formula is invalid, or
  • the field's code or name is already used, or
  • the change isn't allowed, such as changing a locked Code, Data Type, or Applies To.
•  Save is disabled while the form has errors.
• New- Adds a new field to the grid and selects it for editing. It starts as an active Text field on Item-Site
   named "New Custom Field" with code NewField. Change these before saving. The field isn't created until you click Save.
• Delete- Removes the selected field. Before you confirm, StockIQ tells you how many recorded values will be deleted along with it, and the delete can't be undone. A field that another field's formula uses can't be deleted. A new field that hasn't been saved yet is simply removed from the grid.
• Upload Values-   Opens a dialog for uploading stored values from a spreadsheet. The file has one row per value with these columns:
  • ShipperCode
  • CustomFieldCode
  • Value
  • ItemCode, SiteCode, SupplierCode
  • OrderNumber, LineNumber

•  One file can hold values for any mix of fields. Each field's Applies To setting decides which key columns its
   rows need:

  Applies To	Key Columns Needed
  Item	ItemCode
  Item-Site	ItemCode and Site Code
  Supplier	SupplierCode
  ItemSiteSupplier	ItemCode, SiteCode, and SupplierCode
  SalesOrder and SupplyOrderLine	OrderNumber and LineNumber

•  Value formats:
  • Dates: yyyy-MM-dd
  • Decimals: use a period
  • Yes/No: true/false, 1/0, or yes/no
  • An empty Value clears that value

Rows with errors are reported and skipped; the rest of the file is still applied. Uploaded values show up right away and count as user-entered, so the nightly import won't overwrite them. Calculated fields can't be uploaded to. Uploading requires the Edit Custom Field Values permission
 

Warnings/Notes:

• Field codes and names must be unique across all record types.
• Once a field has values, its Code, Data Type, and Applies To can't change. For a calculated field, they're locked as soon as it's saved. The name can always be changed.
• A field that another formula references can't be deactivated, deleted, or recoded.
• A formula that refers to itself, directly or through other fields, is rejected when you save.
• If any value in a formula is missing, the result is blank rather than zero, by design.
• Values will show up as optional CF_<Code> columns in grids, CSV exports, and the public API. They also  appear on four detail panels and in Edison's grid tools.