What is the Format as Text Tool?
The Format as Text tool creates single or multiple text documents, using information provided by Input tools such as the Database Query (ODBC) tool. It requires no global settings.
If required, you can produce dynamic documents such as, alerts and notifications, or data formats such as .CSV for spreadsheets or uploading to other systems. Drag-and-drop recordset columns, variables, and properties from the Task Browser to achieve this.
Created text documents can then be delivered as email bodies or attachments (Send Email (SMTP) tool), text messages (Send Text Message tool), or saved to the local drive (Save File tool) for example.
Format as Text Tool Features
- Single or multiple documents
- New document when data changes or for each row
- Header/Detail/Footer sections
- Merge dynamic data into document
- Produce CSV or other text data formats
White Paper - Format as Text
Format as Text Tool: Working with other Tools
The Format as Text tool can directly interact with the following tools:
Consuming from Other Tools
The Format as Text tool can directly consume objects outputted by the following tools:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Database Query (ODBC) | Input and Data Connectors |
 | Database Query (OLEDB) | Input and Data Connectors |
 | Call Stored Procedure (OLEDB) | Input, Data Connectors, Output, and Execute |
 | Import Flat File | Input |
 | Convert XML to Recordset | Format |
 | Filter Data | General |
Objects Consumed
The following objects are outputted by the above tools and can be directly consumed by the Format as Text tool:
- Recordset — Tabular data from any BPA Platform tool capable of exposing such data (see above)
Exposing to Other Tools
The following tools can consume objects outputted by the Format as Text tool:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Print Document | Output |
 | Save File | Output |
 | Send Email (SMTP) | Output |
 | Send Text Message | Output |
 | Transfer File (FTP) | Output |
 | Call COM Object | Execute |
 | Run External Program | Execute |
 | Run VBScript | Execute |
Objects Exposed
The Format as Text tool outputs the following objects which can be directly consumed by the above tools:
- Documents (Text) — Plain text documents
- RecordSource — If an Input Recordset has been selected (see General tab), this contains the columns included in the recordset
- Step Properties — Standard step properties are available allowing you to use statistical data of the tool
Global Configuration
The Format as Text tool does not require any global configuration before being used in a task.
Step Configuration
To add a new Format as Text step to an existing task, you either:
- Click and drag the Format as Text icon from the Task Browser to the task Design area.
- From the task’s Design tab, right-click on empty space and select Add > Format > Format as Text.
For a detailed description of how to create new tasks, refer to the product help.
About the General Tab
The General tab is used to enter the following details for the step:
- Name — Enter a meaningful name for the stepTIP: If this task instance makes use of two or more Format as Text steps, ensure the Name used is unique for each individual step.
- Description — If required, enter a description of this step
- Use a Recordset — Enable this parameter if recordset data from a previous task step is required to form the document
- Input Recordset — Contains all available recordsets from steps previously created in the task
About the Formatting Tab
Use the Formatting tab to create the text document itself or the structure if creating a dynamic document.
If Not Consuming a Recordset
If the Format as Text step is not set to consume a recordset from a previous task step (see General tab), the tool displays as:
When a recordset is not consumed, the Format as Text tool assumes a basic file structure, that is none, and only a single output is required.
You can enter the required text into the provided box. Drag-and-drop recordset data, variables, and step properties from the Task Browser to the provided box to create a dynamic text document, populated at run-time.
If Consuming a Recordset
If the Format as Text step consumes a recordset from a previous task step (see General tab), the tool displays as:
When a recordset is consumed, the Format as Text tool can create a more structured output. Multiple outputs based on a recordset column value change or a new recordset row are also supported.
One Document Generation
A single document is created containing all data from the recordset. If required, you can add Header and Footer details to the document output, for example, if creating a CSV file you can add a header row, before adding text, recordset columns, variables, and step properties to the Detail panel.
New Document when Column Changes Generation
A new document is created when the nominated recordset column’s value changes. For example, column name companyname groups all the records where companyname = "Codeless Platforms" into one document and each subsequent company into a new document. If required, you can add Header and Footer details to the document output, for example, if creating a CSV file you can add a header row, before adding text, recordset columns, variables, and step properties to the Detail panel.
New Document for Each Row Generation
A new text file is created for each row in the consumed recordset. Like the single document created without consuming a recordset, you are free to create an unstructured document. You can add free-hand text, recordset columns, variables, and step properties to create a dynamically populated text file.
About the Options Tab
The Options tab allows you to define how errors in this step are handled at task runtime.
If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Task).
