Connection

Purpose

Reads or writes data through a saved connection. Available properties depend on the service: IBM Planning Analytics, UBC Analytics, file storage, database or API. Credentials are configured in the connection itself; the block selects the object and exchange rules.

Inputs and outputs

A source has no inputs and supplies a table through out. A target receives in and has optional success and failure outputs. success carries the written table; failure carries a single-row error description. For a TurboIntegrator process, the block is a target that starts the process once or for each distinct combination of parameter-column values.

Parameters

Parameter	Settings and values	Options and limits
`role`	Block role: a source reads data; a target writes the result.	Options: `source`, `target`
`connection_id`	The saved connection through which the block accesses the system.	Up to 64 characters
`object_type`	Business-system object type: cube, dimension or form. An IBM dimension supports source and destination roles; a UBC Analytics dimension is a source.	Options: `cube`, `dimension`, `form` Default: `cube`
`dimension`	The dimension whose elements are read.	Default: `empty` Up to 256 characters
`hierarchy`	The selected dimension’s hierarchy.	Default: `empty` Up to 256 characters
`cube`	The cube to read or write.	Default: `empty` Up to 256 characters
`mapping`	Built-in mapping of table fields to the cube’s dimensions and value.	Default: `not set`
`environment`	The UBC Analytics environment; select it before the object and fields.	Default: `empty` Up to 80 characters
`form`	The UBC Analytics form to read or write.	Default: `empty` Up to 256 characters
`read_scope`	For a form: all records or the record that launched the flow.	Options: `all`, `launch_record` Default: `all`
`columns`	Read only fields or all available columns, including the object’s codes/names.	Options: `fields`, `all` Default: `fields`
`write_mode`	For a form: add with insert, update with update, or add/update with upsert.	Options: `insert`, `update`, `upsert` Default: `insert`
`key_field`	The form’s key field used to find the record during update/upsert.	Default: `empty` Up to 256 characters
`form_mapping`	Mapping of input columns, constants, parameters, reference values or generated values to form fields.	Default: `not set`
`view`	A shared IBM cube view; private views are not supported.	Default: `empty` Up to 256 characters
`read_mode`	Read the selected view or cube.	Options: `view`, `cube` Default: `view`
`element_mode`	Read all, only leaf, or only consolidated dimension elements.	Options: `leaf`, `consolidated`, `all` Default: `all`
`value_column`	The table field containing the measure value.	Default: `Value` Up to 256 characters
`file_kind`	The file-service type for compatible connections.	Options: `google_sheets`, `google_drive`, `onedrive`, `s3`, `ftp`, `network`, `agent_folder` Default: `google_drive`
`selection_mode`	Read specified cells or a workbook’s named range.	Options: `cells`, `defined_name` Default: `cells`
`defined_name`	The name of a range defined in the Excel workbook.	Default: `empty` Up to 255 characters
`defined_scope`	The scope of the named range: workbook or worksheet.	Default: `empty` Up to 128 characters
`json_path`	The path to the array of records in a JSON document.	Default: `empty` Up to 1024 characters
`xml_path`	The path to the elements to read as XML rows.	Default: `./*` Up to 1024 characters
`file_id`	The file identifier or path in the selected storage.	Default: `empty` Up to 2048 characters
`sheet`	The workbook’s worksheet name.	Default: `empty` Up to 128 characters
`range`	A cell range in A1 notation, for example A1:F500.	Default: `A1:M100` Up to 40 characters
`header`	Treat the first row of the range as field names.	Default: `enabled`
`delimiter`	The text file’s field delimiter.	Options: `,`, `;`, `tab` Default: `;`
`clear_range`	Clear the remainder of the configured range after writing; data outside it is unchanged.	Default: `disabled`
`target_mode`	Write data to an object or start an IBM TurboIntegrator process.	Options: `write`, `process` Default: `write`
`process`	The TurboIntegrator process name from the available list.	Default: `empty` Up to 256 characters
`process_parameters`	Process parameters: a constant, run parameter or input-data column.	Count: 0–100
`external`	Settings for the table/query/resource of an external service, API or database.	Default: `not set`
`cube_write`	Cube-writing behaviour: addition, replacement or transactional addition; optionally clear before writing.	Default: `not set`

Mapping and writing to a cube

Parameter	Setting
mapping.bindings	Every dimension and hierarchy; column/constant/parameter source, value, optional Alias and lookup mapping.
mapping.value_column / value_type / decimal	Measure field, number or text, decimal separator.
mapping.blank / duplicates	skip/zero/error for empty values; error/sum for repeated coordinates.
mapping.portion_cells / response_seconds	500–50,000 cells, default 10,000; 10–3600 seconds, default 120.
cube_write.mode	add, replace or transaction. Transaction mode uses a UBC Analytics form-save event.
cube_write.clear	The entire cube or slices selected by elements, data or parameters. Clearing uses replacement.

Tables, APIs and external services

Parameter	What it configures
`external.object / source_mode / query`	The object to read or a custom query where supported by the service.
`select / filter / order_by`	Fields, selection condition and order; the syntax depends on the service.
`write_mode / key_fields`	insert/update/upsert and key fields for supported write operations.
`method / query_params / body / records_path`	For APIs: GET/POST/PUT/PATCH, query parameters, request body and the path to rows in the response.
`pagination / next_link_path`	No pagination, next-page link, page number or offset. next_link_path specifies the path to the link.
`page_param / size_param / page_size / first_page / max_pages`	Page parameter names, size 1–10000, initial page 0/1 and maximum pages 1–10000.
`send_mode / batch_size / batch_key`	Send each row or a batch; the batch size and array key in the request body.
`value_format / value_field / ttl`	For a compatible key–value store: hash/json/string, the content field and retention time in seconds (up to 31536000).
`extra_params`	Additional parameters of a supported service; use only properties shown by its form.

Step-by-step configuration

Create and test a connection in “Connections”. Drag it from the palette into the flow.
Choose the role. For a business system, first select the environment and object type, then the cube, dimension, form or process.
For a source, choose the reading method; for an external service, set the object or query, selection and field list. Read the fields.
For a target, connect the prepared table. Configure mapping, write mode and update keys.
If execution should continue after writing, connect success to the next step and failure to a message or another handler.
Run a simulation; check coordinates, row count and the scope of affected data, then start writing.

Rules and diagnostics

Read/write capabilities are determined by the specific service; a shared configuration field does not mean every connection supports every mode.
A cube requires a value for every dimension and the measure field. Mapping is usually saved directly in the target.
UBC Analytics forms accept tabular mappings; cube mapping and TI execution do not apply to them. The update/upsert key field must receive a value from the mapping.
In a simulation, the TI process is checked in IBM but is not executed. An empty constant parameter value means the process’s default value.
The failure output handles a definite target error. An uncertain external-write result and cancellation require separate status verification; do not assume that writing definitely did not occur.

Configuration example

To load a plan, select the IBM connection, role=target and cube=SalesPlan. Bind Product and Month to columns, Version to the constant Budget, Measure to Amount, and value_column to Value. Choose replace to replace the addressed cells; after success, show a message with the result.

Writing to an IBM dimension

For a destination, select “Dimension”, the dimension and hierarchy. Under “Write to dimension”, choose the principal-name column. Allow missing numeric leaf elements to be created, or disable this for strict reference-data control. To update an attribute, choose its name, value column and update mode: without clearing or clearing all other values first. Duplicate rows for one element must agree on the attribute value.

A consolidated parent can come from a constant, launch parameter or column. For a multi-level structure, add up to 20 parent-column → child-column pairs. Missing parents can be created as consolidations; cycles and unsuitable element types are rejected. Existing relationships are not removed. Simulation reads and validates the hierarchy without changing IBM; state is checked again before writing. Pass a table without cube mapping.

Fields for specialized scenarios

Parameter	Use
simulation_record / simulation_previous	The form record used for simulation and the record supplying before-save values; only for a launch_record source.
dimension_write	IBM dimension destination settings: element name, attribute, parent and hierarchy relationships.
file_kind=agent_folder	A file in an allowed local folder through UBC Agent.