Reference
Cheat-sheet for everything you'll reach for from a script. Cross-references the recipes with full examples.
Runtime objects per location
The platform injects a different set of objects depending on where your script runs. Reading from / writing to the wrong one is a common gotcha:
| Object | Type | Where it's available |
|---|---|---|
etlConfig | com.toolsverse.etl.core.config.EtlConfig | Mapping, scripting transformations, Script flow, almost everywhere |
scenario | com.toolsverse.etl.core.engine.Scenario | Same as etlConfig |
dataSet | com.toolsverse.etl.common.DataSet | Mapping field functions, For Each Row, After Extract, Filter, Validate, Action Conditions |
currentRow | com.toolsverse.etl.common.DataSetRecord | For Each Row, Mapping field functions, Filter, Validate |
row | integer (0-based) | For Each Row, Filter, Validate |
fieldValue | any — the value being calculated | Mapping field functions only |
source | source descriptor | Before Prepare Source Query |
destination | com.toolsverse.etl.core.engine.Destination | Action Conditions |
message | string — the raw source message | Format → Preprocessor |
filter | CSV filter object | CSV Format → row filter |
scriptResult | script-result holder | Python scripts only |
value | any — assign to return | JavaScript scripts (alternative to last-expression) |
To reach etlConfig from a place where it isn't injected (e.g. preprocessors of various kinds):
JavaScript
var etlConfig = com.toolsverse.config.SystemConfig.instance()
.getEtlThreadContext().getData();
var param = etlConfig.getValue('param name');Important context variables
Identifiers and metadata of the currently running flow.
| Need | Code |
|---|---|
| Audit ID (unique per execution) | com.toolsverse.config.SystemConfig.instance().getEtlThreadContext().getRequestId() |
| Flow ID | com.toolsverse.config.SystemConfig.instance().getEtlThreadContext().getFlowId() |
| Flow name | SystemConfig.instance().getEtlThreadContext().getData().getMainScenarioName() |
| Tenant name | SystemConfig.instance().getProperties().get("request_tenant_name") (empty for main account) |
| User name | SystemConfig.instance().getProperties().get("request_user_name") |
| Home URL | etlConfig.getHomeUrl() |
etlConfig — the most-used methods
| Method | Purpose |
|---|---|
setValue(key, anyObject) | Store any object in the flow's key/value storage |
getValue(key) | Retrieve a previously-stored object |
log(message) | Add an entry to the flow's run log |
getConnection(name) | Get a JDBC connection (must be a named connection on this flow) |
getAliasesMap().get(name) | Get a connection's Alias by name |
getLastException() / setLastException(ex) | Inspect / clear the last exception (used in Execute on Exception scripts) |
addResponseHeader(name, value) | Set an outbound HTTP response header (used in user-defined APIs) |
randomizer(locale) | Get the anonymizer for a locale ("en", "de", …) |
getHomeUrl() | Configured Home URL of the app |
scenario — flow variables & sources
| Method | Purpose |
|---|---|
getName() | Scenario / flow name |
getVariable(name) | Get a flow variable (returns Variable — call .getValue()) |
addVariable(Variable) | Add a new flow variable at runtime |
getSources() | Map of named source datasets — useful for in-memory lookups |
To create a Variable:
JavaScript
var v = new com.toolsverse.etl.common.Variable();
v.setName("MY_VAR");
v.setValue("value");
scenario.addVariable(v);DataSet — methods you'll actually use
| Method | Purpose |
|---|---|
getRecordCount() | Number of rows |
getFieldCount() | Number of columns |
getRecord(index) | One row by index |
getData() / setData(DataSetData) | All rows as an array |
getFields() / setFields(DataSetFields) | All columns |
getFieldDef(name) / getFieldDef(index) | Column metadata |
getFieldValue(row, col) | Value at row + column position |
getFieldValue(record, col) | Value from a record + column position |
getFieldValue(record, name) | Value from a record + field name |
setFieldValue(record, col, val) | Set value |
setFieldValue(row, col, val) | Set value |
setValue(record, name, val) | Set by field name; adds the field if missing |
addField(FieldDef) | Add a column |
addField(name, value) | Add a column + value in one call |
findField(name) | Locate a field, including in nested datasets — returns TypedKeyValue<FieldDef, DataSet> |
TaskResult — validation outcomes
Used in Validate transformations to control what happens when a row fails a check.
| Code | Effect |
|---|---|
TaskResult.HALT | Halt the entire flow with an exception |
TaskResult.STOP | Skip the source-to-destination transformation entirely (no rows loaded) |
TaskResult.REJECT | Skip the current row only |
TaskResult.CONTINUE | Accept the row (default) |
For details, see Recipes → Validate.
asText helpers
Quickly turn a record / dataset / field list into a CSV-ish string — useful for log output and quick debugging.
| Call | Returns |
|---|---|
dataSetRecord.asText() | One record as CSV |
dataSet.asText(row) | One row by index as CSV (boundary-checked: 0 ≤ row < count) |
dataSet.asText() | First 10 rows as CSV (boundary-checked: min(count, 10)) |
dataSet.fieldsAsText() | SQL-formatted field declarations (as in CREATE TABLE) |
Variable interpolation in non-script fields
Outside scripting fields — in source SQL, destination SQL, connection params, mapping field tokens — reference variables by name surrounded with curly braces:
| Variable type | Reference syntax |
|---|---|
| Flow variable | {flow_variable_name} — uppercase the name when used inside SQL fields: {VAR_NAME} |
| Global variable | {global_variable_name} |
| Column / calculated field | {column_name} |
Java import patterns
Pick by readability — they all produce the same result.
| Pattern | Example | Best for |
|---|---|---|
| Fully qualified | new java.util.ArrayList() | One-off use |
importPackage() | importPackage(java.util); var l = new ArrayList(); | Multiple classes from the same package |
Java.type("…") | var ArrayList = Java.type("java.util.ArrayList"); | Used repeatedly — bind once |
JavaImporter + with | var imp = new JavaImporter(java.util, com.toolsverse.util); with (imp) { … } | Many packages mixed; avoid in hot loops (slower) |
Common Etlworks packages
| Package | What's in it |
|---|---|
com.toolsverse.util | Utility classes — Utils, FilenameUtils, DateUtil, UniqueNumber, TypedKeyValue |
com.toolsverse.util.log | Logger |
com.toolsverse.config | System config & thread context — SystemConfig |
com.toolsverse.etl.common | Core ETL types — DataSet, DataSetRecord, FieldDef, Variable, Alias, CommonEtlUtils |
com.toolsverse.etl.core.config | Engine config — EtlConfig |
com.toolsverse.etl.core.engine | Engine core — Scenario, Destination, Extractor (lookups) |
com.toolsverse.etl.core.task.common | Common tasks — FileManagerTask |
com.toolsverse.etl.connector.json | JSON connector (used by ConnectorUtils.dataSet2Str) |
com.toolsverse.etl.connector.xml | XML connector |
com.toolsverse.etl.connector.text | CSV connector + TextFilter for row-level CSV filtering |
com.toolsverse.etl.connector | ConnectorUtils — serialize / deserialize between DataSet and string formats |
com.toolsverse.etl.sql.util | SqlUtils — execute arbitrary SQL from script |
com.toolsverse.io | RedisSequenceGenerator — cluster-wide sequences and shared parameters |
com.toolsverse.imaging | ImageProcessor — load / scale / save images |
org.jsoup | HTML5 parser bundled for scraping |
java.util · java.io · java.text | Standard JDK |
Found something missing?
This reference covers what people use most. If you reach for a class or method that's not here and would have saved you 15 minutes, send it to product@etlworks.com and we'll add it.