For simple data, the auto-generation of attributes from column heads and the data-types assumed are generally correct but for more complexed or nuanced tasks there are some points to bear in mind.
Tinderbox assumes the data will contain a first row of column headers which it can use to map data to existing attributes or generate new ones.
The first column always maps to $Name regardless of the #1 column header value. But, see below for behaviour if a 'Name' column is included elsewhere.
Mapping source column headers to existing Tinderbox attributes
Tinderbox will match a column header, case-sensitively, to any existing system or user attribute. Thus header 'Name' will map to $Name but 'name' will create a new (String-type) $name. Special cases:
- If a column other than the first one has the header 'Name', that column maps to $Name. However, no data is then imported from column #1 of the source data.
- 'Text' but not 'text' maps to $Text. If $Text is supplied from source it is not set as a key attribute (more below) but $text would be.
Auto-generated (user) attribute names
If a column-header (other than if column #1) does not match an existing system or user attribute name, then a new user attribute will be created. The new attribute will use the exact (case-sensitive) insofar as the source value matches. 'Illegal' characters for attributes are substituted with underscores. Thus, source 'my / stuff' creates $my___ßtuff, 'my / stuff' creates $my____tuff. Note how the case of legal text is maintained and each illegal character is substituted by an underscore. Underscores - common in some database tables are thus maintained during import.
Date type coercion on import
These appear to be the 'rules' for coercion:
- Boolean. '0', '1', 'true' and 'false' result in a Boolean-type attribute. Any value other than '0' or 'false' passed to an existing Boolean attribute will coerce to a Boolean 'true' value.
- Any positive or negative integer or decimal number, barring '0' and '1' will create a Number-type attribute - including '0.0' and '1.0'.
- All other data maps default to creating String-type data. Lists - i.e. semi-colon-delimited strings - are still coerced to Strings
Forcing a non-default data type mapping
As shown above lists can't be detected and '0' / '1' may be misconstrued as booleans. There are two ways to avoid this:
- Include a dummy first row of data (i.e. after the header row) with values that will force the correct data type. After import delete the note created for the first (dummy) record. However, note this method does not help for data types other than String, Number and Boolean.
- Pre-create the attributes and set type. There are two ways to do this:
- Import the first 2 rows of source and correct the data types of the auto-generated attributes (and check mapping to system attributes). Any user attributes with the wrong data type can have these reset via the Document Inspector, User tab.Then delete the imported date container and notes before importing the full data set. If using copy-paste from another app rather than from a stored data file, you might need to import all data and delete, then reimport after the attributes have been corrected. This method will also show up any attribute naming issues that may arise and which may need correcting at source.
- Manually create the new user attributes from scratch in Tinderbox. If there are a lot of such attributes, the method above may prove quicker.
Import fixes Key Attributes in created notes
The import process sets each new per-row note's $KeyAttributes. If you are going to apply a prototype to these notes you may first wish to reset the new notes' Key Attributes.