Exporting and Importing Databases
Exporting and Importing records in STL format
Note: 'STL' is the extension used by the Istoriam files. The content of the file itself is an SQLite database.
Exporting in STL format
Occasionally, you might want to share only part of your timeline with other users of Istoriam or you might want to split your timelines into multiple smaller ones.
For that, please follow these steps:
-
Start by filtering the records that you want to share.
-
Select 'Export' from the Timeline menu option and then select the STL format.
-
You will then be asked to select the Filters that you want to export.
-
You will finally be asked to specify the name and location of the file where the records will be exported.
You can now share that file with the other users of Istoriam, who can then import it in their own timelines.
Note: If you want to share the whole timeline, you can share the whole file in which your timeline is saved.
Importing an STL file
You can import the content of one Istoriam timeline into another timelines. This could be because another Istoriam user is sharing his or her timeline with you, because you want to merge timelines that were started independently into a larger one, etc. Whatever the reason is, importing a timeline into another is very simple.
-
Select 'Import' from the Timeline menu option, then select the STL option. You will be asked to select the location and name of the file.
-
Once the import is completed, you can review the result of the import, then 'Accept' or 'Reject' the imported records. If you decide to 'Reject' the import, the imported records will be deleted from your database.
Exporting records into a PDF format
You can export your timeline into a PDF format. You will typically use that method if you want to share your database with someone that is not using Istoriam or to print your timeline.
Note: This feature will only export the visible timeline that is displayed in the main Display Window. Record contents such as Description, Locations, Photos, etc. will not be exported in PDF. If you want to share those contents, you can share your database using the STL or the XML format.
To export your timeline to PDF, please follow these steps:
-
Start by filtering the records that you want to share.
-
Select 'Export' from the Timeline menu option and then select the PDF format.
-
You will then be given two format options: Single-page and Multi-page formats.
-
The Single-page format will export the timeline into one, possibly very large, page. This format is appropriate if you want to view the database in a PDF viewer or if you own a special printer that can print on large paper format.
-
The Multi-page format will divide the timeline into separate standard size pages. This format is appropriate if you want to print the timeline on a standard printer.
-
-
You will finally be asked to specify the name and location of the file where the records will be exported.
The timeline will be exported into a standard PDF file.
Note: We use a 3rd party code to export the database into PDF. That library seems to limit the size of the Single-page format. If your timeline is very large, the export will trim it to fit in the specified maximum size. If that happens to your export, you might want to reduce the space between the records (using the Horizontal and Vertical Spacing) or reduce the number of records being displayed.
Importing Records from CSV format
If you have records that are saved in a spreadsheet, a text format or maybe using another application, and if you can export those records into a CSV file, you can then import those records to Istoriam.
To import records from a CSV file, the records have to be structured in a format that can be understood by Istoriam.
Note: Not all the record attributes that are typically used with Istoriam can be imported with a CSV file. For example, record colors, photos, hierarchy structure cannot be imported and will have to be edited manually in Istoriam afterwards.
To import your records from a CSV file, please follow the steps listed below.
Step 1 - Structure the data in a spreadsheet
If your data is already in a spreadsheet, you just need to adjust the columns to the format shown in Figure 1.
If you are not using a spreadsheet with your data, you can either import that data directly into a spreadsheet (most spreadsheet, like Microsoft Excel and Apple Numbers, will import data from text format) or have your application export the data to a CSV file and open the file with your spreadsheet.
Once your data is in a spreadsheet format, have it structured using the format shown in the following figure.
Note: Even if your data does not contain value for some of the attributes in the template, you still need to have that column. However you can keep it cells empty (the import process expects a specific number of attributes in each row, even if those have no value).
Note the following for each attribute:
-
Title: the title of your record. Any text as long as it is less than 50 characters
-
Start Date: the start date of the record. If left empty, default to the 'today' date.
-
End Date: the end date of the record. If left empty or set to a date that is earlier than the Start Date, will default to the Start Date value.
-
Tags: the tags associated with the record. Can be left empty.
-
Description: This is the text associated with your record. It can be of any length.
-
URLs: list of URLs associated with your record. If multiple values are used, those should be separated by a comma. Can be left empty.
-
Level: specifies the level (between 1and 250) at which the record will be displayed. Please refer to the Record Attribute section in the manual for a description of how levels are used.
The Level field can be left empty and will default to the value of 25 EXCEPT FOR THE LAST RECORD IN THE TABLE. If you are not using levels with your records, just type 25 for that last record. If not, you can use whatever value between 1and 250.
Step 2 - Export data to CSV
Once Step 1 is completed, you can export the result into a CSV file.
Before you start the export, you should delete the header row from your spreadsheet. This row has no values that you want to import.
If you are using Apple Numbers, go to the "File" menu and select "Export To" and then select CSV. Ensure that Unicode (UTF-8) text encoding is used.
Step 3 - Import your data to Istoriam
To import your CSV file to Istoriam, go to the "Database" menu and select "Import CSV". In the panel that will open, select the CSV file created in Step 2. The records in that file will be imported in your Istoriam database.
Comma vs. Semicolon
When exporting data to CSV, there are instances where the CSV fields are separated by a comma (typically in countries where a point is used for decimals) while there are other instances where the CSV fields are separated by a semicolon (typically in countries where a comma is used for decimals).
It is not possible for the application to determine what type of separator is being used in your CSV file. Hence the application will ask you, before the importation is started, to specify which of the two types of separators is used in your file.
If you don't know, you can either try to open your CSV file in a text editor and check that, or you can let the application run with the default separator (the comma) and if nothing works, retry the import a second time but now with the selection of the semicolon as the separator.
Note: If you did not delete the heading row from the spreadsheet, the first row will fail in both cases.
Date Format
When importing records, the date format is very important. Is 03/01/2018 equal to 03 January 2018 (non-US format) or March 01, 2018 (US format)?
In the Configuration Panel, you can set the date format that you want the application to use. That format will also be used when importing CSV files. By default, if your operating system is USA configured, then the US date format (Month/Day/Year) will be used. Otherwise, the non-US date format (Day/Month/Year) will be used. However you can change the format that the application should use in the Configuration Panel as you please.
Note: incomplete dates (Month/Year or only Year) can be used as well.
Dealing with Errors
Occasionally, the application will not be able to read some of the data in your CSV file. This might happen typically to the date fields (as there is not a single format that is used to specify a date) and the URLs (which might not be using the complete format). Anytime the application detects a row with an error, an alert window will inform you of the error, the row number and the field that failed. You can then decide to skip the record or abort the import altogether. In the latter case, all the records already imported will be deleted from the database.
Step 4 - Accepting the import
Once all the records have been imported, you are given a last chance to accept the imported records or abort and cancel the process. If you accept the import, then the records will become regular records in your database. However, if you did not like the result, you can reject the import and all the imported records will be removed from the database.
