Import and export

As you work in NarraFirma, the software saves every action you take using "messages" that together form a history. The purpose of such a "journaling" data storage system is to avoid data loss or corruption. Journaling also makes it easier to implement an undo system (which we have not yet implemented).

A project snapshot does not include these historical messages; it simply saves the current state of each element in the project. Because we haven't yet implemented any project-level undo functionality, it doesn't (yet) make any difference if you save a project snapshot or a project history, but in the future it might matter.

The one exception to that "it doesn't matter" statement is that, if you are exporting a project so you can reset it and then restore it without disconnected stories (see below), you do need to choose the snapshot export. The full-history export does not purge disconnected stories.

A project history is a record of everything that took place since you started the project, including the addition of stories, changes to stories, and references to stories. It would be hard (and possibly damaging to a potential future undo system) to pull the story-related messages out of that history.

Yes. You can export the project (with or without collected stories) to a file, then create a new, empty project and import the data into it.

Yes. The file format is independent of either back end. Just export the project, create a new (empty) project in your other installation of NarraFirma, and import the project into it.

Don't do that. It will have unpredictable results. You should always import a project file to an empty project.

No. You can export your stories, and your story forms, as CSV (spreadsheet) files from the Export stories or story forms page.

Projects are exported in JSON format. You can open a project file in any browser or text editor and see the elements defined in it.

You could, but the better way is to go to the project-administration Print page and print a project report.

Yes. Just be careful, and make a backup copy before you make any changes.

Some tips for editing NarraFirma JSON files:

• Do not do this unless you are comfortable working with structured text data.
• Make sure the file stays in plain text format with UTF-8 encoding.
• Because this is a journaling data store, the same data fields may appear in multiple messages. Pay attention to the message timestamps.
• In each addTriple message, "a" is the identifier of the thing being altered (a story form, a story, a question, etc). The "b" field is the name of the property or field being set or changed. The "c" field is the data. So a message that changes the color of a cat named Chloe to gray would read [a:Chloe, b:color, c:gray]. If Chloe's color was later changed to brown, a later message would read [a:Chloe, b:color: c:brown].

For two reasons: to reload a project changed outside of your NarraFirma installation, or to remove disconnected stories.

Changing a project outside of NarraFirma

You can export a NarraFirma project to a JSON file, change the JSON file using a text editor or another installation of NarraFirma, reset the project, and import the changed JSON file into it. This will recreate the project, applying any changes you made to the JSON file.

Removing disconnected stories

To avoid accidentally losing stories, NarraFirma does not delete stories when you delete a story collection. It just removes the container they were in. Most of the time this will not matter, since you might only delete one or two story collections, ever.

However, if you've been importing the same data over and over to get it right, and in the process you've been creating and deleting many story collections, you could end up with many disconnected stories floating around in your project. Because NarraFirma loads everything into memory when it runs, these extra stories can cause NarraFirma to run slower or even run out of Javascript memory. This is not likely to be a problem if you have dozens of stories, or even a hundred. But if you have loaded several hundred stories several times, you might notice a slowdown. In that case, you can use the export-reset-import process to trim out the hidden stories and speed things up.

1. Choose "project snapshot with stories," then click "Export project". Save the JSON file.
2. Click the "Reset project" button to empty out the project.
3. In the "Import" section, choose "project snapshot (with or without stories), then click "Import project." Choose the JSON file you saved in step one.

This will restore the project without the disconnected stories.

No. You can still get them back. When you reset a project, NarraFirma makes a backup copy of it first. To restore the backup:

• With WordPress:
  • Find a plugin that gives you access to your database tables.
  • Using the plugin, find the reset backup table. It should be called

    [your WordPress prefix]narrafirma_reset_backup_[date/time]

  • Rename or delete the original, empty table (the one you reset).
  • Rename the reset backup table to the empty table's name.
• With node.js:
  • Look in the server_data directory of your NarraFirma installation for the backup project folder. It will have the name of the original folder, plus ".backup" and a date-time stamp. Note that the folder may be hidden from view, since it starts with a period (full stop). Find an option that allows you to see hidden folders in your file system.
  • Rename or delete your original, empty folder (the one you reset).
  • Rename the backup folder to the empty folder's name.

You should now be able to start NarraFirma, access the restored backup project, recreate the deleted story collections, and get the stories back.

That's easily done. If you are using WordPress, delete the backup table. If you are using node.js, delete the backup folder.