Migration Guide for the Signal Catalog

Introduction¶

The Signal Catalog enables editing of signal definitions used across the organization's fleet.

In addition, you can migrate all currently applied signal definitions from the machines' PDCs to the DataPlatform or DataPortal. This allows you to edit the repeated signal definitions for all machines at once, instead of editing identical signal definitions separately in each machine's PDC, which previously led to redundant work and conflicts.

This guide describes how to migrate signal definitions to the Signal Catalog, and how to add a new signal once migration is in use.

Start with the migration of system-used metrics

Focus first on migrating the System-Used Signals (value.common.*), i.e. the standard metrics used for DataPlatform standard features such as the Machine Companion App (Google Play), Maintenance Tasks, and OEM Insights. Also start with other easy-to-migrate signals, e.g. signals without conflicts or with predefined units. This allows you to continue using the DataPlatform and DataPortal while migrating the remaining signals subsequently.

Examples of system-used metrics:

value.common.machine.hours.operation.total
value.common.engine.fuel.level
value.common.machine.distance.total

Migrate Signals¶

You can migrate signal definitions to the Signal Catalog individually, or perform a mass migration for all signals that do not have any conflicting configuration. Start the migration with the signals without conflicts, then migrate the signals with conflicts one after the other.

The Signal Catalog migration can be done in incremental steps; you do not need to migrate all signals in one batch.

Warning

Signal migration cannot be reverted.

Note

Migrating signals changes the process for PDC changes and adding new signals, see Add New Signal.

In the Catalog column, the Signal Catalog table shows whether a signal key is Not in Catalog, and indicates Conflicts within signal definitions if there are any. The View summary toggle shows the total number of signals Without conflicts, In Catalog, and Use standard metric key.

Requirements¶

Migrating the signal properties requires the Models:Admin permission set (see Models Subject) for the DataPortal.
Signal definitions are stored at the tenant, so the user must be a member of a tenant organization (see Tenant).
Only valid signal definitions are considered for migration. A valid signal definition:
- Has no conflicts.
- Uses a predefined unit; custom units are not supported.
- Has boundTo: machine, not model.
- Is a standard signal present in the standard Signal Catalog, or a custom signal using the value.* prefix.

Note

In the DataPortal, signal definitions are not strictly validated against the Proemion Standard Metrics.

Migrate All Signal Definitions Without Conflicts¶

Open Settings > Machine Data Management > Signal catalog.

Figure 1: Signal Catalog table
Click Migrate signals to catalog in the upper-right corner.

Note

This button is not shown once all signals have already been migrated.
Confirm the dialog window that displays the number of signals to be migrated.

✓ When the signal definitions are valid, i.e. meet the Requirements, the success message shows the number of successfully migrated signals. In the Signal Catalog table they get the label In Catalog and can then be managed in the UI, see View and Edit or Delete Signal Details.

Migrate Specific Signal Definitions¶

Open Settings > Machine Data Management > Signal catalog.
Click View Signal Details at the end of the row of the desired signal key to open the details page.

Figure 2: Signal definition - Not in Catalog
Click Migrate to catalog in the upper-right corner.

If the signal key does not meet the Requirements, it is not eligible to migrate and the button is greyed out:

Figure 3: Signal not eligible to migrate
Confirm the dialog window to start the migration.

✓ A success message indicates the successful migration. In the Signal Catalog table the signal key then gets the label In Catalog.

Migrate Signals With Conflicts¶

Note

You can display the non-migrated signal definitions by filtering the table on the Not in Catalog option in the Catalog column.

For the general procedure, see Resolve Conflicts. The following sections give guidance on resolving frequently occurring migration conflicts. Contact Service and Support if you run into problems not covered here.

Signal Label Conflicts¶

Choose the most appropriate signal name. If the conflicting signal names are completely different, this could be a case of two different signals using the same key. Resolve this conflict by updating the PDCs first.

Unit Key Conflicts¶

If custom units are used, check whether an appropriate standard unit is available and select it. If no appropriate standard unit is available, check with support whether it can be added. Otherwise, choose the most appropriate custom unit.

If completely different units are used, resolve the conflict by updating the PDCs first; the PDC transformers and the historical data may also need to be adjusted. Contact support for assistance in that case.

Warning

Be careful when resolving conflicts on different units. The wizard suggests changing units that are assigned wrongly to Proemion Standard Metrics signals, which results in the wrong unit being displayed. Resolve this conflict by updating the PDCs first.

Data Type Conflicts¶

This conflict most likely results from different signals using the same signal key. Resolve it by updating the PDCs first.

Format Conflicts¶

Check what is the most reasonable formatting for this signal, and use the highest precision formatting.

Min/Max Conflicts¶

Check the machine's signal specification for the correct values, and use the most narrow range that is still reasonable for this signal.

Logical Type Conflicts¶

Check the machine's signal specification for the correct signal type, and use the most reasonable signal type. If the options are Measurement or a specific type, usually choose the specific type. Set signals that are counters as Counter with the direction setting.

Organization Type Conflicts¶

Check which organization types the signal should be restricted to, and use the most narrow range.

Add New Signal¶

New signals need to be introduced to the Signal Catalog before being added to a PDC.

To add new signals to an existing PDC, or to create an entirely new PDC for a new model, follow these steps:

Create the new signal as described in Create Signal.
Download the PDC file for the respective model as described in PDC Download.
Add the reference to the new signal to the <ValueDefinitions> section by pasting the following line to the tag:
```
<ValueDefinition key="[New Signal Key]" managedByDataPlatform="true"/>
```
Add the parsing definitions for the new signal to the PDC, see PDC Parsing Definition.
Upload the PDC to the model again as described in PDC Upload.
Assign the new version of the PDC to the machines as described in Update machines to a new PDC version.

✓ The new signal is now included in both the Signal Catalog and the PDC, and applied to the machine model.

Adapt PDC¶

If you intend to make manual changes to the PDC, first download the latest version from the DataPortal. On download, the DataPortal replaces all <ValueDefinition> elements for signals from the catalog with <ValueDefinition ... managedByDataPlafrom=true />. You can then apply your changes and upload it again.

Warning

PDCs with a <ValueDefinition> for a signal from the catalog, instead of <ValueDefinition ... managedByDataPlafrom=true />, are rejected upon upload.

Add New PDC¶

To create an entirely new PDC, download the PDC Template and add and adjust the required information, such as uuid, version, Name, Transformers, and ParsingDefinition. See PDC Manual for details.

Warning

The PDC Builder software is deprecated and no longer works for PDCs with migrated signals. Edit the parsing definitions directly in the PDC file using an XML or text editor instead.

Service and Support¶

The latest versions of the drivers, software, firmware, and documentation are available at Document Library.

Do you need help or want to report a bug?
Visit Proemion for more information, or raise a ticket via Support.

Firmware Updates and Support¶

To ensure the best performance and security of your devices, we strongly recommend always installing the latest firmware provided by Proemion.

Please note:

We do not provide technical support for issues caused by outdated firmware.
Errors resulting from outdated firmware are considered non-qualified errors and are not covered by warranty or support.

Regular firmware updates are essential to maintaining the functionality of your devices.
If you need assistance with the update process, please contact our Service and Support.

For more information on the Firmware Update, check the device manual of your device at the Document Library.