Export functions vs. data field validations

You can use export functions to control whether certain data records are output or not.

However, you should consider using data field validations. The advantage is that data is already checked and records are removed when reading the data. This could offer a considerable performance advantage. In addition, the logged information is more convenient because the number of affected objects is logged in the export protocoll, and the objects can be viewed later.

However, the data field validations can only be configured globally in the export template. It is not possible to define a module-specific validation for a data field.

Error logging

For each export function execution the result is returned, or an exception is thrown. The function result replaces the current function token text. If the function throws an exception, the function token text is replaced with an empty string, and an error respectively a warning is logged to the export protocol.

In addition to that, you can configure if errors or warnings should be written into the export file. This may be useful during the implementation of an export template or if you want to analyze a problem.

Processing sequence for export functions

You need to know how export functions are executed to understand how you can use it the right way.

Each export function is executed during an export. The only exception is a function call within a comment "{!...}". The innermost function is exceuted first.

Example:

The innermost functions are {?Function3 "value1"} and {?Function5 "value3"}. The processing sequence is the following:

1. {?Function3 "value1"} --> Result1

2. {?Function2{?Function3 "value1"} Result1, "value2"} --> Result2

3. {?Function5 "value3"} --> Result3

4. {?Function4{?Function5 "value3"} Result3, "value4"} --> Result4

5. {?Function1{?Function2 Result1, "value2"} Result2,{?Function4 Result3, "value4"} Result4 } --> Result5

Conditional function call

A conditional export function call is not possible. Each export function is called during an export.

But if you arrange the nesting the right way, you'll get the correct result. Make sure each function is called with the correct parameter value.

The outermost function handles masking

The following simple example shows this.

Desired exceptions

Sometimes you have to use control characters as part of function parameters to create the output you need. In this cases you must prevent those characters from being masked.

In the following example we want to create an xml tag only if we have content for that.

The most obvious way is just to use an export function that creates an output if a condition is fulfilled, here the condition is "the data field value is not empty" and we can use the IfNotEmptyThen function.

But we don't get the output we've expected, the angle brackets ("<", ">") are masked too.

We have two ways to solve that problem.

Different Data Context

When an export is started, the data to be processed is split into packages. In standard configuration, each package contains 25.000 items to be exported. When enabling parallel processing, multiple packages will be processed simultaneously. For more information about this topic, see: Parallel Export. In case of such an parallel export, the scope of some export functions is limited by the packages that are being processed. We differentiate between two contexts during such exports.

Memory consumption

In a sequential export one data set is executed at a time. In a parallel export, not one but multiple items are processed at the same time.

Additional data that consumes memory can be created by using the functions ValueGet/ValueGetLocal and ValueSet/ValueSetLocal. All data that is written, exists until it is overwritten, cleared or until the export is finished.

The chosen key is important here.

Example:

ValueSet "{&Item.Item no.}{&Language-specific data.Language}" <someValue>

A1german

A1english

A1french

A2german

A2english

A2french

A3german

A3english

A3french

A4german

A4english

A4french

ValueSet "{&Language-specific data.Language}" <someValue>

german

english

french

ValueGet/ValueSet, ValueGetLocal/ValueSetLocal

If you need some logic to store certain data and read it again later, you can use these functions.

The ValueGet and ValueSet 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.

NumberGet/NumberSet/NumberIncrement

Similar to ValueSet and ValueGet, you can use NumberSet and NumberGet to store and read a number by a certain name. Additionally, you can increment a number using NumberIncrement.

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

But due to parallel processing, you could get another number with NumberGet than you've just set by NumberIncrement within a module because that number could have just been changed by another - parallel - export package. That means, the counting with NumberIncrement works in parallel mode, but it is not possible with certainty 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

Both functions return the consecutive number of the current data record within an export module or sub-module where LoopCounter starts at 0 and DatasetCounter at 1.

Important for parallel export mode is that 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.

Format-specific functions: XML

There are some functions to create xml tags:

• CreateXMLTagWithValue

• CreateXMLTagWithContent

• CreateCDataSection

Format-specific functions: JSON

If you want to create JSON files you can use the following functions:

• JSONArray

• JSONObject

• JSONObjectElement

• JSONStringElement

• JSONStringValue

Rules

• no data access within export functions (performance problems: export functions are executed for each exported entry)

• implementation in a core plugin --> install on server and client

• function instances will be reused, that's why functions have to be stateless, i.e. parameter values must not be stored in class variables

Extension point

Export functions have to be contributed at the com.heiler.ppm.script.core.functionClass extension point:

This extension point can be contributed for different standard contexts: "export", "general", "editablePreview" and "fileName"
The context is used in the standard functions implementation to enable functions for a specific context.

• "general": It's the default context of functions if nothing else is set. All functions with this context are generally available in export template module's content

• "export" : Actually it's identical to the "general" context

• "editablePreview": Functions with this context mark a preview export template as making the preview editable

• "fileName": Functions with this context are available for export file name definition

Interface

A custom export function should be a subclass of com.heiler.ppm.script.core.FunctionBaseImpl. That base implementation contains some default implementations already.

Example

This is a simple example of an export function that provides the functionality of org.apache.commons.lang.StringUtils.substring(String str, int start) and org.apache.commons.lang.StringUtils.substring(String str, int start, int end).

It expects two or three parameters. A CoreException is thrown if too less (< 2) or too many (> 3) parameters are passed or if the second or third parameter is invalid.

This function returns a substring of the string given with the first parameter, according to the second and third parameter values.

Enhancements: error level configuration (since PIM 7.1.02.00)

Export functions are usually called for every exported data set. That's why you may get many errors if some data fields are empty. If you don't want this cases to be handled as errors you can enable your function to provide an error level configuration.

Provided "fileName" export functions:

Further information

• A new file name is not saveable if a variable or function isn't available during configuration

• Invalid characters which are not allowed in the file name will be replaced

• If the file name is empty after replacement, an error occur

• If the variable is used in the file name pattern, the variable is not be deletable

• If there is any exception while replacing variables with their value during export, the export will continue with the file name without replacement.