Property definitions¶

Properties are the data fields that appear on entities in MatStream. Your administrator defines which properties are available in the workspace and assigns them to categories. Users fill in property values when creating and editing entities.

What a property definition controls¶

Data types¶

The data type decides how a value is stored, validated, sorted and displayed. It cannot be changed after the property is saved, so choose carefully.

Numbers of any numeric type can be linked to a unit of measure.

Notes per data type¶

• WorkspaceUserRef always refers to a single user, never a group. It only offers the User picker — a plain number field would let someone type a valid user id and silently assign the wrong person.
• EntityRef stores which item is referenced, not its name, so renaming the referenced item never breaks the link.
• Barcode has its own page: Barcode scanning.
• Calculated values are worked out from a formula and cannot be typed into. Choosing this data type shows a Formula field in the property dialog, e.g. [Quantity] * [Unit Price]. The formula is checked when you save: it is refused if it names a property that does not exist, a property that is not a number, the property itself, or another calculated property in a way that would form a loop. See Calculated properties for the syntax and the blank-not-zero rule.

Thumbnail properties¶

To make an image available on a category:

1. Create a property definition with data type Thumbnail. New workspaces include a Thumbnail property that you can reuse.
2. Assign it to the category in the category editor's Properties tab.
3. Set its position, group, and view/edit permissions like any other category property.
4. Users can then upload or paste an image through the thumbnail editor. Add the property as a grid column to display the picture in Library or Explorer.

Thumbnail uses its own image editor, not a text field or a manually entered file ID. Searched is disabled for this datatype; images are not included in text search, and thumbnail columns cannot be sorted or filtered.

The image is stored as a square, centre-cropped 512 × 512 WebP thumbnail. Use a Document or Photo Gallery when you need to retain original files or manage multiple pictures, rather than treating the thumbnail as an original-image archive.

See Thumbnail properties for upload formats, limits, and save behaviour.

Editor types¶

The editor type decides which control users see when they fill in the value — in the item dialog, the Property Browser and editable grids. The Editor type list in the property dialog only offers the editors that suit the chosen data type; leave it on the default unless you need something different.

A few combinations worth knowing:

• String + Combo box gives a list property whose stored value is plain text; Int + Combo box stores a number behind each label (use value|label pairs, see below).
• String + Text box + combo suggests values but still accepts anything typed — use it when the list is a convenience, not a rule.
• Calculated uses a text box only to give the value its normal shape; it is always read-only.

Editor source settings¶

Editors marked with a source setting enable the ⚙ button next to the Editor type list. A short summary of the current settings appears below the list.

• Combo box and Text box + combo — enter the options, one per line. Tick Use value|label pairs to store a value different from what users see, e.g. 1|Receipt, 2|Issue. For a combo box these are the only values allowed; for text box + combo they are only suggestions.
• Entity picker — choose which categories the picker searches, so a Client property only offers customers.
• Rich text (RTF) — optional JSON settings for the editor; {} gives the default editor.

Initial values¶

Initial value is filled in when a new item is created. Type a fixed value or pick one of the functions:

Unique values¶

Tick Unique to stop two items having the same value. When an item is saved, MatStream checks the latest version of every other item in the workspace and refuses the save if the value is already in use, naming the property. Empty values are never considered duplicates. The check applies to text values.

System properties¶

Some properties are marked as system properties. These are created automatically by MatStream and are available in every workspace. System properties cannot be deleted but can be assigned to categories like any other property.

Derived system properties¶

A second kind of system property is not stored at all — it is calculated when the entity is read. Stock figures are the clearest example: a purchase-order line's Ordered Qty, Received Qty and Line Total are summed from the stock ledger every time you look at the line, and cannot be typed into.

Which derived properties an entity has depends on its category's behaviour:

These appear in the property browser and the column chooser like any other property, but are read-only.

System keys¶

Every system property has a stable system key — a short identifier such as RequiredQty or OnHandQty — used internally to find that property regardless of its display name or which workspace it is in.

A stored property definition can also carry a system key. That is how a normal, editable property becomes something the platform can locate reliably: Required Qty on a Material Requirement Line is an ordinary decimal property that a buyer can change, but it carries the system key RequiredQty so the procurement process knows where to write the quantity.

Managing property definitions¶

Navigate to Configuration → Property definitions to manage your workspace properties.

Creating a property¶

1. Click New in the toolbar
2. Enter a Name — this is the label users will see
3. Select a Data type
4. Check the Editor type — it defaults to the usual editor for the data type. If the ⚙ button is enabled, click it to set the options or picker categories (see Editor source settings)
5. For a Calculated property, enter the Formula. Otherwise, optionally set an Initial value
6. Set Required if users must fill in this field before saving, Unique if no two items may share a value, and Searched if you want this property available as a filter in Library
7. Click Save

Editing a property¶

Select a property and click Edit, or double-click it. You can change everything except the data type: name, description, editor type and its source settings, formula, initial value, and the Required, Unique and Searched flags. Changing the data type of an existing property is not supported — create a new property instead.

Renaming a property used in a formula updates those formulas for you: renaming Unit Price to Sales Price turns [Unit Price] into [Sales Price] in every calculated property that uses it, so their values keep working. Two changes are refused while a formula still uses the property: a new name containing [ or ], which a formula cannot refer to, and changing it to a data type that is not a number.

Deleting a property¶

Select a property and click Delete. A property that is assigned to one or more categories cannot be deleted until it is unassigned from all categories.

A property used in the formula of a calculated property cannot be deleted either — the calculated value would silently go blank. The message names the formulas that use it; remove the property from those formulas first, then delete it.

Assigning properties to categories¶

Defining a property makes it available in the workspace, but it does not appear on any entity until it is assigned to a category. Properties are assigned in the Properties tab of the category configuration.

For each property assigned to a category you can configure:

• Sort order — the order in which the property appears on the entity detail page
• Group — optionally group related properties under a heading
• Permissions — which workspace groups can view and edit this property

Permissions are set per assignment, not per property. The same property assigned to two categories is restricted separately in each, so restricting Unit Price on Purchase Order Line does nothing to Unit Price elsewhere.

A property with no permission rows is visible to everyone; adding the first row restricts it to the groups named there and removes it from all others.

→ See Category editor — property permissions for the full rules, and Categories for details on assigning properties.

Base properties¶

When your workspace is created, MatStream seeds the following properties automatically:

These are available immediately and can be assigned to any category.

Related¶

• Categories — assign properties to categories and configure display settings
• Configuration overview — recommended configuration order
• Properties — how users interact with properties on entities
• Barcode scanning - the Barcode data type and the scanner dialogs