Equipment

System: Equipment and Service Management

1. Purpose

The Equipment and Service Management System is designed to manage reservations, services, and associated components for equipment and modules. It provides functionality for equipment management, reservation handling, service property management, user permissions, notifications, and email communication.

This document outlines the key functional elements, dependencies, and workflows of the system based on its codebase.

2. Scope

The document covers the following modules and services:

Equipment Module (/module/equipment)
- ReservationService: Manages all interactions related to equipment reservations.
- EquipmentService: Handles equipment-specific utilities like properties, roles, and module integration.
- PropertyService: Manages custom properties for equipment and modules.
- RoleService: Manages roles and permissions for equipment access.
- StatusService: Manages equipment and module status tracking.

3. Feature Description

3.1 Equipment Reservation (ReservationService)

The system provides advanced reservation management for equipment.

Reservation Functionalities

Reservation CRUD Operations:
- Create: Adding new reservations for equipment and modules.
- Update/Delete: Modify or remove existing reservations.
- Query: Search reservations based on date, equipment, and user-specific filters.
Recurring Reservations:
Handles repetitive reservations (e.g., weekly, bi-weekly, monthly).
- Logic: Based on DateInterval and reservation type constants (e.g., RECURRING_BI_WEEKLY).
Approval System:
Reservations can be approved (or declined).
- Notification emails are sent to the appropriate users upon approval.
- Method: updateReservationApproval(Reservation $reservation, string $approval, ?string $feedback = null)
Permission Management:
- Determines access rights for reservation edits, approvals, and viewing.
- Based on user roles or equipment-specific privileges.
- Methods:
  - userCanEditReservation(Reservation $reservation, User $user): bool
  - userCanApproveReservation(Reservation $reservation, User $user): bool
Form Preparation:
Customizes reservation forms dynamically with user- and equipment-specific options.
- Modules, assets, and users are injected into forms using database data.
- Method: prepareForm(Form $form, Equipment $equipment, User $user)
Email Notifications:
Automatic emails for reservation-related actions:
1. New reservations.
2. Approval requests.
3. Cancellations.
- Emails are composed using the EquipmentMailingVariablesValueObject and sent via MailingService.
Integration with Scheduler and Queueing System:
- Handles job rescheduling and impacted tasks caused by reservation updates.
- Integration is implemented with the QueueService and SchedulerService.
- Method: confirmReservation(Reservation $reservation, string $message): void

Key Entities and Attributes

Reservations:
- Link to equipment and modules.
- Store details like startDate, endDate, title, and status.
- Can be part of a block reservation (managed as a group).
Modules:
- Secondary components linked to the equipment. Manageable via forms.
Users:
- Trained users are allowed to reserve equipment based on configuration.

3.2 Equipment Handling (EquipmentService)

Manages core operations related to equipment and its components.

Equipment Functionalities

Property Management:
- Retrieves, parses, and updates equipment properties.
- Supported property types:
  - Integer, Float, Date, Min-Max, Checkbox, Text, and Radio.
- Methods:
  - parseProperties(Equipment $equipment): array
  - updateEquipmentProperties(Equipment $equipment, array $formDetails): void
Module Parsing: Converts module configurations into usable formats for forms or displays.
- Method: parseModules(Equipment $equipment): array
Scheduler Integration: Retrieves equipment with scheduler functionality enabled.
- Method: findEquipmentWithSchedulerEnabled(): array
Equipment Removal Validation: Ensures that all related modules or maintenance schedules are cleared before deletion.
- Method: cannotDeleteEquipmentReasons(Equipment $equipment): array
Role and Category Classification: Retrieves and organizes categories and roles associated with equipment.

4. Dependencies

Internal Dependencies:

Equipment Module:
Primary relationships between ReservationService and EquipmentService:
- Fetch users, roles, and trained users.
- Check properties and configurations related to reservations.
Entity Management:
All modules rely on Doctrine ORM:
- Entities such as Reservation, Service, and Equipment are persisted and retrieved using repositories.
Services:
- QueueService: For managing reservation-related queue impacts.
- MailingService: For emails related to reservation approvals or rejections.
- RoomService: Injects room configurations into forms.

External Dependencies:

Email Service:
- Used extensively for sending transactional emails, invitations (iCal), and notifications to impacted users.
- Service: EmailService.
TypeScript APIs:
- Frontend interaction with reservations and modules handled by APIs (e.g., getEquipmentModule.ts).

5. Non-Functional Requirements

Performance:
- Reservation query operations handle multiple date ranges and equipment filters efficiently using optimized database queries.
Scalability:
- System allows dynamic addition of modules, properties, and categories.
- Robust scheduler integration ensures handling of high volumes of overlapping jobs or queues.
Security:
- User access controlled through permission levels (edit, view, approve).
- Email addresses validated before sending notifications.

6. Open Issues & Future Enhancements

Conflict Resolution Enhancements:
- Refine overlapping reservation handling for scenarios involving multiple users and schedules.
Improved User Interface for Reservation Forms:
- Add real-time dynamic selections for modules and assets.
Logging & Auditing:
- Implement detailed logging for reservation status changes, including emails sent and user actions.
Asynchronous Email Delivery:
- Delegate email delivery to a queue-based system for improved performance.

7. Key API Endpoints

Reservation Endpoints:
- POST /new/equipment/reservation: Create a new reservation.
- GET /equipment/reservation/:id: Retrieve reservation by ID.
Module Endpoints:
- GET /equipment/module/:id: Retrieve module details for a given ID (as used in getEquipmentModule).

This document provides an overview of the functional requirements and behavior of the equipment and service management system. Further refinements can be made as the system evolves.

8. Entity Model

8.1 Core Entities

8.1.1 Equipment

The Equipment entity is the central entity in the module, representing physical laboratory equipment.

Key Properties:

id: Unique identifier
name: Name of the equipment
number: Equipment identification number
active: Status indicating if the equipment is active
activeInMES: Status indicating if the equipment is active in the Manufacturing Execution System
description: Detailed description of the equipment
reservationPossible: Flag indicating if the equipment can be reserved
trainingPossible: Flag indicating if training is possible on this equipment
doubleBookingPossible: Flag indicating if double booking is allowed
reservationApprovalRequired: Flag indicating if reservations require approval
schedulerEnabled: Flag indicating if the equipment is enabled in the scheduler
ownership: Ownership type of the equipment

Relationships:

location: Physical location of the equipment
room: Room where the equipment is located
zone: Zone where the equipment is located
area: Area where the equipment is located
vendor: Manufacturer or vendor of the equipment
types: Equipment types/categories
module: Modules associated with the equipment
reservation: Reservations for the equipment
request: Training requests for the equipment
equipmentRoles: Roles associated with the equipment
equipmentUsers: Users associated with the equipment
equipmentProperties: Custom properties of the equipment
documents: Documents related to the equipment
links: External links related to the equipment
preventiveMaintenanceMaintenance: Maintenance records
preventiveMaintenanceSchedule: Maintenance schedules
loggings: Usage logs for the equipment
equipmentServices: Services associated with the equipment

8.1.2 Module

The Module entity represents components or sub-units of equipment.

Key Properties:

id: Unique identifier
name: Name of the module
number: Module identification number
active: Status indicating if the module is active
reservationPossible: Flag indicating if the module can be reserved
MESName: Name in the Manufacturing Execution System
hideInSchedulerList: Flag to hide in scheduler list

Relationships:

equipment: Parent equipment
type: Module type
status: Status records
issue: Issues related to the module
ecn: Engineering Change Notices
reservation: Reservations for the module
moduleParameter: Parameters of the module
assets: Assets associated with the module
moduleFacilities: Facilities associated with the module
changelog: Change history
groups: Groups the module belongs to
function: Function of the module
moduleProperties: Custom properties of the module
externalActivity: External activities related to the module

8.1.3 Category

The Category entity represents classifications for equipment.

Key Properties:

id: Unique identifier
name: Category name
description: Category description

Relationships:

types: Types within this category

8.1.4 Role

The Role entity represents user roles for equipment access.

Key Properties:

id: Unique identifier
name: Role name
description: Role description

Relationships:

equipmentRoles: Equipment-role associations

8.2 Supporting Entities

8.2.1 Property

The Property entity represents custom properties that can be assigned to equipment.

Key Properties:

id: Unique identifier
name: Property name
type: Property type (Integer, Float, Date, Min-Max, Checkbox, Text, Radio)
description: Property description
options: Available options for selection properties

8.2.2 Reservation

The Reservation entity represents bookings for equipment and modules.

Key Properties:

id: Unique identifier
title: Reservation title
startDate: Start date and time
endDate: End date and time
status: Reservation status
recurring: Recurring pattern (if applicable)

Relationships:

equipment: Reserved equipment
module: Reserved modules
user: User who made the reservation

8.2.3 Monitor

The Monitor entity represents monitoring configurations for equipment.

Key Properties:

id: Unique identifier
name: Monitor name
description: Monitor description
active: Status indicating if the monitor is active

9. User Interface

9.1 Equipment Management

9.1.1 Equipment List

The equipment list view displays all equipment with filtering and search capabilities.

Features:

Sortable columns for equipment attributes
Filtering by various criteria (name, number, location, etc.)
Quick access to equipment details
Actions for creating, editing, and managing equipment

9.1.2 Equipment Details

The equipment details view shows comprehensive information about a specific equipment.

Features:

Basic equipment information
Associated modules
Custom properties
Location information
Maintenance history
Documents and links
User access information

9.1.3 Equipment Edit

The equipment edit view allows administrators to modify equipment properties.

Features:

Form for editing basic equipment information
Management of custom properties
Assignment of location and categorization
Configuration of reservation settings

9.2 Module Management

9.2.1 Module List

The module list view displays modules associated with equipment.

Features:

Filtering and sorting capabilities
Status indicators
Quick access to module details

9.2.2 Module Details

The module details view shows comprehensive information about a specific module.

Features:

Basic module information
Associated assets
Status history
Issues and ECNs
Custom properties

9.3 Reservation System

9.3.1 Reservation Calendar

The reservation calendar provides a visual representation of equipment and module bookings.

Features:

Day, week, and month views
Color-coded reservations
Drag-and-drop reservation creation and modification

9.3.2 Reservation Form

The reservation form allows users to book equipment and modules.

Features:

Date and time selection
Module selection
Recurring reservation options
Approval workflow for restricted equipment

9.4 User Access Management

9.4.1 Role Assignment

The role assignment interface allows administrators to manage user access to equipment.

Features:

Assignment of roles to users for specific equipment
Training status tracking
Approval workflows for access requests

9.4.2 Training Management

The training management interface tracks user training on equipment.

Features:

Training request submission
Training status tracking
Training history

The Equipment entity is the central entity in the module, representing physical laboratory equipment.

Key Properties:

id: Unique identifier
name: Name of the equipment
number: Equipment identification number
active: Status indicating if the equipment is active
activeInMES: Status indicating if the equipment is active in the Manufacturing Execution System
description: Detailed description of the equipment
reservationPossible: Flag indicating if the equipment can be reserved
trainingPossible: Flag indicating if training is possible on this equipment
doubleBookingPossible: Flag indicating if double booking is allowed
reservationApprovalRequired: Flag indicating if reservations require approval
schedulerEnabled: Flag indicating if the equipment is enabled in the scheduler
ownership: Ownership type of the equipment

Relationships:

location: Physical location of the equipment
room: Room where the equipment is located
zone: Zone where the equipment is located
area: Area where the equipment is located
vendor: Manufacturer or vendor of the equipment
types: Equipment types/categories
module: Modules associated with the equipment
reservation: Reservations for the equipment
request: Training requests for the equipment
equipmentRoles: Roles associated with the equipment
equipmentUsers: Users associated with the equipment
equipmentProperties: Custom properties of the equipment
documents: Documents related to the equipment
links: External links related to the equipment
preventiveMaintenanceMaintenance: Maintenance records
preventiveMaintenanceSchedule: Maintenance schedules
loggings: Usage logs for the equipment
equipmentServices: Services associated with the equipment

8.1.2 Module

The Module entity represents components or sub-units of equipment.

Key Properties:

id: Unique identifier
name: Name of the module
number: Module identification number
active: Status indicating if the module is active
reservationPossible: Flag indicating if the module can be reserved
MESName: Name in the Manufacturing Execution System
hideInSchedulerList: Flag to hide in scheduler list

Relationships:

equipment: Parent equipment
type: Module type
status: Status records
issue: Issues related to the module
ecn: Engineering Change Notices
reservation: Reservations for the module
moduleParameter: Parameters of the module
assets: Assets associated with the module
moduleFacilities: Facilities associated with the module
changelog: Change history
groups: Groups the module belongs to
function: Function of the module
moduleProperties: Custom properties of the module
externalActivity: External activities related to the module

8.1.3 Category

The Category entity represents classifications for equipment.

Key Properties:

id: Unique identifier
name: Category name
description: Category description

Relationships:

types: Types within this category

8.1.4 Role

The Role entity represents user roles for equipment access.

Key Properties:

id: Unique identifier
name: Role name
description: Role description

Relationships:

equipmentRoles: Equipment-role associations

8.2 Supporting Entities

8.2.1 Property

The Property entity represents custom properties that can be assigned to equipment.

Key Properties:

id: Unique identifier
name: Property name
type: Property type (Integer, Float, Date, Min-Max, Checkbox, Text, Radio)
description: Property description
options: Available options for selection properties

8.2.2 Reservation

The Reservation entity represents bookings for equipment and modules.

Key Properties:

id: Unique identifier
title: Reservation title
startDate: Start date and time
endDate: End date and time
status: Reservation status
recurring: Recurring pattern (if applicable)

Relationships:

equipment: Reserved equipment
module: Reserved modules
user: User who made the reservation

8.2.3 Monitor

The Monitor entity represents monitoring configurations for equipment.

Key Properties:

id: Unique identifier
name: Monitor name
description: Monitor description
active: Status indicating if the monitor is active

9. User Interface

9.1 Equipment Management

9.1.1 Equipment List

The equipment list view displays all equipment with filtering and search capabilities.

Features:

Sortable columns for equipment attributes
Filtering by various criteria (name, number, location, etc.)
Quick access to equipment details
Actions for creating, editing, and managing equipment

9.1.2 Equipment Details

The equipment details view shows comprehensive information about a specific equipment.

Features:

Basic equipment information
Associated modules
Custom properties
Location information
Maintenance history
Documents and links
User access information

9.1.3 Equipment Edit

The equipment edit view allows administrators to modify equipment properties.

Features:

Form for editing basic equipment information
Management of custom properties
Assignment of location and categorization
Configuration of reservation settings

9.2 Module Management

9.2.1 Module List

The module list view displays modules associated with equipment.

Features:

Filtering and sorting capabilities
Status indicators
Quick access to module details

9.2.2 Module Details

The module details view shows comprehensive information about a specific module.

Features:

Basic module information
Associated assets
Status history
Issues and ECNs
Custom properties

9.3 Reservation System

9.3.1 Reservation Calendar

The reservation calendar provides a visual representation of equipment and module bookings.

Features:

Day, week, and month views
Color-coded reservations
Drag-and-drop reservation creation and modification

9.3.2 Reservation Form

The reservation form allows users to book equipment and modules.

Features:

Date and time selection
Module selection
Recurring reservation options
Approval workflow for restricted equipment

9.4 User Access Management

9.4.1 Role Assignment

The role assignment interface allows administrators to manage user access to equipment.

Features:

Assignment of roles to users for specific equipment
Training status tracking
Approval workflows for access requests

9.4.2 Training Management

The training management interface tracks user training on equipment.

Features:

Training request submission
Training status tracking
Training history

12 June 2025