Asset / Machine Master User Manual

Overview

The Asset / Machine Master module is the central management hub for defining, configuring, and maintaining physical machines and equipment across your manufacturing enterprise.

Through this module, administrators can register new machines, update machine specifications, assign machines to physical plant locations, associate them with standardized Asset Models, set module access permissions, and control operational status.

Machine Form Architecture & Workflow

The Machine Form provides a streamlined, validated, and interactive interface for creating and editing machine records.

Field Specifications & Requirements Guide

This section outlines every input field available in the Machine Form, detailing mandatory rules, character limits, formatting constraints, and dynamic behaviors.

Field Name	Mandatory?	Input Type	Validation Rules / Limits	Key Behavior & Description
Machine Image	Required `*`	Upload / Drag & Drop	Binary Image File	Displays preview. Auto-fills from Asset Model if available. Cannot submit without an image.
Machine Name	Required `*`	Text Input	1 to 35 characters Pattern: `[a-zA-Z0-9@#&()-_ ]`	Human-readable machine name. Auto-focused when opening form in Add mode.
Machine Code	Required `*`	Text Input	1 to 20 characters Pattern: `[a-zA-Z0-9_-]`	Unique identifier code. Read-only / Disabled in Edit Mode.
Asset Model	Required `*`	Autocomplete Dropdown	Selection Required	Links machine to Asset Model template. Automatically updates image preview.
Commissioned Date	Optional	Date Picker	Valid Calendar Date	Date when machine officially entered service. Stored in ISO 8601 format.
Location	Required `*`	Autocomplete Dropdown	Selection Required	Factory / facility location loaded from Location Master.
Status	Required `*`	Dropdown	`Active` / `Inactive`	Controls operational state. Cannot be cleared (default: `Active`).
Is Shared	Optional	Checkbox	`True` / `False`	Flags if machine is shared across multiple production lines.
Module Access	Required `*`	Checkbox Group	At least 1 module required	Grants module permissions. Highlighted with red border if unselected.
Description	Optional	Multiline Text Area	Free Text	Optional technical notes, specifications, or operational details.

Detailed Field Functional Breakdown

1. Machine Image Upload Zone (`image_file`)

The machine image provides a visual identity for equipment across dashboards, line monitors, and reports.

Mandatory Requirement: An image is strictly required for every machine record. If no image is provided upon form submission, the system triggers a top-right alert message:
```
Please upload an image
```
Asset Model Auto-Sync: When you select or change the Asset Model, the form automatically retrieves the default image configured for that Asset Model and populates the upload zone preview.
Custom Image Upload: Users can click or drag & drop a custom image file to override the default asset model image.
Remove Image: Clicking the Remove Image button clears the current preview and resets the image field to null.

Image Recommendation

Use high-resolution, clear equipment photos with a transparent or neutral background (PNG/JPG format) for optimal display on monitoring dashboards.

2. Machine Name (`machine_name`)

Requirement: Mandatory (*)
Length Constraint: Minimum 1 character, Maximum 35 characters.
Allowed Characters: Alphanumeric characters, spaces, and allowed special characters: @, #, &, (, ), -, _.
Validation Message:
- Empty: "Please enter name"
- Exceeds 35 chars: "Name exceeds the maximum allowed length of 35 characters."
- Disallowed symbols: "Please enter a valid name."
Auto-Focus: In Add Mode, the cursor automatically focuses on the Machine Name input field when the screen opens.

3. Machine Code (`machine_code`)

Requirement: Mandatory (*)
Length Constraint: Minimum 1 character, Maximum 20 characters.
Allowed Characters: Alphanumeric characters, hyphens (-), and underscores (_). No spaces or special symbols allowed.
Edit Mode Lock:
- In Add Mode: Fully editable.
- In Edit Mode: Disabled (Read-only). The machine code acts as a permanent unique identifier in the database and cannot be modified after initial creation.

Machine Code Permanence

Double-check the Machine Code during creation. Once saved, it cannot be edited. If a code change is needed, the machine record must be deleted and recreated.

4. Asset Model (`asset_model_id`)

Requirement: Mandatory (*)
Type: Autocomplete Dropdown Selection.
Functionality:
- Connects the physical machine to a predefined Asset Model (which bundles classification, manufacturer, controller, and monitored data points).
- Automatically captures the associated asset_model_code.
- Automatically loads the default image of the selected Asset Model into the Machine Image Upload Zone (if user has not manually uploaded an image).

5. Commissioned Date (`date_of_commissioned`)

Requirement: Optional
Type: Interactive Calendar Date Picker.
Purpose: Records the official date when the machine was installed, tested, and commissioned for production operations.
Data Format: Converted to ISO string (YYYY-MM-DDTHH:mm:ss.sssZ) upon save.

6. Location (`location_id`)

Requirement: Mandatory (*)
Type: Autocomplete Dropdown Selection.
Data Source: Fetched dynamically from Location Master.
Purpose: Assigns the machine to a specific plant, workshop, building, or geographical site.

7. Status (`status`)

Requirement: Mandatory (*)
Type: Single-select Dropdown (disableClearable).
Options:
- Active (true): Machine is operational and available for production line assignment, shift scheduling, and live monitoring.
- Inactive (false): Machine is disabled or out of service. Inactive machines are excluded from operational line workflows while retaining historical audit logs.
Default Value: Active

8. Is Shared (`is_shared`)

Requirement: Optional
Type: Labeled Checkbox with Information Tooltip.
Helper Note: "Available across lines."
Purpose:
- When Unchecked (Default): The machine is dedicated exclusively to a single production line.
- When Checked: Indicates that the machine is a shared asset that can be utilized by multiple production lines or work centers simultaneously.

9. Module Access Matrix (`module_locations`)

Requirement: Mandatory (*)
Container: Bordered fieldset with legend <legend>Module Access *</legend>.
Functionality:
- Displays a dynamic matrix of available projects/modules (e.g., MES, OEE, WMS, Quality, Maintenance, IoT, etc.) assigned to the customer subscription.
- Controls which application modules are authorized to interact with and process data for this machine.
Validation Rule: At least one module checkbox MUST be selected.
Visual Error Indicator: If no module is checked when submitting the form:
- Validation error message is shown.
- The entire Module Access box border highlights in red (1px solid #bd0000).

10. Description (`description`)

Requirement: Optional
Type: Full-width Multiline Text Area.
Purpose: Allows operators and engineers to enter auxiliary information such as serial numbers, vendor warranty details, capacity ratings, or special maintenance guidelines.

Step-by-Step Operating Procedures

How to Add a New Machine

Navigate to Admin Portal > Asset/Machine Configuration > Asset / Machine Master.
Click the Add New button at the top right of the machine table.
The Machine Form modal/drawer will open with the cursor auto-focused on Name.
Enter the Machine Name (up to 35 characters).
Enter a unique Machine Code (up to 20 alphanumeric/hyphen/underscore characters).
Select an Asset Model from the dropdown. Notice how the machine image preview automatically populates with the model's default image.
Select the physical Location where the machine is installed.
(Optional) Select the Commissioned Date using the calendar date picker.
Select the operational Status (Active or Inactive).
Check Is Shared if this machine is shared across multiple production lines.
Under Module Access, check at least one module (e.g., MES, IoT, Maintenance) to grant module permissions.
(Optional) Replace or upload a custom Machine Image by clicking on the image upload zone.
(Optional) Add extra details in the Description box.
Click Save.

How to Edit an Existing Machine

In the Machine Master list, locate the target machine record.
Click the Edit (pencil) icon under the Actions column.
The Machine Form opens pre-populated with existing record data.
Immutable Field
Notice that the Machine Code field is greyed out/disabled and cannot be modified.
Update desired fields (e.g., Name, Location, Asset Model, Status, Module Access, Description, or Machine Image).
Click Save to update the machine record in the system.

Validation & Error Handling Matrix

Use the reference table below to diagnose and resolve form validation errors:

Error Message / Symptom	Trigger Condition	Solution / Action Required
"Please enter name"	Machine Name field is left blank.	Enter a valid machine name (1-35 characters).
"Name exceeds maximum allowed length..."	Machine Name exceeds 35 characters.	Shorten the machine name to 35 characters or fewer.
"Please enter a valid name."	Name contains invalid special characters (e.g., `$`, `%`, `*`).	Remove invalid symbols. Only `@`, `#`, `&`, `()`, `-`, `_`, space, and alphanumeric characters are allowed.
"Please enter code"	Machine Code field is left blank.	Enter a unique machine code (1-20 characters).
"Code exceeds maximum allowed length..."	Machine Code exceeds 20 characters.	Shorten the code to 20 characters or fewer.
"Please enter a valid code."	Code contains spaces or illegal characters.	Use only letters, digits, hyphens (`-`), or underscores (`_`).
"Please select asset model"	Asset Model dropdown is unselected.	Select an Asset Model from the dropdown list.
"Please select location"	Location dropdown is unselected.	Select a valid location from the dropdown list.
"At least one module must be selected" (Red border on Module Access box)	No checkboxes checked in Module Access fieldset.	Check at least one module (e.g., MES, IoT) under Module Access.
"Please upload an image" (Top-right Snackbar Alert)	`image_file` is empty or removed.	Click the upload zone to upload an image or re-select an Asset Model with a default image.

Summary & Best Practices

Ensure Unique Machine Codes: Establish a standard naming convention for machine codes across your facility (e.g., CNC-VMC-01, PRESS-HYD-02).
Leverage Asset Models: Standardize your setup by creating comprehensive Asset Models beforehand. This speeds up machine onboarding and ensures automatic image and data point mapping.
Assign Module Access Carefully: Only enable module access for applications where the machine data is actively utilized to maintain clean data routing.
Mark Shared Assets: Use the Is Shared flag accurately so scheduling algorithms understand machine availability across multiple lines.

Overview​

Machine Form Architecture & Workflow​

Field Specifications & Requirements Guide​

Detailed Field Functional Breakdown​

1. Machine Image Upload Zone (image_file)​

2. Machine Name (machine_name)​

3. Machine Code (machine_code)​

4. Asset Model (asset_model_id)​

5. Commissioned Date (date_of_commissioned)​

6. Location (location_id)​

7. Status (status)​

8. Is Shared (is_shared)​

9. Module Access Matrix (module_locations)​

10. Description (description)​

Step-by-Step Operating Procedures​

How to Add a New Machine​

How to Edit an Existing Machine​

Validation & Error Handling Matrix​

Summary & Best Practices​