Maintenance Planner Manual

Introduction¶

The Proemion Maintenance Planner is used for planning maintenance tasks for machines.

It uses a YAML file format to define maintenance schedules and tasks specific to each machine model.

These YAML files allow users to set up a Maintenance Catalog that defines maintenance tasks, including task names, descriptions, intervals, and related actions.

The Maintenance Catalog can then be displayed and managed in a graphical overview within Maintenance in the DataPortal. For more information, see Maintenance Tasks in the DataPortal user manual.

The YAML configuration includes triggers for maintenance events based on machine operating hours or specific service intervals. This can support automated task scheduling based on machine-specific requirements.

This guide provides a structured approach to creating a YAML file for maintenance planning. Adapt the content to the specific needs and specifications of your maintenance system. Regular reviews and updates to the YAML file might be necessary to align with changes in maintenance strategies or machine models.

Set Up Maintenance Planner¶

To set up the Maintenance Planner in your DataPortal, follow the first steps below.

Generate a purchase order: This purchase order outlines the scope and cost of setting up the Maintenance Planner.
Create an issue: Create an issue in the corresponding customer collaboration project in JIRA. Include the YAML file containing all maintenance schedules and configuration.
Inform the FAE: Inform the assigned FAE about the setup process. The FAE coordinates the implementation of the Maintenance Planner.

The process of configuring the Maintenance Planner in the Proemion DataPortal is initiated so that maintenance tasks can be managed and scheduled effectively.

Maintenance Catalog Configuration

YAML File Configuration¶

YAML files are used for the configuration and should be written in a clear, structured format.

Familiarize yourself with YAML syntax, including key-value pairs, lists, and nested structures.

Catalog Configuration Example¶

The following example shows the configuration of the catalog for Operating Hours Maintenance.

---
task:
  name:
    en: "Maintenance at $target hours"
  description:
    en: "A generic description which is added to every task."
  source: "customer_name.maintenance"
settings:
  base: "hours"
  advance: 25
  set_checklist_activities: False
  set_description_activities: True
  sort_description_activities_by_text: False
  sort_description_activities_by_cycle: True
  group_root_activities: True
  set_activity_cycle: False
signals:
  operating_hours:
    key: "operating_hours_signal_key"
    mandatory: true
  service_counter:
    key: "service_counter_signal_key"
    mandatory: true
models:
  Example Model:
    links:
      en:
        link name: "href 1"
        link name 2: "href 2"
    unique_activities:
      250:
        en:
        - control part A
        - check part B
      5000:
        en:
          Special Engine Maintenance:
            - setup OEM appointment
            - check part K
          Special Module Maintenance:
            - setup OEM appointment
            - perform action L
    cycle_activities:
      500:
        en:
          - Clean component Q
          - Perform activity R
          - Replace:
            - part D
            - part E
          - Check:
            - liquid P
      1000:
        en:
        - inspect component X
        - report machine state

Explanation¶

Explanation of the keys used in the catalog configuration example above.

Note

Note that a maintenance task may have the states deadline ("upcoming", "overdue") and progress ("unplanned", "planned", "skipped", "completed"), which are calculated and set by the Maintenance Planner.

With exception to "planned" and "completed" progress, which can be actively set by the user, for example a service technician, in the DataPortal.

For more information, see Maintenance Tasks in the DataPortal manual.

Config	Description
`task`	Task related configurations
`name`	Internationalized name used for every task, template string (e.g., $target $cycle)
`description`	Internationalized description for each task, template string (e.g., $machine_operating_hours)
`source`	Used internally to filter and identify tasks of the same machine's sub-history
`settings`	Settings to steer task presentation and logic
`base`	Entry to define the base of the catalog (hours or dtc)
`set_checklist_activities`	Set activities as checklist items
`set_description_activities`	Set activities in the description field as a string
`sort_description_activities_by_text`	Sort top-level activities by text (relevant if set_description_activities is true)
`sort_description_activities_by_cycle`	Sort top-level activities by cycle (relevant if set_description_activities is true)
`set_activity_cycle`	Sets activity cycle in front of every activity string (e.g., '1000h inspect component X')
`group_root_activities`	Groups sub-activities if root activity has the same text (relevant for merged cycles)
`advance`	Hours in advance a task is opened, also defines the size window for detecting upcoming tasks
`signals`	Signal keys for querying last measurements and timeseries, filters machines based on the last measurement
`models`	Model machines that are maintained, filters machines to match configured model names
`links`	Internationalized links added to a task of a machine of that model
`unique_activities`	Internationalized activities that occur only once at the given operating hours
`cycle_activities`	Internationalized activities that repeat in a cycle every time a multiple of the operating hours is reached

Internationalized Configuration¶

If an item or configuration is internationalized, it needs to be configured with at least one language code such as (en, de, it, fr). See also the example above.

Warning

Completeness and order matter.

If multiple languages are provided, all configuration items need to support all languages, including task name, task description, links, and activities.

The order of configuration with the same meaning but in different languages matters for activities and links.

Wrong Ordered Example¶

en:
  - english activity A
  - english activity B
de:
  - german activity B
  - german activity A

A and B activity texts would be mixed up on task creation and show different meanings when switching the DataPortal's language setting.

Correct Ordered Example¶

en:
  - english activity A
  - english activity B
de:
  - german activity A
  - german activity B

Additional Tips¶

Comments: Use # for comments to explain sections or parameters for future reference.
Indentation: YAML is sensitive to indentation. Ensure consistent use of spaces, not tabs, for nested elements.
Consistency: Be consistent with naming conventions and structure throughout the document.

How to Configure Activities¶

Activities are a checklist of single steps for completing the maintenance task. See also Maintenance Activities. Activities can be configured in two ways.

Flat Activities List¶

The simplest way is a flat list of activity strings. Lists are indicated with - in front of an element.

en:
  - control part A
  - check part B

Nested Activities List¶

Nested activities are configured as a map (dict).

en:
  Special Engine Maintenance:
    - setup OEM appointment
    - check part K
  Special Module Maintenance:
    - setup OEM appointment
    - perform action L

Flat and Nested Activities Lists¶

If flat and nested activities appear together, they need to be configured as a list of string and dict elements.

en:
  - Clean component Q
  - Perform activity R
  - Replace:
    - part D
    - part E
  - Check:
    - liquid P

Property and Action Key Configuration¶

This section defines the configuration of property and action keys used within the maintenance setup.

Property keys can be specified to access additional machine properties that are relevant for maintenance.

Action keys can be specified to reference actions that can be executed as part of the maintenance process.

Both configurations are optional and allow mapping between logical keys used in the configuration and the actual property or action identifiers used in the fleet.

Configured properties can be used to exclude individual machines from maintenance based on a defined property value.

---
task:
  ...
settings:
  ...
signals:
  ...
properties:
  equipment_id: "equipment_id_property_key"
actions:
  service_hours_reset: "action_id"
models:
    ...

Explanation¶

properties: (optional) key and value (property key) that are used for getting additional maintenance relevant machine properties.
actions: (optional) key and value (action key) that are used for executing an action.

Ignore Individual Machines Using Machine Properties¶

If a property configuration with the normalized key maintenance_service_excluded is defined in the catalog, machines can be excluded from maintenance based on this property.

The following example shows how to configure the property in the catalog.

properties:
  maintenance_service_excluded: "maintenance_service_excluded_example_key"

All machines that have the property maintenance_service_excluded_example_key configured and populated with the value true (case-insensitive) will be excluded from maintenance, even if their model is present in the catalog.

Note

The actual machine property key is free of choice for the fleet use.

Maintenance Catalog Example¶

This example shows a maintenance catalog based on operating hours for an Industrial Material Handler.

It illustrates a typical setup including maintenance intervals, activities, spare parts, and external links.

Functional Description¶

The maintenance catalog is based on operating hours as the maintenance trigger.

Maintenance tasks are created based on the signal
value.common.machine.hours.operation.total
An advance warning of 50 hours is configured before a task becomes due
A service counter (value.common.machine.service.count) is used to track completed maintenance

Maintenance Intervals¶

The following maintenance intervals are defined:

50h (one-time)
Initial service including checks, replacements, and lubrication
250h (recurring)
Regular service including oil change, inspections, and Kit A
500h (recurring)
Extended service including filter replacements, adjustments, and Kit B
1000h (recurring) Major service including full fluid changes, inspections, and Kit C
2000h (recurring)
Annual inspection including structural checks and major component inspection

Activities and Resources¶

Each interval defines:

A set of activities (e.g. Check, Replace, Inspect, Test)
Required spare parts grouped into kits
Links to external ordering systems and parts catalogs

YAML Configuration Example¶

The following YAML configuration represents the maintenance catalog described above.

YAML Configuration Example (click to view)

---
task:
  name:
    en: "Maintenance at $target hours"
  description:
    en: "Maintenance task for Industrial Material Handler."
  source: "industrial_material_handler.maintenance"

settings:
  base: "hours"
  advance: 50
  set_checklist_activities: False
  set_description_activities: True
  sort_description_activities_by_text: False
  sort_description_activities_by_cycle: True
  group_root_activities: True
  set_activity_cycle: False

signals:
  operating_hours:
    key: "value.common.machine.hours.operation.total"
    mandatory: true
  service_counter:
    key: "value.common.machine.service.count"
    mandatory: true

models:
  Industrial Material Handler:
    links:
      en:
        Order Kit-A: "https://shop.equipment-oem.com/parts-portal#Kit-A"
        Parts catalog: "https://parts.equipment-oem.com/catalog/handler-series"
        Order Kit-B: "https://shop.equipment-oem.com/parts-portal#Kit-B"
        Order Kit-C: "https://shop.equipment-oem.com/parts-portal#Kit-C"

    unique_activities:
      50:
        en:
          Check:
            - Battery connections/electrolyte
            - hydraulic oil level
            - all fluids
            - tire pressure/condition
            - safety systems
          Replace:
            - Engine oil filter (first service)
            - hydraulic pressure filter cartridges
          Lubricate:
            - Pivot points
            - bearings
            - steering linkages

    cycle_activities:
      250:
        en:
          Change:
            - Engine oil (15W-40)
            - engine oil filter
            - fuel filter
          Check:
            - Air filter
            - drive belts
            - brakes
            - hydraulic hoses
          Inspect:
            - Structural welds
            - mounting bolts
            - electrical connections
          Kit A (250h):
            - Engine oil filter ×1
            - fuel filter ×1
            - O-rings ×4
            - drain plug washers ×2

      500:
        en:
          Replace:
            - Primary air filter
            - fuel pre-filter
            - fuel main filter
            - hydraulic return filter
            - cabin air filter
          Change:
            - Transmission oil (if equipped)
          Check/Adjust:
            - Valve clearance
            - parking brake
            - steering alignment
          Test:
            - Hydraulic cylinders load test
            - hydraulic pressure (target ~210 bar)
          Kit B (500h):
            - Primary air filter ×1
            - fuel pre-filter ×1
            - fuel main filter ×1
            - hydraulic return filter ×1
            - cabin air filter ×1
            - transmission oil filter ×1

      1000:
        en:
          Replace:
            - Secondary air filter
            - all hydraulic filters + seals
            - breather filters
            - AdBlue/DEF filter (if equipped)
          Change:
            - Hydraulic oil (full system)
            - axle differential oil
          Inspect:
            - Turbocharger
            - exhaust system
            - engine mounts/dampeners
          Service:
            - Clean radiator/oil cooler
            - flush cooling system and replace coolant
          Kit C (1000h):
            - Hydraulic pressure filters ×3
            - hydraulic return filters ×2
            - breather filters ×2
            - secondary air filter ×1
            - AdBlue filter ×1
            - complete seal kit
            - filter housing O-rings ×12

      2000:
        en:
          Replace:
            - Drive belts (alt/fan/AC)
            - coolant (flush)
            - brake fluid
          Major inspection:
            - Load-test structure
            - NDT of critical welds (if needed)
            - calibrate load sensors/safety systems
          Check:
            - Wheel bearings
            - final drive planetaries
            - hydraulic pump wear/efficiency

Mapping to YAML Configuration¶

The following table maps the functional elements of this example to their corresponding YAML configuration fields.

Functional Concept	YAML Configuration
Machine type	`models: Industrial Material Handler`
Maintenance base (operating hours)	`settings.base: "hours"`
Primary signal (operating hours)	`signals.operating_hours.key`
Service counter	`signals.service_counter.key`
Advance warning (50h)	`settings.advance: 50`
One-time maintenance (50h)	`models.<model>.unique_activities.50`
Recurring maintenance (250h, 500h, etc.)	`models.<model>.cycle_activities.<interval>`
Activities (Check, Replace, etc.)	Nested under `unique_activities` or `cycle_activities`
Spare parts kits	Represented as grouped activity entries
External links	`models.<model>.links`

Use Cases¶

Different use cases for maintenance tasks, maintenance cycles, and their catalog configuration are described below.

Hours To Service¶

The simpler nature of this mode results in a simpler catalog.

There are no unique activities for now and only one cycle per model is allowed, which sits at a fixed 0 hours (hours to next service).

---
settings:
  base: "hours"
  advance: 25
signals:
  hours_to_service:
    key: "hours_to_service_signal_key"
    mandatory: true
  service_counter:
    key: "service_counter_signal_key"
    mandatory: true
models:
  Example Model:
    links:
      en:
        link_name: "example doc link"
    cycle_activities:
      0:
        en:
        - Replace:
          - part B
          - part C
        - Check:
          - liquid P
        - Clean component Q
        - Perform activity R

Default Maintenance¶

A special entry can be added to the catalog: default_maintenance.

This is a reserved name.

If this entry is found in the catalog, all machines or models of the customer's fleet are used for maintenance.

For every model that does not already have an entry in the catalog, see Catalog Configuration Example, the default maintenance entry is applied, with exception to the ignored_models list.

This list can be added to the default_maintenance entry. Defined models are ignored for the default maintenance.

A model cannot be present in the catalog and in the ignored_models list at the same time.

---
settings:
  base: "hours"
  advance: 50
models:
  default_maintenance:
    ignored_models: ['Ignore_Old_Model', 'Ignore_Broken_Model']
    cycle_activities:
      500:
        en:
          - A Default Activity

Note

As soon as this entry is found, maintenance will be performed for all machines of the fleet, if the required data, signals, and properties are given and the machine model is not present in the ignored_models list.

Multimodel Entries¶

If models share the same maintenance configuration, they can be set in a single entry by adding all model names to the key separated with ;.

Instead of configuring as follows:

Model_A:
  cycle_activities:
    1000:
      en:
        Replace:
        - Part X
Model_B:
  cycle_activities:
    1000:
      en:
      Replace:
      - Part X

The models can be configured together as follows:

Model_A;Model_B:
  cycle_activities:
    1000:
      en:
        Replace:
        - Part X

This results in the same configuration.

Complete Catalog Sample¶

The following is a complete example for the catalog regarding Operating Hours Maintenance.

The example also shows how to configure machine property keys and action ids, if they are required for the customer's maintenance logic.

---
task:
  name:
    en: "english name"
  description:
    en: "english description"
settings:
  base: "hours"
  advance: 50
  set_checklist_activities: true
  group_root_activities: true
signals:
  operating_hours:
    key: "operating_hours_signal_key"
    mandatory: true
  service_counter:
    key: "service_counter_signal_key"
    mandatory: true

models:
  default_maintenance:
    ignored_models: ['Test Model', 'Ignored_Old_Model']
    cycle_activities:
      500:
        en:
        - default maintenance information

  Model A;Model B;Model C:
    links:
      en:
        Maintenance Information: "link to maintenance information"
    unique_activities:
      200:
        en:
          Check:
          - part x
          - part y
    cycle_activities:
      500:
        en:
          Replace:
          - part e
          - part f
          Refill:
          - liquid p
      1000:
        en:
          Check:
          - component d
          - part g
          - part h
          Refill:
          - liquid q

  Model D:
    links:
      en:
        Maintenance Information Model D: "link to maintenance information Model D"
    cycle_activities:
      2000:
        en:
          Replace:
          - part k
          - part l
          Refill:
          - liquid p
          - liquid q