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 calendar intervals. This can support automated task scheduling based on model-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.

The catalog's logic details (task, signals, properties, and similar top-level configuration) are typically set up together with your Proemion contact during onboarding. This page focuses on the models section, where you maintain the actual maintenance items and activities.

Catalog Configuration Example¶

The following example shows the models section of a catalog, including both operating-hours-based and calendar-based maintenance items.

models:
  Example Model:
    links:
      en:
        "Service Docs": "https://example.com/docs"
    unique_activities:
      200sh:                  # once at first 200 operating hours
        en:
          - commissioning check
      90cd:                   # once 90 days after activation
        en:
          - first annual inspection
    cycle_activities:
      500sh:                  # every 500 operating hours
        en:
          Replace:
            - oil filter
            - air filter
      1000sh:
        en:
          - inspect drive chain
      500sh|90cd:             # every 500 operating hours OR 90 days, whichever first
        en:
          - lubricate pivot points

Cycle Keys¶

Each activity bucket under unique_activities or cycle_activities is keyed by when it triggers:

Shape	Example	Trigger
`<n>sh`	`500sh`	every `n` operating hours
`<n>cd`	`90cd`	every `n` calendar days since the machine's activation date
`<n>sh\\|<m>cd`	`500sh\\|90cd`	whichever axis is reached first

cycle_activities repeat every period; unique_activities fire exactly once per machine.

A dual-axis cycle key such as 500sh|90cd configures a single maintenance activity that is triggered by either operating hours or calendar time, whichever target is reached first.

This is useful for maintenance instructions such as "every 500 operating hours or every 90 days".

Within a dual-axis cycle, both axes are tracked together: whichever axis triggers the task, completing it resets both axes at once.

Different cycle keys (e.g. 500sh and 500sh|90cd) are independent of each other and each open their own task.

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
`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, keyed by cycle key (e.g. `200sh`, `90cd`)
`cycle_activities`	Internationalized activities that repeat, keyed by cycle key (e.g. `500sh`, `90cd`, `500sh\\|90cd`)

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 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.

type: scheduled
task:
  ...
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.

Note

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

Ignore Individual Machines¶

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.

Calendar Activation Date¶

If a property configuration with the normalized key maintenance_activation_date is defined in the catalog, its value is used as the starting point for calendar-based maintenance items.

If the machine's commission date is available, it is used instead.

For more information, see Calender-based Maintenance in the DataPortal manual.

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

properties:
  maintenance_activation_date: "activation_date_example_key"

Inject Extra Activities¶

If a property configuration with the normalized key maintenance_activities is defined in the catalog, its value is used to inject additional activities into a task at creation time, alongside the catalog-defined activities. This requires activities.set_property: true to also be set in the catalog.

The property value must be JSON-encoded with the same shape as catalog activities, for example:

{
  "en": [
    {"parent_en": ["activity_a_en", "activity_b_en"]},
    "activity_c_en"
  ],
  "de": [{"parent_de": ["activity_a_de", "activity_b_de"]}, "activity_c_de"]
}

Note

If the property is missing, malformed, or doesn't match the catalog's configured languages, it is silently skipped and the task is created from the catalog only.

Maintenance Catalog Example¶

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

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

The catalog's logic details (task, signals, properties, and similar top-level configuration) are typically set up together with your Proemion contact during onboarding.

Functional Description¶

The maintenance catalog is based on operating hours and calendar intervals as maintenance triggers.

Maintenance tasks are created based on the signal
value.common.machine.hours.operation.total
An advance warning of 50 operating hours or 7 calendar days is configured before a task becomes due
A service counter (value.common.machine.service.count) is used to track completed maintenance
Maintenance tasks can also be triggered by a calendar interval. If both a signal-based and a calendar target are configured for the same activity, the task becomes due whichever target is reached first — for example, every 500 operating hours or every 90 days.

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
500h or 90 days (recurring, whichever comes first)
Lubrication and inspection triggered by either operating hours or calendar time
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)

type: scheduled

task:
  name:
    en: "Maintenance at $target hours"
  description:
    en: "Maintenance task for Industrial Material Handler."
  source: "industrial_material_handler.maintenance"
  advance:
    signal_hours: 50
    calendar_days: 7

signals:
  operating_hours:
    key: "value.common.machine.hours.operation.total"
    mandatory: true
  service_counter:                          # optional — only required if task completion
    key: "value.common.machine.service.count" # is detected automatically via signal;
    mandatory: true                         # omit if tasks are closed manually in the UI

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:
      50sh:
        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:
      250sh:
        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

      500sh:
        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

      500sh|90cd:             # every 500 h OR 90 days, whichever comes first
        en:
          Lubricate:
            - Articulated joints and pivot points
            - drive shaft bearings
          Inspect:
            - Hydraulic hose condition
            - visible wear on moving parts

      1000sh:
        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

      2000sh:
        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`
Catalog type (scheduled maintenance)	`type: scheduled`
Primary signal (operating hours)	`signals.operating_hours.key`
Service counter (optional)	`signals.service_counter.key`
Advance warning	`task.advance.signal_hours` / `task.advance.calendar_days`
One-time maintenance (50h)	`models.<model>.unique_activities.50sh`
Recurring maintenance (hours)	`models.<model>.cycle_activities.<interval>sh`
Dual-axis maintenance (hours OR calendar)	`models.<model>.cycle_activities.<n>sh\\|<m>cd`
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.

The examples on this page show the models section only. See Maintenance Catalog Example for a complete catalog configuration.

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 0sh (hours to next service).

models:
  Example Model:
    links:
      en:
        link_name: "example doc link"
    cycle_activities:
      0sh:
        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.

models:
  default_maintenance:
    ignored_models: ['Ignore_Old_Model', 'Ignore_Broken_Model']
    cycle_activities:
      500sh:
        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:
    1000sh:
      en:
        Replace:
        - Part X
Model_B:
  cycle_activities:
    1000sh:
      en:
      Replace:
      - Part X

The models can be configured together as follows:

Model_A;Model_B:
  cycle_activities:
    1000sh:
      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.

See Property and Action Key Configuration for how to configure machine property keys and action ids, if required for the customer's maintenance logic.

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

  Model A;Model B;Model C:
    links:
      en:
        Maintenance Information: "link to maintenance information"
    unique_activities:
      200sh:
        en:
          Check:
          - part x
          - part y
    cycle_activities:
      500sh:
        en:
          Replace:
          - part e
          - part f
          Refill:
          - liquid p
      1000sh:
        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:
      2000sh:
        en:
          Replace:
          - part k
          - part l
          Refill:
          - liquid p
          - liquid q