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:

  1. Start by filtering the records that you want to share.

  2. Select 'Export' from the Timeline menu option and then select the STL format.

  3. You will then be asked to select the Filters that you want to export.

  4. 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. 

 

  1. 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.

  2. 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:

  1. Start by filtering the records that you want to share.

  2. Select 'Export' from the Timeline menu option and then select the PDF format.

  3. 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.

  4. 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.

Exporting and Importing records in XML format

 

WARNING

 

Our expertise with XML is somewhat limited. This is our first venture with that format. Although some decent amount of testing was made, there might be situations or expectation that we are not aware of and that might not work as expected. Please forward any feedback you have and we will try to improve that part of the operation.

 

Note: If you want to share timelines with other users of Istoriam, please export the part that you want to share in STL format instead.

 

The XML format was developed as some Istoriam users expressed the need to see the content of their timeline in a more standard format. XML was selected as it is one of the most commonly used format.

 

Finally please note that the Istoriam database is an SQLite database and can be viewed, if needed, using any SQL reader (many of which are available online).

Exporting in XML format

You can export your Istoriam timeline into an XML format that can be then viewed with any XML reader (obviously without the display part).

 

For that, please follow these steps:

  1. Start by filtering the records that you want to share.

  2. Select 'Export' from the Timeline menu option and then select the XML format.

  3. You will be asked to select whether you want to export the timeline with the records' photos (if you have added photos to some of your records) or without them. If you decide to export the photos too, those will be exported as a Base-64 encoded string.

  4. You will then be asked to select the Filters that you want to export.

  5. You will finally be asked to specify the name and location of the file where the records will be exported.

 

You can now view the content with an XML reader or you can share the file with the other users of Istoriam, who can then import it in their own timelines.

Importing an XML file

You can import an XML file that was created by Istoriam (with the export to XML feature) into another Istoriam timelines. To do, please follow these steps:

 

  1. Select 'Import' from the Timeline menu option, then select the XML option. You will be asked to select the location and name of the file.

  2. You will have then to decide whether you want to replace existing records in your timeline with imported records that carry the same identifiers or whether you prefer to keep both copies in your timeline. This is intended to avoid duplicating records that are imported from an XML file after your timeline STL file has been modified.

  3. 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 and your timeline will revert to its content prior to the import.

Note: While some record attributes can be changed in XML and then re-imported into your timeline, it is not a feature that has been tested extensively. It is clear though that changing some attributes in the XML file (such as 'Record ID' or 'Parent ID') might result in a corrupted database. Other attributes (such as 'Start Date' or 'Description Text') should be re-imported correctly.

 
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.

Screen Shot 2020-04-04 at 9.55.17 AM.png