Retrieve Items

The Retrieve Items Action task locates and extracts items from the OL Connect Database so they can be used with further tasks. The items are retrieved using a set of conditions working together. Since this task can retrieve items at any level, it can be used to generate Metadata (see Metadata) or JSON data used in multiple tasks.

Input

The task requires no input file, but any input information such as Metadata, Job Info variables, a data file or a JSON array can be used to specify which items to retrieve.

Processing

The task requests the items on the OL Connect Server using the conditions set in the task properties. Only the condition information and the returned Metadata or JSON are exchanged.

Note that the order in which the requested items are returned cannot be guaranteed.

Output

The task outputs either Metadata that is equivalent to the output of the appropriate task that would normally create the items, or a JSON Record Data List (see the REST API Cookbook and JSON Record Data List example), or an array of simple JSON objects that - unlike a JSON Record Data List - do not have information about the data type of fields.

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.

Note: The result of a Retrieve Items task can be used with the Create Job task if it is a Content Item or Content Set, but it cannot be used in combination with a Job Preset.

Content Creation tasks accept Metadata as well as JSON data as input.

Task properties

General Tab

  • Entity to retrieve: Use the drop-down to select which items to retrieve.
    • Record: Retrieves one or more Records, whether or not they are part of a Record Set. Output similar to the Execute Data Mapping task.
    • Record Set: Retrieves one or more Record Sets, including all their records. Output similar to the Execute Data Mapping task.
    • Content Item: Retrieves one or more Content Items, whether or not they are part of a Content Set. Output similar to the Create Print Content or Create Web Content tasks.
    • Content Set: Retrieves one or more Content Sets, including all their content items. Output similar to the Create Print Content task.
    • Job: Retrieves one or more Jobs, including all their content items ready to be printed. Output similar to the Create Job task.
    • Job Set: Retrieves one or more Job Sets, including all their content items ready to be printed. Output similar to the Create Job task.
  • Optimized: This option, available when the Entity to retrieve is a Record or a Record set, allows to retrieve a greater number of records and handle large JSON files without memory issues. Note that no duplicates are returned and that the order of the records returned is always ascending, rather than the order in which they were requested.
  • Retrieve by:
    • Condition: Select entities based on one or more conditions, the value of a metadata field for example.
    • ID: Depending on the option selected under Entity to retrieve this is a Record ID, Record Set ID, Content Item ID, Content Set ID, Job ID or Job Set ID.
      IDs can be entered directly; when entering multiple IDs, put each on a new line. Alternatively, they can be passed via variables (see Variable task properties), or as a JSON array, e.g. [6001,6002,6003]. A JSON array may contain variables, e.g. [%1, 75001].
  • Conditions:
    • Add a condition: Click to add a new condition line. This adds the line to the current condition level, by default with an AND operator.
    • Switch conditions: Click to swap two conditions on the same level, or two groups of conditions.
    • Delete the selected condition: Click to delete the currently selected conditions in the list.
    • Clear the rule: Click to delete all rules in the list. Note: This cannot be undone.
    • Import a rule: Click to open the Browse dialog and load a Rules file. This will load its rules into the list.
    • Export the rule: Click to open a Save dialog and save the Rules file to disk.
  • Rule Viewer: Displays a text-based view of the condition using operators and parentheses.
  • Output Type group:
    • Metadata - IDs only: Select to only output minimal Metadata containing the entity IDs.
    • Metadata: Select to output IDs as well as record details in the Metadata, useful for further sorting and filtering of the Metadata.
    • JSON: Select to output a JSON Record Data List (see Output).

    • 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.

Commingling/Batching Tab

Commingling is a method by which Print Content Items are merged together to create mail pieces going to each recipient. For instance, retrieving a letter, an invoice and a notice within the same mail piece, which presumably could be added within the same envelope. Batching is the same principle when all the Print Content Items are generated using the same Template file. This tab is only available if the Content Item option is selected in the General tab's Entity to retrieve drop-down. To modify any of the following options, click in the Parameters box and then click the [...] button that appears.

  • Document contents: Defines the Document ("Mail Piece") level and how they are built.
    • Pick items based on: Use the [...] to open the Pick Parameters dialog and define how to pick which items will be placed in each document. Content items picked using this method will be part of the same mail piece.
    • Sort items based on: Use the [...] to open the Sort Parameters dialog and define how Content Items are sorted within the mail piece.
  • Group contents: Define the Group level (for example, a Mail Route), or how to group mail pieces together in groups.
    • Pick items based on: Use the [...] to open the Pick Parameters dialog and define how to pick which documents will be placed in each Document group. groups are often used to separate mail routes, provinces, or cities.
    • Sort items based on: Use the [...] to open the Sort Parameters dialog and define how documents are sorted within the group, for example by Zip Code.

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.