Execute Data Mapping

The Execute Data Mapping action task generates a record set by executing a data mapping configuration on a data source. It can also automatically create a record set from a PDF/VT file without using a data mapping configuration.

If the input is paginated, this task can create a Print Content Set as well, making it possible to bypass the Job Creation task in a print process if there is no need to merge the data with a template.

Tip: Drag-and-drop a data mapping configuration from the Connect resources in the Configuration Components pane on a process to add this task.

Input

Optional. Both main options can refer to external files, but either one can be the active data file using %F. By default the Data Source is set to use the active data file as input.

Note: To open a Microsoft Access database, you have to use the Load External File task just before the Execute Data Mapping task.

AFP input is dependent on a third party library (CDP), which only allows PReS Connect to run up to 4 AFP input processes on a given machine at a given time.

Note: PDF output of the WinQueue input task is generally unreadable by the OL Connect Execute Data Mapping task. This is because documents are converted to PostScript when printed, and character identity information is usually lost in this process.

Processing

The task executes the selected data mapping configuration on the appropriate data source, or converts the PDF/VT into a Record Set directly.

If the input is paginated, this task can create a Print Content Set as well.

If the data mapping configuration expects a database data source, the Data Source option is ignored and the database is accessed instead. If a PDF/VT file is used, the data mapping configuration option is optional - if one is present, it must be able to read the PDF/VT.

Output

The output to this task is twofold. On the OL Connect Server side, a Record Set containing multiple records is created and saved.

On Connect Workflow's side, Metadata is returned with information about each record set (see Note: Metadata in OL Connect jobs). Alternatively, you can either get an XML file or JSON file containing the full Record Set structure, or skip storing the Record Set on the OL Connect Server and run the operation in Validation mode; the validation results are returned via the Metadata.

Note: Date/time values are stored in the OL Connect database as Unix timestamps, i.e. the total number of seconds from the starting time of UTC (Universal Time, Coordinated) to the current time (with zero time zone offset). For instance: 1675950179.

In JSON output of this task, dates are represented the same way.

In the Metadata, however, date/time values are represented in the following format: YYYY-MM-DDTHH:MM:SSZ.

Properties

General Tab

  • Data Mapping Configuration: Executes data mapping on the appropriate source. Select the appropriate data mapping configuration in the list:

    • "None": Select to execute default, basic data mapping on the input PDF/VT file.

    • "%o": Select to use a dynamic data mapping configuration name. Click on %o to change the expression that determines the name of the data mapping configuration to use. Right-click it to open the contextual menu that allows to select variables, data and lookup functions (see Data selections).

    • Configuration Names: Select the appropriate data mapping configuration. Adding configurations is done through the Send to Workflow option in the DataMapper Module.
      Click the Open data model of selected configuration button to view the data model attached to the configuration in the Data Mapper module, to verify that the correct one is used. Only works for configurations listed (will not work for "None" or "Dynamic" options).

  • Output Type group:

    • Metadata - IDs only: Select to only output the Record and Job IDs in the Metadata. This does not permit sorting and filtering, but it enhances performance since only minimal data is exchanged between the OL Connect Server and Connect Workflow.

    • Metadata: Select to output the full Record table (no Details table) as Metadata in the task. It is then possible to sort and filter the Metadata using the regular Metadata tools, as long as the Update Records from Metadata option is used in further tasks to use the modified Metadata.

    • XML: Select to output an XML structure containing the full Record Set including all detail tables. This option cannot be used with other OL Connect tasks.

    • JSON: Select to output a JSON Record Data List (see the REST API Cookbook and JSON Record Data List example). The file contains the full Record Set including all detail tables and boundary information, which can then be processed in a Run Script task.

    • Simplified JSON: Select to output the full Record Set including all tables as an array of JSON objects. Unlike the output of the "JSON" option, simplified JSON does not contain information about the data type of fields.

    • None (validate only): Select to run the operation in Validation mode and output the validation results in the Metadata. No data is extracted or stored in the Connect Database.
      The task performs a validation REST call and stores the returned JSON object in a validationresult entry on the Group[0] level of the Metadata. (For the structure of the JSON object, see the REST API Cookbook: JSON Data Mapping Validation Result.) The JSON's result and recordcount fields are also stored at the Group[0] level. Each Document node contains the following fields:

      • index: The position of the record in the job. This value is 1-based. Note that this is not a record ID, since the record is never stored in the database.
      • error: The error message, or an empty string when no errors have been reported for this record.

      Document nodes with an error are selected, while those without an error are unselected, to make looping through all errors easy.
      By default, if the validation cannot be performed the task fails and logs an error, but if the Generate error when validation cannot be performed checkbox is unticked, the task will log a warning and it will generate metadata with a single group containing a single document, with the error message "DataMapper could not process the input file".

      Tip: To determine if there were any errors in a job and handle it accordingly, you can use a Condition that checks if
      GetMeta(SelectedCount[0], 11, Job.Group[0])
      is greater than 0, immediately after the task (see Conditions).

  • Runtime Parameters: Runtime parameters pass information from the Workflow process to the data mapping configuration (see Properties and runtime parameters in the Online Help of OL Connect).
    Initially, the value of runtime parameters that are defined in the selected data mapping configuration is set to that of a local variable or else a global variable if there exists a variable with the same name. If no such variable exists, the value will be an empty string.
    To change the source of the value for any runtime parameter, right-click to open the contextual menu that allows to select variables, data and lookup functions (see Data selections).
    If the data mapping configuration name is dynamic, you must enter the name (or select a variable that contains the name) and set the value of all the runtime parameters that may occur in the data mapping configuration.
    If a runtime parameter is defined in a data mapper configuration, but not set in the task properties, an error will be raised.

    Note: Backslashes (\) and double quotes (") in a JSON string must be escaped with a backslash (\\, \") if the JSON string is passed via a global, local, or Job Info variable.
    If the JSON is entered directly in the runtime parameter field, the plugin adds the necessary backslashes.

  • Bypass content creation: Check this option to make the task create a Print Content Set as well a Record Set, so that in a print process, content creation - normally performed by the Create Print Content task - can be skipped if there is no need to merge the extracted data with a template.

    Note: The Bypass content creation option only works if the input is paginated.

    Set the Output type to Metadata if the Content Creation task is omitted and the output is to be used by the Job Creation task later on in the print process.

  • Output Creation:
    •  Duplex: Whether the page sheet is duplex.
    • Tumble: Whether to duplex pages as in a calendar. For this to work, the duplex option must be checked as well.

OL Connect Proxy Tab

This tab is common to all OL Connect tasks and defines where to process the jobs sent through these tasks. When these fields are empty, they use the defaults set in the OL Connect preferences.

Note: Defaults are not used unless the configuration is sent to the Workflow service.

  • OL Connect Proxy Address: Enter the machine name or IP Address where the OL Connect Server resides.

  • Port: Enter the port to use to communicate with the OL Connect Server. Default: 9340

  • User name: Enter the user name expected by the OL Connect Server.

  • Password: Enter the password expected by the OL Connect Server for the above user name.

On Error Tab

For a description of the options on the On Error tab see Using the On Error tab.

Miscellaneous Tab

The Miscellaneous tab is common to all tasks.

It contains a text area (Task comments) that lets you write comments about the task. These comments are saved when the dialog is closed with the OK button and are displayed in The Task Comments Pane.

Check the option Use as step description to display the text next to the icon of the plugin in the Process area.

The tab also provides an option to highlight the task in The Process area with the default color, set in the Preferences (see Colors), or the color selected or defined under Highlight color on this tab.
To revert the selected highlight color to the default color, open this tab, turn the Highlight option off and close the dialog with the OK button; then turn highlighting back on.
Highlighting can also be turned on and off via the task's contextual menu and with the Highlight button on the View ribbon.