Data fields qualified with a unit system

This is the most important and most common use case. Usually, you want to output the code of a unit that is assigned to a field. You had to qualify the unit code field with a unit system as every unit code was unit system specific. If you used the "System units" unit system, the field gets changed to the "Code" field. If you used another unit system or a variable, nothing is changed.

Usually, all used export data fields can be converted automatically to the new version without any issue.

Note: the names of the fields are not changed which might be confusing at first. You could rename such fields easily to avoid misunderstandings.

"All units in a unit system" export data provider

The "Unit system" parameter of this export data provider is not mandatory anymore. If you don't configure a value for it, all existing units will be exported.

This data provider is using the Unit root entity now, before it was UnitSystemSpecific. All used export data fields are converted into fields of the Unit entity without changing the qualification.

Example:

It is strongly recommended to check all export templates that use the "All units in a unit system" export data provider. If you want to export unit system specific codes or names, you have to adjust the data fields accordingly. To emphasize this, the log shows an error when you load an export template that should be checked.

"Structure system" export data provider

The sub-data type "Units" of the "Structure system" export data provider now also uses the Unit root entity instead of UnitSystemSpecific. All export data fields will also be migrated to fields of the Unit entity.

Not covered use cases

If you have a variable of data type "Unit system" in your export template with "System units" as value, the variable will still be used in data field qualifications or as data provider parameter but it doesn't have a valid value anymore.

Find out what functions are used

In order to find out if a certain function is used in your export template, you can open the export template properties dialog (right-click on the root node in the "Export format template" view) and switch to the "Functions" tab. All functions used in the template are listed here.

The affected functions are:

ValueGet/ValueSet

These functions use the global export function context. This ensures that all parallel processed packages can access that data.

But you have to make sure that the names under which you want to store data are unique and that the values are not overwritten by others.

If you only want to collect data of sub-modules within one main module, you should use the ValueSetLocal/ValueGetLocal export functions.

You can find a detailed description of these functions in the chapter Export functions.

NumberSet/NumberGet/NumberIncrement

These functions use the global export function context. This ensures unique numbers when incrementing.

Due to parallel processing, you could get another number with NumberGet than you've just set by NumberSet within a module because that number has just been incremented by another - parallel - export package. That means, the counting with NumberIncrement works in parallel mode, but it is not possible to get the current number within a module that is processed in parallel mode.

What does work is to set a number in a first module, increment that number in a second module in parallel mode, and read the number in a third module.

LoopCounter/DatasetCounter

If data rows are removed by data field validation, there may be gaps in the numbering. If you need consecutive numbering without gaps, you cannot use parallel mode for that export.

The reason for that is, that each package gets its own range for data set counters.

Example:

You have 20 items in two packages of ten each. The first package will use 0 - 9 or 1 - 10, the second package 10 - 19 or 11 - 20. If an item of the first package is removed, there will be a gap; the last number reserved for the first package is not used.

Summary

The most important changes are listed here:

• The ExportComponent class provides access to all factories you need:

  • ExportComponent.getDataProviderFactory()

  • ExportComponent.getDataTypeFactory()

  • ExportComponent.getFunctionRegistry()

• The base implementation for all data providers ReportListModelQueryDataProviderBaseImpl has been replaced by the new DataProviderByReportResultBaseImpl class

• The new extension point com.heiler.ppm.texttemplate.core.exportListModelProviders provides the possibility to map an export sub-data type to all data providers supporting a certain repository root entity

• We have separated responsibilities now: the search for objects to be exported is performed by the corresponding data providers, but data will be loaded by list model providers called by the data providers.

The advantages are:

• You can now either

  • implement a new data provider in order to provide a new algorithm to search for objects to be exported OR

  • you can create a new export sub-data type to export data of repository sub-entities in a special way

• Your new data provider will automatically provide all export sub-data types contributed for the root entity of your data provider

• Your new export sub-data type will automatically provide by all existing data providers of the corresponding root entity

Short migration guide based on the "AllUsers" data provider SDK example (PIM 7.1)

If you have to migrate DataType or DataProvider custom implementations you should first have a look at the following example which is part of the SDK.