Properties and runtime parameters

A data mapping configuration's properties hold data that can be used throughout the data mapping workflow to compare against in conditions or to complement the existing data.

A number of properties are predefined, such as the path of the file that is currently being processed, and the current position of the pointer in the data.
It is also possible to define custom properties. For instance, a unique ID could be created to be added to each record in the output for integrity checks later on, or a time stamp could be added to create reports. A tag could be added to process certain records differently.

Ultimately data mapping configurations are meant to be used in automated processes, to extract data from a particular type of data file.
Runtime parameters can pass values from an automation tool - PlanetPress Workflow, usually - to a template, data mapping configuration or Job Creation Preset. The actual values of the parameters may be different from one time that a process runs to the next, which means the output could be different even when the same template, data mapping configuration and/or Job Creation Presets are used.

In a data mapping configuration, certain runtime parameters are predefined, such as the ones that refer to the JobInfo variables in Workflow. For an overview see Fixed automation properties.

You can also define custom runtime parameters. With those, you could, for example:

• Pass a JSON structure, containing boundary information as well as the name and location of fields to be extracted dynamically from a data stream. This way, a generic data mapping configuration could be used to process several kinds of different files.
• Define default values that are different from one data mapping instance to the next, even when using the same data mapping configuration.

Defining custom properties and runtime parameters

Defining properties

You can define custom properties under Properties in the Preprocessor step (see Preprocessor step properties).

To add a property:

1. Select the Preprocessor step on the Steps pane.
2. On the Step properties pane, under Properties, click the Add button . See Properties for an explanation of the settings for properties.

Defining runtime parameters

Custom runtime parameters in a data mapping configuration are defined via the Parameters pane. This can be found next to the Data Model pane at the right. If it isn't visible, use the menu: Window > Show View > Parameters to make it visible.

To add a runtime parameter, start by opening the data mapping configuration to which the parameter should be added. Make sure the data mapping configuration is visible in the workspace; then open the Parameters pane.

To add a parameter:

1. Click the Add button. The Add Parameter dialog opens.
2. Give the runtime parameter a name. The name is needed to access the parameter in a script and to set its source in the automation tool.
3. Optionally, set a debug value. Note that the debug value is never actually used outside of the DataMapper. Its only purpose is to make it easier to design and test the data mapping configuration. The actual value of a runtime parameter comes from the automation tool, e.g. the Execute Data Mapping task or the All in One task in PlanetPress Workflow.
4. Click OK.

Editing a runtime parameter

To modify a runtime parameter, click its name or value in the Parameters pane and enter the new name or value.

To remove a runtime parameter, select it and click the Remove button ().

Accessing properties and runtime parameters

There are different ways to access properties and runtime parameters in a data mapping workflow.

• Property-based fields. A property-based field is filled with the value of a property. See Property-based field.
• Step settings. Properties can be selected in the Condition, Multiple Conditions and Repeat step properties (see Condition step, Multiple Conditions step and Repeat step).
• Script. Scripts can access properties through the DataMapper Scripts API. (See also: Using scripts in the DataMapper.)
  • The sourceRecord object has a properties array that lets you access custom properties that are added to each individual record, i.e. the scope of the property is set to Each record. (See: sourceRecord.)
    To change the value of such a property you could use an Action step (see Action step). Note that the property's value will be reset at the beginning of each source record.
  • The data object has a properties array that lets you access custom properties of the data as a whole, i.e. the scope of the property is set to Entire data. (See: data.) These are read-only.
  • To access a runtime parameter inside of any JavaScript code within the data mapping configuration,  use automation.parameters.runtimeparametername. (See: automation.) Runtime parameters are read-only.
    
    Runtime parameters in a data mapping configuration are always of the type String. Remember to parse the value if necessary, e.g. before using it in a calculation.