= UNC File Storage Layout =

The UNC File Storage Layout defines how local file documents are physically stored in the UNC document root. UBIK supports a flat layout and a folder-partitioned layout.

Folder partitioning is available from UBIK 5.2 and is the recommended layout for UNC file storage. To maintain downward compatibility, the default remains the existing flat layout until an administrator starts the transfer.

The layout changes only the physical file location. The document object and its '''LOCALPATH''' value remain unchanged.

== Scope ==

The UNC File Storage Layout applies only when '''File Storage Mode''' is set to '''UNC'''.

Folder partitioning is not a separate File Storage Mode. The existing modes remain unchanged:

{| class="wikitable"
! Value
! File Storage Mode
|-
| 0
| Undefined
|-
| 1
| UNC
|-
| 2
| Cloud
|}

Only local file documents with '''IsLocalDoc = true''' are affected. Cloud documents and non-local file documents are ignored.

== UNC File Storage Layout Setting ==

The database setting '''UNC File Storage Layout''' identifies the layout currently used by the database.

{| class="wikitable"
! Value
! Description
|-
| Flat
| Local file documents are stored directly in the document root folder.
|-
| Folder Partitioning
| Local file documents are distributed across generated subfolders based on the document UID.
|}

The setting is visible in the database settings but is read-only. It can be changed only by successfully completing the transfer tool.

For new and existing databases, the default value is '''Flat'''. Updating a database does not change its existing '''File Storage Mode''' or move any files automatically.

== Storage Layouts ==

=== Flat ===

With the flat layout, local file documents are stored directly in the document root folder.

Example:

:''.../doc/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

=== Folder Partitioning ===

With folder partitioning, UBIK generates two folder levels from the document UID:

* The first character of the UID is used for the first folder level.
* The second and third characters of the UID are used for the second folder level.
* Generated folder names use lowercase characters.

Example UID:

:''8ec24142-17eb-4640-bdcf-31d696c398de''

Resulting physical path:

:''.../doc/8/ec/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

== LOCALPATH and Physical File Resolution ==

The '''LOCALPATH''' property continues to contain only the file name and extension:

:''8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

Folder-partitioning subfolders are not stored in '''LOCALPATH'''. UBIK calculates the complete physical file path when the file is accessed, using:

* the document root path
* the File Storage Mode
* the UNC File Storage Layout
* the document UID and '''LOCALPATH'''

== Database-wide Layout ==

A database uses one UNC storage layout for all local file documents. Flat storage and folder partitioning must not be mixed within the same database.

After a successful transfer, all existing and newly created local file documents use the selected layout.

== Transferring Local File Documents ==

Administrators can transfer all local file documents to the other layout using:

:''Tools → Apply UNC File Storage Layout to All Files''

Tooltip:

:''Updates all local files to use the other UNC file storage layout.''

The tool is available only when '''File Storage Mode = UNC'''. Because there are only two layouts, UBIK determines the target automatically:

{| class="wikitable"
! Current layout
! Target layout
|-
| Flat
| Folder Partitioning
|-
| Folder Partitioning
| Flat
|}

The '''UNC File Storage Layout''' setting is changed only after all affected files have been transferred successfully.

=== Transfer Process ===

For each local file document, UBIK:

# calculates the current and target physical file paths
# creates the required target folders
# copies the file to the target path
# verifies that the copied file exists
# deletes the source file only after successful verification

If a file already exists at the target path, the transfer is aborted to prevent data loss.

The transfer changes only the physical storage location. It does not:

* change '''LOCALPATH'''
* update UTS
* create a new document version
* update the update session
* fire events

Empty folders may remain in the previous folder structure after the transfer, but they no longer contain transferred files.

=== Access During the Transfer ===

Local file documents are locked database-wide for all clients and services while the transfer is running. During this time, users and services cannot:

* create new local file document objects
* change existing local file document objects or their properties
* open, read, download, or view local document files

Cloud documents and non-local file documents remain available and are not affected by the lock.

== Transfer Result and Error Handling ==

After a successful transfer, UBIK changes the database setting to the target layout and displays the number of transferred files.

Example:

:''1000 files have been transferred.''

If the transfer fails or is interrupted:

* the transfer is aborted
* the affected file document is reported
* the '''UNC File Storage Layout''' setting remains unchanged
* the database is not left with a mixed UNC storage layout
* the administrator must start the transfer again

A transfer is aborted if a file cannot be found, copied, verified, or deleted, or if the target file already exists.

Failure message:

:''The transfer could not be completed. The UNC File Storage Layout has not been changed.''

== Example: Migrating an Existing Database ==

An existing UBIK database contains 1000 local file documents in flat UNC storage.

# The system is updated to UBIK 5.2.
# The existing File Storage Mode remains unchanged.
# The new '''UNC File Storage Layout''' setting is initialized as '''Flat'''.
# All existing documents remain readable in their current locations.
# An administrator selects ''Tools → Apply UNC File Storage Layout to All Files''.
# UBIK locks local file documents and transfers all files to the generated folder structure.
# After all files have been copied, verified, and removed from their source locations, the layout setting changes to '''Folder Partitioning'''.
# UBIK confirms that 1000 files have been transferred. 
 
From this point onward, newly created local file documents are stored using folder partitioning.

== See also ==

* [[SYSCLS_DOCUMENT]]
* [[SYSCLS_FILEDOCUMENT]]
* [[FILEDOCUMENT]]
* [[SYSCLS_EDITABLEDOCUMENT]]
* [[Documents (Client)]]

[[Category:Document|UNC File Storage Layout]]
[[Category:Studio|UNC File Storage Layout]]
[[Category:Studio tools|UNC File Storage Layout]]

UNC File Storage Layout

2026-09-04T10:13:09Z

LMA:

UNC File Storage Layout

2026-09-04T10:09:02Z

LMA:

= UNC File Storage Layout =

The UNC File Storage Layout defines how local file documents are physically stored in the UNC document root. UBIK supports a flat layout and a folder-partitioned layout.

Folder partitioning is available from UBIK 5.2 and is the recommended layout for UNC file storage. To maintain downward compatibility, the default remains the existing flat layout until an administrator starts the transfer.

The layout changes only the physical file location. The document object and its '''LOCALPATH''' value remain unchanged.

== Scope ==

The UNC File Storage Layout applies only when '''File Storage Mode''' is set to '''UNC'''.

Folder partitioning is not a separate File Storage Mode. The existing modes remain unchanged:

{| class="wikitable"
! Value
! File Storage Mode
|-
| 0
| Undefined
|-
| 1
| UNC
|-
| 2
| Cloud
|}

Only local file documents with '''IsLocalDoc = true''' are affected. Cloud documents and non-local file documents are ignored.

== UNC File Storage Layout Setting ==

The database setting '''UNC File Storage Layout''' identifies the layout currently used by the database.

{| class="wikitable"
! Value
! Description
|-
| Flat
| Local file documents are stored directly in the document root folder.
|-
| Folder Partitioning
| Local file documents are distributed across generated subfolders based on the document UID.
|}

The setting is visible in the database settings but is read-only. It can be changed only by successfully completing the transfer tool.

For new and existing databases, the default value is '''Flat'''. Updating a database does not change its existing '''File Storage Mode''' or move any files automatically.

== Storage Layouts ==

=== Flat ===

With the flat layout, local file documents are stored directly in the document root folder.

Example:

:''.../doc/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

=== Folder Partitioning ===

With folder partitioning, UBIK generates two folder levels from the document UID:

* The first character of the UID is used for the first folder level.
* The second and third characters of the UID are used for the second folder level.
* Generated folder names use lowercase characters.

Example UID:

:''8ec24142-17eb-4640-bdcf-31d696c398de''

Resulting physical path:

:''.../doc/8/ec/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

== LOCALPATH and Physical File Resolution ==

The '''LOCALPATH''' property continues to contain only the file name and extension:

:''8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

Folder-partitioning subfolders are not stored in '''LOCALPATH'''. UBIK calculates the complete physical file path when the file is accessed, using:

* the document root path
* the File Storage Mode
* the UNC File Storage Layout
* the document UID and '''LOCALPATH'''

== Database-wide Layout ==

A database uses one UNC storage layout for all local file documents. Flat storage and folder partitioning must not be mixed within the same database.

After a successful transfer, all existing and newly created local file documents use the selected layout.

== Transferring Local File Documents ==

Administrators can transfer all local file documents to the other layout using:

:''Tools → Apply UNC File Storage Layout to All Files''

Tooltip:

:''Updates all local files to use the other UNC file storage layout.''

The tool is available only when '''File Storage Mode = UNC'''. Because there are only two layouts, UBIK determines the target automatically:

{| class="wikitable"
! Current layout
! Target layout
|-
| Flat
| Folder Partitioning
|-
| Folder Partitioning
| Flat
|}

The '''UNC File Storage Layout''' setting is changed only after all affected files have been transferred successfully.

=== Transfer Process ===

For each local file document, UBIK:

# calculates the current and target physical file paths
# creates the required target folders
# copies the file to the target path
# verifies that the copied file exists
# deletes the source file only after successful verification

If a file already exists at the target path, the transfer is aborted to prevent data loss.

The transfer changes only the physical storage location. It does not:

* change '''LOCALPATH'''
* update UTS
* create a new document version
* update the update session
* fire events

Empty folders may remain in the previous folder structure after the transfer, but they no longer contain transferred files.

=== Access During the Transfer ===

Local file documents are locked database-wide for all clients and services while the transfer is running. During this time, users and services cannot:

* create new local file document objects
* change existing local file document objects or their properties
* open, read, download, or view local document files

Cloud documents and non-local file documents remain available and are not affected by the lock.

== Transfer Result and Error Handling ==

After a successful transfer, UBIK changes the database setting to the target layout and displays the number of transferred files.

Example:

:''1000 files have been transferred.''

If the transfer fails or is interrupted:

* the transfer is aborted
* the affected file document is reported
* the '''UNC File Storage Layout''' setting remains unchanged
* the database is not left with a mixed UNC storage layout
* the administrator must start the transfer again

A transfer is aborted if a file cannot be found, copied, verified, or deleted, or if the target file already exists.

Failure message:

:''The transfer could not be completed. The UNC File Storage Layout has not been changed.''

== Example: Migrating an Existing Database ==

An existing UBIK database contains 1000 local file documents in flat UNC storage.

# The system is updated to UBIK 5.2.
# The existing File Storage Mode remains unchanged.
# The new '''UNC File Storage Layout''' setting is initialized as '''Flat'''.
# All existing documents remain readable in their current locations.
# An administrator selects ''Tools → Apply UNC File Storage Layout to All Files''.
# UBIK locks local file documents and transfers all files to the generated folder structure.
# After all files have been copied, verified, and removed from their source locations, the layout setting changes to '''Folder Partitioning'''.
# UBIK confirms that 1000 files have been transferred.

From this point onward, newly created local file documents are stored using folder partitioning.

[[Category:Document|UNC File Storage Layout]]

UNC File Storage Layout

2026-09-04T10:06:24Z

LMA: Created page with "= UNC File Storage Layout = The UNC File Storage Layout defines how local file documents are physically stored in the UNC document root. UBIK supports a flat layout and a fol..."

= UNC File Storage Layout =

The UNC File Storage Layout defines how local file documents are physically stored in the UNC document root. UBIK supports a flat layout and a folder-partitioned layout.

Folder partitioning is available from UBIK 5.2 and is the recommended layout for UNC file storage. To maintain downward compatibility, the default remains the existing flat layout until an administrator starts the transfer.

The layout changes only the physical file location. The document object and its '''LOCALPATH''' value remain unchanged.

== Scope ==

The UNC File Storage Layout applies only when '''File Storage Mode''' is set to '''UNC'''.

Folder partitioning is not a separate File Storage Mode. The existing modes remain unchanged:

{| class="wikitable"
! Value
! File Storage Mode
|-
| 0
| Undefined
|-
| 1
| UNC
|-
| 2
| Cloud
|}

Only local file documents with '''IsLocalDoc = true''' are affected. Cloud documents and non-local file documents are ignored.

== UNC File Storage Layout Setting ==

The database setting '''UNC File Storage Layout''' identifies the layout currently used by the database.

{| class="wikitable"
! Value
! Description
|-
| Flat
| Local file documents are stored directly in the document root folder.
|-
| Folder Partitioning
| Local file documents are distributed across generated subfolders based on the document UID.
|}

The setting is visible in the database settings but is read-only. It can be changed only by successfully completing the transfer tool.

For new and existing databases, the default value is '''Flat'''. Updating a database does not change its existing '''File Storage Mode''' or move any files automatically.

== Storage Layouts ==

=== Flat ===

With the flat layout, local file documents are stored directly in the document root folder.

Example:

:''.../doc/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

=== Folder Partitioning ===

With folder partitioning, UBIK generates two folder levels from the document UID:

* The first character of the UID is used for the first folder level.
* The second and third characters of the UID are used for the second folder level.
* Generated folder names use lowercase characters.

Example UID:

:''8ec24142-17eb-4640-bdcf-31d696c398de''

Resulting physical path:

:''.../doc/8/ec/8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

== LOCALPATH and Physical File Resolution ==

The '''LOCALPATH''' property continues to contain only the file name and extension:

:''8ec24142-17eb-4640-bdcf-31d696c398de.jpg''

Folder-partitioning subfolders are not stored in '''LOCALPATH'''. UBIK calculates the complete physical file path when the file is accessed, using:

* the document root path
* the File Storage Mode
* the UNC File Storage Layout
* the document UID and '''LOCALPATH'''

== Database-wide Layout ==

A database uses one UNC storage layout for all local file documents. Flat storage and folder partitioning must not be mixed within the same database.

After a successful transfer, all existing and newly created local file documents use the selected layout.

== Transferring Local File Documents ==

Administrators can transfer all local file documents to the other layout using:

:''Tools → Apply UNC File Storage Layout to All Files''

Tooltip:

:''Updates all local files to use the other UNC file storage layout.''

The tool is available only when '''File Storage Mode = UNC'''. Because there are only two layouts, UBIK determines the target automatically:

{| class="wikitable"
! Current layout
! Target layout
|-
| Flat
| Folder Partitioning
|-
| Folder Partitioning
| Flat
|}

The '''UNC File Storage Layout''' setting is changed only after all affected files have been transferred successfully.

=== Transfer Process ===

For each local file document, UBIK:

# calculates the current and target physical file paths
# creates the required target folders
# copies the file to the target path
# verifies that the copied file exists
# deletes the source file only after successful verification

If a file already exists at the target path, the transfer is aborted to prevent data loss.

The transfer changes only the physical storage location. It does not:

* change '''LOCALPATH'''
* update UTS
* create a new document version
* update the update session
* fire events

Empty folders may remain in the previous folder structure after the transfer, but they no longer contain transferred files.

=== Access During the Transfer ===

Local file documents are locked database-wide for all clients and services while the transfer is running. During this time, users and services cannot:

* create new local file document objects
* change existing local file document objects or their properties
* open, read, download, or view local document files

Cloud documents and non-local file documents remain available and are not affected by the lock.

== Transfer Result and Error Handling ==

After a successful transfer, UBIK changes the database setting to the target layout and displays the number of transferred files.

Example:

:''1000 files have been transferred.''

If the transfer fails or is interrupted:

* the transfer is aborted
* the affected file document is reported
* the '''UNC File Storage Layout''' setting remains unchanged
* the database is not left with a mixed UNC storage layout
* the administrator must start the transfer again

A transfer is aborted if a file cannot be found, copied, verified, or deleted, or if the target file already exists.

Failure message:

:''The transfer could not be completed. The UNC File Storage Layout has not been changed.''

== Example: Migrating an Existing Database ==

An existing UBIK database contains 1000 local file documents in flat UNC storage.

# The system is updated to UBIK 5.2.
# The existing File Storage Mode remains unchanged.
# The new '''UNC File Storage Layout''' setting is initialized as '''Flat'''.
# All existing documents remain readable in their current locations.
# An administrator selects ''Tools → Apply UNC File Storage Layout to All Files''.
# UBIK locks local file documents and transfers all files to the generated folder structure.
# After all files have been copied, verified, and removed from their source locations, the layout setting changes to '''Folder Partitioning'''.
# UBIK confirms that 1000 files have been transferred.

From this point onward, newly created local file documents are stored using folder partitioning.

MRO Material Management

2026-09-04T08:37:53Z

LMA: /* See also */

== MRO Material Management ==

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Summary:''' The MRO material management features provide the foundation for handling materials, material master data, reservations, storage locations, and goods movements in MRO workflows. The central objects are Material, MaterialMaster, and Reservation. Materials are linked to master data and storage locations. Reservations are created manually by users and link materials to tasks.
</div>

MRO material management is used to support maintenance work with required spare parts, consumables, tools, or other material items.

Users can see which material is required for a task, where the material is stored, how much material is available, how much material is reserved, and which reservation status applies.

== Basic concept ==

{| class="wikitable"
! Object
! Type
! Purpose
|-
| MaterialMaster
| Master data
| Defines the catalogue entry for a material, including item number, unit, packaging, manufacturer data, and material type.
|-
| Material
| Quantity-bearing MRO object
| Represents a material instance or stock entry in MRO. It links to a material master and a storage location and exposes quantity, reserved quantity, and available quantity logic.
|-
| Reservation
| Workflow object
| Represents a manually created material reservation for a task. It links a material to a task and stores planned and actual quantities.
|-
| GoodsMovement
| Technical base class
| Provides the common QUANTITY property used by both materials and reservations.
|-
| StorageLocation
| Related storage object
| Represents a physical storage location for materials.
|}

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Core idea:''' MaterialMaster defines what the material is. Material represents the material in stock or material context. Reservation links a material to a task and reserves a planned quantity for maintenance execution.
</div>

== MaterialMaster ==

=== Purpose ===

MaterialMaster represents the material master or catalogue entry.

It stores item-level master data that can be referenced by material instances in MRO.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| ITEM_NUMBER
| string
| Item number or material number.
|-
| PACKAGING_UNIT
| string
| Packaging unit.
|-
| PACKAGING_SIZE
| double
| Packaging size.
|-
| ACTIVE
| bool
| Defines whether the material master is active.
|-
| UNIT_OF_MEASURE
| string
| Unit of measure.
|-
| MATERIAL_TYPE / MaterialType
| int / enum
| Material type.
|-
| MANUFACTURER_COMPANY_NAME
| string
| Manufacturer company name.
|-
| MANUFACTURER_PRODUCT_TAG
| string
| Manufacturer product tag or product identifier.
|}

=== Material type ===

Values of MaterialType are:

* SpareParts
* Consumables
* Tools

== Material ==

=== Purpose ===

Material represents a material instance or stock entry in MRO.

It inherits from GoodsMovement and therefore uses the inherited QUANTITY property as its material quantity.

A material links to:

* a material master via LK_MATERIAL_MASTER
* a storage location via LK_STORAGE_LOCATION

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Stored or calculated
|-
| LK_MATERIAL_MASTER
| MaterialMaster
| Link to the material master data.
| Stored link
|-
| LK_STORAGE_LOCATION
| StorageLocation
| Link to the storage location where the material is located.
| Stored link
|-
| QUANTITY
| double
| Material quantity. Inherited from GoodsMovement.
| Stored property
|-
| RESERVED_QUANTITY
| double
| Sum of planned quantities of confirmed reservations for this material.
| Calculated property
|-
| MATERIAL_STATUS / MaterialStatus
| int / enum
| Material status.
| User/admin managed property
|}

=== Material status ===

The material status is stored in MATERIAL_STATUS and exposed through MaterialStatus.

The property is managed by the user or administrator. The system does not change it automatically.

{| class="wikitable"
! Value
! Numeric value
! Meaning
|-
| Undefined
| 0
| No specific material status is defined.
|-
| Inactive
| 10
| Material is inactive and should not be used for new reservations.
|-
| Active
| 20
| Material is active and can be used for reservations.
|}

=== Reserved quantity ===

RESERVED_QUANTITY is calculated at read time.

The calculation uses reservations where:

* LK_MATERIAL points to the current material
* STATUS is ReservationStatus.Confirmed

The calculated value is the sum of QTY_PLANNED of these confirmed reservations.

=== Available quantity ===

The available material quantity is calculated by AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Delete behavior ===

Material.InternalDeleteAllowed() prevents deleting a material if it still has quantity or active reservations.

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' A Material cannot be deleted while it has a quantity greater than 0 or active reservations.
</div>

== Reservation ==

=== Purpose ===

Reservation represents a manually created material reservation for a task.

It links:

* a task via LK_TASK
* a material via LK_MATERIAL

It stores the planned reservation quantity in QTY_PLANNED and the actually issued or consumed quantity in QUANTITY.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Important behavior
|-
| LK_TASK
| Task
| Link to the task for which the material is reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| LK_MATERIAL
| Material
| Link to the material being reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| STATUS / Status
| int / enum
| Reservation status.
| Changes are validated by AllowStatusChange(int newStatus).
|-
| QTY_PLANNED
| double
| Planned quantity for the reservation.
| Setter validates through AllowQuantityPlanned(double).
|-
| QUANTITY
| double
| Actually issued or consumed quantity. Overrides GoodsMovement.QUANTITY.
| Setter validates through AllowQuantity(double).
|}

=== Reservation status ===

Values of ReservationStatus are:

{| class="wikitable"
! Status
! Numeric value
! Meaning
|-
| Planned
| 0
| Reservation is planned.
|-
| Confirmed
| 10
| Reservation is confirmed and contributes to the material's reserved quantity.
|-
| Issued
| 20
| Material has been physically issued.
|-
| Cancelled
| 30
| Reservation was cancelled.
|-
| Expired
| 50
| Reservation has expired.
|}

=== Status change rules ===

Status changes are controlled by AllowStatusChange(int newStatus).

The following rules are applied:

* no status change is allowed when the current status is Issued
* changing from Confirmed back to Planned is not allowed
* other status changes are allowed by this method

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' Once a reservation has status Issued, its status can no longer be changed by the normal status setter logic.
</div>

=== Planned quantity validation ===

The setter of QTY_PLANNED validates changes through AllowQuantityPlanned(double).

A new planned quantity is only allowed if:

* Status is ReservationStatus.Planned
* LK_MATERIAL is assigned
* the new quantity is greater than 0
* the new quantity is lower than or equal to LK_MATERIAL.AvailableQuantity()

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Quantity rule:''' A planned reservation quantity can only be set while the reservation is still Planned and only if the selected material has enough available quantity.
</div>

=== Actual quantity validation ===

The overridden QUANTITY setter validates changes through AllowQuantity(double).

A new actual quantity is only allowed if:

* the new quantity is greater than 0
* the status is either Planned or Confirmed

=== Link editing rules ===

The setters of LK_TASK and LK_MATERIAL are guarded by reservation status.

The links cannot be changed when the reservation is:

* Issued
* Confirmed

== StorageLocation ==

=== Purpose ===

StorageLocation is a related object used to represent a physical storage location.

A material can reference a storage location via LK_STORAGE_LOCATION.

=== Important properties and values ===

{| class="wikitable"
! Property
! Type
! Values / meaning
|-
| STORAGE_TYPE / StorageType
| int / enum
| Floor, Shelf, Rack, Bin, Pallet, Container
|-
| ACCESS_TYPE / AccessType
| int / enum
| Manual, Forklift, Crane, Automated
|-
| OCCUPANCY_STATUS / OccupancyStatus
| int / enum
| Empty, Partial, Full, Reserved, Blocked, OutOfService
|-
| STORAGE_LABEL
| string
| Label of the storage location.
|-
| LEVEL
| int
| Level of the storage location.
|-
| POSITION
| string
| Position identifier.
|}

== GoodsMovement ==

GoodsMovement is a technical base class.

It provides the common QUANTITY property for material-related objects such as Material and Reservation.

== Quantity concepts ==

{| class="wikitable"
! Quantity
! Property / method
! Object
! Stored or calculated
! Notes
|-
| Material quantity
| QUANTITY
| Material
| Stored
| Inherited from GoodsMovement.
|-
| Reserved quantity
| RESERVED_QUANTITY
| Material
| Calculated
| Sum of QTY_PLANNED of confirmed reservations for the material.
|-
| Available quantity
| AvailableQuantity()
| Material
| Calculated
| QUANTITY minus RESERVED_QUANTITY.
|-
| Planned reservation quantity
| QTY_PLANNED
| Reservation
| Stored
| Validated by AllowQuantityPlanned(double).
|-
| Actually issued or consumed quantity
| QUANTITY
| Reservation
| Stored
| Overrides GoodsMovement.QUANTITY and is validated by AllowQuantity(double).
|}

== Reservation workflow ==

=== Creating or editing a reservation ===

Reservations are created manually by the user.

A reservation links a material to a task.

For a reservation to define its planned quantity correctly:

# LK_MATERIAL must be set.
# LK_TASK must point to the task requiring the material.
# Status must still be Planned.
# QTY_PLANNED must be greater than 0.
# QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().

=== Confirmed reservations ===

When a reservation is confirmed, it contributes to the material's reserved quantity.

This affects the available quantity of the material.

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - sum(QTY_PLANNED of confirmed reservations)
</div>

=== Finishing a task ===

When a task is finished, the task logic calls CloseReservations().

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Workflow effect:''' Finishing a task closes its reservations. Confirmed reservations become Issued; other active reservations become Cancelled.
</div>

== Usage in tasks ==

Reservations are the central link between material handling and task execution.

A reservation connects:

* the required material through LK_MATERIAL
* the task through LK_TASK
* the planned quantity through QTY_PLANNED
* the actually issued or consumed quantity through QUANTITY
* the reservation state through Status

This means that material usage is tracked at task level.

== Example workflow ==

=== Step 1: Material master exists ===

A spare part is defined as a MaterialMaster.

{| class="wikitable"
! Field
! Example
|-
| ITEM_NUMBER
| OF-10045
|-
| UNIT_OF_MEASURE
| Piece
|-
| MaterialType
| SpareParts
|}

=== Step 2: Material exists in a storage location ===

A Material object references the material master and a storage location.

{| class="wikitable"
! Property
! Example
|-
| LK_MATERIAL_MASTER
| Oil Filter Type A
|-
| LK_STORAGE_LOCATION
| Storage Shelf A
|-
| QUANTITY
| 10
|-
| RESERVED_QUANTITY
| 0
|-
| AvailableQuantity()
| 10
|}

=== Step 3: Reservation is created for a task ===

A user manually creates a Reservation and links the material to the task.

{| class="wikitable"
! Property
! Example
|-
| LK_TASK
| Replace oil filter
|-
| LK_MATERIAL
| Oil Filter Type A
|-
| Status
| Planned
|-
| QTY_PLANNED
| 1
|}

=== Step 4: Reservation is confirmed ===

The reservation status is changed to Confirmed.

After confirmation, the material's reserved quantity includes the reservation's planned quantity.

{| class="wikitable"
! Quantity
! Value
|-
| Material.QUANTITY
| 10
|-
| Material.RESERVED_QUANTITY
| 1
|-
| Material.AvailableQuantity()
| 9
|}

=== Step 5: Actual quantity is entered ===

The actually issued or consumed quantity is stored in Reservation.QUANTITY.

{| class="wikitable"
! Property
! Example
|-
| Reservation.QUANTITY
| 1
|}

=== Step 6: Task is finished ===

When the task is finished, CloseReservations() is called.

The confirmed reservation is changed to Issued.

== Validation and business rules ==

{| class="wikitable"
! Area
! Rule
|-
| Planned reservation quantity
| QTY_PLANNED must be greater than 0.
|-
| Planned reservation quantity
| QTY_PLANNED can only be changed while the reservation is Planned.
|-
| Planned reservation quantity
| QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().
|-
| Actual issued or consumed quantity
| QUANTITY must be greater than 0.
|-
| Actual issued or consumed quantity
| QUANTITY can only be changed while the reservation is Planned or Confirmed.
|-
| Reservation status
| Status cannot be changed once the reservation is Issued.
|-
| Reservation status
| A reservation cannot be changed from Confirmed back to Planned.
|-
| Reservation links
| LK_TASK and LK_MATERIAL cannot be changed when status is Issued or Confirmed.
|-
| Material deletion
| Material cannot be deleted while QUANTITY is greater than 0.
|-
| Material deletion
| Material cannot be deleted while active reservations exist.
|}

== See also ==
* [[MRO (Plugin)]]
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROMaintenancePlans]]
* [[MRO_Notification]]

MRO Notification

2026-09-04T08:35:33Z

LMA: Created page with "An MRO Notification represents a reported maintenance issue related to an Asset. It records the responsible user, due date, priority, and current processing status. A Notifica..."

An MRO Notification represents a reported maintenance issue related to an Asset. It records the responsible user, due date, priority, and current processing status. A Notification can also serve as the origin of a [[MRO (Plugin)#Work Package|Work Package]]. The created Work Package references the Notification so that its origin remains traceable.

Technical object name: NOTIFICATION

Runtime class: UBIK.MRO.Notification

== Creating and Editing Notifications ==

A Notification is created for an Asset using LK_ASSET. Functional Locations and Equipment can be referenced because they are specialized Asset types.

In addition to the standard properties of a {{UBIK}} content object, a Notification provides MRO-specific properties for its Asset, assigned user, due date, priority, status, and optional Work Package template. These properties can be edited after creation. Changes to NOTIF_STATUS are restricted by the [[#Notification Status|defined status transitions]].

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| LK_ASSET || {{Guid}} || Link to the Asset for which the Notification was created
|-
| LK_WP_TMPL || {{Guid}} || Optional link to a Work Package template
|-
| LK_ASGN_USER || {{Guid}} || Link to the assigned user
|-
| NOTIF_DUE_DATE || {{DateTime}} || Due date of the Notification
|-
| NOTIF_PRIORITY || {{Integer}} || Priority of the Notification
|-
| NOTIF_STATUS || {{Integer}} || Current processing status of the Notification
|}

=== Notification Priority ===

The priority is stored in NOTIF_PRIORITY. The following values are available:

{| class="wikitable" width="50%"
|-
! Value !! Name !! Description
|-
| 0 || Undefined || No priority has been assigned
|-
| 10 || Low || Low priority
|-
| 20 || Medium || Medium priority
|-
| 30 || High || High priority
|}

=== Notification Status ===

The current processing state is stored in NOTIF_STATUS. The following values are available:

{| class="wikitable" width="50%"
|-
! Value !! Status
|-
| 0 || Undefined
|-
| 10 || New
|-
| 20 || Confirmed
|-
| 30 || In Progress
|-
| 40 || Completed
|-
| 50 || Rejected
|-
| 60 || Closed
|}

Status changes are validated by the Notification. Only the following transitions are permitted:

{| class="wikitable" width="70%"
|-
! Current status !! Permitted next status
|-
| Undefined || New
|-
| New || Confirmed or Rejected
|-
| Confirmed || In Progress
|-
| In Progress || Completed
|-
| Completed || Closed
|-
| Rejected || Closed
|-
| Closed || No further transition
|}

Setting the same status again is permitted. Other status changes are rejected. Completed and Rejected Notifications can only be moved to Closed and cannot be reopened through the standard status logic.

== Creating a Work Package from a Notification ==

A Work Package can be created from a Notification either using a Maintenance Plan or through manual creation. In both cases, the created Work Package is linked to the originating Notification using LK_NOTIFICATION. This makes the origin of the Work Package traceable.

=== Maintenance Plan-based Creation ===

For Maintenance Plan-based creation, the Maintenance Plans assigned to the Notification's Asset are evaluated.

* If multiple Maintenance Plans are available, one of them is selected for the creation.
* The Work Package is created based on the selected Maintenance Plan and its Work Package template.
* The created Work Package references the originating Notification through LK_NOTIFICATION.

=== Manual Creation ===

For manual creation, a new Work Package is created for the same Asset as the Notification.

* The Work Package is linked to the Asset referenced by LK_ASSET.
* The Work Package references the originating Notification through LK_NOTIFICATION.
* Subordinate Work Packages and Tasks can be added to structure the required maintenance work.

'''Relevant Work Package property'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| LK_NOTIFICATION || {{Guid}} || Link from the Work Package to the originating Notification
|}

== Supporting File Documents ==

The FileDocumentNotification class provides document attachments for Notifications. Each document is linked to its Notification using LK_NOTIFICATION.

Runtime class: UBIK.MRO.FileDocumentNotification

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| LK_NOTIFICATION || {{Guid}} || Link to the associated Notification
|}

The MRO Notification implementation does not define additional restrictions for file types, file sizes, or the number of attached documents.

== See also ==

* [[MRO (Plugin)]]
* [[MRO (Plugin)#Work Package|Work Package]]
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROMaintenancePlans]]
* [[MRO_Material_Management]]

2026-08-17T11:08:40Z

LMA:

The MRO plugin provides a set of {{UBIK}} objects for representing and documenting maintenance, repair and operations work. The MRO features are available in the supported Mobile and {{UBIK WinX}} clients.

This page is the main documentation for the MRO object model and its task types. Common client behaviour, such as status indicators, locking, and the general evaluation of sequential and grouped tasks, is documented in [[MRO Objects (Client)]].

{| class="wikitable"
|-
! Page !! Scope
|-
| '''MRO (Plugin)''' || MRO concepts, task types, task-specific behaviour, and relevant technical properties
|-
| [[MRO Objects (Client)]] || Common client presentation, status indicators, locking, and behaviour shared by multiple MRO objects
|}

== Basic Features ==

Objects classified as MRO objects generally provide a technical and organisational status as well as an overall work progress based on their underlying data branch.

=== Technical Status ===

For detailed information, see [[MRO Objects (Client)#Technical Status|Technical Status]].

=== Organisational Status ===

For detailed information, see [[MRO Objects (Client)#Organisational Status|Organisational Status]].

=== Work Progress ===

For detailed information, see [[MRO Objects (Client)#Work Progress|Work Progress]].

== MRO Objects ==

MRO uses Task Owners, Work Packages, Tasks, and Procedure Workpackages to represent maintenance workflows.

=== Task Owner ===

A [[MROCLS_MRO_TASKOWNER|Task Owner]] is an object with an underlying structure of work to be performed. It can contain other Task Owners or Work Packages. Their technical status, organisational status, and work progress are accumulated and reported to the Task Owner.

=== Work Package ===

A [[MROCLS_MRO_WORKPACKAGE|Work Package]] collects and summarizes Task Owners, other Work Packages, or Tasks. A Work Package can be confirmed when all associated Tasks have reached the required progress and all subordinate Work Packages have been confirmed.

For Work Package presentation and confirmation in the clients, see [[MRO Objects (Client)#Work Package|Work Package]].

=== Task ===

A [[MROCLS_MRO_TASK|Task]] reports work progress to its owning Work Package. The available task types provide different input, validation, or automatic workflow behaviour.

MRO task values must be validated for work progress to be calculated. A MetaAttribute providing a validation timestamp must therefore be attached to the relevant MetaProperty.

{{Attention|A task value property has to use [[Attributes]] so that its value can be validated. Otherwise, work progress cannot be calculated.}}

All user-editable MRO task types can be set to ''Not Applicable''. In the clients, a completed user-editable task can be reset by selecting ''Not Applicable'' twice. General client behaviour is documented in [[MRO Objects (Client)#Task|Task]].

=== Procedure Workpackage ===

Technical object name: '''PROCEDURE_WORKPACKAGE'''

A [[MROCLS_PROCEDURE|Procedure Workpackage]] is a specialized Work Package for structured workflows. Its structure is defined in JSON using a workflow editor and can contain Tasks as well as subordinate Procedure Workpackages. Depending on its state, the corresponding objects are created or updated.

Procedure Workpackages can use sequential execution, grouped Tasks, branching, calculations, and references to linked data. Their workflows support online and offline use. Steps that require data exchange wait until connectivity is available.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| PROCEDURE_STATUS || {{Integer}} || Current state: Draft = 10, ReadyToUse = 20, Published = 30, Open = 40, Executing = 50, Completed = 60, Approved = 70, Rejected = 80
|-
| JSON || {{String}} || JSON representation of the Procedure Workpackage
|-
| ISTEMPLATE || {{Boolean}} || Indicates whether the Procedure Workpackage is a template
|}

== MRO Task Types ==

The following task types are available in MRO. The technical object names are included to make the task types discoverable through the wiki search.

{| class="wikitable sortable"
|-
! Task type !! Technical object name !! Purpose
|-
| [[#Blinding Task|Blinding Task]] || BLINDING_TASK || Documents a blinding or deblinding operation
|-
| [[#Calculation Task|Calculation Task]] || CALCULATION_TASK || Evaluates an expression and writes its result to a target property
|-
| [[#Check Task|Check Task]] || CHECK_TASK || Confirms a Boolean task using a checkbox
|-
| [[#Commissioning Task|Commissioning Task]] || COMMISSIONING_TASK || Represents a task in an MRO commissioning workflow
|-
| [[#Inspection Task|Inspection Task]] || INSPECTION_TASK || Records a Boolean inspection result with configurable labels
|-
| [[#Interface Task|Interface Task]] || INTERFACE_TASK || Waits for completion information from another software system
|-
| [[#Joint Task|Joint Task]] || JOINT_TASK || Documents the state of a joint location
|-
| [[#Numeric Task|Numeric Task]] || NUMERIC_TASK || Records a numeric value and evaluates it against a configured range
|-
| [[#Pick List Task|Pick List Task]] || PICKLIST_TASK || Selects one integer value from an instance-specific Active List
|-
| [[#Picture Task|Picture Task]] || PICTURE_TASK || Requires at least one child document containing a valid file
|-
| [[#Progress Task|Progress Task]] || PROGRESS_TASK || Reports progress between 0% and 100%
|-
| [[#Signature Task|Signature Task]] || SIGNATURE_TASK || Captures a handwritten signature
|-
| [[#Supervisor Check Task|Supervisor Check Task]] || SUPERVISOR_CHECK_TASK || Applies the four-eyes principle to a Check Task
|-
| [[#Switch End Task|Switch End Task]] || SWITCH_END_TASK || Rejoins the branches of a Procedure workflow
|-
| [[#Switch Start Task|Switch Start Task]] || SWITCH_START_TASK || Selects a Procedure branch by evaluating a Boolean expression
|-
| [[#Text Task|Text Task]] || TEXT_TASK || Records free-form text
|}

=== Blinding Task ===

Technical object name: '''BLINDING_TASK'''

A Blinding Task documents either a blinding or deblinding operation at a linked blinding location. The configured operation type determines the state that must be reported to complete the task.

'''Relevant properties'''

{| class="wikitable" width="70%"
|-
! Name !! Description
|-
| BLINDING_TYPE || Configured operation type: Blinding or DeBlinding
|-
| LK_BLINDING_LOCATION || Link to the associated blinding location
|-
| LK_PREVIOUS_TASK || Link to the preceding Blinding Task
|-
| LOCKED || Prevents the task from being edited
|-
| VALUE || Reported blinding state
|}

The task is complete only when '''VALUE''' matches the configured '''BLINDING_TYPE'''.

=== Calculation Task ===

Technical object name: '''CALCULATION_TASK'''

A [[MROCLS_CALCULATION_TASK|Calculation Task]] automatically evaluates a predefined expression on the client and writes the result to a configured property on its owner. No user input is required.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| EXPRESSION || {{String}} || Expression evaluated by the client
|-
| VALUE || {{Integer}} || Evaluation state: Undefined = 0, Pending = 10, Finished = 20, Error = 30
|-
| TARGET_PROPERTY_NAME || {{String}} || Name of the target property on the owner
|-
| TARGET_PROPERTY_TYPE || {{Integer}} || Target type: Undefined = 0, Boolean = 1, Integer = 3, Double = 4
|}

The task is automatically finished after successful evaluation. The clients display an indicator for a successful evaluation or an evaluation error. A Pending state does not receive an additional indicator.

See also [[#Procedure Task Variants and Workflow Execution|Procedure Task Variants and Workflow Execution]].

=== Check Task ===

Technical object name: '''CHECK_TASK'''

A [[MROCLS_MRO_CHECK_TASK|Check Task]] is a simple Boolean task represented by a checkbox. Clicking the checkbox sets its value and completes the task. It can alternatively be completed using ''Not Applicable''.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Boolean}} || Task value and completion
|}

<gallery widths=497px heights=69px>
File:Check Task finished UWP.png|Check Task (WinX)
File:Check Task android.jpg|Not Applicable Check Task (Mobile)
</gallery>

=== Commissioning Task ===

Technical object name: '''COMMISSIONING_TASK'''

A Commissioning Task is a specialized task type used in MRO commissioning workflows.

'''Relevant property'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| NOTAPPLICABLE || {{Boolean}} || Not Applicable state
|}

=== Inspection Task ===

Technical object name: '''INSPECTION_TASK'''

An [[MROCLS_MRO_INSPECTION_TASK|Inspection Task]] captures a Boolean inspection result. The client presents a positive and a negative option as well as ''Not Applicable''. Selecting an option completes the task.

The labels for the positive and negative outcomes can be configured. Selecting the negative outcome displays the configured false label.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Boolean}} || Selected inspection result
|-
| LABEL_TRUE || {{String}} || Label for the positive outcome
|-
| LABEL_FALSE || {{String}} || Label for the negative outcome
|}

<gallery widths=497px heights=69px>
File:Finished Inspection Task UWP.png|Finished Inspection Task (WinX)
File:Inspection task android.jpg|Finished Inspection Task (Mobile)
</gallery>

=== Interface Task ===

Technical object name: '''INTERFACE_TASK'''

An Interface Task waits for another software system to provide its completion value. The task is complete when its Boolean '''VALUE''' becomes true. If the client is offline, the task waits until connectivity and synchronization are available again.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Boolean}} || Task completion supplied by the external software system
|}

=== Joint Task ===

Technical object name: '''JOINT_TASK'''

A Joint Task documents the state of a linked joint location. The user selects one of the available Joint States.

'''Relevant properties'''

{| class="wikitable" width="70%"
|-
! Name !! Description
|-
| LK_JOINT_LOCATION || Link to the associated joint location
|-
| VALUE || Selected Joint State
|}

The available states are:

* Closed
* Disconnected
* Open
* Planned
* Reconnected
* Torqued
* Undefined
* Verified

The Joint Task is complete when its state is '''Planned''' or '''Closed'''.

=== Numeric Task ===

Technical object name: '''NUMERIC_TASK'''

A [[MROCLS_MRO_NUMERIC_TASK|Numeric Task]] records a Double value, for example a value read from a temperature sensor. Entering a value or selecting ''Not Applicable'' completes the task.

The value is compared against a configured acceptable range that cannot be edited on the client. A value outside the range produces visual feedback and sets the technical status to indicate an issue. An invalid configured range, such as a minimum greater than the maximum, also produces an issue when a value is entered.

A value unit can be configured for an individual task. When present, it overrides the standard unit configured on the [[MetaProperty#Unit_Item|MetaProperty]].

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Double}} || Recorded numeric value
|-
| VALUE_UNIT || {{String}} || Instance-specific value unit
|}

=== Pick List Task ===

Technical object name: '''PICKLIST_TASK'''

A [[MROCLS_PICK_LIST_TASK|Pick List Task]] allows the user to select one value from an [[UBIK Active Lists|Active List]] configured on the task instance. It behaves similarly to a standard Integer Task with a Selective List, but the selectable values are supplied by the Active List rather than being defined globally.

Every list item has an Integer value. Selecting an item or selecting ''Not Applicable'' completes the task.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Integer}} || Value of the selected Active List item
|}

=== Picture Task ===

Technical object name: '''PICTURE_TASK'''

A [[MROCLS_PICTURE_TASK|Picture Task]] is a Boolean task that can only be finished when it has at least one child document containing a valid file. Multiple child documents can be attached. Although pictures are the most common files, the child document can contain another file type.

The clients display a file or photo button next to the task checkbox. The task cannot be completed through the checkbox until the file requirement is satisfied. Selecting ''Not Applicable'' is always possible and bypasses the child-document requirement.

When the user attempts to finish the task while online, the client may first synchronize the task's child objects and download the files of its child documents. During synchronization, the checkbox is replaced by a wait indicator.

* If no child document or no local file is available, the task remains unfinished and the user is informed.
* If at least one child document with a valid local file is available, the task is finished and the file or photo button is disabled.

Child-count information can be configured but is not required. WinX can display the child documents in an expander. This is not shown by default on Mobile due to the available screen size, but it can be customized using [[Object_hierarchy_in_XAML:_NextLevel,_ParentLevel,_LinkedLevel#Show_NextLevel_Children.2FDocuments|Show NextLevel Children/Documents]].

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Boolean}} || Task completion
|}

=== Progress Task ===

Technical object name: '''PROGRESS_TASK'''

A [[MROCLS_MRO_PROGRESS_TASK|Progress Task]] reports progress between 0% and 100%. The reported value contributes to the progress of the owning Work Package. Values below 100% represent partial progress; the task is finished only when the reported progress reaches 100%. It can alternatively be completed using ''Not Applicable''.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Double}} || Currently reported progress
|-
| PREVIOUS_VALUE || {{Double}} || Previously reported progress
|}

An [[MRO_PROGRESS_TASK_EDITOR|alternative editor]] is available for Progress Tasks.

<gallery widths=497px heights=69px>
File:Progress Task UWP.png|Progress Task with reported progress (WinX)
File:Progress Task Android.jpg|Progress Task with current and previous progress (Mobile)
</gallery>

=== Signature Task ===

Technical object name: '''SIGNATURE_TASK'''

A Signature Task is completed by capturing a handwritten signature. Selecting the signature editor opens an in-app dialog in which the user can sign. Confirming the signature saves it and automatically completes the task.

When signing while online, the server resolves and displays the signee and generates the validation timestamp. When signing offline, the signee is resolved and displayed once the client is online again. If the complete signee or validation timestamp cannot be displayed in the editor field, selecting the field opens a popup with the complete information.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Signature}} || Captured signature
|}

=== Supervisor Check Task ===

Technical object name: '''SUPERVISOR_CHECK_TASK'''

A Supervisor Check Task applies the four-eyes principle to a Boolean Check Task on one device. The worker hands the device to a supervisor. The supervisor scans an NFC tag and enters the supervisor PIN. After successful authentication, the checkbox is enabled and must still be selected to finish the task.

Selecting ''Not Applicable'' does not require supervisor authentication.

Successful supervisor authentication removes only the supervisor-related lock. The task can remain locked for another reason, such as sequential dependencies or user rights. If an incorrect PIN is entered three times, authentication is cancelled and the NFC tag has to be scanned again. A setting controls [[RFID tags#Choose which information to use from a tag|which tag information is used]].

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Boolean}} || Check Task completion
|-
| SUPERVISOR || {{Guid}} || Authenticated supervisor
|-
| PERMISSION || {{String}} || Required supervisor permission
|}

<gallery widths=300px heights=300px>
File:UI_Xamarin_Supervisor_Task_Before_Verification.jpg|Supervisor Check Task before verification
File:UI_Xamarin_Supervisor_Task_Enter_PIN.jpg|Supervisor PIN entry
File:UI_Xamarin_Supervisor_Task_After_Verification.jpg|Supervisor Check Task after verification
</gallery>

=== Switch End Task ===

Technical object name: '''SWITCH_END_TASK'''

A [[MROCLS_SWITCH_END_TASK|Switch End Task]] marks the point at which the two branches created by a Switch Start Task merge again. It is linked to exactly one corresponding Switch Start Task. It is not shown to the user and completes automatically after the selected branch has finished, allowing the common Procedure workflow to continue.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{Boolean}} || Task completion
|-
| LK_SWITCH_START_TASK || {{Guid}} || Link to the corresponding Switch Start Task
|}

See also [[#Procedure Task Variants and Workflow Execution|Procedure Task Variants and Workflow Execution]].

=== Switch Start Task ===

Technical object name: '''SWITCH_START_TASK'''

A [[MROCLS_SWITCH_START_TASK|Switch Start Task]] is a sequential workflow-control task used in a Procedure Workpackage. It automatically evaluates a Boolean expression on the client and selects either the true or false branch. Each branch represents a different path of Tasks and must lead to a corresponding Switch End Task.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| EXPRESSION || {{String}} || Expression evaluated by the client
|-
| VALUE || {{Integer}} || Evaluation state: Undefined = 0, Pending = 10, Finished = 20, Error = 30
|-
| BRANCH_TRUE || {{Guid}} || Link to the Task or Task Owner that starts the true branch
|-
| BRANCH_FALSE || {{Guid}} || Link to the Task or Task Owner that starts the false branch
|-
| DISPLAYSTRING_TRUE || {{String}} || Display string for a true result
|-
| DISPLAYSTRING_FALSE || {{String}} || Display string for a false result
|-
| EVALUATION_RESULT || {{Boolean}} || Result of the evaluated expression
|}

After evaluation, only the selected branch is executed. The other branch remains hidden and its Procedure Tasks are set to ''Not Applicable''.

See also [[#Procedure Task Variants and Workflow Execution|Procedure Task Variants and Workflow Execution]].

=== Text Task ===

Technical object name: '''TEXT_TASK'''

A Text Task allows the user to enter free-form text. Entering a value or selecting ''Not Applicable'' completes the task.

'''Properties'''

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| VALUE || {{String}} || Entered text
|}

== Supervisor Base Type ==

Technical object name: '''SUPERVISOR_TASK'''

Supervisor Task is a base type that provides supervisor authentication behaviour. It is not used as a standalone user task. The concrete task type using this behaviour is [[#Supervisor Check Task|Supervisor Check Task]].

== Procedure Task Variants and Workflow Execution ==

Procedure variants are specialized versions of task types for use within Procedure Workpackages. They retain the behaviour of their corresponding task type and additionally implement the [[MROCLS_SEQUENTIALTASK|Sequential Task]] and [[MROCLS_GROUPEDTASK|Grouped Task]] classifications.

Procedure variants are available for:

* Calculation Task
* Check Task
* Inspection Task
* Interface Task
* Numeric Task
* Pick List Task
* Picture Task
* Signature Task
* Supervisor Check Task
* Text Task

Switch Start Tasks, Switch End Tasks, and Calculation Tasks provide automatic workflow-control behaviour in a Procedure Workpackage.

For automatic Calculation and Switch Start Tasks, the clients display an evaluation indicator:

* '''Finished:''' The Task was automatically evaluated successfully.
* '''Error:''' The Task was evaluated but resulted in an error.
* '''Pending:''' The Task has not yet been evaluated. No additional indicator is displayed for this state.

When a predecessor Switch Start Task has not yet finished, its follow-up Procedure Tasks are hidden because the relevant branch is not yet known. After evaluation, the selected branch becomes visible. The other branch remains hidden, is not executed, and its Procedure Tasks are set to ''Not Applicable''.

For example, several predecessor Numeric Tasks can record temperatures from different parts of an equipment. A subsequent Calculation Task can calculate their average. A Switch Start Task can then select a branch based on whether the average exceeds a configured temperature. One branch can contain a Task for activating a cooling mechanism, while the other branch can lead directly to the Switch End Task or contain further Switch Tasks.

Procedure Tasks are intended to execute automatically when their predecessors are finished. However, the completion of the predecessor has to be triggered by a user. If a predecessor becomes finished only because of a server update, the follow-up Procedure workflow is not triggered. This prevents a workflow from executing in the name of users who did not initiate or observe the completion.

The general online and offline evaluation rules for sequential and grouped Tasks are documented in [[MRO Objects (Client)#Sequential Task|Sequential Task]] and [[MRO Objects (Client)#Grouped Task|Grouped Task]].

== Supporting File Documents ==

=== Procedure JSON File Document ===

Technical object name: '''FILEDOCUMENT_MRO_JSON'''

This File Document stores the JSON definition of a Procedure Workpackage.

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| LK_PROCEDURE_WORKPACKAGE || {{Guid}} || Link to the associated Procedure Workpackage
|}

=== Picture Task File Document ===

Technical object name: '''FILEDOCUMENT_MRO_PICTURE_TASK'''

This is a dedicated File Document linked to a Picture Task. A Picture Task can also use another child-document type, provided that the child document contains a valid file.

{| class="wikitable" width="70%"
|-
! Name !! Data type !! Description
|-
| LK_PICTURE_TASK || {{Guid}} || Link to the associated Picture Task
|}

== See also ==

* [[MRO Objects (Client)]]
* [[MROCLS_MRO_TASKOWNER]] (Classification)
* [[MROCLS_MRO_WORKPACKAGE]] (Classification)
* [[MROCLS_MRO_TASK]] (Classification)
* [[MROCLS_MRO_PROGRESS_TASK]] (Classification)
* [[MROCLS_MRO_CHECK_TASK]] (Classification)
* [[MROCLS_MRO_INSPECTION_TASK]] (Classification)
* [[MROCLS_SEQUENTIALTASK]] (Classification)
* [[MROCLS_GROUPEDTASK]] (Classification)
* [[MROCLS_PROCEDURE]] (Classification)
* [[MROCLS_SWITCH_START_TASK]] (Classification)
* [[MROCLS_SWITCH_END_TASK]] (Classification)
* [[MROCLS_CALCULATION_TASK]] (Classification)
* [[MROCLS_PICK_LIST_TASK]] (Classification)
* [[MROCLS_PICTURE_TASK]] (Classification)

[[Category:Module|MRO (Plugin)]]

MRO Material Management

2026-06-23T13:42:35Z

LMA:

2026-06-19T06:42:49Z

LMA: /* See also */

MRO Material Management

2026-06-19T06:41:12Z

LMA: /* Relations */

{{UnderConstructionStart}}
== MRO Material Management ==

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Summary:''' The MRO material management features provide the foundation for handling materials, material master data, reservations, storage locations, and goods movements in MRO workflows. The central objects are Material, MaterialMaster, and Reservation. Materials are linked to master data and storage locations. Reservations are created manually by users and link materials to tasks.
</div>

MRO material management is used to support maintenance work with required spare parts, consumables, tools, or other material items.

Users can see which material is required for a task, where the material is stored, how much material is available, how much material is reserved, and which reservation status applies.

== Basic concept ==

{| class="wikitable"
! Object
! Type
! Purpose
|-
| MaterialMaster
| Master data
| Defines the catalogue entry for a material, including item number, unit, packaging, manufacturer data, and material type.
|-
| Material
| Quantity-bearing MRO object
| Represents a material instance or stock entry in MRO. It links to a material master and a storage location and exposes quantity, reserved quantity, and available quantity logic.
|-
| Reservation
| Workflow object
| Represents a manually created material reservation for a task. It links a material to a task and stores planned and actual quantities.
|-
| GoodsMovement
| Technical base class
| Provides the common QUANTITY property used by both materials and reservations.
|-
| StorageLocation
| Related storage object
| Represents a physical storage location for materials.
|}

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Core idea:''' MaterialMaster defines what the material is. Material represents the material in stock or material context. Reservation links a material to a task and reserves a planned quantity for maintenance execution.
</div>

== Object overview ==

{| class="wikitable"
! Object
! Class name
! Base / inheritance
! Main relations
|-
| Material
| UBIK.MRO.Material
| Inherits from GoodsMovement
| LK_MATERIAL_MASTER, LK_STORAGE_LOCATION
|-
| Material Master
| UBIK.MRO.MaterialMaster
| Master data class
| Referenced by Material via LK_MATERIAL_MASTER
|-
| Reservation
| UBIK.MRO.Reservation
| Inherits from GoodsMovement
| LK_TASK, LK_MATERIAL
|-
| Goods Movement
| UBIK.MRO.GoodsMovement
| Technical base class
| Provides QUANTITY to derived objects
|-
| Storage Location
| UBIK.MRO.StorageLocation
| Functional location specialization
| Referenced by Material via LK_STORAGE_LOCATION
|}

== MaterialMaster ==

=== Purpose ===

MaterialMaster represents the material master or catalogue entry.

It stores item-level master data that can be referenced by material instances in MRO.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| ITEM_NUMBER
| string
| Item number or material number.
|-
| PACKAGING_UNIT
| string
| Packaging unit.
|-
| PACKAGING_SIZE
| double
| Packaging size.
|-
| ACTIVE
| bool
| Defines whether the material master is active.
|-
| UNIT_OF_MEASURE
| string
| Unit of measure.
|-
| MATERIAL_TYPE / MaterialType
| int / enum
| Material type.
|-
| MANUFACTURER_COMPANY_NAME
| string
| Manufacturer company name.
|-
| MANUFACTURER_PRODUCT_TAG
| string
| Manufacturer product tag or product identifier.
|}

=== Material type ===

Values of MaterialType are:

* SpareParts
* Consumables
* Tools

== Material ==

=== Purpose ===

Material represents a material instance or stock entry in MRO.

It inherits from GoodsMovement and therefore uses the inherited QUANTITY property as its material quantity.

A material links to:

* a material master via LK_MATERIAL_MASTER
* a storage location via LK_STORAGE_LOCATION

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Stored or calculated
|-
| LK_MATERIAL_MASTER
| MaterialMaster
| Link to the material master data.
| Stored link
|-
| LK_STORAGE_LOCATION
| StorageLocation
| Link to the storage location where the material is located.
| Stored link
|-
| QUANTITY
| double
| Material quantity. Inherited from GoodsMovement.
| Stored property
|-
| RESERVED_QUANTITY
| double
| Sum of planned quantities of confirmed reservations for this material.
| Calculated property
|-
| MATERIAL_STATUS / MaterialStatus
| int / enum
| Material status.
| User/admin managed property
|}

=== Material status ===

The material status is stored in MATERIAL_STATUS and exposed through MaterialStatus.

The property is managed by the user or administrator. The system does not change it automatically.

{| class="wikitable"
! Value
! Numeric value
! Meaning
|-
| Undefined
| 0
| No specific material status is defined.
|-
| Inactive
| 10
| Material is inactive and should not be used for new reservations.
|-
| Active
| 20
| Material is active and can be used for reservations.
|}

=== Reserved quantity ===

RESERVED_QUANTITY is calculated at read time.

The calculation uses reservations where:

* LK_MATERIAL points to the current material
* STATUS is ReservationStatus.Confirmed

The calculated value is the sum of QTY_PLANNED of these confirmed reservations.

=== Available quantity ===

The available material quantity is calculated by AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Delete behavior ===

Material.InternalDeleteAllowed() prevents deleting a material if it still has quantity or active reservations.

Deletion is only allowed if:

* QUANTITY is lower than or equal to 0
* HasActiveReservation() returns false

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' A Material cannot be deleted while it has a quantity greater than 0 or active reservations.
</div>

== Reservation ==

=== Purpose ===

Reservation represents a manually created material reservation for a task.

It links:

* a task via LK_TASK
* a material via LK_MATERIAL

It stores the planned reservation quantity in QTY_PLANNED and the actually issued or consumed quantity in QUANTITY.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Important behavior
|-
| LK_TASK
| Task
| Link to the task for which the material is reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| LK_MATERIAL
| Material
| Link to the material being reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| STATUS / Status
| int / enum
| Reservation status.
| Changes are validated by AllowStatusChange(int newStatus).
|-
| QTY_PLANNED
| double
| Planned quantity for the reservation.
| Setter validates through AllowQuantityPlanned(double).
|-
| QUANTITY
| double
| Actually issued or consumed quantity. Overrides GoodsMovement.QUANTITY.
| Setter validates through AllowQuantity(double).
|}

=== Reservation status ===

Values of ReservationStatus are:

{| class="wikitable"
! Status
! Numeric value
! Meaning
|-
| Planned
| 0
| Reservation is planned.
|-
| Confirmed
| 10
| Reservation is confirmed and contributes to the material's reserved quantity.
|-
| Issued
| 20
| Material has been physically issued.
|-
| Cancelled
| 30
| Reservation was cancelled.
|-
| Expired
| 50
| Reservation has expired.
|}

=== Status change rules ===

Status changes are controlled by AllowStatusChange(int newStatus).

The following rules are applied:

* no status change is allowed when the current status is Issued
* changing from Confirmed back to Planned is not allowed
* other status changes are allowed by this method

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' Once a reservation has status Issued, its status can no longer be changed by the normal status setter logic.
</div>

=== Planned quantity validation ===

The setter of QTY_PLANNED validates changes through AllowQuantityPlanned(double).

A new planned quantity is only allowed if:

* Status is ReservationStatus.Planned
* LK_MATERIAL is assigned
* the new quantity is greater than 0
* the new quantity is lower than or equal to LK_MATERIAL.AvailableQuantity()

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Quantity rule:''' A planned reservation quantity can only be set while the reservation is still Planned and only if the selected material has enough available quantity.
</div>

=== Actual quantity validation ===

The overridden QUANTITY setter validates changes through AllowQuantity(double).

A new actual quantity is only allowed if:

* the new quantity is greater than 0
* the status is either Planned or Confirmed

=== Link editing rules ===

The setters of LK_TASK and LK_MATERIAL are guarded by reservation status.

The links cannot be changed when the reservation is:

* Issued
* Confirmed

== StorageLocation ==

=== Purpose ===

StorageLocation is a related object used to represent a physical storage location.

A material can reference a storage location via LK_STORAGE_LOCATION.

=== Important properties and values ===

{| class="wikitable"
! Property
! Type
! Values / meaning
|-
| STORAGE_TYPE / StorageType
| int / enum
| Floor, Shelf, Rack, Bin, Pallet, Container
|-
| ACCESS_TYPE / AccessType
| int / enum
| Manual, Forklift, Crane, Automated
|-
| OCCUPANCY_STATUS / OccupancyStatus
| int / enum
| Empty, Partial, Full, Reserved, Blocked, OutOfService
|-
| STORAGE_LABEL
| string
| Label of the storage location.
|-
| LEVEL
| int
| Level of the storage location.
|-
| POSITION
| string
| Position identifier.
|}

== GoodsMovement ==

GoodsMovement is a technical base class.

It provides the common QUANTITY property for material-related objects such as Material and Reservation.

== Quantity concepts ==

{| class="wikitable"
! Quantity
! Property / method
! Object
! Stored or calculated
! Notes
|-
| Material quantity
| QUANTITY
| Material
| Stored
| Inherited from GoodsMovement.
|-
| Reserved quantity
| RESERVED_QUANTITY
| Material
| Calculated
| Sum of QTY_PLANNED of confirmed reservations for the material.
|-
| Available quantity
| AvailableQuantity()
| Material
| Calculated
| QUANTITY minus RESERVED_QUANTITY.
|-
| Planned reservation quantity
| QTY_PLANNED
| Reservation
| Stored
| Validated by AllowQuantityPlanned(double).
|-
| Actually issued or consumed quantity
| QUANTITY
| Reservation
| Stored
| Overrides GoodsMovement.QUANTITY and is validated by AllowQuantity(double).
|}

== Reservation workflow ==

=== Creating or editing a reservation ===

Reservations are created manually by the user.

A reservation links a material to a task.

For a reservation to define its planned quantity correctly:

# LK_MATERIAL must be set.
# LK_TASK must point to the task requiring the material.
# Status must still be Planned.
# QTY_PLANNED must be greater than 0.
# QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().

=== Confirmed reservations ===

When a reservation is confirmed, it contributes to the material's reserved quantity.

This affects the available quantity of the material.

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - sum(QTY_PLANNED of confirmed reservations)
</div>

=== Finishing a task ===

When a task is finished, the task logic calls CloseReservations().

The method processes active reservations for the task:

* if a reservation has status Confirmed, it is set to Issued
* otherwise, it is set to Cancelled

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Workflow effect:''' Finishing a task closes its reservations. Confirmed reservations become Issued; other active reservations become Cancelled.
</div>

== Usage in tasks ==

Reservations are the central link between material handling and task execution.

A reservation connects:

* the required material through LK_MATERIAL
* the task through LK_TASK
* the planned quantity through QTY_PLANNED
* the actually issued or consumed quantity through QUANTITY
* the reservation state through Status

This means that material usage is tracked at task level.

== Example workflow ==

=== Step 1: Material master exists ===

A spare part is defined as a MaterialMaster.

{| class="wikitable"
! Field
! Example
|-
| ITEM_NUMBER
| OF-10045
|-
| UNIT_OF_MEASURE
| Piece
|-
| MaterialType
| SpareParts
|}

=== Step 2: Material exists in a storage location ===

A Material object references the material master and a storage location.

{| class="wikitable"
! Property
! Example
|-
| LK_MATERIAL_MASTER
| Oil Filter Type A
|-
| LK_STORAGE_LOCATION
| Storage Shelf A
|-
| QUANTITY
| 10
|-
| RESERVED_QUANTITY
| 0
|-
| AvailableQuantity()
| 10
|}

=== Step 3: Reservation is created for a task ===

A user manually creates a Reservation and links the material to the task.

{| class="wikitable"
! Property
! Example
|-
| LK_TASK
| Replace oil filter
|-
| LK_MATERIAL
| Oil Filter Type A
|-
| Status
| Planned
|-
| QTY_PLANNED
| 1
|}

=== Step 4: Reservation is confirmed ===

The reservation status is changed to Confirmed.

After confirmation, the material's reserved quantity includes the reservation's planned quantity.

{| class="wikitable"
! Quantity
! Value
|-
| Material.QUANTITY
| 10
|-
| Material.RESERVED_QUANTITY
| 1
|-
| Material.AvailableQuantity()
| 9
|}

=== Step 5: Actual quantity is entered ===

The actually issued or consumed quantity is stored in Reservation.QUANTITY.

{| class="wikitable"
! Property
! Example
|-
| Reservation.QUANTITY
| 1
|}

=== Step 6: Task is finished ===

When the task is finished, CloseReservations() is called.

The confirmed reservation is changed to Issued.

== Validation and business rules ==

{| class="wikitable"
! Area
! Rule
! Implemented by
|-
| Planned reservation quantity
| QTY_PLANNED must be greater than 0.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED can only be changed while the reservation is Planned.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().
| AllowQuantityPlanned(double)
|-
| Actual issued or consumed quantity
| QUANTITY must be greater than 0.
| AllowQuantity(double)
|-
| Actual issued or consumed quantity
| QUANTITY can only be changed while the reservation is Planned or Confirmed.
| AllowQuantity(double)
|-
| Reservation status
| Status cannot be changed once the reservation is Issued.
| AllowStatusChange(int newStatus)
|-
| Reservation status
| A reservation cannot be changed from Confirmed back to Planned.
| AllowStatusChange(int newStatus)
|-
| Reservation links
| LK_TASK and LK_MATERIAL cannot be changed when status is Issued or Confirmed.
| Property setters
|-
| Material deletion
| Material cannot be deleted while QUANTITY is greater than 0.
| InternalDeleteAllowed()
|-
| Material deletion
| Material cannot be deleted while active reservations exist.
| InternalDeleteAllowed() and HasActiveReservation()
|}

== See also ==
* [[MRO (Plugin)]]
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROMaintenancePlans]]
{{UnderConstructionEnd}}

MRO Material Management

2026-06-19T06:40:02Z

LMA: /* Reservation status */

{{UnderConstructionStart}}
== MRO Material Management ==

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Summary:''' The MRO material management features provide the foundation for handling materials, material master data, reservations, storage locations, and goods movements in MRO workflows. The central objects are Material, MaterialMaster, and Reservation. Materials are linked to master data and storage locations. Reservations are created manually by users and link materials to tasks.
</div>

MRO material management is used to support maintenance work with required spare parts, consumables, tools, or other material items.

Users can see which material is required for a task, where the material is stored, how much material is available, how much material is reserved, and which reservation status applies.

== Basic concept ==

{| class="wikitable"
! Object
! Type
! Purpose
|-
| MaterialMaster
| Master data
| Defines the catalogue entry for a material, including item number, unit, packaging, manufacturer data, and material type.
|-
| Material
| Quantity-bearing MRO object
| Represents a material instance or stock entry in MRO. It links to a material master and a storage location and exposes quantity, reserved quantity, and available quantity logic.
|-
| Reservation
| Workflow object
| Represents a manually created material reservation for a task. It links a material to a task and stores planned and actual quantities.
|-
| GoodsMovement
| Technical base class
| Provides the common QUANTITY property used by both materials and reservations.
|-
| StorageLocation
| Related storage object
| Represents a physical storage location for materials.
|}

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Core idea:''' MaterialMaster defines what the material is. Material represents the material in stock or material context. Reservation links a material to a task and reserves a planned quantity for maintenance execution.
</div>

== Object overview ==

{| class="wikitable"
! Object
! Class name
! Base / inheritance
! Main relations
|-
| Material
| UBIK.MRO.Material
| Inherits from GoodsMovement
| LK_MATERIAL_MASTER, LK_STORAGE_LOCATION
|-
| Material Master
| UBIK.MRO.MaterialMaster
| Master data class
| Referenced by Material via LK_MATERIAL_MASTER
|-
| Reservation
| UBIK.MRO.Reservation
| Inherits from GoodsMovement
| LK_TASK, LK_MATERIAL
|-
| Goods Movement
| UBIK.MRO.GoodsMovement
| Technical base class
| Provides QUANTITY to derived objects
|-
| Storage Location
| UBIK.MRO.StorageLocation
| Functional location specialization
| Referenced by Material via LK_STORAGE_LOCATION
|}

== MaterialMaster ==

=== Purpose ===

MaterialMaster represents the material master or catalogue entry.

It stores item-level master data that can be referenced by material instances in MRO.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| ITEM_NUMBER
| string
| Item number or material number.
|-
| PACKAGING_UNIT
| string
| Packaging unit.
|-
| PACKAGING_SIZE
| double
| Packaging size.
|-
| ACTIVE
| bool
| Defines whether the material master is active.
|-
| UNIT_OF_MEASURE
| string
| Unit of measure.
|-
| MATERIAL_TYPE / MaterialType
| int / enum
| Material type.
|-
| MANUFACTURER_COMPANY_NAME
| string
| Manufacturer company name.
|-
| MANUFACTURER_PRODUCT_TAG
| string
| Manufacturer product tag or product identifier.
|}

=== Material type ===

Values of MaterialType are:

* SpareParts
* Consumables
* Tools

== Material ==

=== Purpose ===

Material represents a material instance or stock entry in MRO.

It inherits from GoodsMovement and therefore uses the inherited QUANTITY property as its material quantity.

A material links to:

* a material master via LK_MATERIAL_MASTER
* a storage location via LK_STORAGE_LOCATION

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Stored or calculated
|-
| LK_MATERIAL_MASTER
| MaterialMaster
| Link to the material master data.
| Stored link
|-
| LK_STORAGE_LOCATION
| StorageLocation
| Link to the storage location where the material is located.
| Stored link
|-
| QUANTITY
| double
| Material quantity. Inherited from GoodsMovement.
| Stored property
|-
| RESERVED_QUANTITY
| double
| Sum of planned quantities of confirmed reservations for this material.
| Calculated property
|-
| MATERIAL_STATUS / MaterialStatus
| int / enum
| Material status.
| User/admin managed property
|}

=== Material status ===

The material status is stored in MATERIAL_STATUS and exposed through MaterialStatus.

The property is managed by the user or administrator. The system does not change it automatically.

{| class="wikitable"
! Value
! Numeric value
! Meaning
|-
| Undefined
| 0
| No specific material status is defined.
|-
| Inactive
| 10
| Material is inactive and should not be used for new reservations.
|-
| Active
| 20
| Material is active and can be used for reservations.
|}

=== Reserved quantity ===

RESERVED_QUANTITY is calculated at read time.

The calculation uses reservations where:

* LK_MATERIAL points to the current material
* STATUS is ReservationStatus.Confirmed

The calculated value is the sum of QTY_PLANNED of these confirmed reservations.

=== Available quantity ===

The available material quantity is calculated by AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Delete behavior ===

Material.InternalDeleteAllowed() prevents deleting a material if it still has quantity or active reservations.

Deletion is only allowed if:

* QUANTITY is lower than or equal to 0
* HasActiveReservation() returns false

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' A Material cannot be deleted while it has a quantity greater than 0 or active reservations.
</div>

== Reservation ==

=== Purpose ===

Reservation represents a manually created material reservation for a task.

It links:

* a task via LK_TASK
* a material via LK_MATERIAL

It stores the planned reservation quantity in QTY_PLANNED and the actually issued or consumed quantity in QUANTITY.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Important behavior
|-
| LK_TASK
| Task
| Link to the task for which the material is reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| LK_MATERIAL
| Material
| Link to the material being reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| STATUS / Status
| int / enum
| Reservation status.
| Changes are validated by AllowStatusChange(int newStatus).
|-
| QTY_PLANNED
| double
| Planned quantity for the reservation.
| Setter validates through AllowQuantityPlanned(double).
|-
| QUANTITY
| double
| Actually issued or consumed quantity. Overrides GoodsMovement.QUANTITY.
| Setter validates through AllowQuantity(double).
|}

=== Reservation status ===

Values of ReservationStatus are:

{| class="wikitable"
! Status
! Numeric value
! Meaning
|-
| Planned
| 0
| Reservation is planned.
|-
| Confirmed
| 10
| Reservation is confirmed and contributes to the material's reserved quantity.
|-
| Issued
| 20
| Material has been physically issued.
|-
| Cancelled
| 30
| Reservation was cancelled.
|-
| Expired
| 50
| Reservation has expired.
|}

=== Status change rules ===

Status changes are controlled by AllowStatusChange(int newStatus).

The following rules are applied:

* no status change is allowed when the current status is Issued
* changing from Confirmed back to Planned is not allowed
* other status changes are allowed by this method

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' Once a reservation has status Issued, its status can no longer be changed by the normal status setter logic.
</div>

=== Planned quantity validation ===

The setter of QTY_PLANNED validates changes through AllowQuantityPlanned(double).

A new planned quantity is only allowed if:

* Status is ReservationStatus.Planned
* LK_MATERIAL is assigned
* the new quantity is greater than 0
* the new quantity is lower than or equal to LK_MATERIAL.AvailableQuantity()

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Quantity rule:''' A planned reservation quantity can only be set while the reservation is still Planned and only if the selected material has enough available quantity.
</div>

=== Actual quantity validation ===

The overridden QUANTITY setter validates changes through AllowQuantity(double).

A new actual quantity is only allowed if:

* the new quantity is greater than 0
* the status is either Planned or Confirmed

=== Link editing rules ===

The setters of LK_TASK and LK_MATERIAL are guarded by reservation status.

The links cannot be changed when the reservation is:

* Issued
* Confirmed

== StorageLocation ==

=== Purpose ===

StorageLocation is a related object used to represent a physical storage location.

A material can reference a storage location via LK_STORAGE_LOCATION.

=== Important properties and values ===

{| class="wikitable"
! Property
! Type
! Values / meaning
|-
| STORAGE_TYPE / StorageType
| int / enum
| Floor, Shelf, Rack, Bin, Pallet, Container
|-
| ACCESS_TYPE / AccessType
| int / enum
| Manual, Forklift, Crane, Automated
|-
| OCCUPANCY_STATUS / OccupancyStatus
| int / enum
| Empty, Partial, Full, Reserved, Blocked, OutOfService
|-
| STORAGE_LABEL
| string
| Label of the storage location.
|-
| LEVEL
| int
| Level of the storage location.
|-
| POSITION
| string
| Position identifier.
|}

== GoodsMovement ==

GoodsMovement is a technical base class.

It provides the common QUANTITY property for material-related objects such as Material and Reservation.

== Relations ==

{| class="wikitable"
! Relation
! Source
! Target
! Meaning
|-
| LK_MATERIAL_MASTER
| Material
| MaterialMaster
| Links a material instance to its master data.
|-
| LK_STORAGE_LOCATION
| Material
| StorageLocation
| Defines where the material is stored.
|-
| LK_MATERIAL
| Reservation
| Material
| Defines which material is reserved.
|-
| LK_TASK
| Reservation
| Task
| Defines the task for which the material is reserved.
|}

== Quantity concepts ==

{| class="wikitable"
! Quantity
! Property / method
! Object
! Stored or calculated
! Notes
|-
| Material quantity
| QUANTITY
| Material
| Stored
| Inherited from GoodsMovement.
|-
| Reserved quantity
| RESERVED_QUANTITY
| Material
| Calculated
| Sum of QTY_PLANNED of confirmed reservations for the material.
|-
| Available quantity
| AvailableQuantity()
| Material
| Calculated
| QUANTITY minus RESERVED_QUANTITY.
|-
| Planned reservation quantity
| QTY_PLANNED
| Reservation
| Stored
| Validated by AllowQuantityPlanned(double).
|-
| Actually issued or consumed quantity
| QUANTITY
| Reservation
| Stored
| Overrides GoodsMovement.QUANTITY and is validated by AllowQuantity(double).
|}

== Reservation workflow ==

=== Creating or editing a reservation ===

Reservations are created manually by the user.

A reservation links a material to a task.

For a reservation to define its planned quantity correctly:

# LK_MATERIAL must be set.
# LK_TASK must point to the task requiring the material.
# Status must still be Planned.
# QTY_PLANNED must be greater than 0.
# QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().

=== Confirmed reservations ===

When a reservation is confirmed, it contributes to the material's reserved quantity.

This affects the available quantity of the material.

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - sum(QTY_PLANNED of confirmed reservations)
</div>

=== Finishing a task ===

When a task is finished, the task logic calls CloseReservations().

The method processes active reservations for the task:

* if a reservation has status Confirmed, it is set to Issued
* otherwise, it is set to Cancelled

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Workflow effect:''' Finishing a task closes its reservations. Confirmed reservations become Issued; other active reservations become Cancelled.
</div>

== Usage in tasks ==

Reservations are the central link between material handling and task execution.

A reservation connects:

* the required material through LK_MATERIAL
* the task through LK_TASK
* the planned quantity through QTY_PLANNED
* the actually issued or consumed quantity through QUANTITY
* the reservation state through Status

This means that material usage is tracked at task level.

== Example workflow ==

=== Step 1: Material master exists ===

A spare part is defined as a MaterialMaster.

{| class="wikitable"
! Field
! Example
|-
| ITEM_NUMBER
| OF-10045
|-
| UNIT_OF_MEASURE
| Piece
|-
| MaterialType
| SpareParts
|}

=== Step 2: Material exists in a storage location ===

A Material object references the material master and a storage location.

{| class="wikitable"
! Property
! Example
|-
| LK_MATERIAL_MASTER
| Oil Filter Type A
|-
| LK_STORAGE_LOCATION
| Storage Shelf A
|-
| QUANTITY
| 10
|-
| RESERVED_QUANTITY
| 0
|-
| AvailableQuantity()
| 10
|}

=== Step 3: Reservation is created for a task ===

A user manually creates a Reservation and links the material to the task.

{| class="wikitable"
! Property
! Example
|-
| LK_TASK
| Replace oil filter
|-
| LK_MATERIAL
| Oil Filter Type A
|-
| Status
| Planned
|-
| QTY_PLANNED
| 1
|}

=== Step 4: Reservation is confirmed ===

The reservation status is changed to Confirmed.

After confirmation, the material's reserved quantity includes the reservation's planned quantity.

{| class="wikitable"
! Quantity
! Value
|-
| Material.QUANTITY
| 10
|-
| Material.RESERVED_QUANTITY
| 1
|-
| Material.AvailableQuantity()
| 9
|}

=== Step 5: Actual quantity is entered ===

The actually issued or consumed quantity is stored in Reservation.QUANTITY.

{| class="wikitable"
! Property
! Example
|-
| Reservation.QUANTITY
| 1
|}

=== Step 6: Task is finished ===

When the task is finished, CloseReservations() is called.

The confirmed reservation is changed to Issued.

== Validation and business rules ==

{| class="wikitable"
! Area
! Rule
! Implemented by
|-
| Planned reservation quantity
| QTY_PLANNED must be greater than 0.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED can only be changed while the reservation is Planned.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().
| AllowQuantityPlanned(double)
|-
| Actual issued or consumed quantity
| QUANTITY must be greater than 0.
| AllowQuantity(double)
|-
| Actual issued or consumed quantity
| QUANTITY can only be changed while the reservation is Planned or Confirmed.
| AllowQuantity(double)
|-
| Reservation status
| Status cannot be changed once the reservation is Issued.
| AllowStatusChange(int newStatus)
|-
| Reservation status
| A reservation cannot be changed from Confirmed back to Planned.
| AllowStatusChange(int newStatus)
|-
| Reservation links
| LK_TASK and LK_MATERIAL cannot be changed when status is Issued or Confirmed.
| Property setters
|-
| Material deletion
| Material cannot be deleted while QUANTITY is greater than 0.
| InternalDeleteAllowed()
|-
| Material deletion
| Material cannot be deleted while active reservations exist.
| InternalDeleteAllowed() and HasActiveReservation()
|}

== See also ==
* [[MRO (Plugin)]]
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROMaintenancePlans]]
{{UnderConstructionEnd}}

MRO Material Management

2026-06-19T06:38:54Z

LMA: /* Material type */

{{UnderConstructionStart}}
== MRO Material Management ==

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Summary:''' The MRO material management features provide the foundation for handling materials, material master data, reservations, storage locations, and goods movements in MRO workflows. The central objects are Material, MaterialMaster, and Reservation. Materials are linked to master data and storage locations. Reservations are created manually by users and link materials to tasks.
</div>

MRO material management is used to support maintenance work with required spare parts, consumables, tools, or other material items.

Users can see which material is required for a task, where the material is stored, how much material is available, how much material is reserved, and which reservation status applies.

== Basic concept ==

{| class="wikitable"
! Object
! Type
! Purpose
|-
| MaterialMaster
| Master data
| Defines the catalogue entry for a material, including item number, unit, packaging, manufacturer data, and material type.
|-
| Material
| Quantity-bearing MRO object
| Represents a material instance or stock entry in MRO. It links to a material master and a storage location and exposes quantity, reserved quantity, and available quantity logic.
|-
| Reservation
| Workflow object
| Represents a manually created material reservation for a task. It links a material to a task and stores planned and actual quantities.
|-
| GoodsMovement
| Technical base class
| Provides the common QUANTITY property used by both materials and reservations.
|-
| StorageLocation
| Related storage object
| Represents a physical storage location for materials.
|}

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Core idea:''' MaterialMaster defines what the material is. Material represents the material in stock or material context. Reservation links a material to a task and reserves a planned quantity for maintenance execution.
</div>

== Object overview ==

{| class="wikitable"
! Object
! Class name
! Base / inheritance
! Main relations
|-
| Material
| UBIK.MRO.Material
| Inherits from GoodsMovement
| LK_MATERIAL_MASTER, LK_STORAGE_LOCATION
|-
| Material Master
| UBIK.MRO.MaterialMaster
| Master data class
| Referenced by Material via LK_MATERIAL_MASTER
|-
| Reservation
| UBIK.MRO.Reservation
| Inherits from GoodsMovement
| LK_TASK, LK_MATERIAL
|-
| Goods Movement
| UBIK.MRO.GoodsMovement
| Technical base class
| Provides QUANTITY to derived objects
|-
| Storage Location
| UBIK.MRO.StorageLocation
| Functional location specialization
| Referenced by Material via LK_STORAGE_LOCATION
|}

== MaterialMaster ==

=== Purpose ===

MaterialMaster represents the material master or catalogue entry.

It stores item-level master data that can be referenced by material instances in MRO.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| ITEM_NUMBER
| string
| Item number or material number.
|-
| PACKAGING_UNIT
| string
| Packaging unit.
|-
| PACKAGING_SIZE
| double
| Packaging size.
|-
| ACTIVE
| bool
| Defines whether the material master is active.
|-
| UNIT_OF_MEASURE
| string
| Unit of measure.
|-
| MATERIAL_TYPE / MaterialType
| int / enum
| Material type.
|-
| MANUFACTURER_COMPANY_NAME
| string
| Manufacturer company name.
|-
| MANUFACTURER_PRODUCT_TAG
| string
| Manufacturer product tag or product identifier.
|}

=== Material type ===

Values of MaterialType are:

* SpareParts
* Consumables
* Tools

== Material ==

=== Purpose ===

Material represents a material instance or stock entry in MRO.

It inherits from GoodsMovement and therefore uses the inherited QUANTITY property as its material quantity.

A material links to:

* a material master via LK_MATERIAL_MASTER
* a storage location via LK_STORAGE_LOCATION

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Stored or calculated
|-
| LK_MATERIAL_MASTER
| MaterialMaster
| Link to the material master data.
| Stored link
|-
| LK_STORAGE_LOCATION
| StorageLocation
| Link to the storage location where the material is located.
| Stored link
|-
| QUANTITY
| double
| Material quantity. Inherited from GoodsMovement.
| Stored property
|-
| RESERVED_QUANTITY
| double
| Sum of planned quantities of confirmed reservations for this material.
| Calculated property
|-
| MATERIAL_STATUS / MaterialStatus
| int / enum
| Material status.
| User/admin managed property
|}

=== Material status ===

The material status is stored in MATERIAL_STATUS and exposed through MaterialStatus.

The property is managed by the user or administrator. The system does not change it automatically.

{| class="wikitable"
! Value
! Numeric value
! Meaning
|-
| Undefined
| 0
| No specific material status is defined.
|-
| Inactive
| 10
| Material is inactive and should not be used for new reservations.
|-
| Active
| 20
| Material is active and can be used for reservations.
|}

=== Reserved quantity ===

RESERVED_QUANTITY is calculated at read time.

The calculation uses reservations where:

* LK_MATERIAL points to the current material
* STATUS is ReservationStatus.Confirmed

The calculated value is the sum of QTY_PLANNED of these confirmed reservations.

=== Available quantity ===

The available material quantity is calculated by AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Delete behavior ===

Material.InternalDeleteAllowed() prevents deleting a material if it still has quantity or active reservations.

Deletion is only allowed if:

* QUANTITY is lower than or equal to 0
* HasActiveReservation() returns false

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' A Material cannot be deleted while it has a quantity greater than 0 or active reservations.
</div>

== Reservation ==

=== Purpose ===

Reservation represents a manually created material reservation for a task.

It links:

* a task via LK_TASK
* a material via LK_MATERIAL

It stores the planned reservation quantity in QTY_PLANNED and the actually issued or consumed quantity in QUANTITY.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Important behavior
|-
| LK_TASK
| Task
| Link to the task for which the material is reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| LK_MATERIAL
| Material
| Link to the material being reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| STATUS / Status
| int / enum
| Reservation status.
| Changes are validated by AllowStatusChange(int newStatus).
|-
| QTY_PLANNED
| double
| Planned quantity for the reservation.
| Setter validates through AllowQuantityPlanned(double).
|-
| QUANTITY
| double
| Actually issued or consumed quantity. Overrides GoodsMovement.QUANTITY.
| Setter validates through AllowQuantity(double).
|}

=== Reservation status ===

Known values of ReservationStatus are:

{| class="wikitable"
! Status
! Numeric value
! Meaning
|-
| Planned
| 0
| Reservation is planned.
|-
| Confirmed
| 10
| Reservation is confirmed and contributes to the material's reserved quantity.
|-
| Issued
| 20
| Material has been physically issued.
|-
| Cancelled
| 30
| Reservation was cancelled.
|-
| Expired
| 50
| Reservation has expired.
|}

=== Status change rules ===

Status changes are controlled by AllowStatusChange(int newStatus).

The following rules are applied:

* no status change is allowed when the current status is Issued
* changing from Confirmed back to Planned is not allowed
* other status changes are allowed by this method

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' Once a reservation has status Issued, its status can no longer be changed by the normal status setter logic.
</div>

=== Planned quantity validation ===

The setter of QTY_PLANNED validates changes through AllowQuantityPlanned(double).

A new planned quantity is only allowed if:

* Status is ReservationStatus.Planned
* LK_MATERIAL is assigned
* the new quantity is greater than 0
* the new quantity is lower than or equal to LK_MATERIAL.AvailableQuantity()

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Quantity rule:''' A planned reservation quantity can only be set while the reservation is still Planned and only if the selected material has enough available quantity.
</div>

=== Actual quantity validation ===

The overridden QUANTITY setter validates changes through AllowQuantity(double).

A new actual quantity is only allowed if:

* the new quantity is greater than 0
* the status is either Planned or Confirmed

=== Link editing rules ===

The setters of LK_TASK and LK_MATERIAL are guarded by reservation status.

The links cannot be changed when the reservation is:

* Issued
* Confirmed

== StorageLocation ==

=== Purpose ===

StorageLocation is a related object used to represent a physical storage location.

A material can reference a storage location via LK_STORAGE_LOCATION.

=== Important properties and values ===

{| class="wikitable"
! Property
! Type
! Values / meaning
|-
| STORAGE_TYPE / StorageType
| int / enum
| Floor, Shelf, Rack, Bin, Pallet, Container
|-
| ACCESS_TYPE / AccessType
| int / enum
| Manual, Forklift, Crane, Automated
|-
| OCCUPANCY_STATUS / OccupancyStatus
| int / enum
| Empty, Partial, Full, Reserved, Blocked, OutOfService
|-
| STORAGE_LABEL
| string
| Label of the storage location.
|-
| LEVEL
| int
| Level of the storage location.
|-
| POSITION
| string
| Position identifier.
|}

== GoodsMovement ==

GoodsMovement is a technical base class.

It provides the common QUANTITY property for material-related objects such as Material and Reservation.

== Relations ==

{| class="wikitable"
! Relation
! Source
! Target
! Meaning
|-
| LK_MATERIAL_MASTER
| Material
| MaterialMaster
| Links a material instance to its master data.
|-
| LK_STORAGE_LOCATION
| Material
| StorageLocation
| Defines where the material is stored.
|-
| LK_MATERIAL
| Reservation
| Material
| Defines which material is reserved.
|-
| LK_TASK
| Reservation
| Task
| Defines the task for which the material is reserved.
|}

== Quantity concepts ==

{| class="wikitable"
! Quantity
! Property / method
! Object
! Stored or calculated
! Notes
|-
| Material quantity
| QUANTITY
| Material
| Stored
| Inherited from GoodsMovement.
|-
| Reserved quantity
| RESERVED_QUANTITY
| Material
| Calculated
| Sum of QTY_PLANNED of confirmed reservations for the material.
|-
| Available quantity
| AvailableQuantity()
| Material
| Calculated
| QUANTITY minus RESERVED_QUANTITY.
|-
| Planned reservation quantity
| QTY_PLANNED
| Reservation
| Stored
| Validated by AllowQuantityPlanned(double).
|-
| Actually issued or consumed quantity
| QUANTITY
| Reservation
| Stored
| Overrides GoodsMovement.QUANTITY and is validated by AllowQuantity(double).
|}

== Reservation workflow ==

=== Creating or editing a reservation ===

Reservations are created manually by the user.

A reservation links a material to a task.

For a reservation to define its planned quantity correctly:

# LK_MATERIAL must be set.
# LK_TASK must point to the task requiring the material.
# Status must still be Planned.
# QTY_PLANNED must be greater than 0.
# QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().

=== Confirmed reservations ===

When a reservation is confirmed, it contributes to the material's reserved quantity.

This affects the available quantity of the material.

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - sum(QTY_PLANNED of confirmed reservations)
</div>

=== Finishing a task ===

When a task is finished, the task logic calls CloseReservations().

The method processes active reservations for the task:

* if a reservation has status Confirmed, it is set to Issued
* otherwise, it is set to Cancelled

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Workflow effect:''' Finishing a task closes its reservations. Confirmed reservations become Issued; other active reservations become Cancelled.
</div>

== Usage in tasks ==

Reservations are the central link between material handling and task execution.

A reservation connects:

* the required material through LK_MATERIAL
* the task through LK_TASK
* the planned quantity through QTY_PLANNED
* the actually issued or consumed quantity through QUANTITY
* the reservation state through Status

This means that material usage is tracked at task level.

== Example workflow ==

=== Step 1: Material master exists ===

A spare part is defined as a MaterialMaster.

{| class="wikitable"
! Field
! Example
|-
| ITEM_NUMBER
| OF-10045
|-
| UNIT_OF_MEASURE
| Piece
|-
| MaterialType
| SpareParts
|}

=== Step 2: Material exists in a storage location ===

A Material object references the material master and a storage location.

{| class="wikitable"
! Property
! Example
|-
| LK_MATERIAL_MASTER
| Oil Filter Type A
|-
| LK_STORAGE_LOCATION
| Storage Shelf A
|-
| QUANTITY
| 10
|-
| RESERVED_QUANTITY
| 0
|-
| AvailableQuantity()
| 10
|}

=== Step 3: Reservation is created for a task ===

A user manually creates a Reservation and links the material to the task.

{| class="wikitable"
! Property
! Example
|-
| LK_TASK
| Replace oil filter
|-
| LK_MATERIAL
| Oil Filter Type A
|-
| Status
| Planned
|-
| QTY_PLANNED
| 1
|}

=== Step 4: Reservation is confirmed ===

The reservation status is changed to Confirmed.

After confirmation, the material's reserved quantity includes the reservation's planned quantity.

{| class="wikitable"
! Quantity
! Value
|-
| Material.QUANTITY
| 10
|-
| Material.RESERVED_QUANTITY
| 1
|-
| Material.AvailableQuantity()
| 9
|}

=== Step 5: Actual quantity is entered ===

The actually issued or consumed quantity is stored in Reservation.QUANTITY.

{| class="wikitable"
! Property
! Example
|-
| Reservation.QUANTITY
| 1
|}

=== Step 6: Task is finished ===

When the task is finished, CloseReservations() is called.

The confirmed reservation is changed to Issued.

== Validation and business rules ==

{| class="wikitable"
! Area
! Rule
! Implemented by
|-
| Planned reservation quantity
| QTY_PLANNED must be greater than 0.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED can only be changed while the reservation is Planned.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().
| AllowQuantityPlanned(double)
|-
| Actual issued or consumed quantity
| QUANTITY must be greater than 0.
| AllowQuantity(double)
|-
| Actual issued or consumed quantity
| QUANTITY can only be changed while the reservation is Planned or Confirmed.
| AllowQuantity(double)
|-
| Reservation status
| Status cannot be changed once the reservation is Issued.
| AllowStatusChange(int newStatus)
|-
| Reservation status
| A reservation cannot be changed from Confirmed back to Planned.
| AllowStatusChange(int newStatus)
|-
| Reservation links
| LK_TASK and LK_MATERIAL cannot be changed when status is Issued or Confirmed.
| Property setters
|-
| Material deletion
| Material cannot be deleted while QUANTITY is greater than 0.
| InternalDeleteAllowed()
|-
| Material deletion
| Material cannot be deleted while active reservations exist.
| InternalDeleteAllowed() and HasActiveReservation()
|}

== See also ==
* [[MRO (Plugin)]]
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROMaintenancePlans]]
{{UnderConstructionEnd}}

MRO Material Management

2026-06-19T06:37:42Z

LMA:

{{UnderConstructionStart}}
== MRO Material Management ==

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Summary:''' The MRO material management features provide the foundation for handling materials, material master data, reservations, storage locations, and goods movements in MRO workflows. The central objects are Material, MaterialMaster, and Reservation. Materials are linked to master data and storage locations. Reservations are created manually by users and link materials to tasks.
</div>

MRO material management is used to support maintenance work with required spare parts, consumables, tools, or other material items.

Users can see which material is required for a task, where the material is stored, how much material is available, how much material is reserved, and which reservation status applies.

== Basic concept ==

{| class="wikitable"
! Object
! Type
! Purpose
|-
| MaterialMaster
| Master data
| Defines the catalogue entry for a material, including item number, unit, packaging, manufacturer data, and material type.
|-
| Material
| Quantity-bearing MRO object
| Represents a material instance or stock entry in MRO. It links to a material master and a storage location and exposes quantity, reserved quantity, and available quantity logic.
|-
| Reservation
| Workflow object
| Represents a manually created material reservation for a task. It links a material to a task and stores planned and actual quantities.
|-
| GoodsMovement
| Technical base class
| Provides the common QUANTITY property used by both materials and reservations.
|-
| StorageLocation
| Related storage object
| Represents a physical storage location for materials.
|}

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Core idea:''' MaterialMaster defines what the material is. Material represents the material in stock or material context. Reservation links a material to a task and reserves a planned quantity for maintenance execution.
</div>

== Object overview ==

{| class="wikitable"
! Object
! Class name
! Base / inheritance
! Main relations
|-
| Material
| UBIK.MRO.Material
| Inherits from GoodsMovement
| LK_MATERIAL_MASTER, LK_STORAGE_LOCATION
|-
| Material Master
| UBIK.MRO.MaterialMaster
| Master data class
| Referenced by Material via LK_MATERIAL_MASTER
|-
| Reservation
| UBIK.MRO.Reservation
| Inherits from GoodsMovement
| LK_TASK, LK_MATERIAL
|-
| Goods Movement
| UBIK.MRO.GoodsMovement
| Technical base class
| Provides QUANTITY to derived objects
|-
| Storage Location
| UBIK.MRO.StorageLocation
| Functional location specialization
| Referenced by Material via LK_STORAGE_LOCATION
|}

== MaterialMaster ==

=== Purpose ===

MaterialMaster represents the material master or catalogue entry.

It stores item-level master data that can be referenced by material instances in MRO.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| ITEM_NUMBER
| string
| Item number or material number.
|-
| PACKAGING_UNIT
| string
| Packaging unit.
|-
| PACKAGING_SIZE
| double
| Packaging size.
|-
| ACTIVE
| bool
| Defines whether the material master is active.
|-
| UNIT_OF_MEASURE
| string
| Unit of measure.
|-
| MATERIAL_TYPE / MaterialType
| int / enum
| Material type.
|-
| MANUFACTURER_COMPANY_NAME
| string
| Manufacturer company name.
|-
| MANUFACTURER_PRODUCT_TAG
| string
| Manufacturer product tag or product identifier.
|}

=== Material type ===

Known values of MaterialType are:

* SpareParts
* Consumables
* Tools

== Material ==

=== Purpose ===

Material represents a material instance or stock entry in MRO.

It inherits from GoodsMovement and therefore uses the inherited QUANTITY property as its material quantity.

A material links to:

* a material master via LK_MATERIAL_MASTER
* a storage location via LK_STORAGE_LOCATION

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Stored or calculated
|-
| LK_MATERIAL_MASTER
| MaterialMaster
| Link to the material master data.
| Stored link
|-
| LK_STORAGE_LOCATION
| StorageLocation
| Link to the storage location where the material is located.
| Stored link
|-
| QUANTITY
| double
| Material quantity. Inherited from GoodsMovement.
| Stored property
|-
| RESERVED_QUANTITY
| double
| Sum of planned quantities of confirmed reservations for this material.
| Calculated property
|-
| MATERIAL_STATUS / MaterialStatus
| int / enum
| Material status.
| User/admin managed property
|}

=== Material status ===

The material status is stored in MATERIAL_STATUS and exposed through MaterialStatus.

The property is managed by the user or administrator. The system does not change it automatically.

{| class="wikitable"
! Value
! Numeric value
! Meaning
|-
| Undefined
| 0
| No specific material status is defined.
|-
| Inactive
| 10
| Material is inactive and should not be used for new reservations.
|-
| Active
| 20
| Material is active and can be used for reservations.
|}

=== Reserved quantity ===

RESERVED_QUANTITY is calculated at read time.

The calculation uses reservations where:

* LK_MATERIAL points to the current material
* STATUS is ReservationStatus.Confirmed

The calculated value is the sum of QTY_PLANNED of these confirmed reservations.

=== Available quantity ===

The available material quantity is calculated by AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Delete behavior ===

Material.InternalDeleteAllowed() prevents deleting a material if it still has quantity or active reservations.

Deletion is only allowed if:

* QUANTITY is lower than or equal to 0
* HasActiveReservation() returns false

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' A Material cannot be deleted while it has a quantity greater than 0 or active reservations.
</div>

== Reservation ==

=== Purpose ===

Reservation represents a manually created material reservation for a task.

It links:

* a task via LK_TASK
* a material via LK_MATERIAL

It stores the planned reservation quantity in QTY_PLANNED and the actually issued or consumed quantity in QUANTITY.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Important behavior
|-
| LK_TASK
| Task
| Link to the task for which the material is reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| LK_MATERIAL
| Material
| Link to the material being reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| STATUS / Status
| int / enum
| Reservation status.
| Changes are validated by AllowStatusChange(int newStatus).
|-
| QTY_PLANNED
| double
| Planned quantity for the reservation.
| Setter validates through AllowQuantityPlanned(double).
|-
| QUANTITY
| double
| Actually issued or consumed quantity. Overrides GoodsMovement.QUANTITY.
| Setter validates through AllowQuantity(double).
|}

=== Reservation status ===

Known values of ReservationStatus are:

{| class="wikitable"
! Status
! Numeric value
! Meaning
|-
| Planned
| 0
| Reservation is planned.
|-
| Confirmed
| 10
| Reservation is confirmed and contributes to the material's reserved quantity.
|-
| Issued
| 20
| Material has been physically issued.
|-
| Cancelled
| 30
| Reservation was cancelled.
|-
| Expired
| 50
| Reservation has expired.
|}

=== Status change rules ===

Status changes are controlled by AllowStatusChange(int newStatus).

The following rules are applied:

* no status change is allowed when the current status is Issued
* changing from Confirmed back to Planned is not allowed
* other status changes are allowed by this method

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' Once a reservation has status Issued, its status can no longer be changed by the normal status setter logic.
</div>

=== Planned quantity validation ===

The setter of QTY_PLANNED validates changes through AllowQuantityPlanned(double).

A new planned quantity is only allowed if:

* Status is ReservationStatus.Planned
* LK_MATERIAL is assigned
* the new quantity is greater than 0
* the new quantity is lower than or equal to LK_MATERIAL.AvailableQuantity()

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Quantity rule:''' A planned reservation quantity can only be set while the reservation is still Planned and only if the selected material has enough available quantity.
</div>

=== Actual quantity validation ===

The overridden QUANTITY setter validates changes through AllowQuantity(double).

A new actual quantity is only allowed if:

* the new quantity is greater than 0
* the status is either Planned or Confirmed

=== Link editing rules ===

The setters of LK_TASK and LK_MATERIAL are guarded by reservation status.

The links cannot be changed when the reservation is:

* Issued
* Confirmed

== StorageLocation ==

=== Purpose ===

StorageLocation is a related object used to represent a physical storage location.

A material can reference a storage location via LK_STORAGE_LOCATION.

=== Important properties and values ===

{| class="wikitable"
! Property
! Type
! Values / meaning
|-
| STORAGE_TYPE / StorageType
| int / enum
| Floor, Shelf, Rack, Bin, Pallet, Container
|-
| ACCESS_TYPE / AccessType
| int / enum
| Manual, Forklift, Crane, Automated
|-
| OCCUPANCY_STATUS / OccupancyStatus
| int / enum
| Empty, Partial, Full, Reserved, Blocked, OutOfService
|-
| STORAGE_LABEL
| string
| Label of the storage location.
|-
| LEVEL
| int
| Level of the storage location.
|-
| POSITION
| string
| Position identifier.
|}

== GoodsMovement ==

GoodsMovement is a technical base class.

It provides the common QUANTITY property for material-related objects such as Material and Reservation.

== Relations ==

{| class="wikitable"
! Relation
! Source
! Target
! Meaning
|-
| LK_MATERIAL_MASTER
| Material
| MaterialMaster
| Links a material instance to its master data.
|-
| LK_STORAGE_LOCATION
| Material
| StorageLocation
| Defines where the material is stored.
|-
| LK_MATERIAL
| Reservation
| Material
| Defines which material is reserved.
|-
| LK_TASK
| Reservation
| Task
| Defines the task for which the material is reserved.
|}

== Quantity concepts ==

{| class="wikitable"
! Quantity
! Property / method
! Object
! Stored or calculated
! Notes
|-
| Material quantity
| QUANTITY
| Material
| Stored
| Inherited from GoodsMovement.
|-
| Reserved quantity
| RESERVED_QUANTITY
| Material
| Calculated
| Sum of QTY_PLANNED of confirmed reservations for the material.
|-
| Available quantity
| AvailableQuantity()
| Material
| Calculated
| QUANTITY minus RESERVED_QUANTITY.
|-
| Planned reservation quantity
| QTY_PLANNED
| Reservation
| Stored
| Validated by AllowQuantityPlanned(double).
|-
| Actually issued or consumed quantity
| QUANTITY
| Reservation
| Stored
| Overrides GoodsMovement.QUANTITY and is validated by AllowQuantity(double).
|}

== Reservation workflow ==

=== Creating or editing a reservation ===

Reservations are created manually by the user.

A reservation links a material to a task.

For a reservation to define its planned quantity correctly:

# LK_MATERIAL must be set.
# LK_TASK must point to the task requiring the material.
# Status must still be Planned.
# QTY_PLANNED must be greater than 0.
# QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().

=== Confirmed reservations ===

When a reservation is confirmed, it contributes to the material's reserved quantity.

This affects the available quantity of the material.

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - sum(QTY_PLANNED of confirmed reservations)
</div>

=== Finishing a task ===

When a task is finished, the task logic calls CloseReservations().

The method processes active reservations for the task:

* if a reservation has status Confirmed, it is set to Issued
* otherwise, it is set to Cancelled

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Workflow effect:''' Finishing a task closes its reservations. Confirmed reservations become Issued; other active reservations become Cancelled.
</div>

== Usage in tasks ==

Reservations are the central link between material handling and task execution.

A reservation connects:

* the required material through LK_MATERIAL
* the task through LK_TASK
* the planned quantity through QTY_PLANNED
* the actually issued or consumed quantity through QUANTITY
* the reservation state through Status

This means that material usage is tracked at task level.

== Example workflow ==

=== Step 1: Material master exists ===

A spare part is defined as a MaterialMaster.

{| class="wikitable"
! Field
! Example
|-
| ITEM_NUMBER
| OF-10045
|-
| UNIT_OF_MEASURE
| Piece
|-
| MaterialType
| SpareParts
|}

=== Step 2: Material exists in a storage location ===

A Material object references the material master and a storage location.

{| class="wikitable"
! Property
! Example
|-
| LK_MATERIAL_MASTER
| Oil Filter Type A
|-
| LK_STORAGE_LOCATION
| Storage Shelf A
|-
| QUANTITY
| 10
|-
| RESERVED_QUANTITY
| 0
|-
| AvailableQuantity()
| 10
|}

=== Step 3: Reservation is created for a task ===

A user manually creates a Reservation and links the material to the task.

{| class="wikitable"
! Property
! Example
|-
| LK_TASK
| Replace oil filter
|-
| LK_MATERIAL
| Oil Filter Type A
|-
| Status
| Planned
|-
| QTY_PLANNED
| 1
|}

=== Step 4: Reservation is confirmed ===

The reservation status is changed to Confirmed.

After confirmation, the material's reserved quantity includes the reservation's planned quantity.

{| class="wikitable"
! Quantity
! Value
|-
| Material.QUANTITY
| 10
|-
| Material.RESERVED_QUANTITY
| 1
|-
| Material.AvailableQuantity()
| 9
|}

=== Step 5: Actual quantity is entered ===

The actually issued or consumed quantity is stored in Reservation.QUANTITY.

{| class="wikitable"
! Property
! Example
|-
| Reservation.QUANTITY
| 1
|}

=== Step 6: Task is finished ===

When the task is finished, CloseReservations() is called.

The confirmed reservation is changed to Issued.

== Validation and business rules ==

{| class="wikitable"
! Area
! Rule
! Implemented by
|-
| Planned reservation quantity
| QTY_PLANNED must be greater than 0.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED can only be changed while the reservation is Planned.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().
| AllowQuantityPlanned(double)
|-
| Actual issued or consumed quantity
| QUANTITY must be greater than 0.
| AllowQuantity(double)
|-
| Actual issued or consumed quantity
| QUANTITY can only be changed while the reservation is Planned or Confirmed.
| AllowQuantity(double)
|-
| Reservation status
| Status cannot be changed once the reservation is Issued.
| AllowStatusChange(int newStatus)
|-
| Reservation status
| A reservation cannot be changed from Confirmed back to Planned.
| AllowStatusChange(int newStatus)
|-
| Reservation links
| LK_TASK and LK_MATERIAL cannot be changed when status is Issued or Confirmed.
| Property setters
|-
| Material deletion
| Material cannot be deleted while QUANTITY is greater than 0.
| InternalDeleteAllowed()
|-
| Material deletion
| Material cannot be deleted while active reservations exist.
| InternalDeleteAllowed() and HasActiveReservation()
|}

== See also ==
* [[MRO (Plugin)]]
* [[MRO_Objects_(Client)]]
* [[MRO_Implemented_Objects]]
* [[MROMaintenancePlans]]
{{UnderConstructionEnd}}

MRO Material Management

2026-06-18T14:48:44Z

LMA: /* Usage in tasks */

{{UnderConstructionStart}}
== MRO Material Management ==

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Summary:''' The MRO material management features provide the foundation for handling materials, material master data, reservations, storage locations, and goods movements in MRO workflows. The central objects are Material, MaterialMaster, Reservation, GoodsMovement, and StorageLocation. Materials are linked to master data and storage locations. Reservations link materials to tasks and define planned or actual quantities for maintenance work.
</div>

MRO material management is used to support maintenance work with the required spare parts, consumables, tools, or other material items.

In a maintenance workflow, users may need to know:

* which material is required for a task
* which material master data belongs to a material
* where the material is stored
* how much material is available
* how much material is already reserved
* which reservations exist for a task
* whether a reservation is planned, confirmed, issued, cancelled, or expired

The material management implementation separates the general material catalogue from the actual material quantity and reservation handling.

== Basic concept ==

The material management implementation is built around the following main objects:

{| class="wikitable"
! Object
! Type
! Purpose
|-
| MaterialMaster
| Master data
| Defines the catalogue entry for a material, including item number, unit, packaging, manufacturer data, and material type.
|-
| Material
| Quantity-bearing MRO object
| Represents a material instance or stock entry in MRO. It links to a material master and a storage location and exposes quantity, reserved quantity, and available quantity logic.
|-
| Reservation
| Workflow / transaction object
| Represents a material reservation for a task. It links a material to a task and stores planned and actual quantities.
|-
| GoodsMovement
| Base class
| Provides the common QUANTITY property used by both materials and reservations.
|-
| StorageLocation
| Storage master / location object
| Represents a physical storage location and stores storage-related information such as storage type, dimensions, access type, and occupancy status.
|}

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Core idea:''' MaterialMaster defines what the material is. Material represents the material in the MRO stock or material context. Reservation links a material to a task and reserves a planned quantity for maintenance execution.
</div>

== Object overview ==

{| class="wikitable"
! Object
! Class name
! Base / inheritance
! Main relations
|-
| Material
| UBIK.MRO.Material
| Inherits from GoodsMovement
| LK_MATERIAL_MASTER, LK_STORAGE_LOCATION
|-
| Material Master
| UBIK.MRO.MaterialMaster
| Master data class
| Referenced by Material via LK_MATERIAL_MASTER
|-
| Reservation
| UBIK.MRO.Reservation
| Inherits from GoodsMovement
| LK_TASK, LK_MATERIAL
|-
| Goods Movement
| UBIK.MRO.GoodsMovement
| Base class
| Provides QUANTITY to derived objects
|-
| Storage Location
| UBIK.MRO.StorageLocation
| Functional location specialization
| Referenced by Material via LK_STORAGE_LOCATION
|}

== GoodsMovement ==

=== Purpose ===

GoodsMovement is the base class for material-related quantity-bearing objects.

It defines the common quantity concept used by both:

* Material
* Reservation

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| QUANTITY
| double
| Quantity value for the goods movement. For Material, this is the material quantity. For Reservation, this is the actual reservation quantity and has reservation-specific validation.
|}

== MaterialMaster ==

=== Purpose ===

MaterialMaster represents the material master or catalogue entry.

It stores item-level master data that can be referenced by material instances in MRO.

A material master describes the material independently from a concrete reservation or task.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| ITEM_NUMBER
| string
| Item number or material number of the material master.
|-
| PACKAGING_UNIT
| string
| Packaging unit of the material.
|-
| PACKAGING_SIZE
| double
| Packaging size.
|-
| ACTIVE
| bool
| Defines whether the material master is active.
|-
| UNIT_OF_MEASURE
| string
| Unit of measure used for the material.
|-
| MATERIAL_TYPE
| int
| Underlying integer value for the material type.
|-
| MaterialType
| enum
| Typed accessor for MATERIAL_TYPE.
|-
| MANUFACTURER_COMPANY_NAME
| string
| Manufacturer company name.
|-
| MANUFACTURER_PRODUCT_TAG
| string
| Manufacturer product tag or product identifier.
|}

=== Material type ===

The typed material type accessor is MaterialType.

Known values are:

* SpareParts
* Consumables
* Tools

== Material ==

=== Purpose ===

Material represents a material instance or stock entry in MRO.

It inherits from GoodsMovement and therefore uses the inherited QUANTITY property as its material quantity.

A material links to:

* a material master via LK_MATERIAL_MASTER
* a storage location via LK_STORAGE_LOCATION

It also exposes calculated reservation and availability logic.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Stored or calculated
|-
| LK_MATERIAL_MASTER
| MaterialMaster
| Link to the material master data.
| Stored link
|-
| LK_STORAGE_LOCATION
| StorageLocation
| Link to the storage location where the material is located.
| Stored link
|-
| QUANTITY
| double
| Material quantity. Inherited from GoodsMovement.
| Stored property
|-
| RESERVED_QUANTITY
| double
| Sum of planned quantities of confirmed reservations for this material.
| Calculated property
|-
| MATERIAL_STATUS
| int
| Underlying integer value for the material status.
| Stored property
|-
| MaterialStatus
| enum
| Typed accessor for MATERIAL_STATUS.
| Stored through MATERIAL_STATUS
|}

=== Material status ===

The material status is stored in MATERIAL_STATUS and exposed through the typed accessor MaterialStatus.

Known values are:

{| class="wikitable"
! Value
! Numeric value
! Meaning
|-
| Undefined
| 0
| No specific material status is defined.
|-
| Inactive
| 10
| Material is inactive.
|-
| Active
| 20
| Material is active.
|}

=== Reserved quantity ===

RESERVED_QUANTITY is calculated at read time.

The calculation uses reservations where:

* LK_MATERIAL points to the current material
* STATUS is ReservationStatus.Confirmed

The calculated value is the sum of QTY_PLANNED of these confirmed reservations.

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Important:''' RESERVED_QUANTITY is not treated as a normal stored quantity in the business logic. It is computed from confirmed Reservation objects.
</div>

=== Available quantity ===

The available material quantity is calculated by the method AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Active reservations ===

The method HasActiveReservation() checks whether active reservations exist for the material.

It queries reservations where:

* LK_MATERIAL points to the current material
* STATUS is lower than or equal to ReservationStatus.Confirmed

This means the method considers reservations up to the confirmed state as active.

=== Delete behavior ===

Material.InternalDeleteAllowed() prevents deleting a material if it still has quantity or active reservations.

Deletion is only allowed if the base delete conditions are fulfilled and:

* QUANTITY is lower than or equal to 0
* HasActiveReservation() returns false

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' A Material cannot be deleted while it has a quantity greater than 0 or active reservations.
</div>

== Reservation ==

=== Purpose ===

Reservation represents a material reservation for a task.

It links:

* a task via LK_TASK
* a material via LK_MATERIAL

It stores the planned reservation quantity in QTY_PLANNED and can also store an actual quantity through the overridden QUANTITY property.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
! Important behavior
|-
| LK_TASK
| Task
| Link to the task for which the material is reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| LK_MATERIAL
| Material
| Link to the material being reserved.
| Setter is blocked when status is Issued or Confirmed.
|-
| STATUS
| int
| Underlying integer value for the reservation status.
| Changes are validated by AllowStatusChange(int newStatus).
|-
| Status
| ReservationStatus
| Typed accessor for STATUS.
| Uses the ReservationStatus enum.
|-
| QTY_PLANNED
| double
| Planned quantity for the reservation.
| Setter validates through AllowQuantityPlanned(double).
|-
| QUANTITY
| double
| Actual reservation quantity. Overrides GoodsMovement.QUANTITY.
| Setter validates through AllowQuantity(double).
|}

=== Reservation status ===

The reservation status is stored in STATUS and exposed through the typed accessor Status.

Known values of ReservationStatus are:

{| class="wikitable"
! Status
! Numeric value
! Meaning
|-
| Planned
| 0
| Reservation is planned.
|-
| Confirmed
| 10
| Reservation is confirmed and contributes to the material's reserved quantity.
|-
| Issued
| 20
| Material has been physically issued.
|-
| Cancelled
| 30
| Reservation was cancelled. This is only allowed if the reservation has not been issued.
|-
| Expired
| 50
| Reservation has expired.
|}

=== Status change rules ===

Status changes are controlled by AllowStatusChange(int newStatus).

The following rules are applied:

* no status change is allowed when the current status is Issued
* changing from Confirmed back to Planned is not allowed
* other status changes are allowed by this method

<div style="border-left: 4px solid #d33; background-color: #fff5f5; padding: 10px 12px; margin: 12px 0;">
'''Restriction:''' Once a reservation has status Issued, its status can no longer be changed by the normal status setter logic.
</div>

=== Planned quantity validation ===

The setter of QTY_PLANNED validates changes through AllowQuantityPlanned(double).

A new planned quantity is only allowed if:

* Status is ReservationStatus.Planned
* LK_MATERIAL is assigned
* the new quantity is greater than 0
* the new quantity is lower than or equal to LK_MATERIAL.AvailableQuantity()

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Quantity rule:''' A planned reservation quantity can only be set while the reservation is still Planned and only if the selected material has enough available quantity.
</div>

=== Actual quantity validation ===

The overridden QUANTITY setter validates changes through AllowQuantity(double).

A new actual quantity is only allowed if:

* the new quantity is greater than 0
* the status is either Planned or Confirmed

=== Link editing rules ===

The setters of LK_TASK and LK_MATERIAL are guarded by reservation status.

The links cannot be changed when the reservation is:

* Issued
* Confirmed

This prevents changing the task or material after the reservation has reached a more binding status.

== StorageLocation ==

=== Purpose ===

StorageLocation represents a physical storage location.

It is a functional location specialization and can be linked from Material via LK_STORAGE_LOCATION.

A storage location stores information about storage type, dimensions, access type, label, level, position, and occupancy.

=== Important properties ===

{| class="wikitable"
! Property
! Type
! Meaning
|-
| STORAGE_TYPE
| int
| Underlying integer value for storage type.
|-
| StorageType
| enum
| Typed accessor for STORAGE_TYPE.
|-
| MAX_WEIGHT
| double
| Maximum allowed weight for the storage location.
|-
| MAX_VOLUME
| double
| Maximum allowed volume for the storage location.
|-
| LENGTH
| double
| Length of the storage location.
|-
| WIDTH
| double
| Width of the storage location.
|-
| HEIGHT
| double
| Height of the storage location.
|-
| ACCESS_TYPE
| int
| Underlying integer value for access type.
|-
| AccessType
| enum
| Typed accessor for ACCESS_TYPE.
|-
| STORAGE_LABEL
| string
| Label of the storage location.
|-
| LEVEL
| int
| Level of the storage location.
|-
| POSITION
| string
| Position identifier.
|-
| OCCUPANCY_STATUS
| int
| Underlying integer value for occupancy status.
|-
| OccupancyStatus
| enum
| Typed accessor for OCCUPANCY_STATUS.
|}

=== Storage type ===

Known values of StorageType are:

* Floor
* Shelf
* Rack
* Bin
* Pallet
* Container

=== Access type ===

Known values of AccessType are:

* Manual
* Forklift
* Crane
* Automated

=== Occupancy status ===

Known values of OccupancyStatus are:

* Empty
* Partial
* Full
* Reserved
* Blocked
* OutOfService

== Relations ==

The following relations are relevant for material management.

{| class="wikitable"
! Relation
! Source
! Target
! Meaning
|-
| LK_MATERIAL_MASTER
| Material
| MaterialMaster
| Links a material instance to its master data.
|-
| LK_STORAGE_LOCATION
| Material
| StorageLocation
| Defines where the material is stored.
|-
| LK_MATERIAL
| Reservation
| Material
| Defines which material is reserved.
|-
| LK_TASK
| Reservation
| Task
| Defines the task for which the material is reserved.
|}

== Quantity concepts ==

=== Material quantity ===

The material quantity is stored in Material.QUANTITY.

Because Material inherits from GoodsMovement, the property is inherited from the base class.

=== Reserved quantity ===

The reserved quantity is exposed through Material.RESERVED_QUANTITY.

It is calculated by summing the QTY_PLANNED values of confirmed reservations for the material.

Only reservations with Status equal to ReservationStatus.Confirmed are included in this calculation.

=== Available quantity ===

Available quantity is calculated by Material.AvailableQuantity().

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - RESERVED_QUANTITY
</div>

=== Planned reservation quantity ===

The planned reservation quantity is stored in Reservation.QTY_PLANNED.

It can only be set if:

* the reservation is still Planned
* a material is assigned
* the quantity is greater than 0
* the quantity does not exceed the material's available quantity

=== Actual reservation quantity ===

The actual reservation quantity is stored in Reservation.QUANTITY.

This property overrides GoodsMovement.QUANTITY and can only be set if the status is Planned or Confirmed and the new quantity is greater than 0.

=== Quantity overview ===

{| class="wikitable"
! Quantity
! Property / method
! Object
! Stored or calculated
! Notes
|-
| Material quantity
| QUANTITY
| Material
| Stored
| Inherited from GoodsMovement.
|-
| Reserved quantity
| RESERVED_QUANTITY
| Material
| Calculated
| Sum of QTY_PLANNED of confirmed reservations for the material.
|-
| Available quantity
| AvailableQuantity()
| Material
| Calculated
| QUANTITY minus RESERVED_QUANTITY.
|-
| Planned reservation quantity
| QTY_PLANNED
| Reservation
| Stored
| Validated by AllowQuantityPlanned(double).
|-
| Actual reservation quantity
| QUANTITY
| Reservation
| Stored
| Overrides GoodsMovement.QUANTITY and is validated by AllowQuantity(double).
|}

== Reservation workflow ==

=== Creating or editing a reservation ===

A reservation links a material to a task.

For a reservation to define its planned quantity correctly:

# LK_MATERIAL must be set.
# LK_TASK should point to the task requiring the material.
# Status must still be Planned.
# QTY_PLANNED must be greater than 0.
# QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().

=== Confirmed reservations ===

When a reservation is confirmed, it contributes to the material's reserved quantity.

This affects the available quantity of the material because:

<div style="font-family: Consolas, 'Courier New', monospace; color: #202122; background-color: #f8f9fa; border: 1px solid #c8ccd1; border-radius: 3px; padding: 8px 10px; margin: 10px 0;">
AvailableQuantity = QUANTITY - sum(QTY_PLANNED of confirmed reservations)
</div>

=== Finishing a task ===

When a task is finished, the task logic calls CloseReservations().

The method processes active reservations for the task:

* if a reservation has status Confirmed, it is set to Issued
* otherwise, it is set to Cancelled

The changed reservations are added to the unsaved children through AddToUnsavedChildren(reservation) so that the changes are persisted.

<div style="border-left: 4px solid #36c; background-color: #f8f9fa; padding: 10px 12px; margin: 12px 0;">
'''Workflow effect:''' Finishing a task closes its reservations. Confirmed reservations become Issued; other active reservations become Cancelled.
</div>

== Usage in tasks ==

Reservations are the central link between material handling and task execution.

A reservation connects:

* the required material through LK_MATERIAL
* the task through LK_TASK
* the planned quantity through QTY_PLANNED
* the reservation state through Status

This means that material usage is tracked at task level in the inspected implementation.

== Goods movement usage ==

GoodsMovement is the common base class for quantity-bearing material objects.

Both Material and Reservation inherit from it and expose QUANTITY.

In the inspected implementation:

* Material.QUANTITY represents the material quantity
* Reservation.QUANTITY represents the actual quantity for the reservation and applies reservation-specific validation
* Reservation.QTY_PLANNED represents the planned reserved quantity
* Material.RESERVED_QUANTITY is calculated from confirmed reservations

== Example workflow ==

=== Scenario ===

A task requires one spare part from stock.

=== Step 1: Material master exists ===

The spare part is defined as a MaterialMaster.

{| class="wikitable"
! Field
! Example
|-
| ITEM_NUMBER
| OF-10045
|-
| UNIT_OF_MEASURE
| Piece
|-
| MaterialType
| SpareParts
|}

=== Step 2: Material exists in a storage location ===

A Material object references the material master and a storage location.

{| class="wikitable"
! Property
! Example
|-
| LK_MATERIAL_MASTER
| Oil Filter Type A
|-
| LK_STORAGE_LOCATION
| Storage Shelf A
|-
| QUANTITY
| 10
|-
| RESERVED_QUANTITY
| 0
|-
| AvailableQuantity()
| 10
|}

=== Step 3: Reservation is created for a task ===

A Reservation links the material to the task.

{| class="wikitable"
! Property
! Example
|-
| LK_TASK
| Replace oil filter
|-
| LK_MATERIAL
| Oil Filter Type A
|-
| Status
| Planned
|-
| QTY_PLANNED
| 1
|}

The planned quantity is allowed because the material has enough available quantity.

=== Step 4: Reservation is confirmed ===

The reservation status is changed to Confirmed.

After confirmation, the material's reserved quantity includes the reservation's planned quantity.

{| class="wikitable"
! Quantity
! Value
|-
| Material.QUANTITY
| 10
|-
| Material.RESERVED_QUANTITY
| 1
|-
| Material.AvailableQuantity()
| 9
|}

=== Step 5: Task is finished ===

When the task is finished, CloseReservations() is called.

The confirmed reservation is changed to Issued.

== Validation and business rules ==

The following business rules are implemented in the inspected material management logic.

{| class="wikitable"
! Area
! Rule
! Implemented by
|-
| Planned reservation quantity
| QTY_PLANNED must be greater than 0.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED can only be changed while the reservation is Planned.
| AllowQuantityPlanned(double)
|-
| Planned reservation quantity
| QTY_PLANNED must not exceed LK_MATERIAL.AvailableQuantity().
| AllowQuantityPlanned(double)
|-
| Actual reservation quantity
| QUANTITY must be greater than 0.
| AllowQuantity(double)
|-
| Actual reservation quantity
| QUANTITY can only be changed while the reservation is Planned or Confirmed.
| AllowQuantity(double)
|-
| Reservation status
| Status cannot be changed once the reservation is Issued.
| AllowStatusChange(int newStatus)
|-
| Reservation status
| A reservation cannot be changed from Confirmed back to Planned.
| AllowStatusChange(int newStatus)
|-
| Reservation links
| LK_TASK and LK_MATERIAL cannot be changed when status is Issued or Confirmed.
| Property setters
|-
| Material deletion
| Material cannot be deleted while QUANTITY is greater than 0.
| InternalDeleteAllowed()
|-
| Material deletion
| Material cannot be deleted while active reservations exist.
| InternalDeleteAllowed() and HasActiveReservation()
|}

{{UnderConstructionEnd}}