Fields

  Table of Contents

• Overview
• Field Definitions
  • Field Keys
  • Archiving Fields and Options
  • Standard Fields
  • Filtering by Fields
  • Definition-Specific and Instance-Specific Fields
• Required Fields
• Data Tables

Overview

Fields collect structured data on inventory, work orders, users, and work order tasks.

Field Definitions

Field definitions are configured globally and can be reused wherever Factorial supports fields. Each definition has a name, a key, a type, and any options required by that type.

Factorial supports these field types:

• Text
• Number
• Date
• Date & time
• Checkbox
• Select
• Multiselect

A checkbox will record one of two values: checked or unchecked. It will start unchecked, so it has no unanswered state. Use a select when a third answer, such as "not applicable," must be distinguishable from unchecked.

Select and multiselect definitions specify the available options.

A text definition can be multiline. A multiline field is entered in a text area, for notes and longer answers, instead of on one line. This only changes how values are entered, so it can be switched at any time without affecting values already recorded.

A date & time records a moment. It is entered and shown in the time zone of the device recording it, and history shows it in UTC like other times.

Whether a value is required is not part of the definition. See Required Fields.

Additional definition settings are planned. Like a definition's type and options, they will apply everywhere the definition is used:

• Entity-reference types, such as a user, part, work order, or step. An entity-reference definition will allow one or multiple referenced entities.
• A unit of measure on numeric definitions.
• An acceptable range for numeric values.

Administrators manage field definitions under Fields in the Organization menu. The page shows each definition as a card. A definition's name, key, and options are edited on its card, so there is no separate page per definition. Other users see the same cards with editing disabled.

Anyone who can edit a step can also create a definition while placing it. Select New field in the field picker of a data field or a data table column, then give the definition a name, a type, and, for a select or multiselect, its options. Factorial creates the definition and places it in one change, so a placement that fails leaves no definition behind. The new definition is shared like any other: administrators can rename, rekey, or archive it on the Fields page. Search the picker before creating a definition, so the same value is not recorded under two names.

A definition's type cannot change after the definition is created. An archived definition or option cannot be renamed until it is restored. Renaming a definition or one of its options changes it everywhere it appears, including steps on released procedure revisions and values already recorded with it. To leave those unchanged, add a new option and archive the old one instead of renaming it. Renaming a definition or an option on the definition's card asks for confirmation first.

Each creation, rename, key change, multiline change, archive, and restore of a definition or an option is recorded in the event stream with the values it replaced, so a change that reaches released procedures can be traced to who made it and when.

Field Keys

A definition's key is the name plugins and the API use for it. Factorial generates the key from the name when the definition is created: its letters and numbers in lowercase, with accents dropped and each run of other characters replaced by one underscore. A definition named "Jacket wall thickness (mm)" gets the key jacket_wall_thickness_mm. When that key is already in use, Factorial adds a number, such as jacket_wall_thickness_mm_2.

Renaming a definition does not change its key, so an integration that refers to the key keeps working. An administrator can change the key on the definition's card, which asks for confirmation first, or through the API. A plugin or integration that still refers to the old key no longer finds the definition, so change a key before anything depends on it.

A key contains lowercase letters and numbers, with single underscores between them. Keys are unique across all definitions, including archived ones, so a key always identifies one definition. An archived definition keeps its key until it is restored and the key is changed.

Archiving Fields and Options

Factorial does not delete field definitions or their options, because steps on released procedure revisions refer to them. Archive a definition or an option instead.

An archived definition can no longer be placed on a step. Steps that already use it keep it, and the step editor marks it as archived. An archived option is no longer offered as a choice. Both can be restored.

A select or multiselect definition must have at least one active option before it can be placed on a step. Once a step places it, its last active option cannot be archived. Add another option first, or archive the definition.

A procedure revision cannot be released with an archived definition on its steps. A revision that is already released keeps a definition archived after its release, but a draft or a revision in review that places an archived definition, as a data field or as a data table column, cannot be submitted for review or released. The procedure page lists those placements and links to their steps. Change the field on each data field block, or remove the block or column, while the revision is a draft, or restore the definition. A redline may still carry an archived definition, because its step is already in use on the work order.

Option values are unique within a definition, ignoring case, so "Crack" and "crack" cannot both be options. An archived option keeps its value, so restore it instead of adding the same value again.

Active definitions have unique names, ignoring case. Archiving a definition frees its name, so the definition can be restored only while no active definition uses that name.

Standard Fields

A standard field applies to every existing and future record of its configured type. Administrators enable a definition for Inventory, Work orders, or Users under Standard fields on its card in Organization → Fields. The same definition can be enabled for more than one type.

Values appear under Fields on each record’s detail page. Each input saves when edited. Inventory values require Parts permission, work order values require Work orders permission, and user values require administrator permission. These fields are optional and remain editable after a work order is completed.

Archiving a placement keeps its values visible and read-only for that entity type. Archiving the definition makes its standard-field values read-only everywhere. Restoring the placement and definition restores editing; neither archive action deletes values. Plugins can still read archived values.

Inventory values belong to its durable inventory group. Splitting copies all values, including archived values, to both resulting groups. Merging copies identical values and is blocked when values conflict, including when one group has a value and another has none. Resolve the values before merging; archived fields must first be restored. Source groups retain their values.

Plugins load values by key using include.inventory.fields, include.work_orders.fields, or include.users.fields. See Querying Standard Fields.

Filtering by Fields

Inventory, work order, and user collections can filter by their standard fields, including fields reached through a relationship. Select Add filter, then choose the field. Archived definitions, placements, and options remain available for filtering retained values.

Select and multiselect filters use option labels. EQ matches a selected option; IN matches any option in the supplied list. For multiselect fields, EQ means “contains this option.” NEQ and NOTIN require an answered field and exclude records containing any of the specified options. Use ISNULL for unanswered fields and ISNOTNULL for answered fields.

Checkboxes always have an answer: an unrecorded checkbox is false. Filtering for false includes unchecked and unrecorded checkboxes.

The query API and CLI explorer identify custom fields by cf_ followed by the field key. For example, {"f":"cf_pedigree","o":"IN","v":["1","2"]} matches either option. Date filters use YYYY-MM-DD. Changing a field key breaks filters that use its old key.

The API's not: true negates the entire filter. Unlike NEQ, negating EQ also includes unanswered fields.

Definition-Specific and Instance-Specific Fields

Step fields carry forward to the corresponding work order task.

Definition-specific inventory fields are planned: an inventory record will receive the union of global inventory fields and fields configured on its part. Instance-specific placements are also planned. The current standard-field configuration supports global placements only.

Required Fields

Requiredness is configured each time a field definition is placed, not on the definition itself. The same definition may be required on one step and optional on another. Because the setting is part of the step, it is versioned and reviewed with the procedure revision or redline that contains it.

A task with an incomplete required field cannot be marked as completed. A required checkbox must be checked, because a checkbox starts unchecked and has no unanswered state. Any other required field must have a value, and a required select or multiselect must have at least one option chosen. See Data Input.

See Data Fields for how procedures configure step inputs and Data Input for their behavior during execution.

Data Tables

A data table places several field definitions on a procedure step as the columns of a table, so the same set of values can be recorded on many rows. Data tables are available on procedure steps, redlines, and project tasks. Each column uses a field definition to determine its value type, and each placement is required or optional on its own, like a data field.

The same definition may appear in more than one column of a table, for example a torque reading before and after a rework. Each column may have a label that is shown instead of the definition's name. No two columns of a table may show the same name, ignoring case, so a definition used twice needs a label on at least one of its columns.

Use a data field when a task requires one value. Use a data table when operators may record the same set of values multiple times during a task.