Creating import recipes and projects

Configure a CSV importer, validate parsing and mapping on real files, and save the recipe or project for reuse.

Create a CSV recipe

  1. Open Importer tools → Importer Builder… and choose File → New recipe. In General, set the name and a reusable Stable ID. Enter the version and description, and use Filename matching regex to restrict accepted filenames. In Representative file, choose a file that represents the real layout. Check Contract to see whether a CSV recipe can produce that contract.
  2. In the parser tab, set the delimiter, header position, preamble and footer rows, comment prefix, encoding, and decimal separator. The preamble count refers to physical lines. Verify that the example uses a field delimiter distinct from its decimal comma.
  3. In Mapping table, use Edit → Add mapping… for each column. The five fields are Column, Variable, Unit, Scale, and Offset. The canonical value is source × Scale + Offset. Use the Edit menu to change, remove, or reorder mappings. The equivalent form in Advanced text is column | Variable | unit | scale | offset.
  4. To retain a property extracted from the filename or header, define Metadata key and a regular expression with a first capture group. Use a sample with a recognizable value and check the value after publication.

Test, save, and reuse the recipe

Run → Preview source (bounded) processes a sample. Test complete parser checks the entire file, so errors in later rows can appear only at that step. Use Cancel request to interrupt a request when available. Before saving, check the draft status and confirm that the result corresponds to the current settings. Preview and Test create no Dataset.

File → Save saves the recipe to the profile. Duplicate prompts for a new ID, saves the copy under that ID, and opens it for editing. Use Export definition… to create a portable INI. Import definition… registers the definition in the profile and loads it in the editor. If the same ID is already present, the Builder can refuse the overwrite and keep the current definition. Remove removes a saved definition, Reload definition inventory reloads the inventory, and Close closes the editor. For help, choose Recipe workflow and limits from the menu.

Return to Acquisition, refresh the list, and select the recipe under Custom importers. Queue the sample or use Folder… with filenames accepted by the regular expression. Import, open the canonical table, and check the recipe reference and hash in Provenance. If the recipe changed after you queued the file, review the source and add it again under the current recipe before retrying.

Open Acquisition Plugin Builder

File → New Acquisition plugin project… or Open Acquisition plugin project… opens a separate native-project editor. Describe the module in Module metadata, the profiles in Format profiles, and the source files in Registered sources. Keep the project in a writable working directory. Validate checks declarations, Build requires a compatible toolchain, Test requires a sample and profile, and Export candidate exports a candidate. Cancel is available while a compatible request is running. A candidate project follows a separate workflow from a CSV recipe saved in the profile.

Millivolts, decimal commas, and batch IDs in filenames

  1. Use serie-L17-misura.dat. The admission regex is ^serie-L([0-9]+)-misura\.dat$. Set Metadata key to lotto and reuse the same regex in Filename capture regex to keep 17.
  2. In Parsing set semicolon, Header rows 1, Physical rows before header 1, Footer data rows 1, Comment prefix #, Python input encoding utf-8, Decimal convention comma.
  3. In Advanced text, enter 1 | time_s | s | 1 | 0 and 2 | voltage_V | V | 0.001 | 0.05 on separate lines. Return to the table and check the five fields. The first canonical value is 125.0 × 0.001 + 0.05 = 0.175 V. Column 3 is excluded from the mapping.
  4. Click Preview source (bounded) and Test complete parser. The short file passes with four rows. The file serie-L18-misura.dat contains an invalid cell near the end that prevents the Test from passing. Preview shows the first twelve rows. Restore the L17 file and save, then select the Misura didattica in millivolt recipe in Acquisition. Import with ID calibrazione_csv and check the four rows, names, units, batch ID, and actual configuration.

Contract: KNOWN_COMPATIBLE means the table contract is recognized. INCOMPATIBLE_TABLE means the contract is known but incompatible with a CSV table. UNKNOWN_UNAVAILABLE means the ID or provider is unavailable. Correct the field before testing the parser. The result CURRENT_CAPTURE identifies the draft and source current at capture time. Run the request again if you change the settings after capture.

On a minimal native project saved without profiles, Validate starts and reports that at least one real profile is required. Build and Export candidate remain unavailable. Test reports that you must save a profile first. Register source files under Registered sources and check bindings and callbacks before retrying.

Validate, build, test, and export a real project

Use Open Acquisition plugin project… on a writable copy of the Scientific measurement module’s source directory from the installation. Open Module metadata and verify the ID, version, and dependencies. Format profiles lists five profiles. Registered sources shows declared files, roles, sizes, and bindings. A valid association between the registered C++ file and the recognize, inspect, and import symbols is required for callbacks. Correct and save an invalid change before running the test.

  1. Use Validate and wait for PASS. After Build checks BUILT.
  2. Open Test, choose spettro-ir.csv, select spectral_csv, and enter the semantic settings from Scientific measurement. Click Run Test. The test returns PASS and discards its temporary outputs. The project retains its saved settings.
  3. Export candidate returns CANDIDATE_EXPORTED and reports the ZIP in the project directory. The candidate appears in the tree only after the normal installation workflow.

In the recipe pane, edit a descriptive field during Test without changing the source. STALE_DRAFT · captured result only identifies the result for the settings captured when the request started. Run the test again to update the result. During a long request, Cancel request stops the parser. Neither the test nor its cancellation publishes a Dataset to the Session.

To capture from the header instead of the filename, leave Filename capture regex blank, set Metadata key to header_token, and set Header capture regex to Time;(Millivolt);Reference. Test displays importer_meta_header_token Millivolt in the captured properties.

Exercise files

Sources, licenses, and SHA-256

Screenshots

Open a screenshot to view it at full size.

General tab of the recipe with ID, regex, contract, and example file.
General tab of the recipe with ID, regex, contract, and example file.
Parsing tab with separator, physical rows to exclude, and decimal comma convention.
Parsing tab with separator, physical rows to exclude, and decimal comma convention.
Mapping table in Variables / Metadata, with canonical names and units for the two selected columns.
Mapping table in Variables / Metadata, with canonical names and units for the two selected columns.
Advanced text in Variables / Metadata, with factors, offsets, and batch capture from the filename.
Advanced text in Variables / Metadata, with factors, offsets, and batch capture from the filename.
Test complete parser on the valid L17 file. The summary reports four rows.
Test complete parser on the valid L17 file. The summary reports four rows.
The full test on L18 reports an error in the footer. The limited preview remains visible above.
The full test on L18 reports an error in the footer. The limited preview remains visible above.
Definition inventory with the registered training recipe.
Definition inventory with the registered training recipe.
Canonical table of calibrazione_csv after importing with the recipe. Columns display units and transformed values.
Canonical table of calibrazione_csv after importing with the recipe. Columns display units and transformed values.
Native plugin project editor, Module metadata tab and declaration fields.
Native plugin project editor, Module metadata tab and declaration fields.
Profiles tab for the scientific measurement project.
Profiles tab for the scientific measurement project.
C++ sources tab associated with the example project.
C++ sources tab associated with the example project.
Run Test window with the source and temporary scientific configuration.
Run Test window with the source and temporary scientific configuration.
The Run Test of the scientific project reports PASS. This temporary test does not add a Dataset to the Session.
The Run Test of the scientific project reports PASS. This temporary test does not add a Dataset to the Session.
The screenshot distinguishes the parser capture from the draft modified after capture.
The screenshot distinguishes the parser capture from the draft modified after capture.

Controls and settings

Menu bar

Open the menus or use the window shortcuts to reach a command.

Split-pane area

Drag the divider to give more space to the list, the fields, or the result.

Scrollbar

Use the horizontal or vertical scrollbar to reach fields, entries, or text outside the visible area.

Saved CSV recipes

Select a saved recipe to reopen its settings.

Split-pane area

Drag the divider to give more space to the list, the fields, or the result.

Builder tabs

Use General for identity, Parsing for reading, and Variables / Metadata for mapping and captures.

Scrollbar

Use the horizontal or vertical scrollbar to reach fields, entries, or text outside the visible area.

Stable ID

Choose a stable ID so you can find the recipe after saving. Do not reuse the ID of another recipe.

Display name

Type the name you want to see in the Acquisition tree.

Version

Indicates the definition version, to distinguish shared revisions.

Description

Describe the origin and expected structure of the files.

Filename matching regex

Defines the filename filter. The Folder… command uses this regex.

Dataset contract

Check that the contract is compatible with a table and read the status below the field.
  • (catalogo dinamico) · The entries come from the contracts visible in the installation. Check the name, conditions, and origin in Contracts…, and any Other… option in the working view.

Representative file

Sets the path of the actual file used by Preview and Test.

Browse…

Open the chooser to select the representative file.

Scrollbar

Use the horizontal or vertical scrollbar to reach fields, entries, or text outside the visible area.

Request results

Read the sample, digest, and diagnostics. The window footer shows whether the result belongs to the current draft.

Scrollbar

Use the horizontal or vertical scrollbar to reach fields, entries, or text outside the visible area.

Scrollbar

Use the horizontal or vertical scrollbar to reach fields, entries, or text outside the visible area.

New recipe

Opens a new draft. If the Builder asks for confirmation, decide first whether to save the previous one.

Save

Validates and saves the definition under its ID. After saving, check the list and the Custom importers family.

Duplicate

Creates a derived draft. Assign a new ID before saving.

Import definition…

Imports a portable INI as a draft; check the fields and contract before saving.

Export definition…

Writes the recipe definition as a portable INI.

Remove

Deletes a saved recipe from the profile, after confirmation if requested.

Close

Closes the editor. Check for unsaved draft changes before closing.

Add mapping…

Adds a mapping from a source column to a variable and sets unit, scale, and offset.

Edit mapping…

Edits the selected mapping; check the value preview.

Remove mapping

Delete the selected mapping.

Move mapping up / Move mapping down

Changes the order of the published variables.

Preview source (bounded)

Performs a limited read of the sample source and shows the rows and digests for that sample.

Test complete parser

Checks the whole representative source, including errors beyond the initial sample.

Cancel request

Interrupts Preview or Test processing when a request is active.

Reload definition inventory

Rereads the stored recipes and updates the list.

Recipe workflow and limits

Opens help on the recipe API contract.

New Acquisition plugin project…

Creates a native project and keeps the recipe Builder open.

Open Acquisition plugin project…

Opens an existing native project.

Validate

Checks the consistency of the project metadata and profiles.

Build

Starts compiling the project with the enabled toolchain.

Test

Runs the project tests on a test source for the selected profile.

Export candidate

Exports the candidate under the conditions the project allows.